MCP guru

MCP运维云端

提供方 Xcelency

运维云端 stdio · 本地进程 Token 社区 / 第三方 Claude DesktopClaude
查看接入方式

MCP Guru是一个生产就绪的语义路由层,位于Claude Code和多个MCP服务器之间,通过智能路由、发现、执行和结果过滤,将100多个MCP工具整合为一个智能路由器。

一句话选型结论

按资料字段整理

MCP guru 属于运维云端类 MCP 服务器,stdio · 本地进程,Token,可直接接入 Claude Desktop、Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类运维云端 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 8 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

运维云端
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量8暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

语义路由Python本地部署工具整合智能过滤异步执行性能监控

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
python3 -m venv venv

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 8 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
云资源查询

查实例、存储、账单等云上资源状态。

部署与发布

把部署、重启、回滚这类操作接进对话。

监控与告警

拉取监控指标,异常时让模型帮你判断。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 8 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在运维云端场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
MCP guru当前 8 stdio · 本地进程 本地部署 有 2026-05-17
lobehub 未标注 stdio · 本地进程 本地部署 有 2026-04-11
TrendRadar 未标注 stdio · 本地进程 本地部署 有 2026-04-13
Ui Tars Desktop 8a825770 未标注 stdio · 本地进程 本地部署 有 2026-05-17
ruflo 未标注 stdio · 本地进程 本地部署 有 2026-04-13
FastGPT 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

运维云端
字段来自项目仓库与公开索引,中文说明由本站标注
提供方Xcelency上游标注的维护方 Xcelency
分类运维云端本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

26.9 KB
来自项目仓库与上游目录的原文,未做删改

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路线:**

|服务器|功能|描述|
|--------|-------------|-------------|
| **剧作家** |浏览器自动化、屏幕截图、可视化测试|网络抓取和浏览器控制|
| **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分钟设置:**```bash
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:本地安装

在您的机器上手动设置:```bash
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配置中:```json
{
"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


## 生产特点

### 🏥 健康监测

所有组件的内置健康检查:```json
{
"action": "health"
}

答复:```json
{
"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
}
}
}


**使用案例:**

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

### 📊 度量与监控

获取实时性能指标:```json
{
"action": "metrics"
}

答复:```json
{
"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`:**```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攻击
  • 保护下游服务
  • 确保跨工具的公平使用
  • 可按服务容量配置

✅ 配置验证

启动时自动验证可确保正确设置:```bash
$ 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密钥存在(如果启用云回退)

**错误示例:**```bash
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

💾 备份和恢复

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

快速备份:```bash
./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作业兼容

自动计划:```bash

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`

使用自然语言对工具进行语义搜索:```json
{
"action": "search",
"query": "scrape a website and extract tables"
}

答复:```json
[
{
"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`

执行具有智能过滤和可选异步模式的工具:```json
{
"action": "execute",
"query": "playwright.browser_snapshot",
"arguments": {
"url": "https://example.com"
},
"summarize": "smart",
"extraction_hint": "pricing table"
}

总结模式:

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

答复:```json
{
"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`

检查异步执行状态:```json
{
"action": "poll",
"execution_id": "exec-123"
}

答复:```json
{
"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服务器:```json
{
"action": "list_servers"
}

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


### `get_schema`

获取任何工具的详细工具架构:```json
{
"action": "get_schema",
"query": "playwright.browser_snapshot"
}

答复:```json
{
"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检索原始(未过滤)结果:```json
{
"action": "get_raw",
"query": "raw-456"
}

答复:```json
{
"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`

检查系统运行状况:```json
{
"action": "health"
}

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

metrics

获取性能指标:```json
{
"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)用于零成本分类

智能过滤

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

结果大小 决策
\<50KB 始终返回原始数据
50-100KB 取决于意图
>100KB 使用Olama来决定+提取

过滤过程:

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

优点:

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

异步执行

对于长时间运行的操作(>5秒):```python

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检索
- 压缩存储

**执行历史:**

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

**绩效指标:**

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

## 演出

|度量|目标|典型|
|--------|--------|---------|
|搜索延迟|\&lt;500ms|300ms|
|奥利玛滤波(100KB)|2-5s|3s|
|端到端(缓存)|\&lt;1s|700ms|
|端到端(新鲜)|\&lt;8s|5.5s|
|健康检查|\&lt;100ms|50ms|
|度量检索|\&lt;50ms|20ms|

**基准:**

- CPU:英特尔i7或苹果M1
- 内存:16GB
- 奥利玛:qwen2.5:32b-结构体
- 存储:SSD

## 建筑```
┌─────────────────────────────────────────────────────────┐
│                    Claude Code                          │
└───────────────────┬─────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│              MCP Guru Tool (1 tool, 8 actions)         │
│  search | execute | poll | list_servers | get_schema  │
│  get_raw | health | metrics                            │
└───────────────────┬────────────────────────────────────┘
│
┌───────────┴───────────┐
│                       │
▼                       ▼
┌───────────────┐      ┌──────────────────┐
│  Config       │      │   Monitoring     │
│  Validator    │      │   - Health       │
│               │      │   - Metrics      │
└───────────────┘      │   - Rate Limit   │
└──────────────────┘
│
┌───────────────────────┴────────────────┐
│                                         │
▼                                         ▼
┌──────────────────┐                    ┌─────────────────┐
│ Semantic Router  │                    │  Smart Filter   │
│ - Embeddings     │                    │  - Intent Class │
│ - Tool Search    │                    │  - LLM Filter   │
└──────────────────┘                    └─────────────────┘
│                                         │
└───────────────────┬────────────────────┘
│
▼
┌─────────────────────┐
│   Tool Executor     │
│   - Rate Limited    │
│   - Async Support   │
└──────────┬──────────┘
│
┌──────────────────┼──────────────────┐
│                  │                  │
▼                  ▼                  ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Playwright  │  │  Filesystem  │  │   Postgres   │
│     MCP      │  │     MCP      │  │     MCP      │
└──────────────┘  └──────────────┘  └──────────────┘
│                  │                  │
└──────────────────┼──────────────────┘
│
▼
┌─────────────────────┐
│  SQLite Storage     │
│  - Executions       │
│  - Raw Results      │
│  - Metrics          │
└─────────────────────┘

配置

环境变量

创建 .env 文件或设置系统环境变量:```bash

Required

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

Optional

LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FORMAT=json # json or text
TOOL_SEARCH_TIMEOUT=10 # seconds
EXECUTION_TIMEOUT=30 # seconds
ASYNC_EXECUTION_TIMEOUT=300 # seconds (5 minutes)
AUTO_SUMMARIZE_THRESHOLD_KB=100 # KB threshold for auto-summarization
RAW_RESULT_RETENTION_DAYS=7 # days to keep raw results
CLEANUP_INTERVAL_HOURS=24 # hours between cleanup runs
DEBUG=false # Enable debug mode
PROFILE=false # Enable profiling

Cloud LLM Fallback (optional)

ENABLE_CLOUD_FALLBACK=false
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...


**启动验证:**
配置会自动验证,并显示明确的错误消息。

### MCP服务器配置

编辑 `config/mcp_servers.yaml`:```yaml
servers:
- name: playwright
transport: stdio
command: npx
args: [&quot;@anthropic-ai/playwright-mcp&quot;]
capabilities: [&quot;browser&quot;, &quot;scraping&quot;, &quot;screenshots&quot;]

- name: filesystem
transport: stdio
command: npx
args: [&quot;@anthropic-ai/filesystem-mcp&quot;]
capabilities: [&quot;files&quot;, &quot;directories&quot;]

- name: postgres
transport: stdio
command: npx
args: [&quot;-y&quot;, &quot;@modelcontextprotocol/server-postgres&quot;, &quot;postgresql://localhost:5432/mydb&quot;]
capabilities: [&quot;database&quot;, &quot;sql&quot;]

- name: github
transport: stdio
command: npx
args: [&quot;-y&quot;, &quot;@modelcontextprotocol/server-github&quot;]
capabilities: [&quot;repository&quot;, &quot;pull_requests&quot;, &quot;issues&quot;]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: &quot;${GITHUB_TOKEN}&quot;

- name: memory
transport: stdio
command: npx
args: [&quot;-y&quot;, &quot;@modelcontextprotocol/server-memory&quot;]
capabilities: [&quot;knowledge_graph&quot;, &quot;persistent_context&quot;]

# Rate limiting configuration
rate_limiting:
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

# LLM configuration
llm:
ollama_base_url: &quot;http://localhost:11434&quot;
model: &quot;qwen2.5:32b-instruct&quot;
timeout: 10
auto_summarize_threshold_kb: 100

# Storage configuration
storage:
db_path: &quot;./mcp_guru.db&quot;

# Execution configuration
execution:
timeout: 30
max_async_timeout: 300

LLM设置

小学(本地-免费):```yaml
llm:
ollama_base_url: "http://localhost:11434"
model: "qwen2.5:32b-instruct"
timeout: 10


**回退(云-可选):**```yaml
fallback:
provider: openai
model: gpt-4o-mini
api_key_env: OPENAI_API_KEY

过滤模式```yaml

filtering:
default_mode: "smart" # auto, always, never, smart
auto_summarize_threshold_kb: 100
store_raw_results: true
raw_retention_days: 7


## 成本分析

### 每月费用(1000次查询/天)

|组件|成本|
|-----------|------|
|Ollama(当地)| **$0** |
|SQLite(存储)| **$0** |
|电力(Ollama)|~5美元|
| **总计** | **~5美元/月** |

**与使用云LLM相比:**

- GPT-3.5涡轮增压:约150美元/月
- GPT-4o-mini:约150美元/月
- 克劳德·海库:约100美元/月

**节省:95-145美元/月** 💰

## 故障排除

### Ollama没有回应```
Error: Connection refused to http://localhost:11434

修复:```bash

Start Ollama

ollama serve

In another terminal, pull model

ollama pull qwen2.5:32b-instruct

Verify it's running

curl http://localhost:11434/api/tags


### 配置验证失败```
ERROR: Missing required environment variable: OLLAMA_BASE_URL

修复:```bash

Create .env file

cp .env.example .env

Edit and set required variables

nano .env

Verify

python -m mcp_guru.server


### 未发现工具```
Error: Tool index is empty

修复:

  1. 检查 config/mcp_servers.yaml 路径
  2. 验证MCP包是否已全局安装:```bash
    npm list -g | grep mcp
1. 测试单个MCP服务器:```bash
npx @anthropic-ai/playwright-mcp
  1. 检查服务器登录 mcp_guru.log

结果太大```

Result exceeds token limit


**修复:** 配置中的摘要阈值较低:```yaml
llm:
auto_summarize_threshold_kb: 50  # Reduced from 100

健康检查失败```json

{
"status": "unhealthy",
"components": {
"storage": {"healthy": false, "message": "Database locked"}
}
}


**修复:**

1. 检查数据库文件是否存在并且可写
1. 确保没有其他进程锁定数据库
1. 重新启动MCP Guru
1. 检查日志: `tail -f mcp_guru.log`

### 拒绝利率限制```
Rate limit denied for playwright after timeout

修复: 调整配置中的速率限制:```yaml
rate_limiting:
playwright_requests_per_second: 10.0 # Increased from 5.0
playwright_burst_size: 20 # Increased from 10


## 发展

### 设置开发环境```bash
# Clone repository
git clone
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 &quot;.[dev]&quot;

# Verify installation
python -m pytest --version
black --version
ruff --version

包含的开发工具:

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

代码质量

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

格式代码:```bash
black src/ tests/


**棉绒编码:**```bash
ruff check src/ tests/

# Auto-fix issues
ruff check --fix src/ tests/

运行测试:```bash

All tests

pytest tests/ -v

With coverage

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

Specific test file

pytest tests/test_registry.py -v


**全面质量检查:**```bash
black --check src/ tests/ &amp;&amp; \
ruff check src/ tests/ &amp;&amp; \
pytest tests/ -v

安全

要求:

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

安全审计:```bash
pip-audit


### 构建分发```bash
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


**运行特定测试:**```bash
# 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. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 确保所有测试通过,代码不起毛
  5. 提交拉取请求

规范标准:

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

文档

  • README.md -此文件,全面概述
  • BACKUP_RESTORE.md -备份和灾难恢复
  • 生产_READY.md -生产准备报告
  • MCP_GURU_INSTALLATION_GUIDE.md -详细设置
  • 建筑.md -系统架构深度挖掘
  • 实施_ SUMMARY.md -实施细节

许可证

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

支持

问题和疑问:

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

资源:

  • 文件:见 /docs 目录
  • 示例:参见 /examples 目录
  • 配置: config/mcp_servers.yaml

致谢

内置:

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

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

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
MCP guru 怎么安装?

在客户端按下面的安装命令接入:python3 -m venv venv。装完在客户端配置里引用同一个包或端点。

MCP guru 怎么在 Claude Desktop、Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

MCP guru 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

MCP guru 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

MCP guru 支持哪些客户端?

资料标注支持 Claude Desktop、Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

MCP guru 能提供哪些能力?

资料显示约 8 个工具;能力标签包括 Python、Claude、性能监控。具体工具清单以官方文档为准。

MCP guru 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

MCP guru 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。