MCP guru

MCP Guru-通用MCP编排网关

将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路线：

直接访问（无路由）：

• 塞雷娜 -代码分析（需要即时访问）
• 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

它是如何工作的：

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

意图分类

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

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

智能过滤

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

过滤过程：

1. 检查尺寸阈值
2. 对用户意图进行分类
3. 如果是大型的，问法学硕士：“摘要会丢失关键信息吗？”
4. 使用提取提示提取相关部分
5. 使用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大师：一个工具。无限的可能性。生产准备就绪。** 🚀