Lazy MCP Preload

mcp代理

](https://github.com/IAMSamuelRodda/mcp-proxy/releases) 

聚合MCP代理，可将上下文窗口使用率降低约95%，同时提供零延迟工具执行。

运作原理

mcp代理没有将所有工具直接暴露给Claude（消耗约15000多个令牌），而是只暴露了2个元工具：

1. get_tools_in_category -浏览可用工具的层次树
2. execute_tool -按路径执行任何工具

这种渐进式披露模式将上下文减少到约800个令牌，同时保持对所有工具的完全访问。

特性

快速开始

# 1. Clone
git clone https://github.com/IAMSamuelRodda/mcp-proxy.git
cd mcp-proxy

# 2. Create your config
cp config/config.template.json config/config.local.json

# 3. Edit config.local.json:
#    - Remove example-* entries
#    - Add your MCP servers with source URLs
#    - Keep ${VARIABLES} as-is (expanded automatically)

# 4. Bootstrap (validates config, installs servers, updates ~/.claude.json)
./scripts/bootstrap.sh

# 5. Restart Claude Code

最小配置示例

{
  "mcpProxy": {
    "hierarchyPath": "${MCP_PROXY_DIR}/hierarchy",
    "options": { "lazyLoad": true, "preloadAll": true }
  },
  "mcpServers": {
    "my-server": {
      "source": { "type": "git", "url": "https://github.com/you/my-mcp.git" },
      "transportType": "stdio",
      "command": "${MCP_SERVERS_DIR}/my-server/.venv/bin/python",
      "args": ["${MCP_SERVERS_DIR}/my-server/server.py"],
      "envFile": "${MCP_SERVERS_DIR}/my-server/.env",
      "env": {},
      "options": { "lazyLoad": true }
    }
  }
}

要点：

• 使用 ${MCP_SERVERS_DIR} 对于服务器路径（展开为 ~/.claude/mcp-servers)
• 使用 ${MCP_PROXY_DIR} 对于代理路径（展开为 ~/.claude/mcp-proxy)
• 添加 envFile 为了 .env 秘密或使用 env: {} 用于内联变量
• 每台服务器都需要 source 让bootstrap安装它

Bootstrap工作流

引导脚本编排完整的工作站设置：

./scripts/bootstrap.sh [FLAGS]

它的作用：

1. 验证配置 -检查缺失/占位符值
2. 安装MCP服务器 -从git克隆，创建venvs
3. 构建mcp代理 -编译Go二进制+结构生成器
4. 部署 -复制到 ~/.claude/mcp-proxy/，展开变量
5. 更新~/.claude.json -自动添加mcp代理条目
6. *（--仅安全）* 安装bitwarder警卫+openbao代理

配置

带变量的可移植配置

配置文件使用在部署时展开的变量：

{
  "mcpProxy": {
    "hierarchyPath": "${MCP_PROXY_DIR}/hierarchy"
  },
  "mcpServers": {
    "my-server": {
      "source": {
        "type": "git",
        "url": "https://github.com/user/mcp-server.git"
      },
      "command": "${MCP_SERVERS_DIR}/my-server/.venv/bin/python",
      "args": ["${MCP_SERVERS_DIR}/my-server/server.py"]
    }
  }
}

可用变量：

源类型

每个MCP服务器都可以指定一个安装源：

Git源代码 （推荐）：

"source": {
  "type": "git",
  "url": "https://github.com/user/mcp-server.git"
}

本地来源 （发展）：

"source": {
  "type": "local",
  "path": "~/repos/my-mcp-server"
}

远程HTTP （无需安装）：

"transportType": "streamable-http",
"url": "https://example.com/mcp"

更新行为

Venv重建 仅在以下情况下发生 pyproject.toml 或 requirements.txt 更改（基于哈希的检测）。

设置选项

简单模式： 使用环境变量配置MCP服务器。看 config.template.json.

安全模式： 与OpenBao、Bitwarden集成的全面秘密管理。看 docs/SECURE_SETUP.md.

Claude代码集成

添加 ~/.claude.json:

{
  "mcpServers": {
    "mcp-proxy": {
      "type": "stdio",
      "command": "~/.claude/mcp-proxy/mcp-proxy",
      "args": ["--config", "~/.claude/mcp-proxy/config.json"]
    }
  }
}

⚠️ 关键： 你的 ~/.claude.json 应包含 仅 这 mcp-proxy 上面的条目。 删除所有其他MCP服务器条目（cloudflare、joplin等）-代理会处理它们。 同时拥有直接服务器和mcp代理会导致重复连接和浪费上下文。 安装脚本将检测到这一点，并提示您自动清理。

建筑

┌─────────────────────────────────────────────────────┐
│                   Claude Code                        │
│                        │                             │
│                        ▼                             │
│         ┌──────────────────────────────┐            │
│         │         mcp-proxy            │            │
│         │                              │            │
│         │  2 meta-tools (~800 tokens)  │            │
│         │  • get_tools_in_category()   │            │
│         │  • execute_tool()            │            │
│         │                              │            │
│         │  Background: preload all     │            │
│         └──────────────────────────────┘            │
│                        │                             │
│     ┌──────────────────┼──────────────────┐         │
│     ▼                  ▼                  ▼         │
│ [Server 1]        [Server 2]        [Server 3]      │
│   warm              warm              warm          │
└─────────────────────────────────────────────────────┘

项目结构

mcp-proxy/
├── cmd/mcp-proxy/         # Main entry point
├── internal/
│   ├── client/            # MCP client connections
│   ├── config/            # Configuration parsing
│   ├── hierarchy/         # Tool schema management
│   ├── secrets/           # Secrets provider interface
│   └── server/            # Proxy server logic
├── structure_generator/   # Hierarchy generation tool
├── config/                # Configuration templates
│   ├── config.template.json   # Portable template with variables
│   └── config.local.json      # Your local config (gitignored)
├── scripts/
│   ├── bootstrap.sh       # Full setup (MCP servers + proxy) - recommended
│   ├── install.sh         # Binary-only (if servers already installed)
│   └── install-go.sh      # Install Go if missing
└── docs/
    └── SECURE_SETUP.md    # OpenBao + Bitwarden guide

发展

# Build
make build

# Test
go test ./...

# Deploy binary only (keeps existing config)
make deploy

# Full install (binary + config from config.local.json)
make install

# Regenerate hierarchy only
make generate-hierarchy

致谢

这个项目的灵感来自 语音树实验室/懒惰mcp，为渐进式工具披露引入了优雅的2兆位模具图案。mcp代理通过后台预加载、多传输支持、secrets集成和生产弹性功能扩展了这一基础。

许可证

MIT许可证