MCP Guru-通用MCP编排网关

![Production Ready](<>) ![Python 3.11+](<>) ![Tests](<>) ![Code Style](<>) ![Linting](<>) ![Security](<>)

将Claude Code的上下文窗口污染从100多个MCP工具减少到一个智能路由器。

MCP Guru是一个生产就绪的语义路由器层，位于Claude Code和多个MCP服务器之间。它暴露了一个 mcp_guru 该工具具有智能路由、发现、执行和结果过滤功能。

📋 目录

问题
解决方案
快速开始
生产特点
行动
配置
演出
建筑
发展
故障排除
路线图

问题

Traditional setup:
Claude Code loads 100+ tools directly
├── playwright.browser_snapshot
├── playwright.browser_click
├── filesystem.read_file
├── filesystem.write_file
├── ... 90+ more tools
└── Token cost: Context window pollution 😭

MCP Guru setup:
Claude Code loads 1 tool
└── mcp_guru (with 8 actions)
    └── Token savings: 🚀

解决方案

MCP Guru处理：

✅ 语义工具发现 -从任何问题中找到合适的工具
✅ 意图分类 -了解你真正在问什么
✅ 智能过滤 -使用本地LLM自动汇总大型结果
✅ 异步执行 -通过轮询实现非阻塞执行
✅ 结果缓存 -历史和原始结果的SQLite存储
✅ 健康监测 -内置健康检查和指标
✅ 速率限制 -防止MCP服务器不堪重负
✅ 配置验证 -启动前确保设置正确
✅ 备份/恢复 -自动化数据保护

快速入门（选择您的路径）

状态：✅ 生产就绪-已配置11台MCP服务器

MCP Guru随附 11个预配置的MCP服务器 准备使用：

通过Guru路线：

服务器	功能	描述
剧作家	浏览器自动化、屏幕截图、可视化测试	网络抓取和浏览器控制
Chrome 开发者工具	调试、性能分析、网络检查	浏览器调试和分析
背景7	文档查找、代码示例	库和API参考
ShadCn	组件引用、UI模式	ShadCN UI组件库
魔术UI	高级UI模式、动画	具有效果的现代UI组件
码头工人	容器管理、组合	Docker操作和编排
Lucide图标	图标搜索、库参考	1000+开源图标
PostgreSQL	数据库查询、模式检查	PostgreSQL数据库操作
GitHub	存储库、PR、问题	GitHub API集成
记忆	知识图，持久上下文	跨会话内存存储
获取	Web抓取、API测试、HTTP请求	Web内容检索

直接访问（无路由）：

塞雷娜 -代码分析（需要即时访问）
Byterover -知识库（需要即时访问）

选项A:Docker（推荐）

使用集装箱Ollama进行3分钟设置：

git clone https://github.com/yourusername/mcp-guru
cd mcp-guru

# Copy environment template
cp .env.example .env

# Configure credentials (edit .env with your values)
# DATABASE_URL=postgresql://...
# SCALEKIT_CLIENT_ID=...
# SCALEKIT_CLIENT_SECRET=...

# Install MCPs globally
npm install -g \
  @playwright/mcp \
  chrome-devtools-mcp \
  @upstash/context7-mcp \
  @jpisnice/shadcn-ui-mcp-server \
  @magicuidesign/mcp \
  docker-mcp \
  @modelcontextprotocol/server-postgres \
  @modelcontextprotocol/server-github \
  @modelcontextprotocol/server-memory \
  @modelcontextprotocol/server-fetch

# For Lucide Icons (requires separate build)
# git clone 
# cd lucide-icons-mcp && npm install && npm run build

# Start containers
docker-compose up --build

# Wait 30 seconds for Ollama, then pull model:
docker-compose exec ollama ollama pull qwen2.5:32b-instruct

看 MCP_GURU_INSTALLATION_GUIDE.md 详细设置。

选项B：本地安装

在您的机器上手动设置：

git clone https://github.com/yourusername/mcp-guru
cd mcp-guru

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install MCP Guru
pip install -e ".[dev]"

# Install MCPs globally (see Quick Start for full list)
npm install -g @playwright/mcp chrome-devtools-mcp @upstash/context7-mcp ...

# Ensure Ollama is running
ollama serve

# In another terminal:
ollama pull qwen2.5:32b-instruct

# Start MCP Guru
python -m mcp_guru.server

配置Claude代码

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "serena": {
      "command": "...",
      "args": [...]
    },
    "byterover": {
      "command": "...",
      "args": [...]
    },
    "mcp-guru": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-guru-server", "python", "-m", "mcp_guru.server"]
    }
  }
}

用法示例

User: "Take a screenshot of example.com and extract the pricing table"

Claude Code:
  → mcp_guru({
      action: "search",
      query: "take a screenshot and extract table"
    })

MCP Guru:
  1. Classifies intent: data_extraction
  2. Finds: playwright.browser_snapshot (0.95 score)
  3. Executes Playwright → 500KB HTML
  4. Summarizes with Ollama → 10KB pricing table
  5. Stores raw in SQLite

Claude gets: Concise summary + ability to request raw if needed

生产特点

🏥 健康监测

所有组件的内置健康检查：

{
  "action": "health"
}

答复：

{
  "status": "healthy",
  "overall": {
    "healthy": true,
    "component": "system",
    "message": "All components healthy",
    "metadata": {
      "total_components": 3,
      "healthy_components": 3,
      "last_check": "2025-01-14T12:00:00Z"
    }
  },
  "components": {
    "storage": {
      "healthy": true,
      "message": "Storage operational",
      "latency_ms": 5.2,
      "metadata": {"type": "sqlite"}
    },
    "mcp_servers": {
      "healthy": true,
      "message": "11 MCP servers connected",
      "latency_ms": 12.3,
      "metadata": {"server_count": 11}
    },
    "embeddings": {
      "healthy": true,
      "message": "Embedding service operational",
      "latency_ms": 8.1
    }
  }
}

使用案例：

启动验证
监控仪表板
警报系统
调试部署问题

📊 度量与监控

获取实时性能指标：

{
  "action": "metrics"
}

答复：

{
  "metrics": {
    "timestamp": "2025-01-14T12:00:00Z",
    "total_requests": 1547,
    "successful_requests": 1523,
    "failed_requests": 24,
    "success_rate": 0.98,
    "avg_latency_ms": 234.5,
    "p95_latency_ms": 567.3,
    "active_connections": 3,
    "cache_hit_rate": 0.82,
    "uptime_seconds": 86400,
    "requests_per_second": 0.018
  },
  "rate_limiter": {
    "playwright": {
      "total_requests": 234,
      "allowed": 234,
      "denied": 0,
      "wait_time_ms": 1250,
      "available_tokens": 18.5
    },
    "filesystem": {
      "total_requests": 512,
      "allowed": 512,
      "denied": 0,
      "wait_time_ms": 890,
      "available_tokens": 19.2
    }
  }
}

跟踪指标：

请求计数（总数、成功、失败）
成功率计算
延迟（平均值和P95）
活动连接
缓存效率
正常运行时间和吞吐量
每台服务器的速率限制器统计信息

🚦 速率限制

令牌桶算法可防止下游服务器不堪重负：

在中配置 config/mcp_servers.yaml:

rate_limiting:
  # Global defaults
  default_requests_per_second: 10.0
  default_burst_size: 20

  # Per-server overrides
  playwright_requests_per_second: 5.0
  playwright_burst_size: 10

  filesystem_requests_per_second: 20.0
  filesystem_burst_size: 50

特征：

每台服务器的速率限制
鞋钉爆裂能力
自动回退并重试
超时保护（默认30秒）
统计跟踪
公平的资源分配

优点：

防止DoS攻击
保护下游服务
确保跨工具的公平使用
可按服务容量配置

✅ 配置验证

启动时自动验证可确保正确设置：

$ python -m mcp_guru.server

INFO: Initializing MCP Guru...
INFO: Configuration validation passed
  ✓ MCP_GURU_CONFIG: ./config/mcp_servers.yaml
  ✓ OLLAMA_BASE_URL: http://localhost:11434
  ✓ OLLAMA_MODEL: qwen2.5:32b-instruct
  ✓ SQLITE_DB_PATH: ./mcp_guru.db
INFO: MCP Guru initialized successfully

验证：

所需的环境变量
文件路径存在
类型检查（整数、布尔值）
值范围和格式
API密钥存在（如果启用云回退）

错误示例：

ERROR: Configuration validation failed:
  - Missing required environment variable: OLLAMA_BASE_URL
  - Invalid value for EXECUTION_TIMEOUT: "abc" (expected integer)
  - Config file not found: ./config/missing.yaml

💾 备份和恢复

使用自动化脚本进行全面的数据保护：

快速备份：

./scripts/backup.sh

输出：

Starting backup: mcp-guru-20250114-120000
  ✓ Database backed up (5.2 MB)
  ✓ Configuration backed up
  ✓ Environment backed up
  ✓ Archive created: backups/mcp-guru-20250114-120000.tar.gz
  ✓ Cleanup completed (removed 2 old backups)
Backup successful!

特征：

自动化SQLite VACUUM（紧凑备份）
配置保存
30天保留政策
压缩档案（tar.gz）
自动清理旧备份
Cron作业兼容

自动计划：

# Daily backups at 2 AM
crontab -e
0 2 * * * cd /path/to/mcp-guru && ./scripts/backup.sh >> logs/backup.log 2>&1

看 BACKUP_RESTORE.md 用于：

恢复程序
灾难恢复
云存储集成（S3、GCS）
Docker卷备份
安全最佳实践

行动

MCP大师公开 8行动 通过单一工具：

`search`

使用自然语言对工具进行语义搜索：

{
  "action": "search",
  "query": "scrape a website and extract tables"
}

答复：

[
  {
    "tool_id": "playwright.browser_snapshot",
    "tool_name": "browser_snapshot",
    "server": "playwright",
    "description": "Take a snapshot of current page",
    "embedding_score": 0.92,
    "overall_score": 0.92
  },
  {
    "tool_id": "playwright.browser_click",
    "tool_name": "browser_click",
    "server": "playwright",
    "description": "Click an element on the page",
    "embedding_score": 0.78,
    "overall_score": 0.78
  }
]

`execute`

执行具有智能过滤和可选异步模式的工具：

{
  "action": "execute",
  "query": "playwright.browser_snapshot",
  "arguments": {
    "url": "https://example.com"
  },
  "summarize": "smart",
  "extraction_hint": "pricing table"
}

总结模式：

auto -根据大小自动（默认）
always -始终总结
never -返回原始结果
smart -使用意图分类+LLM决策

答复：

{
  "success": true,
  "content": "Pricing table with 3 tiers: Basic ($10/mo), Pro ($25/mo), Enterprise (custom)",
  "filtered": true,
  "raw_available": true,
  "raw_id": "raw-abc123",
  "latency_ms": 3450,
  "execution_id": "exec-123"
}

`poll`

检查异步执行状态：

{
  "action": "poll",
  "execution_id": "exec-123"
}

答复：

{
  "id": "exec-123",
  "status": "completed",
  "tool_name": "playwright.browser_snapshot",
  "result_summary": "Found 10 products with prices ranging $5-$50",
  "raw_id": "raw-456",
  "latency_ms": 5200,
  "created_at": "2025-01-14T12:00:00Z",
  "completed_at": "2025-01-14T12:00:05Z"
}

状态值： pending, running, completed, failed

`list_servers`

列出所有连接的MCP服务器：

{
  "action": "list_servers"
}

答复：

{
  "servers": [
    "playwright",
    "chrome-devtools",
    "context7",
    "shadcn",
    "magic-ui",
    "docker",
    "lucide-icons",
    "postgres",
    "github",
    "memory",
    "fetch"
  ],
  "count": 11
}

`get_schema`

获取任何工具的详细工具架构：

{
  "action": "get_schema",
  "query": "playwright.browser_snapshot"
}

答复：

{
  "name": "browser_snapshot",
  "description": "Take a snapshot of the current browser page",
  "input_schema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "URL to navigate to"
      },
      "wait_time": {
        "type": "number",
        "description": "Time to wait before snapshot (ms)"
      }
    },
    "required": ["url"]
  }
}

`get_raw`

按ID检索原始（未过滤）结果：

{
  "action": "get_raw",
  "query": "raw-456"
}

答复：

{
  "id": "raw-456",
  "tool_name": "playwright.browser_snapshot",
  "content": "... full HTML content ...",
  "created_at": "2025-01-14T12:00:00Z",
  "expires_at": "2025-01-21T12:00:00Z"
}

注：原始结果在7天后过期（可配置）

`health`

检查系统运行状况：

{
  "action": "health"
}

看生产特点-健康监测了解详情。

`metrics`

获取性能指标：

{
  "action": "metrics"
}

看生产特性-度量与监控了解详情。

功能深潜

语义工具搜索

通过自然语言查询查找工具：

"Take a screenshot of TradingView"
  → playwright.browser_snapshot

"List files in /home/user"
  → filesystem.list_directory

"Query the user database"
  → postgres.query

"Get React component docs"
  → context7.lookup

它是如何工作的：

基于嵌入的相似性搜索
上下文意图分类
按相关性得分排名
返回Top-K结果（可配置）

意图分类

自动确定是否应过滤结果：

意图	描述	过滤策略
数据提取	“获取价格”	总结具体事实
分析	“了解结构”	返回原始数据进行分析
监控	“检查状态”	只是要点
自动化	“创建文件”	需要完整输出

技术支持： Qwen2.5:32b（当地Olama）用于零成本分类

智能过滤

基于大小和意图的智能结果过滤：

结果大小	决策
\100KB	使用Olama来决定+提取

过滤过程：

检查尺寸阈值
对用户意图进行分类
如果是大型的，问法学硕士：“摘要会丢失关键信息吗？”
使用提取提示提取相关部分
使用7天TTL储存原材料

优点：

减少令牌使用
更快的Claude响应
需要时访问原始文件
免费使用当地Olama

异步执行

对于长时间运行的操作（>5秒）：

# 1. Start async execution
response = mcp_guru({
    "action": "execute",
    "query": "playwright.browser_snapshot",
    "arguments": {"url": "https://slow-site.com"},
    "async_mode": True
})
execution_id = response["execution_id"]

# 2. Continue other work...

# 3. Poll periodically
status = mcp_guru({
    "action": "poll",
    "execution_id": execution_id
})

# 4. When status.status == "completed"
if status["raw_available"]:
    raw = mcp_guru({
        "action": "get_raw",
        "query": status["raw_id"]
    })

优点：

非阻塞执行
优雅地处理超时
监督进展
多个并发执行

结果存储

基于SQLite的存储，具有自动管理功能：

原始结果：

7天TTL（可配置）
通过cron自动清理
可通过ID检索
压缩存储

执行历史：

永久记录
性能跟踪
成功/失败率
调试信息

绩效指标：

按工具统计
平均延迟
成功率
上次使用时间戳

演出

度量	目标	典型
搜索延迟	\

cd mcp-guru

Create virtual environment

python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate

Install in development mode with dev dependencies

pip install -e ".[dev]"

Verify installation

python -m pytest --version black --version ruff --version


**包含的开发工具：**

- pytest（测试框架）
- pytest-asyncio（异步测试支持）
- pytest-cov（覆盖率报告）
- 黑色（代码格式化）
- 绒毛

### 代码质量

MCP大师维护 **100%符合皮棉要求** 和 **零安全漏洞**.

**格式代码：**

black src/ tests/


**棉绒编码：**

ruff check src/ tests/

Auto-fix issues

ruff check --fix src/ tests/


**运行测试：**

All tests

pytest tests/ -v

With coverage

pytest tests/ -v --cov=src/mcp_guru

Specific test file

pytest tests/test_registry.py -v


**全面质量检查：**

black --check src/ tests/ && \ ruff check src/ tests/ && \ pytest tests/ -v


### 安全

**要求：**

- ✅ pip≥25.3（固定GHSA-4xh5-x5gv-qwph）
- ✅ 未弃用 `datetime.utcnow()` 用法
- ✅ 在所有端点上进行输入验证
- ✅ 速率限制可防止DoS
- ✅ 无已知漏洞

**安全审计：**

pip-audit


### 构建分发

pip install build python -m build

Output:

dist/mcp_guru-0.1.0-py3-none-any.whl

dist/mcp_guru-0.1.0.tar.gz


### 测试

**测试结构：**

tests/ ├── __init__.py ├── test_registry.py # Tool indexing & embeddings ├── test_storage.py # SQLite backend └── conftest.py # Shared fixtures


**运行特定测试：**

Registry tests only

pytest tests/test_registry.py -v

Storage tests only

pytest tests/test_storage.py -v

Single test function

pytest tests/test_registry.py::test_tool_indexer_add_and_retrieve -v


## 路线图

**✅ 完整的：**

- \[x\] 使用令牌桶算法进行速率限制
- \[x\] 健康监测系统
- \[x\] 配置验证
- \[x\] 备份/恢复程序和自动化
- \[x\] 绩效指标收集
- \[x\] 生产就绪代码质量

**🚧 进行中：**

- \[\]Prometheus指标导出端点
- \[\]Grafana仪表板模板

**📋 计划：**

- \[\]云LLM回退（OpenAI/Anthropic）
- \[\]刀具组成（链式多刀具）
- \[\]高级缓存层（支持Redis）
- \[\]用于度量和配置的Web UI
- \[\]自定义功能标记
- \[\]支持多用户身份验证
- \[\]Webhook通知
- \[\]断路器模式
- \[\]过滤策略的A/B测试

## 贡献

欢迎投稿！我们特别感兴趣的是：

**优先领域：**

- 其他MCP服务器适配器
- 性能优化
- 测试覆盖率提高
- 文档增强
- 安全强化

**如何做出贡献：**

1. 分叉存储库
1. 创建要素分支
1. 进行更改
1. 确保所有测试通过，代码不起毛
1. 提交拉取请求

**规范标准：**

- 遵循黑色代码风格（100字符行长度）
- 通过所有Ruff检查
- 保持测试覆盖率
- 为新功能添加文档

## 文档

- **[README.md](README.md)** -此文件，全面概述
- **[BACKUP_RESTORE.md](BACKUP_RESTORE.md)** -备份和灾难恢复
- **[生产_READY.md](PRODUCTION_READY.md)** -生产准备报告
- **[MCP_GURU_INSTALLATION_GUIDE.md](MCP_GURU_INSTALLATION_GUIDE.md)** -详细设置
- **[建筑.md](ARCHITECTURE.md)** -系统架构深度挖掘
- **[实施\_ SUMMARY.md](IMPLEMENTATION_SUMMARY.md)** -实施细节

## 许可证

MIT许可证-有关详细信息，请参阅许可证文件

## 支持

**问题和疑问：**

- GitHub问题：报告错误或请求功能
- 讨论：提问并分享想法

**资源：**

- 文件：见 `/docs` 目录
- 示例：参见 `/examples` 目录
- 配置： `config/mcp_servers.yaml`

## 致谢

内置：

- **MCP协议** -Anthropic的模型上下文协议
- **奥拉玛** -本地LLM运行时
- **问题2.5** -阿里巴巴的开源法学硕士
- **句子变换器** -嵌入模型
- **FastAPI/MCP** -服务器框架

______________________________________________________________________

**MCP大师：一个工具。无限的可能性。生产准备就绪。** 🚀

](<>)

MCP guru

快速接入

详细介绍

MCP Guru-通用MCP编排网关

📋 目录

问题

解决方案

快速入门（选择您的路径）

状态：✅ 生产就绪-已配置11台MCP服务器

选项A:Docker（推荐）

选项B：本地安装

配置Claude代码

用法示例

生产特点

🏥 健康监测

📊 度量与监控

🚦 速率限制

✅ 配置验证

💾 备份和恢复

行动

search

execute

poll

list_servers

get_schema

get_raw

health

metrics

功能深潜

语义工具搜索

意图分类

智能过滤

异步执行

结果存储

演出

Create virtual environment

Install in development mode with dev dependencies

Verify installation

Auto-fix issues

All tests

With coverage

Specific test file

Output:

dist/mcp_guru-0.1.0-py3-none-any.whl

dist/mcp_guru-0.1.0.tar.gz

Registry tests only

Storage tests only

Single test function

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`search`

`execute`

`poll`

`list_servers`

`get_schema`

`get_raw`

`health`

`metrics`