Skip to main content
Glama

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

按关键字搜索完整的上游目录(名称 + 描述,子串匹配,最多 10 条结果)。返回 name — one-line description 行。

describe

按小写名称返回某个工具的完整原始 schema 和文档。在调用不熟悉的工具之前先使用。

call

按名称调用任意上游工具,并传入 args 对象,包括不在 used 中的工具。

典型的智能体流程: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——仅支持工具。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A stdio MCP proxy that connects to one or more upstream MCP servers and exposes their tools, resources, and prompts through a single endpoint with a configurable middleware pipeline.
      14
      186 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A lightweight MCP gateway that aggregates multiple MCP services into a unified stdio interface, automatically prefixing tool names with the service name to avoid conflicts.
      13 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Serves any OpenAPI 3.x/Swagger 2.x API as a local MCP server over stdio, converting every operation into a tool that proxies requests to the upstream API with configurable headers and fixed parameters.
      6 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A deterministic MCP tool-list relay that lets operators filter tools by include/exclude rules and exposes a filtered stdio MCP server to local clients.
      10 npm
      MIT