mcp-quality Skill 技能

技能简介

mcp-quality（GitHub 仓库名 mcp-probe）是面向 MCP（Model Context Protocol）服务器的 CI 质量套件，定位为"agent 工具的 pytest + lighthouse"。它在 CI 流水线里以无 LLM、零 API Key 的方式给任意 MCP 服务打出一个综合 MCP Quality Score（A–F 等级），并能在 PR 合并前阻断评分下滑。它由 swarmproof 团队开发并开源，Python 3.11+ 支持，2026-10-06 升至 0.5.0 版本，发布在 PyPI。

框架将 MCP 服务器的质量拆解为六类检查族：Contract（契约）/ Cost（成本）/ Legibility（可读性）/ Performance（性能）/ Security-lite（轻量安全）/ Safety-Contract（注解契约）。每类检查对应一种质量问题（如 Legibility 用"消歧矩阵"揭露工具描述歧义导致的 Agent 选错工具），并提供 --reliability K 重跑系数与 pass^k 可靠性叠加指标。框架与 mcp-scan、Cisco mcp-scanner、mcp-xray 等安全扫描工具互补，统一了"质量门禁"这一 CI 维度，并自动生成 shields.io 徽章。

核心能力

• MCP Quality Score 综合评分：六类检查族加权汇总成 0–100 分加 A–F 等级；任一族出现 F 即硬门禁把总成绩压至 C，避免单维度短板拉高平均分。
• Contract 契约检查（零 LLM）：JSON-RPC/握手一致性、Schema 合法性、输出合规、确定性、错误路径与恢复探测、stateless-conformance（2026-07-28 规范）、snapshot 与版本漂移回归——全离线可在 air-gapped 环境运行。
• Cost 成本分析（零 LLM）：完整工具集 token 权重、单工具冗余分析（leave-one-out）、运行时响应膨胀、$ 每次任务成本估算；为 Agent 经济成本治理提供数据底座。
• Legibility 可读性矩阵（差异点）：用小型模型（如 ollama:qwen2.5-3b）生成消歧矩阵、Agent 选择准确率、过触发率、描述 lint，并给出可自动 PR 的改写建议。
• Performance 真实性能：基于 MCP 语义（stdio/Streamable-HTTP/SSE）做并发 Agent 负载压测，输出 p50/p95/p99 与连接泄漏诊断，非 naive HTTP 工具。
• Safety-Contract 注解真实性校验：检查 delete_* 是否被错误标记 readOnlyHint（绕过宿主确认）、缺失的 hint、重试不安全写入等危险标注。
• Security-lite 安全基线（零 LLM + opt-in）：注入/密钥/危险能力 lint，映射 OWASP MCP Top 10；--deep-security 可集成 mcp-scan 与 Cisco mcp-scanner 结果。
• CI 门禁与徽章：--fail-under B + --no-regressions 让 PR 在评分下滑或断点变更时直接失败；mcp-quality badge 输出 shields.io SVG 徽章贴 README。

安装配置

1. 环境准备：Python ≥ 3.11；CI 环境推荐 ubuntu-latest runner；本地或 GitHub Actions 均可直接运行，无需 LLM Key。
2. 安装：一行 pip install mcp-quality 即装即用；可选 [registry] extra 启用 hosted scoring API 客户端。
3. CI 接入：在 .github/workflows/mcp-quality.yml 中固定 python-version: "3.12"，依次执行 pip install mcp-quality 与 mcp-quality run "python my_server.py" --fail-under B --no-regressions。
4. 离线/无网环境：使用 mcp-quality static ./server.mcp.json 离线评分；适合 air-gapped CI 与受监管部署。
5. 启用 Legibility 矩阵：本地安装 qwen2.5-3b（Ollama 即可），通过 --legibility --model ollama:qwen2.5-3b 触发消歧分析；亦可换 OpenAI/Anthropic 等兼容端点。
6. 可选深度安全：与 mcp-scan、Cisco mcp-scanner 联动时，添加 --deep-security 自动汇总其扫描结果进总分。

使用步骤

1. 快速评分：运行 mcp-quality run "python my_server.py" 立刻拿到 MCP Quality Score 报告与等级判定；末尾附带 shields.io 徽章片段可贴 README。
2. CI 门禁：在 workflow 中执行 mcp-quality run "python my_server.py" --json --fail-under B，未达 B 即 exit 1，PR 自动 fail；同时建议加 --no-regressions 阻断分数倒退。
3. 回归基线：首次运行 mcp-quality snapshot "python my_server.py" 写入 baseline；后续 PR 与 baseline 对比，工具新增/删除或评分下滑都会触发告警。
4. 消歧矩阵：加 --legibility --model ollama:qwen2.5-3b 后，框架会生成"correct tool × chosen tool"的选择率矩阵；读出"工具描述歧义"导致的 Agent 误选。
5. 自动改写：运行 mcp-quality fix --legibility --pr 把 Legibility 矩阵中识别的歧义工具描述生成改写建议，并自动创建 PR。
6. 实时压测：mcp-quality run 默认开启 Performance 族，给出 p50/p95/p99 与并发上限；结合 --reliability 5 输出 pass^5（5 次全过的预估概率）。
7. 公开排行榜：leaderboard.md 收录 server-memory、mcp-server-time、mcp-server-git、server-sequential-thinking 等真实公开 MCP 服务器的 grade 与 token 占用。

适用场景

• MCP 服务器发布前质量门禁：把 mcp-quality 接进 CI，要求 PR 必须达到 B 及以上才能合并，杜绝"评分倒退"事故。
• Agent 工具集成本评估：Cost 族给出每个 MCP 服务器的 token 税与单任务成本，帮助 Agent 架构师做工具选型与冗余剔除。
• 公开 MCP 服务器排行榜：用 mcp-quality 给 server-filesystem、server-memory 等知名 MCP 服务打分并生成对比报告，方便用户在多个候选中选择。
• Agent 选错工具问题定位：当生产环境出现"Agent 误调用 delete 而非 archive"类故障时，跑 Legibility 矩阵复现并生成 PR 修复。
• 受监管/气隙环境部署：零 LLM 路径（Contract + Cost + Safety）可在 air-gapped CI 中完全离线运行，满足金融/医疗等数据敏感场景。
• 多团队 MCP 仓库统一治理：大厂/平台型组织可将 mcp-quality 作为内部 MCP 注册中心准入审核工具，统一评估所有接入 MCP 的服务。

适用人群

• Agent 平台/中台工程师：负责 MCP 服务器接入审核、回归治理、token 成本控制的平台团队。
• MCP 服务开发者：在发布前自查质量，把 Legibility 矩阵与 Cost 评分作为发布前的"必检清单"。
• Agent 应用架构师：选型阶段需要对比多个 MCP 候选服务器（filesystem vs git vs memory 等）的质量与成本。
• DevOps / SRE：把 mcp-quality 嵌入 CI 后，可对 MCP 服务的可用性、可靠性（pass^k）与性能 p99 做长期跟踪。
• 安全/合规团队：通过 Security-lite 与 OWASP MCP Top 10 映射快速识别危险工具描述与危险能力。

工作原理

mcp-quality 围绕"契约-成本-可读性-性能-安全-注解"六族检查构建。每族检查对应一个独立可执行的子命令与评分逻辑，结果按版本化加权 rubric 汇总成 MCP Quality Score；任一族评 F 即硬门禁把总分压至 C，避免单维度短板拉高均值。

零 LLM 路径（Contract / Cost / Safety-Contract）走纯静态与契约分析，无需 API Key 或网络，可在 air-gapped 环境中跑；Legibility 族则调用一个小型可理解模型（如 ollama:qwen2.5-3b）生成消歧矩阵，给出"应选工具 × 实际选择"的选择率表，并产出可自动 PR 的描述改写建议。Performance 族基于 MCP 真实语义（stdio/Streamable-HTTP/SSE）做并发 Agent 负载压测，输出 p50/p95/p99 与连接泄漏诊断。整条流水线以确定性方式输出 JSON 报告，便于 CI 通过 --json --fail-under B 做合并控制；--reliability K 把非确定性族重跑 K 次并计算 pass^k，给出"实际工程每次能用"的可靠性叠加指标。

官方链接

• PyPI 包：https://pypi.org/project/mcp-quality/
• GitHub 仓库：https://github.com/swarmproof/mcp-probe
• 公开排行榜：https://github.com/swarmproof/mcp-probe/blob/main/docs/leaderboard.md
• CI Workflow 模板：.github/workflows/mcp-quality.yml（仓库内）
• 作者主页：https://github.com/swarmproof（旗下另有 stampede / mockworld / costbomb / exactly-once / agent-postmortems 等信任基础设施系列项目）
• 许可证：以仓库 LICENSE 文件为准（建议查阅 Apache-2.0 / MIT，README 中带 shields.io 标识）