MCP Bundles (MCPB)

⚠️ 重要通知：此项目名称从DXT（桌面扩展）更改为MCPB（MCP捆绑包）

如果您正在寻找DXT工具，请注意它们已被重命名为MCPB。请更新您的依赖项和工具：

• dxt CLI现在是mcpb
• .dxt文件现在是.mcpb文件
• @anthropic-ai/dxt包将被移动到@anthropic-ai/mcpb

MCP Bundles（.mcpb）是包含本地MCP服务器及其manifest.json描述文件的zip存档。该格式在精神上类似于Chrome扩展（.crx）或VS Code扩展（.vsix），使最终用户能够通过单击安装本地MCP服务器。

此仓库提供了三个组件：捆绑包规范在MANIFEST.md，用于创建捆绑包的CLI工具（参见CLI.md），以及Claude用于macOS和Windows加载和验证MCPB捆绑包的代码（src/index.ts）。

• 对于本地MCP服务器的开发者，我们的目标是使这些服务器的分发和安装更加方便。
• 对于支持本地MCP服务器的应用程序的开发者，我们的目标是使其易于添加对MCPB捆绑包的支持。

Claude for macOS和Windows使用此仓库中的代码来实现本地MCP服务器的单击安装，包括一系列用户友好的功能——如自动更新、轻松配置MCP服务器及其所需的变量和参数，以及一个精选目录。我们致力于围绕MCP服务器的开放生态系统，并相信其能够被多个应用程序和服务普遍采用的能力对于希望将AI工具连接到其他应用和服务的开发者来说具有益处。因此，我们将开源MCP捆绑包规范、工具链以及Claude for macOS和Windows用来实现自身对MCP捆绑包支持的模式和关键函数。我们希望mcpb格式不仅能让Claude的本地MCP服务器更具可移植性，也能让其他AI桌面应用程序受益。

对于捆绑包开发者

核心而言，MCPB只是包含整个MCP服务器和一个manifest.json的简单zip文件。因此，将本地MCP服务器转换成捆绑包非常直接：只需将所有必需的文件放入一个文件夹中，创建一个manifest.json，然后创建一个归档文件即可。

为了简化这一过程，本包提供了一个CLI工具，帮助您创建manifest.json和最终的.mcpb文件。要安装它，请运行：

npm install -g @anthropic-ai/mcpb

1. 在包含您的本地MCP服务器的文件夹中运行mcpb init。此命令将引导您完成manifest.json的创建。
2. 运行mcpb pack以创建一个mcpb文件。
3. 现在，任何实现MCPB支持的应用程序都可以运行您的本地MCP服务器。例如，用Claude for macOS和Windows打开文件以显示安装对话框。

您可以在MANIFEST.md中找到manifest.json的完整规范及其所有必填和选填字段。示例捆绑包可以在examples中找到。

AI工具的提示模板

像Claude Code这样的AI工具在了解规范后特别擅长创建MCP捆绑包。当提示AI编码工具构建捆绑包时，简要说明您的捆绑包旨在做什么——然后在您的指令中添加以下上下文。

我想将其作为MCP捆绑包（简称“MCPB”）来构建。请按照以下步骤操作：

1. 仔细阅读规范：
   • https://github.com/anthropics/mcpb/blob/main/README.md - MCPB架构概述、能力和集成模式
   • https://github.com/anthropics/mcpb/blob/main/MANIFEST.md - 完整的捆绑包清单结构和字段定义
   • https://github.com/anthropics/mcpb/tree/main/examples - 包括“Hello World”示例在内的参考实现
2. 创建适当的捆绑包结构：
   • 根据MANIFEST.md规范生成有效的manifest.json
   • 使用@modelcontextprotocol/sdk实现MCP服务器并正确定义工具
   • 包含适当的错误处理、安全措施和超时管理
3. 遵循最佳开发实践：
   • 通过stdio传输实现正确的MCP协议通信
   • 使用清晰的模式、验证和一致的JSON响应来组织工具
   • 利用这个捆绑包将在本地运行的事实
   • 添加适当的日志记录和调试能力
   • 包含适当的文档和设置说明
4. 测试考虑：
   • 验证所有工具调用返回结构良好的响应
   • 验证清单正确加载且主机集成工作正常

生成完整的、生产就绪的代码，可以立即进行测试。专注于防御性编程、清晰的错误消息，并严格遵循MCPB规范以确保与生态系统的兼容性。

目录结构

最小捆绑包

manifest.json是唯一必需的文件。

示例：Node.js捆绑包

bundle.mcpb (ZIP文件)
├── manifest.json         # 必需：捆绑包元数据和配置
├── server/               # 服务器文件
│   └── index.js          # 主入口点
├── node_modules/         # 捆绑的依赖项
├── package.json          # 可选：NPM包定义
├── icon.png              # 可选：捆绑包图标
└── assets/               # 可选：附加资产

示例：Python捆绑包

bundle.mcpb (ZIP文件)
├── manifest.json         # 必需：捆绑包元数据和配置
├── server/               # 服务器文件
│   ├── main.py           # 主入口点
│   └── utils.py          # 额外模块
├── lib/                  # 捆绑的Python包
├── requirements.txt      # 可选：Python依赖列表
└── icon.png              # 可选：捆绑包图标

示例：二进制捆绑包

bundle.mcpb (ZIP文件)
├── manifest.json         # 必需：捆绑包元数据和配置
├── server/               # 服务器文件
│   ├── my-server         # Unix可执行文件
│   ├── my-server.exe     # Windows可执行文件
└── icon.png              # 可选：捆绑包图标

语言选择建议

我们建议使用Node.js实现MCP服务器而不是Python，以减少安装摩擦。Node.js随Claude for macOS和Windows一起提供，这意味着您的捆绑包将开箱即用，无需用户安装额外的Python运行时（或您手动打包它们）。

捆绑依赖项

Python捆绑包：

• 将所有必需的包捆绑在server/lib/目录中
• 或者在server/venv/中捆绑一个完整的虚拟环境
• 使用pip-tools、poetry或pipenv等工具创建可重复的捆绑包
• 通过mcp_config.env设置PYTHONPATH以包含捆绑的包

Node.js捆绑包：

• 运行npm install --production以创建node_modules
• 将整个node_modules目录与您的捆绑包一起捆绑
• 使用npm ci或yarn install --frozen-lockfile进行可重复构建
• 服务器入口点在manifest.json的server.entry_point中指定

二进制捆绑包：

• 优先静态链接以获得最大兼容性
• 如果使用动态链接，则包含所有必需的共享库
• 在没有开发工具的干净系统上进行测试

贡献

我们欢迎贡献！请参阅我们的贡献指南以获取详细信息。

开发设置

# 克隆仓库
git clone https://github.com/anthropics/mcpb.git
cd mcpb

# 安装依赖项
yarn

# 构建项目
yarn build

# 运行测试
yarn test

发布流程

1. 更新package.json中的版本号
2. 创建带有版本提升的拉取请求
3. 合并后，创建GitHub发布
4. 包将自动发布到npm

许可证

本项目根据MIT许可证发布 - 详情请参阅LICENSE文件。