modelcontextprotocol/mcpb

# MCP Bundles (MCPB) MCP Bundles (`.mcpb`) 是包含本地 MCP server 和 `manifest.json`（用于描述服务器及其功能）的 zip 归档文件。该格式在精神上类似于 Chrome 扩展程序 (`.crx`) 或 VS Code 扩展程序 (`.vsix`))，使最终用户能够通过单击安装本地 MCP server。 此仓库提供了三个组件：[MANIFEST.md](MANIFEST.md) 中的 bundle 规范、用于创建 bundle 的 CLI 工具（见 [CLI.md](CLI.md)），以及 Claude for macOS 和 Windows 用于加载和验证 MCPB bundle 的代码（[src/index.ts](src/index.ts)）。 - 对于本地 MCP server 的开发者，我们旨在让上述 server 的分发和安装变得便捷 - 对于支持本地 MCP server 的应用开发者，我们旨在让其轻松添加对 MCPB bundle 的支持 Claude for macOS 和 Windows 使用此仓库中的代码来实现本地 MCP server 的单击安装，包括许多对最终用户友好的功能——例如自动更新、便捷的 MCP server 配置及其所需的变量和参数，以及一个精选的目录。我们致力于围绕 MCP server 的开放生态系统，并相信其能够被多个应用和服务普遍采用的能力，将使那些旨在将 AI 工具连接到其他应用和服务的开发者受益。因此，我们正在将 MCP Bundle 规范、工具链，以及 Claude for macOS 和 Windows 用于实现自身对 MCP Bundles 支持的 schemas 和关键函数进行开源。我们希望 `mcpb` 格式不仅能让本地 MCP server 对 Claude 来说更具可移植性，对其他 AI 桌面应用程序也是如此。 # Bundle 开发者指南 本质上，MCPB 是简单的 zip 文件，包含您的整个 MCP server 和一个 `manifest.json`。因此，将本地 MCP server 转换为 bundle 非常简单：您只需将所有必需的文件放在一个文件夹中，创建一个 `manifest.json`，然后创建一个归档文件。 为了使此过程更轻松，此包提供了一个 CLI，可帮助您创建 `manifest.json` 和最终的 `.mcpb` 文件。要安装它，请运行： ``` npm install -g @anthropic-ai/mcpb ``` 1. 在包含您本地 MCP server 的文件夹中，运行 `mcpb init`。此命令将引导您完成 `manifest.json` 的创建。 2. 运行 `mcpb pack` 以创建一个 `mcpb` 文件。 3. 现在，任何实现了对 MCPB 支持的应用都可以运行您的本地 MCP server。例如，在 Claude for macOS 和 Windows 中打开该文件以显示安装对话框。 您可以在 [MANIFEST.md](MANIFEST.md) 中找到 `manifest.json` 的完整规范及其所有必填和选填字段。Bundle 的示例可以在 [examples](./examples/) 中找到。 ## AI 工具的 Prompt 模板 像 Claude Code 这样的 AI 工具在了解了规范后，特别擅长创建 MCP bundles。在提示 AI 编码工具构建 bundle 时，请简要说明您的 bundle 旨在做什么——然后将以下上下文添加到您的指令中。 ## 目录结构 ### 最小 Bundle `manifest.json` 是唯一必需的文件。 ### 示例：Node.js Bundle ``` bundle.mcpb (ZIP file) ├── manifest.json # Required: Bundle metadata and configuration ├── server/ # Server files │ └── index.js # Main entry point ├── node_modules/ # Bundled dependencies ├── package.json # Optional: NPM package definition ├── icon.png # Optional: Bundle icon └── assets/ # Optional: Additional assets ``` ### 示例：Python Bundle ``` bundle.mcpb (ZIP file) ├── manifest.json # Required: Bundle metadata and configuration ├── server/ # Server files │ ├── main.py # Main entry point │ └── utils.py # Additional modules ├── lib/ # Bundled Python packages ├── requirements.txt # Optional: Python dependencies list └── icon.png # Optional: Bundle icon ``` ### 示例：Binary Bundle ``` bundle.mcpb (ZIP file) ├── manifest.json # Required: Bundle metadata and configuration ├── server/ # Server files │ ├── my-server # Unix executable │ ├── my-server.exe # Windows executable └── icon.png # Optional: Bundle icon ``` ### 语言选择建议 **我们建议使用 Node.js 而非 Python 来实现 MCP server**，以减少安装阻力。Node.js 随 Claude for macOS 和 Windows 一起提供，这意味着您的 bundle 将为用户提供开箱即用的体验，而无需他们安装额外的 Python runtime（或由您手动打包它们）。 ### 打包依赖 **UV Runtime (v0.4+):** - 在 manifest 中使用 `server.type = "uv"` - 包含带有依赖项的 `pyproject.toml`（无需打包额外的包） - 宿主应用程序自动管理 Python 和依赖项 - 无需用户安装 Python 即可跨平台工作 - 参见 `examples/hello-world-uv` **Python Bundles（传统方式）：** - 在 manifest 中使用 `server.type = "python"` - 将所有必需的包打包在 `server/lib/` 目录中 - 或者将完整的虚拟环境打包在 `server/venv/` 目录中 - 使用 `pip-tools`、`poetry` 或 `pipenv` 等工具创建可重现的 bundles - 通过 `mcp_config.env` 设置 `PYTHONPATH` 以包含已打包的包 - **限制**：无法以可移植的方式打包编译型依赖项（例如，MCP Python SDK 所需的 pydantic） **Node.js Bundles:** - 运行 `npm install --production` 以创建 `node_modules` - 将整个 `node_modules` 目录与您的 bundle 打包在一起 - 使用 `npm ci` 或 `yarn install --frozen-lockfile` 进行可重现的构建 - Server 入口点在 manifest.json 的 `server.entry_point` 中指定 **Binary Bundles:** - 首选静态链接以获得最大兼容性 - 如果使用动态链接，请包含所有必需的共享库 - 在没有开发工具的纯净系统上进行测试 ## 开发设置 ``` # Clone repository git clone https://github.com/anthropics/mcpb.git cd mcpb # Install dependencies yarn # Build project yarn build # Run tests yarn test ``` ## 发布流程 1. 更新 `package.json` 中的版本 2. 创建一个包含版本升级的 pull request 3. 合并后，创建一个 GitHub release 4. 包将自动发布到 npm # 许可证 此项目的新贡献根据 Apache License 2.0 进行许可，现有代码则基于 MIT 许可——详情请参阅 [LICENSE](LICENSE) 文件。

标签：MCP, MITM代理, 打包格式, 暗色界面, 桌面应用, 自动化攻击