MCP Quality Gate

mcp质量门

](https://www.npmjs.com/package/mcp-quality-gate)   ](https://nodejs.org/) 

MCP服务器的质量门。 喜欢 npm audit 对于包裹，但对于 模型上下文协议 服务器。

当LLM连接到您的MCP服务器时，它信任您公开的任何内容。错误的工具模式意味着错误的工具调用。缺少描述意味着模型只能猜测。50多种工具充斥着上下文窗口。泄露的环境变量暴露了秘密。mcp质量门在一个命令中捕获所有这些。

npx mcp-quality-gate validate "npx -y @modelcontextprotocol/server-filesystem /tmp"

一个命令。四个维度。0-100分。

它捕获了什么

mcp质量门在四个维度上对每个mcp服务器进行评分：

安装

npm install -g mcp-quality-gate

需要Node.js>=22。

用法

# Test any stdio MCP server
mcp-quality-gate validate "npx -y @modelcontextprotocol/server-filesystem /tmp"

# Test with environment variables
mcp-quality-gate validate "npx -y @supabase/mcp-server-supabase@latest --read-only --project-ref REF" \
  --env "SUPABASE_ACCESS_TOKEN=your-token"

# JSON output for CI/CD pipelines
mcp-quality-gate validate "./my-server" --reporter json --output report.json

# Fail CI if score is below threshold
mcp-quality-gate validate "./my-server" --threshold 80

# Test HTTP/SSE servers
mcp-quality-gate validate "http://localhost:3000/mcp" --transport http

真实世界基准

针对官方MCP参考服务器进行了测试（2026年4月）。这些是来自实时服务器连接的真实结果，而不是合成数据：

测试的服务器： @modelcontextprotocol/server-memory, @modelcontextprotocol/server-sequential-thinking, @modelcontextprotocol/server-everything, @modelcontextprotocol/server-filesystem, @anthropic/mcp-server-playwright.

输出示例

mcp-quality-gate v0.1.0
Server: npx -y @modelcontextprotocol/server-filesystem /tmp

  lifecycle
    PASS Server reports name and version (0ms)
    PASS Server reports capabilities (0ms)
    PASS Server responds to ping (1ms)

  tools
    PASS Server lists tools without error (5ms)
    PASS Tool definitions have required fields (6ms)
    PASS Tool names follow naming convention (8ms)
    PASS Tool inputSchema has type object (4ms)
    PASS Can call a listed tool (10ms)
    PASS Calling nonexistent tool returns error (1ms)
    PASS Tool descriptions are present (8ms)

  resources
    SKIP Server lists resources without error
    SKIP Resource definitions have required fields
    SKIP Resource descriptions are present
    SKIP Can read a listed resource

  prompts
    SKIP Server lists prompts without error
    SKIP Prompt definitions have required fields
    SKIP Can get a listed prompt

  efficiency
    14 tools, ~3057 schema tokens

  quality
    Param description coverage: 28%
    Deprecated: read_file
    Duplicates: read_file, read_text_file
    CRIT 18 of 25 parameters lack descriptions (72%)
    CRIT 1 deprecated tool(s) still listed: read_file
    WARN Tools with identical schemas: read_file, read_text_file

  security
    WARN "write_file" performs destructive operations — description warns of risk

Results: 10 passed, 7 skipped (45ms)
Score: 81/100
  compliance 40/40 | quality 11/25 | efficiency 15/15 | security 15/20

合规性测试（17）

mcp质量门连接到您的服务器，进行真正的协议调用，并验证行为。这不是静态分析，而是一个实时测试套件，它实际上用生成的参数调用您的工具。

当服务器没有通告功能时，会跳过测试（而不是失败）。仅使用工具的服务器不会因缺少资源而失去分数。

完整测试参考

质量分析

检查您的工具模式如何帮助LLM理解和使用您的工具：

证券分析

对工具定义进行静态分析，以检测常见的安全反模式：

效率分析

捕获工具激增和模式膨胀——MCP服务器LLM性能不佳的主要原因：

令牌估计使用 chars/4 启发式（JSON模式的准确率约为15%，而tiktoken的准确率为15%）。

评分

综合0-100分。每个维度从其最大值开始，并根据发现进行推断：

跳过维度 --skip-* 旗帜意味着这些积分不会被授予。具有以下功能的服务器 --skip-security 最多可以得分80分。

CLI 参考

CI/CD集成

添加到GitHub操作工作流：

- name: Test MCP Server
  run: npx mcp-quality-gate validate "./my-server" --threshold 80 --reporter json --output mcp-quality-gate-report.json

当分数低于1时，mcp质量门以代码1退出 --threshold，CI步骤失败。

程序化API

import {
  createMCPClient,
  listAllTools,
  runTests,
  complianceTests,
  analyzeEfficiency,
  analyzeQuality,
  analyzeSecurity,
  ConsoleReporter,
} from "mcp-quality-gate";

const client = await createMCPClient({
  command: "node",
  args: ["./my-server.js"],
  transport: "stdio",
});

const tools = await listAllTools(client);
const efficiency = analyzeEfficiency(tools);
const quality = analyzeQuality(tools);
const security = analyzeSecurity(tools);

const result = await runTests(
  complianceTests,
  { client, timeout: 10000 },
  undefined,
  "my-server",
  efficiency,
  quality,
  security,
);

console.log(new ConsoleReporter().format(result));
await client.close();

建筑

mcp-quality-gate
├── CLI (Commander)         → parse args, orchestrate
├── MCP Client Wrapper      → connect via stdio or HTTP, manage lifecycle
├── Compliance Tests (17)   → live protocol verification
│   ├── Lifecycle (3)       → init, capabilities, ping
│   ├── Tools (7)           → list, fields, naming, schema, call, errors, descriptions
│   ├── Resources (4)       → list, fields, descriptions, read
│   └── Prompts (3)         → list, fields, get
├── Quality Analyzer        → param descriptions, description length, deprecated, duplicates
├── Security Analyzer       → env exposure, code execution, dangerous defaults
├── Efficiency Analyzer     → tool count, schema token estimation
├── Score Calculator        → 4-dimension weighted composite (40+25+15+20=100)
└── Reporters               → console (colored), JSON (CI/CD)

发布

mcp质量门如下 语义版本控制:

• 0.x.y -在1.0之前，API可能会在次要版本之间发生变化
• 补丁 （0.x.Y）--错误修复、新的合规性测试、文档更新
• 次要的 （0.X.0）--新的分析器维度、新的报告器、CLI标志
• 重大 （X.0.0）-突破API变化，评分公式变化

发布工作原理

1. 碰撞 version 在 package.json
2. 更新 CHANGELOG.md 使用新版本条目
3. 合并到 main
4. CI自动运行：运行lint+test+build，发布到带有出处的npm，创建带有标签的GitHub Release v{version}

这 prepublishOnly 脚本运行 lint && build && test 作为安全门。看 贡献.md 获取完整的发布说明。

路线图

• \[x\] v0.1 --合规性测试（生命周期、工具、资源、提示）、质量+安全+效率分析、四维评分、CI/CD工作流程
• \[ \] v0.2 --传输合规性测试（HTTP/SSE边缘情况）、响应模式验证、能力拒绝测试
• \[ \] v0.3 — mcp-quality-gate init 脚手架、GitHub CI行动、性能基准测试
• \[ \] v1.0 -动态安全测试，MCP服务器注册表扫描，稳定的API

贡献

看 贡献.md 用于开发设置、代码标准以及如何添加测试。

安全

看 安全.md 用于报告漏洞。

行为准则

看 代码_OF_CONDUCT.md.

许可证

麻省理工学院