MCP Trust Kit

MCP记分卡

MCP服务器的确定性、CI优先质量记分卡。

MCP Scorecard 是一个开源基础设施工具，用于在MCP服务器进入之前对其进行审查 真实的工作流程。它通过以下方式在本地启动服务器 stdio，发现其工具，应用 确定性规则集，并在以下方面产生可审查的分数和发现：

• conformance
• security
• ergonomics
• metadata

输出是为CI构建的：稳定的终端摘要、机器可读的JSON记分卡报告、， 以及用于代码扫描系统的SARIF。

这个项目故意不是一个人工智能包装器。它不依赖于LLM评分，隐藏 例如分析、判断或托管分析。目标是为工程团队提供一个可重复、可审计的基线 可以打开拉取请求并释放管道。

快速值：

• 在本地针对真实的MCP服务器运行
• CI低于确定性阈值
• 导出JSON和SARIF以实现自动化
• 确定性地审查有风险的MCP表面

这是什么

MCP Scorecard 是MCP服务器的确定性质量记分卡。

它专为团队需要回答以下问题的情况而设计：

• 在我们采用之前，这个服务器表面是否可以审查？
• 它是否暴露了CI中值得额外审查的功能？
• 工具名称、描述和模式是否足够清晰，便于人工审查？
• 我们能否为自动化和策略生成稳定的机器可读报告？

如今，该工具侧重于本地 stdio MCP服务器和易于使用的确定性评分模型 解释、测试和版本。

为什么存在

MCP服务器是基础设施。它们定义了可调用的工具表面，用于代理、运行时和 自动化可以调用。这意味着他们应该像其他人一样认真地审查 整合边界。

在实践中，团队经常临时评估MCP服务器：

• 描述模糊
• 模式较弱或约束不足
• 高风险能力发现较晚
• CI没有一致的基线

MCP Scorecard 将一线审查转化为确定性合同：

• 本地运行
• 在CI中运行它
• 检查类别分数和发现
• 导出JSON和SARIF
• 随着时间的推移，保持结果的可审查性

它检查什么

当前的评分模型使用四个显式桶。

这里的一致性是指确定性接口级一致性和模式可审查性检查， 没有完整的协议认证。

一致性

检查服务器表面是否结构良好，是否可作为MCP接口进行审查。

示例：

• 重复的工具名称
• 缺少架构类型
• 任意顶级属性
• 关键输入字段未标记为必填项

安全

检查是否存在显著增加爆炸半径或值得明确审查的暴露能力。

示例：

• 命令执行
• 文件系统突变
• 网络和HTTP请求原语
• 下载并执行模式

人体工程学

检查服务器表面是否足够易于理解，以便人工和自动化进行审查 没有猜测。

示例：

• 过于通用的工具名称
• 模糊的描述
• 弱输入模式
• 没有可见作用域提示的文件系统变异工具

元数据

检查是否存在基本的描述性元数据，以及破坏性行为是否变得容易 现场。

示例：

• 缺少工具描述
• 明确宣传广泛破坏性访问的描述

它没有承诺什么

MCP Scorecard 故意缩小范围，诚实对待范围。

确实如此 不 承诺：

• 高分意味着服务器是安全的
• 低分意味着服务器是恶意的
• 运行时可利用性分析
• 部署或隔离验证
• 商业意图分类
• 服务器表面外的人工审批策略评估
• 基于LLM的评分
• 托管扫描或注册表支持的认证声明

分数衡量 仅限确定性、可审查的属性.

这就是工具的意义所在。

快速入门本地

扫描附带的不安全演示服务器：

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
mcp-scorecard scan --cmd python examples/insecure-server/server.py

生成JSON和SARIF并强制执行分数门：

mcp-scorecard scan \
  --min-score 80 \
  --json-out mcp-scorecard-report.json \
  --sarif mcp-scorecard-report.sarif \
  --cmd python examples/insecure-server/server.py

扫描仪启动 --cmd 直接没有外壳。实际上，这意味着 python, npx, uvx，或者只要传递真实的可执行文件和参数，编译后的二进制文件都可以工作。

的首选CLI名称 v1.0.0 是 mcp-scorecard.遗产 mcp-trust 命令仍然存在 可用作兼容性别名。Python模块仍然存在 mcp_trust.

Windows (PowerShell)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]
.\.venv\Scripts\mcp-scorecard scan --cmd .\.venv\Scripts\python examples\insecure-server\server.py

GitHub操作快速入门

将此工作流放入您的存储库：

name: MCP Scorecard

on:
  pull_request:
  workflow_dispatch:

permissions:
  contents: read
  security-events: write

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

      - name: Run MCP Scorecard
        id: scorecard
        uses: aak204/MCP-Scorecard@v1.0.0
        with:
          cmd: python path/to/your/server.py
          min-score: "80"
          json-out: mcp-scorecard-report.json
          sarif-out: mcp-scorecard-report.sarif
          markdown-out: mcp-scorecard-summary.md

      - name: Use Scorecard Outputs
        if: always()
        run: |
          echo "total score: ${{ steps.scorecard.outputs.total-score }}"
          echo "passed: ${{ steps.scorecard.outputs.passed }}"
          echo 'category scores: ${{ steps.scorecard.outputs.category-scores }}'

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: mcp-scorecard-report.sarif

该操作保留了当前的本地用例，但将其打包为CI第一记分卡步骤。

输入：

• cmd
• min-score
• json-out
• sarif-out
• markdown-out

输出：

• total-score
• category-scores
• passed

每次运行还将一个PR友好的Markdown摘要写入GitHub Actions步骤摘要。如果 markdown-out 设置后，相同的摘要将写入工作区内的文件。

迁移说明：

• 更喜欢 aak204/MCP-Scorecard@v1.0.0 在新的工作流程中
• 遗留引用 aak204/MCP-Trust-Kit 可能仍存在于旧文档或链接中

输出示例

电流端子输出 examples/insecure-server:

Generator: MCP Scorecard (mcp-scorecard 1.0.0)
Report Schema: mcp-scorecard-report@1.0
Scan Timestamp: 2026-04-09T15:49:48.930250+00:00
Server: Insecure Demo Server
Version: 0.1.0
Protocol: 2025-11-25
Target: stdio:[".\\.venv\\Scripts\\python","examples\\insecure-server\\server.py"]
Target Description: Local MCP server launched over stdio.
Tools: 4
Finding Counts: total=7, error=2, warning=5, info=0
Total Score: 10/100
Why This Score: Score is driven mainly by security findings in command execution and file system and ergonomics findings.
Score Meaning: Deterministic CI-first quality scorecard based on conformance, security-relevant capabilities, ergonomics, and metadata hygiene.
Category Scores:
- conformance: 90/100 (findings: 1, penalties: 10)
- security: 60/100 (findings: 2, penalties: 40)
- ergonomics: 60/100 (findings: 4, penalties: 40)
- metadata: 100/100 (findings: 0, penalties: 0)
Findings By Bucket:
- security: 2 findings, penalties: 40
  - ERROR dangerous_exec_tool [exec_command]: Tool 'exec_command' appears to expose host command execution.
  - ERROR dangerous_fs_write_tool [write_file]: Tool 'write_file' appears to provide filesystem write access.
- ergonomics: 4 findings, penalties: 40
  - WARNING weak_input_schema [debug_payload]: Tool 'debug_payload' exposes a weak input schema that leaves free-form input underconstrained.
  - WARNING overly_generic_tool_name [do_it]: Tool 'do_it' uses an overly generic name that hides its behavior.
  - WARNING vague_tool_description [do_it]: Tool 'do_it' uses a vague description that does not explain its behavior clearly.
  - WARNING write_tool_without_scope_hint [write_file]: Tool 'write_file' modifies the filesystem without any visible scope hint.
- conformance: 1 finding, penalties: 10
  - WARNING schema_allows_arbitrary_properties [debug_payload]: Tool 'debug_payload' allows arbitrary additional input properties.
Limitations:
- Low score means more deterministic findings or higher-risk exposed surface, not malicious intent.
- High score means fewer deterministic findings, not a guarantee of safety.

此存储库中的示例工件：

• 示例报告/insecure-server.report.json
• 示例报告/insecure-server.report.sarif
• 样本报告/insecure-server.terminal.md

分数模型摘要

评分模型故意简单。

1. 开始于 100
2. 对调查结果应用固定的确定性惩罚
3. 将分数夹到 0..100
4. 以相同的方式计算bucket分数 conformance, security, ergonomics，以及 metadata

当前版本线中的严重性映射：

每个检查都携带明确的元数据：

• id
• title
• bucket
• severity
• rationale

每份报告都揭示了：

• 总分
• 类别分数
• 查找计数
• 带有完整元数据的调查结果
• 按桶分组的发现
• 为什么这个分数
• 分数含义和限制

这使输出在CI中保持可审查、可测试和稳定。

输出格式

MCP Scorecard 目前发出四种实际输出：

终端摘要

本地运行和CI日志的可读摘要。

JSON V1记分卡报告

标准的机器可读报告格式。稳定的V1顶级形状是：

• schema
• generator
• scan
• inventory
• scorecard
• checks
• findings
• grouped_findings
• metadata

萨里夫

适用于GitHub代码扫描和其他支持SARIF的消费者。SARIF与当前保持一致 研究结果模型，包括SARIF运行的记分卡元数据。

GitHub操作步骤摘要

PR友好的Markdown摘要，包括总分、通过/失败和类别分数。

JUnit有意地超出了当前版本的范围。

分数意味着什么

分数是一个确定的复习信号。

• 高分确实如此 不 平均安全
• 分数低 不 恶意的意思
• 该分数仅衡量确定性、可审查的属性

这意味着分数是有用的：

• CI门
• 审查基线
• 释放工件
• 对更广泛工程判断的输入

它不能替代运行时控制、沙盒、环境隔离或人工批准。

局限性

当前的限制是明确的：

• 主要交通重点是当地 stdio
• 检查是静态和确定性的，而不是动态或行为性的
• 运行时隔离超出范围
• 可利用性声明超出了范围
• 商业意图超出范围
• LLM评分超出范围
• 宿主扫描超出范围

这个范围是有意的。较小的确定性契约在CI中比更广泛的契约更有用 但系统不透明。

公共扫描快照

现在更有用的参考是 全批扫描 30 公共MCP服务器：

• MCP_SCORECAD_30_SERVER_BATCH.md
• MCP_SCORECAD_30_SERVER_BATCH.summary.json

该批次是更好的工件，因为它可以分离：

• 能够干净地启动和评分的服务器
• 启动但出现确定性审查问题的服务器
• 在盲CI条件下无法正常启动的服务器

从整批中选出有趣的例子：

整个批次也给出了一个更诚实的结论： MCP Scorecard 看起来有用，但可重复 大规模的公共扫描需要一个单独的飞行前/发射层。

输出和架构参考

• docs/architecture.md
• MCP_SCORECAD_30_SERVER_BATCH.md
• MCP_SCORECAD_30_SERVER_BATCH.summary.json
• docs/assets/filesystem-scan-hero.svg
• 示例/不安全服务器/README.md

路线图

当前发布表面后的近期工作：

• 扩展确定性检查 conformance, security, ergonomics，以及 metadata
• 在源上下文可用时改进SARIF位置映射
• 添加更多真实世界的验证案例和示例报告
• 一旦当前得分合同保持稳定，添加更多交通选项
• 清理repo/package/action引用周围的剩余兼容性命名

不在直接路径上：

• 核心发动机LLM评分
• 托管记分卡服务
• 发布路径中的注册表集成
• 认证风格声明

贡献

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
python -m pytest
python -m ruff check .
python -m mypy

良好贡献领域：

• 新的确定性检查与测试
• stdio 运输硬化
• 保持稳定输出的报告器改进
• 可重复验证案例
• 文档和样本工件

许可证

阿帕奇-2.0。看 许可证.