feat: package DBHub as a Claude Desktop MCP Bundle (.mcpb)#356
Merged
Conversation
Add one-click Claude Desktop distribution via the MCP Bundle format: double-click install, DSN prompted from user settings (stored in the OS keychain), running locally over stdio. The bundle is read-only by design (readonly = true, max_rows = 1000 on execute_sql) — the curated path for giving non-technical users database access without a remote HTTP endpoint or OAuth setup (#146). No server code changes: the bundle ships a static dbhub.toml that uses the existing ${ENV_VAR} interpolation (dsn = "${DBHUB_DSN}"), with DBHUB_DSN injected by the client from the manifest's user_config. - mcpb/: manifest (MCPB v0.3), read-only TOML config, icon - scripts/build-mcpb.mjs: stages dist/ + runtime deps + drivers (derived from optionalDependencies, cloud-auth packages excluded), packs and validates with @anthropic-ai/mcpb; `pnpm run build:mcpb` - scripts/smoke-test-mcpb.mjs: unpacks the archive outside the repo (so module resolution can't lean on the project's node_modules) and drives it over stdio with the MCP SDK client; `pnpm run test:mcpb` - .github/workflows/mcpb-release.yml: on version bumps, builds, smoke tests, and attaches the bundle to GitHub release v<version> - docs: new dbhub.ai/mcpb page + pointers from README/installation Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds an MCP Bundle (.mcpb) distribution path for DBHub, enabling one-click installation in Claude Desktop with a bundled, read-only configuration and a CI workflow to publish the bundle as a GitHub release asset.
Changes:
- Add MCPB manifest + bundled
dbhub.tomltemplate configured for read-only operation with DSN injected viaDBHUB_DSN. - Add build + smoke-test scripts (
pnpm run build:mcpb,pnpm run test:mcpb) to stage, pack, unpack, and validate the bundle over stdio. - Add release automation and documentation updates to surface the new installation path.
Reviewed changes
Copilot reviewed 12 out of 15 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/smoke-test-mcpb.mjs | Adds an end-to-end smoke test that unpacks the .mcpb outside the repo and drives the server over stdio. |
| scripts/mcpb-common.mjs | Shared constants/helpers for MCPB build/test scripts (root path, bundle version, local bin resolution). |
| scripts/build-mcpb.mjs | Stages dist/ + bundle assets, installs runtime deps/drivers, validates and packs the .mcpb. |
| README.md | Documents the Claude Desktop MCP Bundle installation path and security/read-only posture. |
| pnpm-lock.yaml | Adds @anthropic-ai/mcpb and its dependency graph to the lockfile. |
| package.json | Adds build:mcpb / test:mcpb scripts and the @anthropic-ai/mcpb devDependency. |
| mcpb/manifest.json | Introduces MCPB v0.3 manifest with user-configured DSN and stdio server launch config. |
| mcpb/dbhub.toml | Adds the bundled read-only TOML template using ${DBHUB_DSN} interpolation. |
| docs/mcpb.mdx | New documentation page describing install flow, security model, and repackaging instructions. |
| docs/installation.mdx | Adds MCP Bundle as a recommended install option and cross-links to the new guide. |
| docs/docs.json | Adds the new mcpb page to the docs navigation. |
| CLAUDE.md | Documents the new MCP Bundle build/test commands and design notes for contributors. |
| .gitignore | Ignores only root /dbhub.toml (keeps mcpb/dbhub.toml tracked) and ignores dist-mcpb/. |
| .github/workflows/mcpb-release.yml | Adds GitHub Actions workflow to build/smoke-test and upload .mcpb to releases on version bumps. |
Files not reviewed (1)
- pnpm-lock.yaml: Generated file
- Attach the stderr listener before connect() — the SDK exposes the PassThrough before spawning, so a startup crash now surfaces its stderr instead of logging an empty string - Convert stderr chunks to text explicitly - Handle non-Error throws in the catch path; make client.close() best-effort so a close failure can't mask the real outcome - Include the spawn error message when mcpb unpack fails to start Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…top-only MCPB is governed by the Model Context Protocol project and installs directly in Claude Desktop, Claude Code, and MCP for Windows; other clients can run the unpacked bundle as a plain stdio server. Reword README, docs, manifest, and comments accordingly, keeping Claude Desktop as the concrete install walkthrough. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
build-mcpb.mjs stages the bundle's node_modules via npm install, and Node 22.22.2's bundled npm is broken (missing promise-retry). Apply the same bootstrap-without-npm upgrade step npm-publish.yml already uses. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds one-click Claude Desktop distribution via the MCP Bundle format, as requested in #146 (bitconym, and addressing the Desktop-without-OAuth case from Moongazer): download
dbhub-<version>.mcpb, double-click, enter a connection string. Runs locally over stdio — no remote HTTP endpoint, no OAuth.No server code changes. The bundle ships a static
dbhub.tomlusing the existing${ENV_VAR}interpolation (dsn = "${DBHUB_DSN}"); Claude Desktop injectsDBHUB_DSNfrom the user's extension settings, which are stored in the OS keychain.Read-only by design. The bundled config sets
readonly = true+max_rows = 1000onexecute_sql, so writes are rejected by the classifier and the DB session is set read-only at the engine level (#342). Teams needing a different policy repackage with their own TOML — documented recipe included.Changes
mcpb/— MCPB v0.3 manifest (single required+sensitivedsnsetting), read-only TOML config, iconscripts/build-mcpb.mjs(pnpm run build:mcpb) — stagesdist/(minus workbench frontend, demo data,.d.ts), installs runtime deps + DB drivers (derived fromoptionalDependencies; cloud-auth packages excluded for size), validates and packs with@anthropic-ai/mcpb. Output: ~12 MB packedscripts/smoke-test-mcpb.mjs(pnpm run test:mcpb) — unpacks the packed archive into an OS temp dir outside the repo (so module resolution can't silently lean on the project'snode_modules— this caught a real packaging bug during development) and drives it over stdio with the MCP SDK client.github/workflows/mcpb-release.yml— on any push tomaintouchingpackage.json: skips when releasev<version>already has the bundle asset, otherwise build → smoke test → create the release and attach the bundle (same semantics asnpm-publish.yml: publish iff this version isn't in the channel yet). Skip decision runs beforepnpm installso no-op runs are cheap.gitignore: anchoreddbhub.toml→/dbhub.tomlso the trackedmcpb/dbhub.tomltemplate needs no negationNotes for review
0.23.0(minor: new distribution channel), so merging publishesv0.23.0across all channels — npm, Docker, MCP registry, and the first GitHub release with the bundle attachedcompatibility), matching the existing engines constraintTest plan
pnpm run build:mcpb— manifest validates, packs at 11.8 MBpnpm run test:mcpb— all checks pass against the packed archive: initialize, exactly two tools listed, SELECT succeeds, CREATE rejected read-only, all five connectors load from bundled driverspnpm run test:unit— 782 tests pass.mcpbin Claude Desktop and query a real database🤖 Generated with Claude Code