Mcp Broker

mcp-broker

mcp-broker 是一个供 MCP 客户端使用的本地模型上下文协议进程代理。

可以把它看作面向 MCP 的 PgBouncer：在众多上游 MCP 服务前提供一个稳定的本地端点。代理负责上游服务的启动、复用、清理、配置文件暴露、状态管理和安全工具路由。

核心理念很简单：不要让每个 Agent 会话都在用户提出任务之前加载所有上游工具定义。

为什么需要它

使用多个 MCP 服务的 AI 编码会话往往会遇到同样的问题：

• 每个客户端配置都要重复列出同一组 MCP 服务
• 每个新会话都可能启动重复的上游进程
• OAuth、浏览器状态、本地文件和数据库句柄分散在各个工具中
• 原始工具列表会在任务开始前占用上下文
• 托管连接器缓存可能会重复包含本地 MCP 工具
• 客户端会话退出后，孤立的 MCP 进程仍会继续运行

mcp-broker 在这些上游服务前提供一个精简的代理门面。它不是托管工作流构建器，而是一种本地基础设施，可让 MCP 客户端保持精简、行为可预测，并遵循统一的配置约定。

Client profile
        |
        | one local MCP entry
        v
  mcp-broker-client
        |
        | Unix socket
        v
  mcp-broker-daemon
        |
        | profile gates, namespace routing, status, cleanup
        v
  upstream MCP servers

客户端会看到一组精简的代理工具：

broker_search_tools
broker_describe_tool
broker_call_tool
broker_status
broker_close_session

上游 MCP 服务仍然存在。任务需要时，代理会发现并调用它们。

已测量的上下文缩减

在 2026-05-24，测量显示，Codex 配置从大量原始 MCP 和托管应用工具定义，缩减为一个代理门面，以及经过精简的 codex_apps 缓存。

范围	之前	之后	缩减比例
直接配置的 Codex MCP 服务条目	11	1	90.91%
MCP 工具定义	414	4	99.03%
托管的 codex_apps 工具定义	195	39	80.00%
始终加载的工具定义总数	609	43	92.94%
序列化工具载荷总字节数	1,026,171	185,877	81.89%
o200k_base 工具令牌总数	276,989	45,281	83.65%

92.94% 表示工具定义数量的缩减比例。83.65% 表示使用 tiktoken 的 o200k_base 测量规范序列化工具载荷后得到的令牌缩减比例。

证据和注意事项请参阅 docs/context-reduction-measurement.md。

功能

• 通过 Unix 套接字运行一个本地代理守护进程。
• 向 MCP 客户端提供一个轻量级 stdio 客户端垫片。
• 按需启动上游 MCP 服务。
• 根据配置，在不同会话之间复用共享上游服务。
• 当状态不得共享时，隔离每个会话的上游服务。
• 将上游工具映射到稳定的命名空间。
• 提供精简的搜索、描述、调用、状态和绑定调用方的会话关闭工具。
• 强制执行配置文件级工具预算和暴露门控。
• 除非配置文件允许列表授权，否则禁止暴露会更改数据的上游工具。
• 将运行时状态存储在仓库之外的 $HOME/mcp/mcp-broker 下。
• 支持以试运行、备份和回滚方式生成 MCP 客户端配置条目。
• 为 macOS 提供 LaunchAgent 安装和卸载流程。
• 为 Linux systemd 用户服务提供生成、安装、卸载和移除流程。
• 为 Windows PowerShell 计划任务提供生成、安装和移除流程。
• 通过 Makefile 目标提供单元、旅程、实时和端到端测试。

核心差异化特点：

• 按配置文件限定暴露范围：每个 MCP 客户端都能看到经过配置的上游服务视图，而不是默认看到所有工具。
• 更改类工具门控：只有获得配置文件允许列表授权后，才会显示会更改数据的上游工具。
• 生命周期管理：代理负责启动、监控、停止和回收共享及会话专属的上游服务。
• 客户端一致性检查：应用配置前，可通过同一个精简代理门面验证生成的配置文件。

适用对象

如果你：

• 使用 Codex、Claude Code、AGY CLI 或其他 MCP 客户端
• 拥有的 MCP 工具多到不想在每个会话中都加载
• 需要共享本地 MCP 服务，避免重复启动进程
• 希望集中管理 OAuth 状态、浏览器状态、套接字、日志和清理
• 需要按客户端配置不同的配置文件，而不是让所有客户端使用相同的工具列表
• 希望使用精简的 Broker 门面，而不是原始的上游工具清单

那么可以使用 mcp-broker。

此仓库不是企业级 MCP 控制平面，而是面向开发者 Agent 工作流的本地桌面基础设施。

当前状态

已实现：

• 从 config/broker.example.yaml 创建的 config/broker.private.yaml 加载 YAML 配置。
• 对运行时、客户端、配置文件、上游服务和策略块进行严格的 YAML 契约验证。
• 通过 config/broker.schema.json 进行公开 JSON Schema 验证。
• 从 runtime.root 推导运行时路径。
• 根据已配置的上游前缀映射工具命名空间。
• 管理本地上游子进程生命周期，并清理进程组。
• 通过 Unix 套接字运行 Broker 守护进程。
• 为已配置的 MCP 客户端配置文件提供 MCP 客户端 shim 和渲染器，包括 Codex、Claude 和 AGY。
• 将 AGY 配置文件渲染到 .gemini/config/mcp_config.json，包括其 MCP 允许服务策略。
• 提供客户端配置渲染的试运行、应用时备份和回滚。
• 提供默认采用试运行模式的 LaunchAgent 渲染和安装脚本。
• 提供精简的 Broker 门面，支持搜索、描述、调用、状态查询和与调用方绑定的会话关闭。
• 通过 YAML 冒烟探测验证配置文件。
• 检查精简客户端配置文件之间的发现结果一致性。
• 通过 Makefile 目标提供面向公开用户和维护者的质量门禁。
• 通过 P3.8 E2E 验证共享运行时保护措施契约，同时默认禁用托管执行。

接入状态：

• Codex 已通过 Broker 接入。
• Claude 在通过配置文件验证并手动确认 /mcp 后，已通过 Broker 接入。
• AGY 已通过渲染 .gemini/config/mcp_config.json 的方式接入 Broker。

公开发布状态：

• 此仓库的设计目标是始终适合公开发布。
• 私有上游清单、账户路径、OAuth 状态、密钥、套接字、日志和生成的客户端配置均保留在 git 仓库之外。
• 稳定版发布元数据通过 make release-version-check 验证；发布验证情况记录在 docs/distribution.md 中。
• 支持适用于容器环境的 Docker 镜像配置。向 Docker MCP Catalog 提交仍需经过 Docker 审核。
• mcpb/manifest.json 中包含 MCPB 元数据，可供本地目录审核。

有关面向公众的发布工作，请参阅 ROADMAP.md。

架构

mcp-broker 包含三个运行时层：

层	职责
客户端 shim	向每个 MCP 客户端提供一个 stdio MCP 服务入口，并通过 Broker 套接字转发 JSON-RPC。
Broker 守护进程	管理配置文件门控、命名空间路由、上游生命周期、状态、日志和清理。
上游 MCP 服务	按配置作为 stdio、HTTP、streamable HTTP 或 SSE 连接器运行，并采用共享或按会话设置的进程策略。

配置文件是契约。配置文件决定暴露哪些内容，上游服务定义传输方式和生命周期行为，冒烟探测则定义用于验证的安全读取调用。

对比

方案	最适用场景	权衡
原始 MCP 客户端配置	仅有少量工具的小型配置。	每个会话都会加载完整工具列表，且每个客户端都要重复配置。
简易 MCP 代理	将一个服务转发给一个客户端。	不负责上游生命周期、配置文件预算或跨客户端清理。
托管应用连接器	由客户端提供商管理的 SaaS 工具。	本地 MCP 状态和跨客户端一致性仍不受用户控制。
mcp-broker	在多个 MCP 客户端中使用许多上游 MCP 服务的本地开发者。	需要安装和监控本地守护进程及配置契约。

截图或 GIF

快速入门流程应如下所示：

make config-init
make config-validate
make broker-status
make codex-facade-smoke

在 MCP 客户端中，/mcp 应显示一个 mcp-broker 条目。使用 broker_status 检查配置文件可见的上游状态。

快速入门

先决条件：

• macOS，使用 LaunchAgent 时需具备 launchctl。
• 可通过 python3 使用 Python 3.10 或更高版本。
• make。
• 使用基于 npm 的上游 MCP 服务时需具备 Node.js 和 npx。
• 本仓库的克隆副本。

安装软件包：

pipx install mcp-broker
uv tool install mcp-broker
brew tap ${HOMEBREW_TAP_REF}
brew install mcp-broker

Homebrew 安装的控制台脚本与 Python 软件包相同。软件包安装不会写入 MCP 客户端配置；客户端接入仍需显式执行 Makefile 操作。

Docker 适用于容器友好型配置：

docker build -t mcp-broker:local .
docker run --rm -i mcp-broker:local

本地 stdio 客户端和 MCPB 风格的安装使用由软件包管理的生命周期：

mcp-broker stdio --init-if-missing

创建本地虚拟环境、安装依赖项并验证运行时布局：

make setup

根据公开模板创建私有配置：

make config-init

config-init 会在需要时创建目标目录，并复制公开模板作为起点。它不会导入本地 MCP 清单、用户路径或密钥。

编辑 config/broker.private.yaml 配置本地上游。请勿将密钥值放入配置中。请使用环境变量名称或以下目录中的文件：

$HOME/mcp/mcp-broker/secrets/

运行质量检查：

make quality-gate

验证配置的 YAML 契约：

make config-validate

启动代理：

make broker-start

检查状态：

make broker-status

完整安装流程请参阅 docs/install.md。 从克隆仓库到运行的接入流程请参阅 docs/adoption-guide.md#clone-to-running-path。 共享运行时边界请参阅 docs/shared-runtime-guardrails.md。 P3.8 E2E 验证涵盖租户隔离、授权拒绝、配额拒绝、会话亲和性、审计事件、回滚、降级模式、仅本地路由以及符合共享条件的路由。公共本地代理仍不支持托管执行。

运行时布局

默认运行时根目录：

$HOME/mcp/mcp-broker/
|- backups/
|- logs/
|- renders/
|- run/
|- secrets/
|- sockets/
`- state/
   `- upstreams/

运行时文件不是仓库文件。上游 OAuth 状态、浏览器状态、密钥文件、套接字、日志、渲染后的客户端配置、备份和守护进程状态均应放在运行时根目录下。

请参阅 docs/runtime-layout.md。

客户端接入

备份客户端配置：

make config-backup CLIENT=codex

试运行渲染：

make config-render CLIENT=codex CONFIG_RENDER_APPLY=0

查看 $HOME/mcp/mcp-broker/renders/ 下渲染的文件后再应用：

make config-render CLIENT=codex CONFIG_RENDER_APPLY=1

回滚：

make config-rollback CLIENT=codex

在该配置文件的冒烟测试通过，且确定该客户端应使用代理后，再使用 CLIENT=claude 或 CLIENT=agy。对于新的基于 JSON 的 MCP 客户端，可生成一个起始配置块：

make profile-snippet NEW_PROFILE=local-client NEW_CLIENT_FORMAT=mcp-settings-json

完整的新配置文件流程请参阅 docs/add-profile.md。

精简代理门面

精简门面让面向聊天的配置文件保持简洁：

工具	用途
broker_search_tools	按查询搜索已配置的上游工具。结果包含名称、说明、上游、用途、标签和是否会修改数据的标记；省略较大的 inputSchema，并按需通过 broker_describe_tool 获取。
broker_describe_tool	返回一个上游工具的架构和元数据。
broker_call_tool	通过代理路由调用一个上游工具。可选接受 projection（{"paths": [...], "max_array_items": N}），在响应到达客户端之前由服务端对其进行裁剪。
broker_status	显示配置文件可见的上游状态、被动身份验证探测结果和最后的错误，不会启动工具。
broker_close_session	释放调用方拥有的、按会话划分的上游进程，不会停止共享上游或其他客户端会话。

Codex /mcp 按设计只显示一个 mcp-broker 条目。各上游的可见性、状态和套接字路径由 broker_status 提供。

配置文件与安全

配置文件决定客户端可以查看和调用哪些上游服务。

支持的概念：

• max_tools 可避免客户端面对过多工具。
• compact_tools_enabled 会公开代理门面工具，而非原始上游工具。
• broker_tool_name_style 会调整代理门面工具的名称，以适配无法显示带点号工具名称的客户端。
• result_size_chars 会在 broker_call_tool 上声明 anthropic/maxResultSizeChars（最多 500000），让 Claude Code 将更大的结果保留为内联内容。
• result_budget_chars 会在每个转发的 tools/call 的 _meta 中发送 mcp-broker/result_budget_chars，让上游服务能够根据客户端调整答案大小。参见 docs/add-profile.md。
• mcp_allowed_servers 会为需要显式服务器允许列表的 MCP 客户端生成客户端设置。
• 公开可变更的上游服务前，必须设置 allow_mutating_upstreams。
• shared 模式会复用一个上游进程，适用于可以共享账号状态的情况。
• per_session 模式会隔离每个客户端会话的上游状态。
• per_call 模式会为每次工具调用或工具列表操作启动一个新的 stdio 进程，并在返回前停止该进程。
• disabled 模式会保留兼容性记录，但不公开上游服务。

状态报告会显示正在进行的 per_call 操作的 active_call_count，包括工具发现操作。操作成功、失败或超时清理后，该计数会归零。此计数独立于 session_count，也不代表已保存会话的数量。读取状态不会启动上游服务；配置文件中隐藏的上游服务仍保持隐藏。

OAuth、浏览器状态、文件系统根目录和数据库等受保护的接口需要显式配置和验证。公开示例会保持禁用状态或使用占位符。

参见 docs/security-review.md 和 docs/upstream-compatibility-matrix.md。 如需更深入的安全检查清单，请参见 docs/safety.md。

配置约定

公开模板为 config/broker.example.yaml。 对应的 JSON Schema 为 config/broker.schema.json。

支持的顶层部分：

schema_version: 1
runtime: {}
broker: {}
profiles: {}
clients: {}
upstreams: {}

加载器会拒绝未知键。上游命令、参数、工作目录和环境变量文件路径中可以使用 {runtime.root}、{runtime.state_dir} 和 {runtime.secrets_dir} 等运行时占位符。

make config-validate 会先根据公开 JSON Schema 检查所选的 CONFIG_PATH，然后运行运行时加载器，使语义规则通过代理使用的同一代码路径得到强制执行。

向配置文件公开的每个已启用上游服务都应定义一个安全的冒烟测试探针：

smoke:
  query: read example graph
  tool: example-store.read_graph
  arguments: {}
  call: true

make profile-validation PROFILE=<profile> 会通过 broker_status、broker_search_tools、broker_describe_tool 和已配置的安全 broker_call_tool，验证该配置文件可见的每个已启用上游服务。

Codex 操作员验收

仓库自带的测试通过本地客户端 shim 验证代理行为。最后一项 Codex 专项检查必须在活跃的 Codex 会话中运行，因为延迟加载的 MCP 包装器工具 只有在那里才会提供。

根据 YAML 生成当前的验收步骤：

make codex-deferred-acceptance

此目标会读取已配置的 smoke 探针，并打印用于搜索、描述和安全调用的准确 mcp__mcp_broker__ 包装器调用。它不会调用 Codex，不会调用外部 LLM 会话，也不属于 make quality-gate。

参见 docs/codex-deferred-tool-acceptance.md。

LaunchAgent

渲染但不写入：

make launchagent-install

应用并加载：

make launchagent-install LAUNCHAGENT_APPLY=1
make launchagent-load
make broker-status

卸载或移除：

make launchagent-unload
make launchagent-uninstall LAUNCHAGENT_APPLY=1

systemd

Linux 用户服务安装使用相同的运行时根目录和配置路径约定：

make systemd-install
make systemd-install SYSTEMD_APPLY=1
make systemd-load

对于通过软件包安装的情况，请先将 MCP_BROKER_DAEMON_COMMAND 设置为已安装的守护进程 路径，再应用服务。

Windows

Windows 启动通过 PowerShell 计划任务命令实现，并遵循相同的运行时根目录和配置路径约定：

make windows-install
make windows-install WINDOWS_APPLY=1
make windows-load

使用以下命令移除：

make windows-unload
make windows-uninstall WINDOWS_APPLY=1

测试与发布门禁

运行所有级别的测试：

make test

运行公开质量门禁：

make quality-gate

覆盖率门禁针对 Python 源码检查行覆盖率和分支覆盖率。

准备标签时运行发布门禁：

make release-gate

release-gate 会运行打包、冒烟和变异测试检查。变异测试会根据 LOCAL_CPU_BUDGET 和 RELEASE_GATE_JOBS 计算适用于发布的子进程数量，因此在其他发布子进程运行时不会占用全部 CPU 预算。变异测试最后运行公开单元测试和流程测试，并将总数、得分以及按排名排列的 blocked_by_file 条目写入 var/quality/mutation_stats.json。在 macOS 上，发布门禁会在 Linux 容器中运行变异测试，以避免本地 mutmut 分叉失败。E2E 测试仍包含在 make quality-gate 中。

运行冒烟测试和运行时清理检查：

make config-validate
make broker-smoke
make broker-stop
make broker-reap
make doctor
make release-smoke

发布或应用客户端配置前，应等待以下检查完成：

• make quality-gate
• make config-validate
• make broker-smoke
• 为每个目标客户端进行配置渲染试运行
• 回滚测试
• make release-smoke
• 打标签前运行 make release-gate
• 运行 make doctor，确保没有遗留的 Broker 管理资源

请参阅 docs/release-checklist.md。

公开命令

这些目标使用本仓库以及声明的 Python 和 Node 前置条件：

对于源码贡献，请在 PATH 中安装 gitleaks，并在每个检出目录中运行 make hooks-install。受版本控制的 pre-commit hook 要求先对暂存内容进行脱敏后的密钥扫描，然后通过 Make 运行受影响的提交级测试。缺少扫描工具、暂存范围为空，以及扫描或测试失败，都会阻止提交。GITLEAKS 和 PYTHON 用于指定扫描器和维护者使用的解释器。安装时会使用 Git 的 worktree 专属配置，并拒绝处理需要迁移的未知现有 hook，或常见的 core.worktree/裸仓库设置。不会启动托管工作流。

make setup
make config-init
make test
make test-unit
make test-journey
make test-live
make test-e2e
make test-cov
make precommit
make quality-gate
make release-gate
make config-validate
make broker-smoke
make broker-start
make broker-status
make broker-stop
make broker-reap
make doctor
make config-backup
make codex-app-policy
make config-render
make config-rollback
make tools-count
make facade-smoke
make codex-facade-smoke
make claude-facade-smoke
make agy-facade-smoke
make profile-validation
make codex-profile-validation
make claude-profile-validation
make agy-profile-validation
make discovery-parity
make codex-claude-discovery-parity
make codex-deferred-acceptance
make launchagent-install
make launchagent-load
make launchagent-unload
make launchagent-uninstall
make systemd-install
make systemd-load
make systemd-unload
make systemd-uninstall
make windows-install
make windows-load
make windows-unload
make windows-uninstall
make linux-container-smoke
make windows-powershell-smoke
make release-smoke
make mutation
make mutation-linux

make quality-gate 仅在本仓库内运行，不会调用仓库外的个人脚本。

make codex-deferred-acceptance 仅供维护者使用。它不会调用 Codex 或外部 LLM 会话，而是读取相同的 YAML smoke 探测项，并打印可在活动 Codex 会话中运行的确切 mcp__mcp_broker__ 延迟封装调用。请参阅 docs/codex-deferred-tool-acceptance.md。

项目目录结构

mcp-broker/
|- .gitignore
|- Makefile
|- README.md
|- pyproject.toml
|- requirements.txt
|- config/
|  |- broker.example.yaml
|  |- broker.private.yaml        # local, ignored by git
|  `- broker.schema.json
|- docs/
|- registry/
|- scripts/
|  `- check_mutation_stats.py
|- src/
|  `- mcp_broker/
|- tests/
|  |- unit/
|  |- journey/
|  |- live/
|  |- e2e/
|  `- support/
`- var/                         # tracked skeleton; generated contents ignored

生成的报告保存在 var/ 下，尤其是 var/coverage/、var/test-logs/ 和 var/quality/。

文档

• SECURITY.md
• CONTRIBUTING.md
• ROADMAP.md
• docs/install.md
• docs/add-profile.md
• docs/migration.md
• docs/adoption-guide.md
• docs/comparison.md
• docs/distribution.md
• docs/github-publication.md
• docs/community-launch.md
• docs/auth-recipes.md
• docs/architecture.md
• docs/protocol.md
• docs/runtime-layout.md
• docs/safety.md
• docs/security-review.md
• docs/upstream-compatibility-matrix.md
• docs/codex-deferred-tool-acceptance.md
• docs/context-reduction-measurement.md
• docs/mutation-testing.md
• docs/release-checklist.md
• docs/troubleshooting.md

设计规则

• 将上游定义保存在中央配置中。
• 将运行时状态保存在 $HOME/mcp/mcp-broker 下。
• 将私有上游清单保存在 config/broker.private.yaml 中，该文件已被 git 忽略。
• 不要在配置和源代码中保存机密值。
• 不要在源代码、测试、文档或公开配置中硬编码个人路径。
• 通过 Makefile 执行构建、测试、运行时和配置操作。