MetaMCP

MetaMCP

MetaMCP 是面向大量长尾 MCP 服务的安全、按需网关。它为 MCP 客户端提供三个稳定的工具：

• mcp_discover 可查找已配置的服务、缓存的工具架构和经过审核的 Method，而无需启动所有子服务。
• mcp_call 可按需调用一个明确指定的子工具。
• mcp_run 可执行有界、经过架构验证的声明式 Method。

MetaMCP 并非要取代所有直接 MCP 连接。重要、常用、精简或经过强身份验证的 MCP 应保持直连。将不规则的长尾服务接入 MetaMCP，并把反复执行的多步骤流程整理为 Method。

                               ┌─ direct: GitHub / Codex Apps / core runtime
MCP client ────────────────────┤
                               └─ MetaMCP (3 tools)
                                    ├─ discover cached capabilities
                                    ├─ call one lazy child
                                    └─ run reviewed Methods

选择合适的路径

路径	最适用场景	原因
直接 MCP	高频、精简、安全敏感或基础服务	保留类型化架构、原生身份验证和显式审批
mcp_discover + mcp_call	长尾或不规则功能	在不隐藏组装语言的前提下，精简客户端界面
mcp_run	重复执行 Acquire → Normalize → Analyze 工作流	让有界行为可测试、可进行版本管理并能生成证据

不要仅为减少工具数量，就通过 MetaMCP 路由计费、基础设施变更、身份管理或其他后果严重的服务。正确的边界取决于实际运行需求，而非理念。

快速开始

需要 Node.js 20 或更高版本。

npx @mentu/metamcp@latest --config .mcp.json

在配置客户端之前，检查面向模型的完整界面：

npx @mentu/metamcp@latest tools
npx @mentu/metamcp@latest tools --json

检查器读取与 MCP tools/list 返回结果相同的定义，然后在加载配置、打开存储、启动子服务或绑定传输之前退出。--json 会包含完整的输入架构，便于自动化审核和版本间差异比较。

创建 .mcp.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/[email protected]", "/path/to/allowed/files"]
    },
    "internal-api": {
      "command": "node",
      "args": ["./servers/internal-api.js"],
      "env": { "API_TOKEN": "${INTERNAL_API_TOKEN}" },
      "inheritEnv": ["HTTP_PROXY"]
    }
  }
}

子服务只会在显式刷新、调用或由 Method 使用时启动。普通发现会读取配置和缓存的架构，不会启动所有子服务。

服务名称是稳定的缓存标识，必须包含 1-128 个字母、数字、点、下划线或连字符；不允许使用路径分隔符和类似路径遍历的名称。

安全配置客户端

除非提供 --yes，否则 init 仅预览，不会实际执行。未指定客户端名称时，它只会检查现有的客户端配置文件。

metamcp init                         # preview, no writes
metamcp init --client Codex          # preview one client
metamcp init --client Codex --yes    # apply atomically and write a .bak

格式错误的 JSON 会被拒绝并保持不变。可以显式创建指定客户端；MetaMCP 默认不会创建所有受支持的客户端配置。

手动配置客户端时，请使用绝对路径，避免网关依赖客户端的工作目录：

{
  "mcpServers": {
    "metamcp": {
      "command": "npx",
      "args": [
        "-y",
        "@mentu/metamcp@latest",
        "--config",
        "/absolute/path/to/.mcp.json"
      ]
    }
  }
}

@latest 适合用于评估。在受控环境中，请固定为 @mentu/[email protected]，以便有计划地升级并进行审核。

三个工具

发现

{ "query": "capture screenshot", "kind": "tool" }

发现只会搜索正在运行或已缓存的架构。如需从某个服务的实时工具列表刷新该服务：

{ "server": "browser", "refresh": true }

不指定服务的 refresh 会被拒绝，以免 Agent 意外地对整个配置进行扇出操作。

调用

{
  "server": "browser",
  "tool": "capture_page",
  "args": { "url": "https://example.com" },
  "timeoutMs": 60000
}

MetaMCP 绝不会在子调用超时或传输失败后自动重放该调用。响应丢失前，子服务可能已经完成了变更操作。之后的 Method 只有在清单明确将该步骤声明为 idempotency: "safe" 时才可以重试。

运行方法

将 JSON 清单放入 .metamcp/methods/，或传入 --methods <directory>。以下子服务和工具名称仅作示例；请在自己的配置中将它们绑定到经过审核的服务：

{
  "apiVersion": "metamcp.io/v1alpha1",
  "kind": "Method",
  "metadata": {
    "name": "content.acquire-and-normalize",
    "version": "1.0.0",
    "description": "Acquire content and normalize it into a stable record"
  },
  "spec": {
    "effects": "read",
    "inputSchema": {
      "type": "object",
      "properties": { "url": { "type": "string" } },
      "required": ["url"],
      "additionalProperties": false
    },
    "steps": [
      {
        "id": "acquire",
        "server": "fetch",
        "tool": "fetch",
        "args": { "url": "${input.url}" }
      },
      {
        "id": "normalize",
        "server": "content",
        "tool": "normalize",
        "dependsOn": ["acquire"],
        "args": { "document": "${steps.acquire.structuredContent}" }
      }
    ],
    "output": "${steps.normalize.structuredContent}"
  }
}

然后调用：

{ "method": "content.acquire-and-normalize", "input": { "url": "https://example.com" } }

方法采用声明式定义，而非任意 JavaScript。它们具有受限的步骤数、截止时间和输出大小；输入／输出 JSON Schema；明确的读／写效果；安全插值；带类型的间隙；以及逐步跟踪记录。除非网关操作员使用 --allow-writes 启动 MetaMCP，否则写入或混合效果的方法将被禁用。

请参阅方法模式、清单架构和示例方法。此设计将 Crawlio 方法模式中记录的一致性层推广应用。

配置和密钥

env 和 HTTP headers 中的 ${NAME} 引用默认从主机环境中解析。无法解析的引用会导致启动失败；不会将其作为字面占位符传递给子进程。

MetaMCP 不会将其环境变量传递给 stdio 子进程。它只继承少量运行时允许列表中的变量（PATH、主目录／临时目录／区域设置变量及平台对应变量）、inheritEnv 中指定的变量，以及子进程 env 块中明确设置的值。嵌入方可以为密钥链或保管库安装自定义 SecretProvider。

默认情况下，发现功能使用本地关键词搜索。若要启用基于 Voyage 的语义搜索，请显式设置 METAMCP_VOYAGE_API_KEY；随后，发现查询将发送到 Voyage，并启用可选的本地 SQLite 向量索引。环境中已有的 ANTHROPIC_API_KEY 或 VOYAGE_API_KEY 变量不会触发网络调用。

远程子服务使用 url、transportType、headers 和现有 OAuth 字段：

{
  "mcpServers": {
    "remote": {
      "url": "https://mcp.example.com/mcp",
      "transportType": "http",
      "headers": { "Authorization": "Bearer ${REMOTE_TOKEN}" }
    }
  }
}

HTTP 网关

HTTP 模式默认绑定到 127.0.0.1：

metamcp --transport http --port 8080 --config .mcp.json

未认证的非环回绑定会默认拒绝。公开监听器之前，请配置 OAuth 资源服务验证或 METAMCP_HTTP_BEARER_TOKEN。除非通过 --allow-origin 或 METAMCP_ALLOWED_ORIGINS 提供完全匹配的来源，否则带有 Origin 标头的浏览器请求将被拒绝。

MetaMCP 通过 stdio 和 Streamable HTTP 为传统 MCP 客户端以及 2026-07-28 无状态请求信封提供服务。有关支持的边界和部署指南，请参阅架构。

证据

已完成的 mcp_call 和 mcp_run 尝试会序列化到 .metamcp/ledger.jsonl。导出可移植的哈希链接包：

metamcp export-evidence \
  --ledger .metamcp/ledger.jsonl \
  --out .metamcp/evidence-bundle.json

metamcp export-evidence --out .metamcp/evidence-bundle.json --verify

运行日志不是远程证明系统。导出可检测包内之后发生的更改，但无法证明受入侵的主机记录了每个事件。

可选应用库

此软件包仍提供由人工操作的服务应用库：

metamcp add --list
metamcp add playwright sentry --config .mcp.json

运行时绝不会响应 MCP 工具调用而安装软件包。安装仍是明确的 CLI／用户操作。

应用库条目可以是本地启动器（command + args），也可以是托管的 Streamable HTTP 端点（url，在 --list 中显示为 🌐）。托管条目会作为原生远程服务写入 .mcp.json；应用库绝不会通过 stdio 桥接软件包路由远程服务。

从 0.x 升级

1.0 版有意移除了面向模型的配置、技能建议和 JavaScript 执行工具。此外，它还更改了 HTTP 绑定、子进程环境继承、重试机制和 init。升级前请阅读迁移到 1.0。

安全

子 MCP 服务是具有自身权限的可信本地或远程代码。MetaMCP 是策略和生命周期边界，并非用于隔离不可信软件包的操作系统沙箱。请检查命令，在适当情况下固定软件包版本，为每个子服务单独设置凭据，并确保危险的直连服务需要客户端人工审批。

请按照 SECURITY.md 中的说明私下报告漏洞。

开发

npm ci
npm run typecheck
npm test
./scripts/smoke-test.sh
npm run check:release
npm pack --dry-run

npm publish 会再次运行完整的 verify:release 检查。该检查会根据已构建的 CLI 确定公开工具的范围，并检查软件包、锁文件、更新日志和官方 MCP Registry 元数据中的版本是否一致。

采用 Apache-2.0 许可证。由 Mentu AI 维护。