build-mcpb 是一个用于把本地 MCP 服务器打包成 MCPB(Bundled Local MCP Server,随附运行时的本地 MCP 服务器)的技能。MCPB 是一个包含服务器运行时的本地 MCP 服务器分发包,用户只需安装一个文件,即可在无需预装 Node、Python 或任何工具链的机器上运行。它是分发本地 MCP 服务器的受认可方式。
用途与定位:MCPB 是次要分发路径;对于目录上架场景,更推荐远程 MCP 服务器。只有当服务器必须运行在用户机器上时才使用 MCPB,例如读取本地文件、驱动桌面应用、访问 localhost 服务或调用操作系统级 API;如果服务器只访问云端 API,应改用远程 HTTP 服务器,因为本地打包没有额外收益,还会增加维护本地安全的负担。
包结构:.mcpb 是 zip 归档,通常包含 manifest.json(定义身份、入口点、配置 schema 和兼容性)、server/ 目录(服务器代码与打包的 node_modules 依赖或 vendor 依赖)以及 icon.png。宿主读取 manifest.json 后,会按 server.mcp_config.command 以 stdio MCP 服务器方式启动,并转发消息;对代码而言,这与普通本地 stdio 服务器一致,区别只在打包方式。
Manifest 要点:manifest_version 为 0.4,并通过 $schema 指向官方 schema;server.type 可为 node、python 或 binary,仅作说明,实际启动命令来自 mcp_config;mcp_config 给出要执行的 command、args、env,路径可用 ${__dirname} 表示包内相对路径,配置可用 ${user_config.<key>} 代入安装时选项;user_config 定义安装时在宿主界面展示的配置项,type 为 directory 时提供原生文件夹选择器,sensitive: true 时存入操作系统钥匙串。env 不做自动前缀,服务器读取的变量名与 manifest 中写明的完全一致。
服务器代码:服务器本身是标准 stdio MCP 服务器,工具逻辑中无 MCPB 特有内容。示例使用 @modelcontextprotocol/sdk 的 McpServer 与 StdioServerTransport,注册 list_files、read_file 等工具,并从 mcp_config.env 注入的 ROOT_DIR 读取根目录。建议优先检查宿主是否支持 roots/list,以规范方式获取用户批准的目录。
构建流程:Node 项目可执行 npm install,再用 esbuild 打包为 server/index.js;若原生依赖难以打包,可直接复制 node_modules。Python 项目用 pip install -t server/vendor 安装依赖,并在入口脚本中把 vendor 目录加入 sys.path;原生扩展需按目标平台分别构建,能避免则避免。最后运行 npx @anthropic-ai/mcpb pack 打包,并校验 manifest 是否符合 schema。
安全与限制:MCPB 没有 manifest 级权限或沙箱,服务器以完整用户权限运行,因此路径穿越防护、根目录限制、spawn 白名单、最小权限等必须由开发者在工具处理逻辑中自行实现。
测试与分发:可用 npx @anthropic-ai/mcpb init 交互式创建 manifest,用 @modelcontextprotocol/inspector 通过 stdio 直接调试服务器,用 mcpb validate 校验、mcpb pack 打包、mcpb sign 签名;安装时将 .mcpb 文件拖入 Antigravity Desktop。发布前应在没有开发工具链的机器上测试,以避免依赖未被真正打包导致问题。MCPB 服务器也可像远程 MCP 应用一样提供 UI 资源,窗口部件机制与传输方式无关。