MCP Verify

MCP验证

一个与框架无关的CLI和GitHub Action，用于验证 MCP（模型上下文协议） 用于规范一致性、安全漏洞和健康指标的服务器。

$ npx mcp-server-verify https://your-mcp-server.com/mcp

  MCP Verify 1.2.2 — MCP spec 2024-11-05

  Target:    https://your-mcp-server.com/mcp
  Transport: http

  Conformance Score: 94.3 / 100

  Category Breakdown:
  +-----------------+-------+------+------+------+
  | Category        | Score | Pass | Warn | Fail |
  +-----------------+-------+------+------+------+
  | Initialization  |   100 |    4 |    0 |    0 |
  | JSON-RPC Base   |    85 |    3 |    0 |    1 |
  | Tools           |    93 |    5 |    1 |    0 |
  | Resources       |   100 |    2 |    0 |    0 |
  | Prompts         |   100 |    2 |    0 |    0 |
  | Transport       |   100 |    3 |    0 |    0 |
  +-----------------+-------+------+------+------+

  Security Findings: 0 critical, 0 high, 1 medium, 0 low

  Result: PASS (exit code 0)

特性

• 规格一致性评分 --6个方案类别的加权评分（0-100）
• 安全漏洞检测 --5种常见MCP攻击模式的内置检查
• 多种输出格式 --终端（彩色）、JSON（结构化）、Markdown（GitHub友好）
• CI/CD集成 --GitHub Action，带有PR注释、可配置阈值、退出代码
• 历史跟踪 --评分历史、基线、回归检测
• 网络仪表盘 --带有图表、趋势和投资组合视图的本地仪表板
• 插件系统 --通过JavaScript插件使用自定义检查进行扩展
• 实时进度指示器 --验证过程中的实时反馈
• 智能交通检测 --自动检测HTTP、stdio和npm包目标
• 自定义身份验证标头 -支持Bearer令牌、API密钥和自定义头
• 零配置 --使用合理的默认值即可开箱即用
• 轻量级 --~111KB捆绑包，无严重依赖关系

快速开始

# Verify an HTTP MCP server
npx mcp-server-verify https://your-server.com/mcp

# Verify a stdio MCP server
npx mcp-server-verify stdio://./my-server.js

# Verify an npm package MCP server (auto-detected)
npx mcp-server-verify @anthropic/mcp-server-example

# With custom auth header
npx mcp-server-verify https://your-server.com/mcp --header "Authorization: Bearer token123"

# JSON output for CI
npx mcp-server-verify https://your-server.com/mcp --format json

# Fail CI on high+ severity findings
npx mcp-server-verify https://your-server.com/mcp --fail-on-severity high

# Require minimum 80% conformance
npx mcp-server-verify https://your-server.com/mcp --conformance-threshold 80

目录

• 它检查什么

- 规格一致性（6类） - 安全检查（内置5个） - 它不检查什么

• 安装
• CLI 参考

- 验证命令 - 基线指挥 - 历史导出命令 - 服务指挥

• 退出代码
• 配置文件
• 输出格式
• 网络仪表盘
• 历史跟踪和回归检测
• 插件系统
• 评分算法
• CI/CD示例
• 限制和诚实的差距
• 贡献
• 许可证

它检查什么

规格一致性（6类）

MCP验证根据MCP规范（2024-11-05）在6个加权类别中验证您的服务器：

每个类别从100分开始。不合格扣15分，警告扣7分。总分是一个加权平均值，固定在\[0，100\]。

特殊情况： 如果初始化握手完全失败，无论其他类别如何，总分都是0。

安全检查（内置5个）

所有发现包括：唯一ID、检查ID、严重程度、CVSS评分、成分、标题、描述、补救指南和置信度标签。

它不检查什么

坦诚面对局限性：

• 工具执行行为 --不调用工具或验证它们是否执行了声称的操作
• TLS/加密 --不验证HTTPS证书或TLS版本
• 速率限制/DoS弹性 --未测试（可作为 示例插件)
• 数据隐私/PII --不检查个人信息的数据流
• 身份验证强度 --检测身份验证的缺失，而不是身份验证的弱点
• 实际可利用性 --检查是基于模式的，而不是基于漏洞的。发现意味着“这看起来很可疑”，而不是“这被证明是可利用的”
• 性能/负载测试 --仅测量单个请求响应时间

这 插件系统 存在填补这些空白以满足您的特定需求。

安装

# Run directly (no install needed)
npx mcp-server-verify https://your-server.com/mcp

# Install globally
npm install -g mcp-server-verify

# Install as dev dependency
npm install --save-dev mcp-server-verify

要求： Linux、macOS或Windows上的Node.js 18、20或22。

CLI 参考

验证命令

默认命令。 mcp-verify 等同于 mcp-verify verify .

mcp-verify verify  [options]

# Basic
mcp-verify https://example.com/mcp

# CI pipeline: JSON output, fail on high findings, require 80% score
mcp-verify https://example.com/mcp \
  --format json \
  --fail-on-severity high \
  --conformance-threshold 80

# Save to file with terminal summary
mcp-verify https://example.com/mcp --format json --output report.json

# Compare with previous run
mcp-verify https://example.com/mcp --compare-last

# Strict mode, verbose errors
mcp-verify https://example.com/mcp --strict --verbose

# Custom auth headers
mcp-verify https://example.com/mcp --header "Authorization: Bearer mytoken"
mcp-verify https://example.com/mcp --header "X-API-Key: abc123" --header "X-Tenant: acme"

# Verify npm package server (auto-spawns via npx)
mcp-verify @anthropic/mcp-server-filesystem

智能交通自动检测

MCP验证自动检测目标类型：

基线指挥

为回归门控设置一个已知的良好状态。

# Run verification and store result as baseline
mcp-verify baseline https://example.com/mcp

# Promote the most recent history entry as baseline (no re-run)
mcp-verify baseline --existing https://example.com/mcp

当存在基线时， --compare-last 与之比较。使用 --compare-previous 而是与前一次运行进行比较。

基线存储在 ~/.mcp-verify/baselines/.

历史导出命令

导出运行历史记录，用于SIEM摄取或外部分析。

# Export history for one server
mcp-verify history export https://example.com/mcp --output history.json

# Export all tracked servers
mcp-verify history export --all --output all-history.json

输出是一个JSON对象 exportedAt, toolVersion和a runs 阵列。

服务指挥

启动本地web仪表板。

# Default port 4000
mcp-verify serve

# Custom port
mcp-verify serve --port 8080

看 网络仪表盘 了解详情。

退出代码

配置文件

创建 mcp-verify.json 或 .mcp-verify.json 在项目根目录中：

{
  "timeout": 15000,
  "format": "terminal",
  "failOnSeverity": "high",
  "conformanceThreshold": 80,
  "checkMode": "balanced",
  "verbose": false,
  "skip": [
    {
      "checkId": "cors-wildcard",
      "justification": "Development server only — CORS is restricted in production"
    },
    {
      "checkId": "auth-gap",
      "justification": "Auth handled by API gateway, not the MCP server directly"
    }
  ]
}

优先： CLI标志>配置文件>默认值。

被抑制的发现不会被隐藏——它们会出现在所有标有“被抑制”的输出格式中，并带有理由文本，从而保持审计跟踪。

使用 --config 指向特定文件，或让CLI在当前目录中自动发现。

输出格式

终端（默认）

带有方框图表格的彩色编码人类可读输出。尊重 NO_COLOR=1 环境变量。

JSON

CI管道和程序化消费的结构化输出：

{
  "schemaVersion": "1.0",
  "meta": {
    "toolVersion": "1.2.2",
    "specVersion": "2024-11-05",
    "timestamp": "2026-03-29T12:00:00.000Z",
    "target": "https://example.com/mcp",
    "transport": "http",
    "durationMs": 1234,
    "checkMode": "balanced"
  },
  "conformance": {
    "score": 94.3,
    "breakdown": {
      "initialization": 100,
      "jsonrpc-base": 85,
      "tools": 93,
      "resources": 100,
      "prompts": 100,
      "transport": 100
    },
    "violations": []
  },
  "security": {
    "findings": [],
    "suppressed": []
  },
  "summary": {
    "pass": true,
    "exitCode": 0,
    "blockerCount": { "critical": 0, "high": 0, "medium": 0, "low": 0 }
  }
}

完整架构记录于 docs/report-schema.json.

标记语言

带有管道表的GitHub风格的Markdown。适用于公关评论、维基页面和审计文档。

GitHub行动

添加到您的工作流程中：

name: MCP Verify
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start MCP server
        run: node my-server.js &

      - name: Verify MCP server
        uses: mcp-verify/action@v1
        with:
          target: http://localhost:3000/mcp
          fail-on-severity: high
          conformance-threshold: 80

动作输入

行动输出

PR评论

开 pull_request 事件，该操作会自动发布（或更新）Markdown摘要作为PR评论。注释是幂等的——相同的注释在重新运行时会更新，而不是重复。

需要 GITHUB_TOKEN 和 write 拉取请求的权限。如果缺少标记，则会优雅地跳过注释步骤。

网络仪表盘

启动本地仪表板，以可视化所有MCP服务器的分数历史记录：

mcp-verify serve
# Dashboard available at http://localhost:4000

特征：

• 投资组合视图 --将所有跟踪的服务器放在一个表中，其中包含最新得分、查找计数、趋势方向和上次运行时间。可排序列。
• 分数图表 --每台服务器的一致性得分时间序列线图。切换单个类别覆盖。
• 安全趋势 --按严重程度排列的调查结果柱状图。
• 回归标记 --分数上的红色指标下降超过5分。
• 完全本地化 --所有资产都是内嵌的。零外部网络请求。CSP标头已强制执行： default-src 'self'。没有分析、CDN字体或遥测。

历史数据存储在 ~/.mcp-verify/history/ 作为JSONL文件（每个目标一个）。

历史跟踪和回归检测

每次验证运行都会自动保存到本地历史记录中（禁用 --no-history).

与上一次运行相比

# Compare against baseline (or last run if no baseline)
mcp-verify https://example.com/mcp --compare-last

# Always compare against the immediately previous run
mcp-verify https://example.com/mcp --compare-previous

输出包括：

• 以前的分数与当前分数的差值
• 新发现（在当前运行中，但不是以前）
• 已解决的发现（在之前的运行中，但不是当前的）
• 分数下降时出现回归警告

固定基线

# Run verification and save as baseline
mcp-verify baseline https://example.com/mcp

# Or promote the latest history entry
mcp-verify baseline --existing https://example.com/mcp

导出历史记录

# Single target
mcp-verify history export https://example.com/mcp --output history.json

# All targets
mcp-verify history export --all --output all-history.json

插件系统

使用自定义检查扩展MCP验证。插件是接收完整验证上下文并返回结果的JavaScript模块。

快速示例

my-check.js:

export default {
  id: 'my-check',
  name: 'My Custom Check',
  description: 'Checks for something specific to my org',
  version: '1.0.0',
  check: async (context) => {
    const findings = [];
    if (context.transport === 'http' && context.toolsList.length > 50) {
      findings.push({
        checkId: 'my-check:too-many-tools',
        severity: 'medium',
        cvssScore: 4.0,
        component: 'tools',
        title: 'Excessive tool count',
        description: `Server exposes ${context.toolsList.length} tools`,
        remediation: 'Consider reducing the number of exposed tools',
        confidence: 'heuristic',
      });
    }
    return findings;
  },
};

mcp-verify.config.js:

export default {
  plugins: ['./my-check.js'],
  rules: {
    'my-check': { maxTools: 50 },
  },
};

插件行为

• 插件发现显示在 所有输出格式 以及内置的发现
• 插件发现 为退出代码做出贡献 通过 failOnSeverity
• 插件发现 可以被抑制 通过 skip 配置
• 30秒超时 每个插件--超过它将打印警告并继续
• 错误隔离 --插件中的异常永远不会使工具崩溃
• 两个参考插件 包括： examples/plugins/custom-auth-check 和 examples/plugins/rate-limit-check

完整指南： docs/plugin-authoring.md

评分算法

1. 6个评分类别中的每一个都从 100分
2. 每 失败 扣除 15分 从其类别
3. 每 警告 扣除 7分 从其类别
4. 类别分数被限制在 \[0, 100\]
5. 总体得分= 加权平均数 类别分数（见 重量表)
6. 如果初始化握手完全失败→ 总得分= 0

报告了错误处理违规行为，但 0重量 --它们不会影响数字分数。

CI/CD示例

GitHub 操作

jobs:
  mcp-verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mcp-verify/action@v1
        with:
          target: http://localhost:3000/mcp
          fail-on-severity: high
          conformance-threshold: 80

GitLab 的

mcp-verify:
  image: node:20
  script:
    - npx mcp-server-verify http://localhost:3000/mcp
      --format json
      --output report.json
      --fail-on-severity high
      --conformance-threshold 80
  artifacts:
    paths: [report.json]

CircleCI 的

jobs:
  mcp-verify:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Verify MCP server
          command: |
            npx mcp-server-verify http://localhost:3000/mcp \
              --format json \
              --output report.json \
              --fail-on-severity high
      - store_artifacts:
          path: report.json

完整的CI示例，包括矩阵构建、配置文件和高级工作流： docs/examples/

限制和诚实的差距

MCP验证是 静态分析和协议验证工具。它不是渗透测试框架或运行时行为监视器。

安全调查结果仅供参考。 “关键”发现意味着该模式强烈表明存在漏洞，而不是已经证明存在漏洞。始终在部署的上下文中验证发现。

插件系统旨在缩小特定的差距——为您的组织的身份验证要求、速率限制策略或任何特定于域的检查编写插件。

贡献

git clone https://github.com/dipandhali2021/mcp-verify.git
cd mcp-verify
npm install
npm test          # 646 tests
npm run typecheck # TypeScript strict mode
npm run build     # Bundle to dist/

许可证

麻省理工学院