context-proxy

mcp-lazy-proxy

通过延迟加载和架构缓存，将 MCP 工具架构的令牌开销降低 6–7 倍

有验证，不是空口宣称。 每个会话都会将证明日志写入 ~/.mcp-proxy-metrics.jsonl。 运行 mcp-lazy-proxy --report，查看实际节省量，而非营销估算。

⚠️ 安全提示：唯一的官方软件包是 npm 上由 kiraautonoma 发布的 mcp-lazy-proxy。我们不认可第三方分支或以其他作用域重新打包的版本，它们可能包含恶意代码。MCP 服务拥有广泛的系统访问权限——请始终从官方源安装。

问题

如果你使用多个 MCP 服务，每次 API 调用都会让工具定义占用数千个上下文窗口令牌——甚至在你提出问题之前就已如此。

使用 10 个服务 × 10 个工具 × 每个架构约 344 个令牌 = 每次调用开销 34,000 个令牌。 按每百万令牌 3 美元计（Claude Sonnet）：每次调用浪费 0.10 美元，每天调用 100 次时每月浪费 261 美元。

解决方案

这个代理位于 MCP 客户端和上游 MCP 服务之间。它不会预先发送完整的工具架构，而是：

1. 返回压缩的存根——仅包含工具名称和单行描述（每个约 54 个令牌）
2. 延迟加载完整架构——仅在实际调用工具时加载
3. 将架构缓存到磁盘——后续调用命中缓存，而非上游服务
4. 去重——跨服务的相同架构只存储一次

基准测试（真实数据）

服务数	工具数	预加载令牌数	延迟加载令牌数	降幅	每月节省*
1	10	3,555	550	6.5 倍	$27
3	30	11,140	1,620	6.9 倍	$86
5	60	20,607	3,224	6.4 倍	$156
10	100	34,360	5,350	6.4 倍	$261
10	200	71,583	10,790	6.6 倍	$547
15	225	81,460	12,115	6.7 倍	$624
20	200	71,997	10,760	6.7 倍	$551

*按每百万输入令牌 3 美元、每天调用 100 次 API 计算

快速开始

npm install -g mcp-lazy-proxy

封装单个 MCP 服务

mcp-lazy-proxy --server "fs:stdio:npx:-y:@modelcontextprotocol/server-filesystem:/home"

通过配置封装多个服务

{
  "servers": [
    {
      "id": "filesystem",
      "name": "Filesystem MCP",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home"]
    },
    {
      "id": "github",
      "name": "GitHub MCP",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  ],
  "mode": "lazy"
}

mcp-lazy-proxy --config proxy.json

与 Claude Desktop 搭配使用

{
  "mcpServers": {
    "proxy": {
      "command": "mcp-lazy-proxy",
      "args": ["--config", "/path/to/proxy.json"]
    }
  }
}

模式

模式	描述	令牌节省
lazy	首次使用工具时加载架构（默认）	~85%
stub-only	从不发送完整架构（节省最多）	~85%
eager	预先加载所有架构（不节省，仅用于调试）	0%

端到端测试结果

针对官方 @modelcontextprotocol/server-filesystem（14 个工具）进行测试：

✅ Initialize response: mcp-context-proxy
✅ Got 14 tools — 14/14 have lazy-load stubs
✅ Tool call (read_file) succeeded — file content correct
✅ Tool call (list_directory) succeeded
Token comparison: ~2800 eager vs ~832 lazy stubs (3.4x on this small server)

使用 10 个以上服务时，随着架构复杂度增加，比例会提高到 6–7 倍。

API（编程使用）

import { MCPContextProxy } from 'mcp-lazy-proxy';

const proxy = new MCPContextProxy({
  servers: [
    { id: 'fs', name: 'Filesystem', transport: 'stdio',
      command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'] }
  ],
  mode: 'lazy'
});

await proxy.start();

可验证的节省证明

与其他只展示估算值的 MCP 优化器不同，mcp-lazy-proxy 会记录每次交互：

# See your actual savings (not estimates)
mcp-lazy-proxy --report

原始证明位于 ~/.mcp-proxy-metrics.jsonl——每次工具调用对应一行 JSON，可全面审计。

对比

功能	mcp-lazy-proxy	Atlassian mcp-compressor
语言	Node.js/npm	Python/pip
机制	调用时延迟加载	压缩描述
架构缓存	✅ 磁盘（24 小时 TTL）	❌
证明日志	✅ 可审计的 JSONL	❌
响应压缩	✅ JSON 摘要 + 文本截断	❌
托管选项	🔜 计划中	❌

响应压缩（v0.2）

大型工具调用响应会在到达大模型前自动压缩：

• JSON 响应：生成摘要——数组截断为前 3 项并注明数量，长字符串缩短，保留完整结构
• 纯文本：截断至 10,000 个字符，并附上 [truncated, X chars total] 提示
• 错误响应：从不压缩（大模型需要完整的错误上下文）
• 可配置：在配置中设置 responseCompression: false 以禁用，或微调阈值

{
  "servers": [...],
  "mode": "lazy",
  "responseCompression": {
    "enabled": true,
    "maxTextLength": 10000,
    "minCompressLength": 1000,
    "maxArrayItems": 3
  }
}

状态

• 核心延迟加载代理（v0.1）
• 架构持久化缓存（24h TTL）
• 可验证的会话级节省量证明
• 用于审计节省量的 --report CLI
• 已使用真实 MCP 服务完成端到端测试
• 响应压缩（v0.2）
• HTTP/SSE 传输支持
• 架构变更检测（webhook）
• 托管式 SaaS 选项

许可证

MIT — 由自主 AI Agent Kira 构建。