jmunch-mcp

jmunch-mcp

适用于几乎所有其他 MCP 服务的透明 MCP 代理，可降低大型上游工具响应的 Token 成本。它封装单个上游 MCP、转发每次调用，并将庞大的载荷转换为内容感知后端，供 Agent 使用一组通用动词（peek、slice、search、aggregate、describe、list_handles）查询。

基准测试

针对两个热门的真实 MCP 服务进行端到端测量。每次运行都会执行一组固定的工具调用两次——一次直接调用，一次通过 jmunch-mcp 调用；在代理调用侧，还会执行三次后续 jmunch.* 动词调用，以模拟 Agent 深入查询大型结果，而不是将其全部读入。

套件	上游	直接调用 Token 数	通过 jmunch-mcp	节省
GitHub（facebook/react issues/PR/commits）	@modelcontextprotocol/server-github	379,878	44,328	335,550（88.3%）
Firecrawl（Wikipedia 抓取 + 站点地图 + 搜索）	firecrawl-mcp	259,574	2,928	256,646（98.9%）

尽管增加了额外的动词调用，在这两个测试套件中，使用代理的实际耗时也更短——Agent 无需逐页读取庞大的载荷：

套件	直接调用	通过 jmunch-mcp	差值
GitHub	8.4s	6.8s	−1.6s（−19.0%）
Firecrawl	16.4s	9.2s	−7.2s（−43.9%）

表格内容（GitHub）会路由到 SQLite 后端，并支持 peek/slice/aggregate；JSON 内容（Firecrawl 抓取结果/站点地图）会路由到 JSON 树后端，并支持 peek/slice（JSONPath）/search。请参阅 bench/README.md 了解复现方法。

安装

pip install jmunch-mcp

从源码安装：

git clone https://github.com/jgravelle/jmunch-mcp
cd jmunch-mcp
pip install -e .

快速开始

jmunch-mcp init

init 会扫描三个来源——你的 MCP 客户端配置（Claude Desktop、Claude Code、Cursor、Windsurf、Continue）、正在运行的进程，以及包含热门上游服务（GitHub、Firecrawl、filesystem、fetch、Brave Search、Slack）的小型目录——然后生成一份清单。勾选要封装的上游服务后，它会将每项选择分别写入一个 ./configs/ 下的 <name>.toml 文件。非交互式选项：--yes（选择客户端中已注册的所有服务）、--dry-run、--overwrite、--out <dir>、--no-running、--no-catalog。

手动配置

jmunch-mcp --config examples/config.toml

配置 MCP 客户端，使其启动 jmunch-mcp --config <path>，而不是直接启动上游服务。添加 --report 可在关闭时打印会话摘要。

网关模式（v2 — 通用代理）

上面的 MCP 代理可为 MCP 客户端节省 Token。网关则可为任何使用 OpenAI 或 Anthropic HTTP API 的 AI 应用节省 Token——包括 LangChain、LlamaIndex、CrewAI、AutoGen、Continue、Cline、Aider 或原始 SDK。应用无需修改代码，只需将 base_url 指向 jmunch。

pip install 'jmunch-mcp[gateway]'
jmunch-mcp gateway --config configs/gateway.example.toml
# listening on http://127.0.0.1:7879

配置应用：

# OpenAI SDK, LangChain, Aider, Continue, Cline, Ollama-compat apps:
export OPENAI_API_BASE=http://127.0.0.1:7879/v1

# Native Anthropic SDK / Claude Code:
export ANTHROPIC_BASE_URL=http://127.0.0.1:7879

它会透明地执行以下操作：

• 将庞大的 tool_results 转换为句柄：应用的工具返回 100KB 的 JSON，模型看到的则是 1KB 摘要和不透明句柄。
• 将 jmunch 动词（peek、slice、search、aggregate、describe、summarize、list_handles）注入请求的 tools 数组，让模型可以深入查询。
• 在本地处理动词调用：当模型调用 jmunch_peek 时，网关会根据句柄注册表在本地解析，并合成后续轮次。应用不会看到 jmunch tool_calls；这些调用的完成过程不会消耗上游 Token。
• 持久化句柄至 ~/.jmunch/handles.db，并支持配置 TTL，以便在重启后保留句柄并跨会话读取。
• 双向流式传输：OpenAI SSE 和 Anthropic 事件流会先缓冲再重放，并正确解析动词调用。

可通过请求头控制每次请求：

• X-Jmunch-Upstream: <name> — 覆盖已配置的上游服务。
• X-Jmunch-Inject: false — 禁用本次调用的工具注入（仅透传 + 在请求侧转换句柄）。

指标会汇入与 MCP 代理相同的仪表板。在 /api/stats 和 /api/calls 上使用 ?surface=gateway 或 ?surface=mcp 进行筛选。

仪表板

一个只读的本地 Web UI，展示各代理写入的指标数据库内容。显示累计总量、按上游服务划分的明细，以及转发调用的时间序列。

jmunch-mcp dashboard              # http://127.0.0.1:7878
jmunch-mcp dashboard --open       # also open in your default browser

标志：--port（默认值为 7878）、--host（默认值为 127.0.0.1）、--db <path>（用于指定非默认指标数据库），以及 --open（用于启动浏览器）。只有在代理记录了调用后，指标才会显示，因此请先通过封装后的上游服务运行客户端。

许可证

jmunch-mcp 基于 MIT 许可证 发布，可免费用于使用、修改、分发，并嵌入商业产品。

请注意，你通过 jmunch-mcp 代理的上游 MCP 服务的许可由这些服务各自的条款约束。这适用于第三方 MCP 服务（GitHub、文件系统提供商、供应商 API），也适用于你可能会组合使用的更广泛检索生态中的任何同类工具——重新分发前，请检查各上游服务的许可证。