使用说明

MCP智能代理

模型上下文协议（MCP）的智能代理——令牌更少，上下文集中，一切都在本地运行。无数据泄露。

🎯 为什么选择MCP智能代理？

模型上下文协议（MCP）的优化层。传统实施方式浪费高达 81% 上下文窗口（Cloudflare）；这个代理将其缩减为 10–30%.

好处	解释
💰 更少的代币	70–90% 代币消费减少→ 成本更低，浪费更少。
🎯 更精确的LLM	更小、更专注的背景→ 更少的噪音，更少的幻觉。
🔒 安全，无泄漏	完全在本地运行；没有向第三方发送提示或数据。

✨ 主要特点

语义路由 --将请求路由到最相关的工具
语义缓存 --当查询在语义上相似时，返回缓存的MCP响应（请参见语义缓存)
基于矢量的存储器 -本地嵌入（例如Xenova/all-MiniLM），无外部API
工具聚合 --多个MCP服务器的统一接口
性能监控 --实时分析和仪表板
可流式传输的HTTP --上游MCP服务器使用 HTTP 端点（MCP流式HTTP），与现代MCP客户端（例如。 type: "streamable" 在支持的地方）。麻省理工学院许可。

⚡ 快速开始

代理暴露 MCP流式HTTP 上 POST /mcp。您可以配置二事情：（1） 上游MCP服务器 代理调用(config/default.json 在这个仓库中），以及（2）你的 MCP客户端 发送流量（您的编辑器或代理的MCP设置——文件路径取决于产品——指向您的代理URL）。

1.运行代理

git clone https://github.com/Mourad95/mcp-smart-proxy.git
cd mcp-smart-proxy
npm ci
npm run build
node dist/index.js start --config ./config/default.json

检查： curl http://localhost:3000/health → status: healthy.

默认端口为 3000 （参见 port 在 config/default.json 或通过 --port 3000).

2.配置上游MCP服务器（在此仓库内）

编辑 config/default.json （或传递另一个文件 --config).在...之下 mcpServers，列出每个 远程MCP 代理应该使用。每 url 必须是 可流式传输的HTTP MCP网址(http:// 或 https://，通常以结尾 /mcp).

示例(data.gouv.fr MCP):

"mcpServers": [
  {
    "name": "datagouv",
    "url": "https://mcp.data.gouv.fr/mcp",
    "description": "data.gouv.fr",
    "enabled": true,
    "timeout": 60000
  }
]

集 "enabled": true 对于您希望激活的每台服务器。
可选的 headers （例如Composio x-api-key)每次请求都会发送到该上游。
编辑文件后重新启动代理。

此文件是仅通过阅读 代理进程。IDE不会直接打开它。

3.将您的MCP客户端指向代理（而不是直接指向data.gov）

在你的 客户端的MCP配置，添加a 可流式传输的 HTTP端点，其 url 是代理基本URL包括 /mcp （确切的文件位置取决于编辑器或代理）。示例形状：

{
  "mcpServers": {
    "mcp-smart-proxy": {
      "type": "streamable",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

重新加载或重新启动客户端，使其接受更改。交通流量： MCP客户端 → http://127.0.0.1:3000/mcp → 代理 → 来自步骤2的上游URL（例如。 https://mcp.data.gouv.fr/mcp).

对于 克劳德桌面版 以及使用 mcp-remote 要桥接HTTP MCP，请指向 mcp-remote 位于同一代理URL(http://127.0.0.1:3000/mcp)而不是上游服务器。

健康与指标： curl http://localhost:3000/health · curl http://localhost:3000/metrics ·仪表板： http://localhost:3000/dashboard （如果启用并构建）。

其他安装选项

方法	命令
Docker Compose	`make docker-compose` 然后 `curl http://localhost:3000/health`
Makefile	`make install && make build && make run` （或 `make dev`)
全局CLI	`npm install -g mcp-smart-proxy` 然后 `mcp-smart-proxy start --config ./config/default.json`

烟雾脚本（可选）： node scripts/smoke-http.mjs （无上游）， node scripts/smoke-mcp-http.mjs （需要启用上游+网络）。

📊 问题：上下文浪费和幻觉

传统MCP废物 81% 上下文（不必要的工具描述、无关的上下文、重复、糟糕的工具选择）。这也增加了幻觉——模型噪音太大，通过发明细节来填补空白。

我们的方法： 智能工具过滤、语义上下文选择、重复数据删除和优化路由，使模型接收的上下文更少，但更有针对性→ 更少的幻觉，更好的可靠性。

🔒 安全与隐私

完全在你这边运行：代理、嵌入和向量索引留在你的机器或基础设施上-- 没有向第三方发送提示或数据.响应被净化（API密钥、令牌、DB URL被屏蔽）。您可以控制哪些MCP服务器和嵌入模型在何处运行。看 安全.md 用于速率限制、验证和部署。

🏗️ 建筑

flowchart LR
  subgraph client[" "]
    A["MCP client"]
  end
  subgraph proxy[" "]
    B["MCP Smart Proxy"]
  end
  subgraph servers[" "]
    C[GitHub]
    D[SQLite]
    E[Filesystem]
    F[Custom...]
  end
  A -->|"request"| B
  B --> C
  B --> D
  B --> E
  B --> F
  C --> B
  D --> B
  E --> B
  F --> B
  B -->|"optimized response"| A

一目了然： 客户只与代理人交谈；代理选择正确的MCP服务器（GitHub、SQLite、文件系统等），修剪上下文，并返回一个精简的答案——更少的令牌、更少的幻觉，一切都是本地的。

Internal components (ASCII)

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │    │   Smart Proxy   │    │   MCP Servers   │
│   (Claude, etc.)│    │                 │    │                 │
│                 │    │  ┌───────────┐  │    │  ┌───────────┐  │
│  ┌───────────┐  │    │  │ Semantic  │  │    │  │   Tool A  │  │
│  │   Query   │──┼───▶│  │  Router   │──┼───▶│  │           │  │
│  └───────────┘  │    │  └───────────┘  │    │  └───────────┘  │
│                 │    │                 │    │                 │
│  ┌───────────┐  │    │  ┌───────────┐  │    │  ┌───────────┐  │
│  │ Optimized │◀─┼────│  │ Context   │◀─┼────│  │   Tool B  │  │
│  │ Response  │  │    │  │ Optimizer │  │    │  │           │  │
│  └───────────┘  │    │  └───────────┘  │    │  └───────────┘  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                        │  ┌───────────┐  │
                        │  │ Vector    │  │
                        │  │  Memory   │  │
                        │  └───────────┘  │
                        └─────────────────┘

⚙️ 配置

基本配置

使用 config/default.json （或复制）。每 mcpServers[].url 是上游可流式传输的HTTP MCP端点（不是代理URL）。

秘密和 `config/local.json` （未承诺）

放 API密钥和仅限机器的重写 在 config/local.json 在 同一目录 作为您传递的配置文件 --config （例如。 config/local.json 旁边 config/default.json).该文件是 被忽视 和合并在主文件之后：顶级密钥覆盖，以及 mcpServers 条目已合并 通过 name （因此，您只能添加例如 headers 为了 composio).复制 config/local.example.json 到 config/local.json 并替换占位符。 旋转任何曾经犯下的秘密 到存储库。

提交的主文件示例（没有以git表示的API密钥）：

{
  "port": 3000,
  "mcpServers": [
    {
      "name": "datagouv",
      "url": "https://mcp.data.gouv.fr/mcp",
      "description": "Example upstream MCP",
      "enabled": true,
      "timeout": 60000
    }
  ],
  "optimization": {
    "enabled": true,
    "maxContextTokens": 1000,
    "embeddingModel": "Xenova/all-MiniLM-L6-v2",
    "cacheEnabled": true,
    "semanticRouting": true,
    "minRelevanceScore": 0.3
  },
  "logging": { "level": "info", "format": "text" },
  "analytics": { "enabled": true, "retentionDays": 30, "dashboardEnabled": true }
}

tools/list 优化： 当 optimization.enabled 是真的，每一个 tools/list 运行相同 optimizeContext 路径。如果客户端发送 params.context.query，使用该字符串；否则 toolsListOptimizationQuery （或env MCP_TOOLS_LIST_OPTIMIZATION_QUERY)提供默认值。如果语义过滤会删除每个工具，那么代理 返回完整的工具列表当优化 残疾的，代理返回完整目录（传递）并记录目录度量。

环境变量

# Proxy configuration
export MCP_PROXY_PORT=3000
export MCP_PROXY_LOG_LEVEL=info

# Optimization settings
export MCP_OPTIMIZATION_ENABLED=true
export MCP_MAX_CONTEXT_TOKENS=1000

# Vector memory
export MCP_VECTOR_MEMORY_PATH="./.mcp-vector-index"
export MCP_EMBEDDING_MODEL="Xenova/all-MiniLM-L6-v2"

# Optimization statistics and dashboard data (default: ./data/stats)
export MCP_STATS_DIR="./data/stats"

数据存储

优化统计数据和仪表板数据存储在磁盘上，以便在重新启动后继续使用。

位置	内容
`MCP_STATS_DIR` （默认值： `./data/stats`)	优化统计信息目录。包含 `optimization-stats.json` （汇总指标：总请求、令牌节省、每小时细分、顶级工具），加上日志(`optimization.log`, `stats.json`).
`./data/reports`	使用仪表板“导出报告”或 `/api/reports/export` 终点。

集 MCP_STATS_DIR 更改统计数据的写入位置（例如。 /data/stats 在Docker中）。仪表板中的“最近请求”列表仅在内存中，并在代理重新启动时清除。

📁 项目结构（概述）

mcp-smart-proxy/
├── src/
│   ├── index.ts                 # CLI entry (start, analyze, maintenance)
│   ├── proxy/
│   │   ├── server.ts            # Express: /health, /mcp, /optimize, /proxy/:name, …
│   │   └── mcp-http-transport.ts # MCP Streamable HTTP client to upstream servers
│   ├── optimization/
│   │   └── context-optimizer.ts
│   ├── memory/
│   │   └── vector-memory.ts
│   ├── cache/
│   │   └── semantic-cache.ts
│   ├── analytics/
│   ├── config/
│   └── types/
├── config/                   # default.json, production.json, local-smoke.json
├── scripts/                  # smoke-http.mjs, smoke-mcp-http.mjs
├── dashboard/                # Optional React dashboard (build with npm run build:full)
├── docs/                     # e.g. SEMANTIC-CACHE.md
└── package.json

📈 性能指标

代币节省

场景	传统MCP	智能代理	节省
简单查询	1000个令牌	300个令牌	70%
复杂查询	5000个令牌	1000个令牌	80%
多工具	10000个代币	2000个代币	80%
大上下文	50000个令牌	5000个令牌	90%

速度提升

工具选择：语义路由速度提高50%
上下文处理：处理时间减少70%
总体延迟：改善30-50%
缓存命中率：>80%用于常见查询

🔧 高级用法

每台服务器转发： POST /proxy/:serverName JSON-RPC主体转发到中指定的上游服务器 config/default.json (mcpServers[].name).
优化API： POST /optimize （公开）或 POST /api/optimize （如果配置了仪表板身份验证） { "query": "...", "tools": [ ... ] }.
库导入： 该软件包主要作为 命令行界面；没有稳定的 SmartProxy / createProxy 在已发布的构建中导出--通过运行 node dist/index.js 或 mcp-smart-proxy 二进制后 npm run build.

🧪 测试

npm test
npm run test:coverage

手动烟雾测试 （代理必须正在运行）：

# No upstream MCP (only /health + /optimize)
node dist/index.js start --config ./config/local-smoke.json --port 3456
SMOKE_BASE_URL=http://127.0.0.1:3456 node scripts/smoke-http.mjs

# With upstream (enable server(s) in config/default.json, e.g. data.gouv)
node dist/index.js start --config ./config/default.json
node scripts/smoke-mcp-http.mjs

🔍 运作原理

语义分析（嵌入）→ MCP服务器的智能路由→ 上下文优化（去重、令牌高效格式）→ 可选从查询模式中学习。

📊 监控

仪表板位于 http://localhost:3000/dashboard.指标： curl http://localhost:3000/metrics （普罗米修斯： /metrics/prometheus，JSON： /analytics/json).跟踪：令牌节省、响应时间、缓存命中率、工具使用率、错误率。

🔄 维护

定期维护任务

# Run maintenance
npm run maintenance

# Or via CLI
mcp-smart-proxy maintenance --optimize --cleanup

自动化维护

# Set up cron job for daily maintenance
0 2 * * * cd /path/to/mcp-smart-proxy && npm run maintenance

🚨 故障排除

常见问题

“代理未连接到MCP服务器”

curl http://localhost:3000/health

确保每个 mcpServers[].url 可以联系到(https://…/mcp), enabled 是 true，编辑后重新启动了代理 config/default.json.

“性能缓慢”

# Clear cache
mcp-smart-proxy maintenance --clear-cache

# Reduce optimization complexity
export MCP_OPTIMIZATION_LEVEL=basic

“内存使用率高”

# Limit vector memory size
export MCP_VECTOR_MEMORY_MAX_SIZE=1000

# Disable unused features
export MCP_SEMANTIC_ROUTING=false

调试模式

# Enable debug logging
DEBUG=mcp-smart-proxy:* npm start

# Or set environment variable
export MCP_DEBUG=true

🔮 路线图

计划功能

[ ] 高级ML模型：更好的语义理解
[ ] 分布式处理：跨多个节点扩展
[ ] 插件系统：自定义优化和集成
[ ] 实时仪表盘：实时监控
[ ] API网关：用于编程访问的REST API
[ ] 多协议支持：超越MCP兼容性

进行中

[x] 核心代理：基本路线和优化
[x] 矢量存储器：语义搜索和上下文选择
[x] 性能监控：指标和分析
[x] 文档：综合指南和示例

🤝 贡献

我们欢迎社区的贡献！以下是如何开始：

分叉存储库
创建要素分支
进行更改
运行测试: npm test
提交拉取请求

开发设置

git clone https://github.com/Mourad95/mcp-smart-proxy.git && cd mcp-smart-proxy
make install && make build && make test

代码标准

遵循TypeScript的最佳实践
为新功能添加测试
更新文档
尽量减少依赖关系

📚 文档

入门指南 -首次设置指南
API 参考 -完整的API文件
高级用法 -自定义配置
语义缓存 -语义缓存（基于相似性的响应缓存）
性能调优 -优化指南
故障排除 -常见问题和解决方案
安全.md -安全、隐私、本地部署

🐳 生产部署

生产Docker设置：多级Dockerfile、带sidecar MCP服务器的Docker Compose、健康检查、持久卷（矢量数据）、可选的Prometheus+Grafana。看部署.md 完整的指南。

📄 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

🙏 致谢

人类用于创建模型上下文协议
云耀突出上下文浪费问题
OpenClaw社区 用于灵感和测试
所有贡献者 为了使这个项目变得更好

🔗 链接

GitHub: https://github.com/openclaw-community/mcp-smart-proxy
文档: https://mcp-smart-proxy.openclaw.ai
不和谐社区: https://discord.com/invite/clawd
问题追踪: https://github.com/openclaw-community/mcp-smart-proxy/issues

立即开始优化您的MCP使用！ 🚀

npm install mcp-smart-proxy

令牌更少，上下文集中，仅限于本地——没有数据泄漏。Cloudflare显示MCP浪费了81%的上下文，而我们节省了高达90%的上下文。