mcp-facade

一个通用的 MCP 门面（facade）：一个 stdio 进程位于上游 MCP 服务器之前，只暴露其工具的一个已配置子集——使用压缩后的 schema——外加三个元工具（discover、describe、call），让目录的其余部分按需可访问。

为什么

每个 MCP 服务器暴露的工具都会以 JSON schema 的形式注入模型上下文，并且在每次请求上都是如此。一个拥有 40 个工具的臃肿服务器，在开始任何工作之前就可能让会话花费数万 token——其中大部分是你从未调用过的工具。

门面扭转了这种成本结构：你只为实际使用的工具（在 used 中列出）支付完整的 schema token，而且这些 schema 被压缩到最核心的部分。其余所有工具仍然可以通过元工具发现，元工具总共只需要三个很小的 schema。

Related MCP server: @zhangzwd/mcp-gateway

功能

• 作为 stdio MCP 服务器运行：bun run facade.ts --server <name>。每个上游服务器对应一个进程。

• 读取 facade.servers.json（位于 facade.ts 旁）并选取 <name> 条目。

• 在第一次 tools/list 时获取上游目录并缓存到磁盘（~/.omp/agent/mcp-facade/catalogs/<name>.json，7 天 TTL）。上游连接是惰性的——首次使用前不会建立连接。

• 以下列方式提供 used 中每个工具的压缩 schema：

  • 每个 description 字符串（工具级以及 JSON schema 内部）被截断到第一句，最多 140 个字符；

  • $comment、examples 和 default 键会被递归删除；

  • 结构（类型、属性、required、enums）保持不变；

  • 工具名转换为小写；查找时不区分大小写。

• 总是附加这三个元工具（见下文）。

• 如果在 tools/list 时无法获取目录，则降级为仅提供元工具，并将原因记录到 stderr。

• 将调用转发给上游。对于带有 credentialId 的 HTTP 上游，401/未授权/令牌过期错误会触发一次令牌强制刷新和一次重试。

元工具

典型的智能体流程：discover "worklog" → describe addworklog → call { tool: "addworklog", args: { ... } }。

要求

• Bun（门面直接运行 TypeScript）。

• 对于受 OAuth 保护的 HTTP 上游：已在 ~/.bun/bin/omp 安装 OMP omp CLI，且凭证已完成授权。门面通过 omp token <credentialId> 获取令牌（并在重试时使用 omp token --force-refresh <credentialId>）。机密信息从不存储在配置中。

• 对于需要环境变量（API 密钥、令牌）的 stdio 上游：在 ~/.claude.json 中需有一个现有的 Claude 主机配置，其中包含该服务器的 env 块（见下面的 envFrom）。

安装

bun install
cp facade.servers.example.json facade.servers.json   # then edit

facade.servers.json 被 gitignore 忽略——它可能包含本地路径。

配置

facade.servers.json 将服务器名称映射到其上游和已用工具列表：

{
  "<name>": {
    "upstream": {
      // HTTP upstream (Streamable HTTP transport):
      "url": "https://mcp.example.com/v1/mcp",
      "credentialId": "mcp_oauth:profile:default:https://mcp.example.com/v1/mcp" // optional

      // …or stdio upstream:
      // "command": "/usr/local/bin/npx",
      // "args": ["-y", "@example/mcp-server"],
      // "envFrom": "claude:<server-name>",  // optional: pull env from ~/.claude.json mcpServers.<server-name>.env
      // "env": { "EXTRA": "value" }          // optional: merged on top
    },
    "used": ["tool_one", "tool_two"]  // exposed directly; everything else via meta-tools
  }
}

注意：

• used 条目不区分大小写匹配，并且以小写形式提供服务。

• envFrom 目前仅支持 claude:<name> 前缀。

• 空的 used 列表有效：此时门面只暴露元工具。

注册到主机

将主机和 MCP 配置指向门面，每个上游一个条目：

{
  "mcpServers": {
    "acme": {
      "command": "/path/to/bun",
      "args": ["run", "/path/to/mcp-facade/facade.ts", "--server", "acme-http"]
    }
  }
}

⚠️ stdout 是协议

stdio 传输占用 stdout。绝不将日志、诊断或调试输出写入 stdout——stdout 上的任何输出都会破坏 JSON-RPC 流并卡死主机。门面只向 stderr（console.error）记录日志；任何分支中都要保持这一点。

局限性

• 硬编码路径：目录缓存位于 ~/.omp/agent/mcp-facade/catalogs/，OMP 二进制文件位于 ~/.bun/bin/omp，envFrom 只读取 ~/.claude.json。

• 目录用一次 listTools F 调用获取——没有分页，也不处理 tools/list_changed。重启门面（或等待 7 天 TTL 过期）以获取上游工具变更。

• discover 是简单的子串匹配，最多返回 10 个结果。

• 认证失败时只重试一次；其他上游错误原样传播。

• 不支持上游的 prompts、resources 或 sampling——仅支持工具。