Create MCPB bundle template for generated local servers

[jmagar]

Goal

Create an MCPB bundle template so generated local MCP servers can ship as one-click installable .mcpb bundles for compatible desktop hosts.

Current facts

• MCP Bundles (.mcpb) are ZIP archives containing a local MCP server and a manifest.json that describes the server and its capabilities.
• The MCPB project is the renamed successor of DXT/Desktop Extensions:
  • dxt CLI is now mcpb.
  • .dxt files are now .mcpb files.
  • @anthropic-ai/dxt is moving to @anthropic-ai/mcpb.
• Claude for macOS and Windows uses the MCPB implementation for single-click local MCP server installation, configuration, verification, and automatic updates.
• Bundle creation flow is currently mcpb init to create manifest.json, mcpb validate to validate it, and mcpb pack to create the .mcpb archive.

Requirements

• Add a template path that emits a valid MCPB bundle layout for generated rmcp-template services.
• Generate or maintain manifest.json according to the MCPB manifest spec.
• Package the local server binary or launcher and any required assets/config defaults.
• Support stdio MCP launch cleanly; logs must not corrupt JSON-RPC stdout.
• Include user-configurable inputs/variables in the manifest for env vars, tokens, URLs, and other generated service settings.
• Include icons/metadata where appropriate.
• Add build/pack commands, likely via xtask, just, or release tooling.
• Add validation in CI that the generated bundle manifest is valid and the archive can be produced.
• Coordinate versioning with release-please/release components and npm/native artifact work where relevant.

Implementation phases

1. Define bundle layout.

   • Decide generated path, likely dist/mcpb/<service>/ or packages/mcpb/.
   • Decide whether the bundle contains native binaries directly or a launcher that invokes packaged/release artifacts.
   • Decide how generated config/env inputs map into MCPB manifest user configuration.

2. Generate manifest.

   • Add a template for manifest.json populated from scaffold/service metadata.
   • Include command, args, env/user config, tools/capabilities summary, icon metadata, and version.
   • Keep secret values as user config inputs, not embedded literals.

3. Build and pack.

   • Add xtask/just commands for mcpb validate and mcpb pack.
   • Add CI validation for generated fixture bundles.
   • Add release artifact upload for .mcpb when the profile is enabled.

4. Integrate with release/distribution.

   • Coordinate version bumps with Implement release-please across template release surfaces #72.
   • Reuse binaries or launchers from Create Node distribution package with npx MCP launch support #73 where appropriate.
   • Keep registry publishing (Add GitHub Actions workflow to publish server to MCP Registry #79) separate but document how an MCPB artifact may be referenced if supported.

5. Test host compatibility.

   • Validate manifest with mcpb validate.
   • Smoke stdio launch outside the bundle.
   • If possible, install/test in a Claude Desktop-compatible environment or document manual validation steps.

Alignment with related issues

• Implement release-please across template release surfaces #72 owns versioning and release automation for the MCPB manifest/artifact.
• Create Node distribution package with npx MCP launch support #73 may provide a shared launcher or native artifact naming convention.
• Add GitHub Actions workflow to publish server to MCP Registry #79 owns MCP Registry publication and should not be required to build .mcpb artifacts.
• Implement MCP Apps / MCP-UI support for Claude and ChatGPT #81 owns interactive UI resources; MCPB may bundle UI assets if a generated server opts into UI support, but that is not required for baseline MCPB packaging.

Local files likely touched

• xtask/src/* for bundle generation/validation/pack commands
• Justfile
• release/components.toml
• .github/workflows/*release*
• docs/*MCPB* or distribution docs
• generated scaffold templates for manifest.json, icons, launch scripts, and bundle layout
• package/artifact directories created by Create Node distribution package with npx MCP launch support #73 if reused

Risks

• MCPB naming and package names recently changed from DXT; docs and generated files must use current MCPB names while mentioning legacy terms only for migration.
• Bundling native binaries can multiply artifact size and platform matrix complexity.
• Launcher scripts must preserve stdio JSON-RPC cleanliness.
• Manifest user config can leak secrets if defaults are generated incorrectly.
• Host support may differ between Claude Desktop and other MCP clients.

Acceptance criteria

• Template can generate an MCPB folder with a valid manifest.json for a generated MCP server.
• mcpb validate passes for the generated manifest.
• mcpb pack or an equivalent automated command produces a .mcpb artifact.
• Bundle starts the generated server over stdio without stdout log contamination.
• Configurable values are represented in the manifest rather than hardcoded into bundled scripts.
• CI validates manifest shape and packability.
• Docs explain install/test flow for Claude desktop-compatible hosts and note the DXT-to-MCPB rename.
• Release artifacts can include .mcpb output without colliding with npm/crates.io/registry publishing.

Sources

• MCPB repository: https://github.com/modelcontextprotocol/mcpb
• MCPB README / bundle overview: https://github.com/modelcontextprotocol/mcpb#readme
• MCPB manifest spec: https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md
• MCPB CLI docs: https://github.com/modelcontextprotocol/mcpb/blob/main/CLI.md
• Claude MCPB docs: https://claude.com/docs/connectors/building/mcpb
• Anthropic engineering note on Desktop Extensions / .mcpb: https://www.anthropic.com/engineering/desktop-extensions