feat(mcp): package server as MCPB (.mcpb) for one-click Claude Desktop install#102
Open
feat(mcp): package server as MCPB (.mcpb) for one-click Claude Desktop install#102
Conversation
MCP Bundles (formerly DXT — renamed during Anthropic's 2025 rebrand) are Claude Desktop's one-click install format for local MCP servers. A .mcpb is a zip containing the server source plus a manifest.json declaring metadata, runtime requirements, and user-config (env-var) prompts. Refs: - Spec: https://github.com/anthropics/mcpb/blob/main/MANIFEST.md - Reference: https://github.com/anthropics/mcpb/tree/main/examples/hello-world-uv - Tracking issue: #99 - Pattern ported from statuspro PR #62 (dougborg/statuspro-openapi-client#62) This commit lands just the build mechanics; CI wiring + docs follow in sibling commits. Adds: - ``frontapp_mcp_server/mcpb/manifest.template.json`` — manifest_version 0.4 with ``server.type = "uv"`` (matches the hello-world-uv reference; delegates dep resolution to UV at install time, no bundled interpreter or virtualenv). Declares ``user_config.api_key`` as a sensitive string, which Claude Desktop prompts for at install and injects as ``FRONTAPP_API_KEY`` via the ``env`` block. Version is a ``__VERSION__`` placeholder substituted at build time. - ``frontapp_mcp_server/mcpb/pyproject.template.toml`` — bundle's own pyproject. Hand-mirrors production deps from the package's pyproject but omits the ``[tool.uv.sources]`` workspace ref, which doesn't resolve outside the monorepo. The build script verifies the dep lists match and fails loudly on drift. - ``frontapp_mcp_server/mcpb/.mcpbignore`` — pack-time excludes for Python build artefacts (``__pycache__/``, ``.venv/``, etc.) on top of the CLI's defaults. - ``scripts/build_mcpb.py`` — orchestrator. Reads the package's pyproject for the version, verifies the bundle dep mirror, stages ``build/mcpb/`` (manifest + pyproject + ``src/frontapp_mcp/`` source + README), runs ``mcpb validate`` then ``mcpb pack`` to produce ``dist/frontapp-mcp-server-<version>.mcpb``. Honors ``MCPB_SKIP_PACK=1`` for local dry-runs without the CLI installed. - ``[tool.poe.tasks].build-mcpb`` — convenience entry point. Also fixes a pre-existing dep-constraint bug surfaced by the bundle: ``frontapp_mcp_server/pyproject.toml`` declared ``frontapp-openapi-client>=0.51.0`` but only 0.1.0 (and below) ever existed. The workspace ref hides this inside the monorepo, but the bundle resolves from PyPI and would fail on launch. Constraint is now truthful (``>=0.1.0``) and the bundle template mirrors it; the build script's dep-mirror verification keeps them in sync going forward. Verified end-to-end with ``mcpb`` CLI v2.1.2 — manifest validates against the schema; the produced .mcpb (77.3 kB, 34 files) inspects correctly via ``mcpb info``. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a ``build-mcpb`` job to ``.github/workflows/release-mcp.yml`` that runs alongside the existing PyPI publish job on ``mcp-v*`` tag pushes: - Sets up Python (no uv — the build script is stdlib-only) and Node 20. - Installs the ``mcpb`` CLI via npm. - Runs ``python scripts/build_mcpb.py``; captures the artifact path printed on stdout. - Uploads the .mcpb as a workflow artifact. - On real tag pushes (``startsWith(github.ref, 'refs/tags/mcp-v')``) attaches the .mcpb to the existing GitHub release that semantic-release created earlier in the workflow. Each ``mcp-v*`` tag now produces both a PyPI wheel and a downloadable ``.mcpb`` on the release page, ready for one-click install in Claude Desktop. Pattern ported from statuspro PR #62 (dougborg/statuspro-openapi-client#62). Refs #99. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…top flow Reorders the Claude Desktop section in ``frontapp_mcp_server/README.md`` to lead with the .mcpb bundle (download from the latest mcp-v release, drag into Claude Desktop, prompts for the API key via UI) and demote the manual ``uvx`` JSON config to a labeled fallback. The .mcpb path is friendlier for non-technical users — no JSON editing, no remembering env-var names, and the API key is stored in Claude Desktop's secrets store rather than a plaintext config file. Updates the dev-mode caveat note to mention both ``.mcpb`` and ``uvx`` resolve from PyPI (so neither works against an unpublished local clone until issue #10 lands the publish workflow). Pattern ported from statuspro PR #62 (dougborg/statuspro-openapi-client#62). Refs #99. Co-Authored-By: Claude Opus 4.7 (1M context) <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
1 participant
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
Packages `frontapp-mcp-server` as an MCP Bundle (.mcpb) — Claude Desktop's one-click install format for local MCP servers. The bundle ships the server source plus a manifest declaring runtime requirements and prompting for `FRONTAPP_API_KEY` via the Claude Desktop UI (no JSON config editing).
Closes #99. Near-direct port of statuspro PR #62 — same monorepo layout, same UV-runtime bundle pattern, same dep-mirror verification.
What's added
Bundled bug fix
The bundle surfaced a pre-existing footgun: `frontapp_mcp_server/pyproject.toml` declared `frontapp-openapi-client>=0.51.0` but only 0.1.0 ever existed (workspace ref hides this in-monorepo, but the bundle resolves from PyPI). Fixed the constraint to `>=0.1.0`; the bundle template mirrors it; the build script's dep-mirror check keeps them in sync going forward. Same exact bug + fix as statuspro #62.
Build output
```
Output: dist/frontapp-mcp-server-0.1.0.mcpb
```
Test plan
🤖 Generated with Claude Code