SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场build-mcpb

build-mcpb

智能体与模型

查看项目

更新于 10-30 16:19

技能介绍

用途

build-mcpb 用于构建 MCPB（Bundled Local MCP Server），即把本地 MCP 服务器与其运行时一起打包。用户只需安装一个文件，无需在机器上安装 Node、Python 或任何工具链即可运行。这是分发本地 MCP 服务器的官方认可方式。

MCPB 是次要分发路径。Anthropic 推荐远程 MCP 服务器用于目录收录，参见 https://claude.com/docs/connectors/building/what-to-build。

当服务器必须运行在用户机器上时使用 MCPB：读取本地文件、驱动桌面应用、与 localhost 服务通信、调用操作系统级 API。如果服务器只访问云端 API，几乎肯定应该改用远程 HTTP 服务器（参见 build-mcp-server），不要为可以用 URL 实现的东西支付 MCPB 打包成本。

MCPB 包的内容

my-server.mcpb              (zip archive)
├── manifest.json           ← identity, entry point, config schema, compatibility
├── server/                 ← your MCP server code
│   ├── index.js
│   └── node_modules/       ← bundled dependencies (or vendored)
└── icon.png

宿主读取 manifest.json，以 stdio MCP 服务器方式启动 server.mcp_config.command，并传递消息。从代码角度看，它与本地 stdio 服务器完全相同，唯一区别是打包方式。

Manifest

{
  "$schema": "https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json",
  "manifest_version": "0.4",
  "name": "local-files",
  "version": "0.1.0",
  "description": "Read, search, and watch files on the local filesystem.",
  "author": { "name": "Your Name" },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "ROOT_DIR": "${user_config.rootDir}"
      }
    }
  },
  "user_config": {
    "rootDir": {
      "type": "directory",
      "title": "Root directory",
      "description": "Directory to expose. Defaults to ~/Documents.",
      "default": "${HOME}/Documents",
      "required": true
    }
  },
  "compatibility": {
    "claude_desktop": ">=1.0.0",
    "platforms": ["darwin", "win32", "linux"]
  }
}
  • server.type — node、python 或 binary。仅作信息用途；实际启动来自 mcp_config。
  • server.mcp_config — 实际要 spawn 的 command/args/env。使用 ${__dirname} 表示包内相对路径，使用 ${user_config.<key>} 替换安装时配置。没有自动前缀——服务器读取的环境变量名就是你在 env 中写入的名称。
  • user_config — 在宿主 UI 中呈现的安装时设置。type: "directory" 会渲染原生文件夹选择器。sensitive: true 会存储到操作系统钥匙串。所有字段参见 references/manifest-schema.md。

服务器代码：与本地 stdio 相同

服务器本身是标准 stdio MCP 服务器，工具逻辑中没有任何 MCPB 特有内容。

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { readFile, readdir } from "node:fs/promises";
import { join } from "node:path";
import { homedir } from "node:os";

// ROOT_DIR comes from what you put in manifest's server.mcp_config.env — no auto-prefix
const ROOT = (process.env.ROOT_DIR ?? join(homedir(), "Documents"));

const server = new McpServer({ name: "local-files", version: "0.1.0" });

server.registerTool(
  "list_files",
  {
    description: "List files in a directory under the configured root.",
    inputSchema: { path: z.string().default(".") },
    annotations: { readOnlyHint: true },
  },
  async ({ path }) => {
    const entries = await readdir(join(ROOT, path), { withFileTypes: true });
    const list = entries.map(e => ({ name: e.name, dir: e.isDirectory() }));
    return { content: [{ type: "text", text: JSON.stringify(list, null, 2) }] };
  },
);

server.registerTool(
  "read_file",
  {
    description: "Read a file's contents. Path is relative to the configured root.",
    inputSchema: { path: z.string() },
    annotations: { readOnlyHint: true },
  },
  async ({ path }) => {
    const text = await readFile(join(ROOT, path), "utf8");
    return { content: [{ type: "text", text }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

沙箱完全由你负责。没有清单级沙箱——进程以完整用户权限运行。必须校验路径、拒绝逃逸 ROOT、对 spawn 使用白名单。参见 references/local-security.md。

在从配置环境变量硬编码 ROOT 之前，检查宿主是否支持 roots/list——这是规范原生的获取用户批准目录的方式。模式参见 references/local-security.md。

构建流水线

Node：

npm install
npx esbuild src/index.ts --bundle --platform=node --outfile=server/index.js
# or: copy node_modules wholesale if native deps resist bundling
npx @anthropic-ai/mcpb pack

mcpb pack 会压缩目录并根据 schema 校验 manifest.json。

Python：

pip install -t server/vendor -r requirements.txt
npx @anthropic-ai/mcpb pack

将依赖 vendoring 到子目录，并在入口脚本中将其前置到 sys.path。原生扩展（numpy 等）必须为每个目标平台构建——尽可能避免原生依赖。

MCPB 没有沙箱——安全由你负责

与移动应用商店不同，MCPB 不强制执行权限。manifest 没有 permissions 块——服务器以完整用户权限运行。references/local-security.md 是必读而非可选。每个路径都必须校验，每个 spawn 都必须白名单，因为平台层面没有任何东西阻止你。

如果你期望从 manifest 获得文件系统/网络范围限制：它不存在。请在工具处理程序中自行构建。

如果服务器的唯一工作是访问云端 API，请停止——那是穿着 MCPB 外衣的远程服务器。用户在本地运行它没有任何收益，而你无端承担了本地安全负担。

MCPB + UI 组件

MCPB 服务器可以像远程 MCP 应用一样提供 UI 资源——组件机制与传输方式无关。例如浏览实际磁盘的本地文件选择器、控制原生应用的对话框等。

组件编写在 build-mcp-app 技能中介绍，此处工作方式相同。唯一区别是服务器运行的位置。

测试

# Interactive manifest creation (first time)
npx @anthropic-ai/mcpb init

# Run the server directly over stdio, poke it with the inspector
npx @modelcontextprotocol/inspector node server/index.js

# Validate manifest against schema, then pack
npx @anthropic-ai/mcpb validate
npx @anthropic-ai/mcpb pack

# Sign for distribution
npx @anthropic-ai/mcpb sign dist/local-files.mcpb

# Install: drag the .mcpb file onto Claude Desktop

发布前请在没有开发工具链的机器上测试。MCPB 中“在我机器上能跑”的失败几乎总是源于某个依赖实际上没有被打包。

参考文件

  • references/manifest-schema.md — 完整的 manifest.json 字段参考
  • references/local-security.md — 路径遍历、沙箱、最小权限