mcp-scorecard

mcp-scorecard

适用于任意 MCP 服务的 Agent 就绪度评分卡。
通过 stdio 探测目标，执行 10 项检查，并输出 0-100 分的评分及逐项检查结果。

---

快速开始

# Audit a published npm package
npx -y mcp-scorecard whoop-mcp-unofficial

# Audit a GitHub repo (auto-resolves to the published npm package, or local dist)
npx -y mcp-scorecard https://github.com/davidmosiah/whoop-mcp

# Audit a local build (entry file or package directory)
npx -y mcp-scorecard /Users/you/Desktop/my-mcp/dist/index.js
npx -y mcp-scorecard ./my-mcp          # resolves package.json bin/main
npx -y mcp-scorecard ./dist/index.js   # relative paths work offline

# CI gate: fail the build if the score drops
npx -y mcp-scorecard my-mcp --min-score 80

# Structured JSON for piping into your own tooling
npx -y mcp-scorecard my-mcp --json

# Run scorecard itself as an MCP server (stdio default)
npx -y mcp-scorecard serve

# Same server on Streamable HTTP — v2 stateless, loopback only
npx -y mcp-scorecard serve --http
# GET  http://127.0.0.1:3000/health
# POST http://127.0.0.1:3000/mcp   (sessionless)

HTTP 环境变量：MCP_SCORECARD_HOST、MCP_SCORECARD_PORT、MCP_SCORECARD_TRANSPORT=http。

演示

对官方 MCP 参考服务 @modelcontextprotocol/server-everything 进行审计的真实运行记录——这里的内容未经手动编辑，完全是 CLI 打印的原文：

$ npx -y mcp-scorecard @modelcontextprotocol/server-everything

# mcp-scorecard - @modelcontextprotocol/server-everything @2026.1.26

**Agent-readiness score:** 44/100

- [PASS] Schema validity              (13/13 tools have valid input schema)
- [FAIL] Tool naming convention       (12/13 tools violate snake_case)
- [FAIL] Privacy modes documented     (only 1 tool(s) mention privacy modes)
- [PASS] Mutation gating              (no write tools — n/a)
- [FAIL] Agent manifest               (no agent_manifest tool)
- [FAIL] Smoke test                   (no smoke script and no test script)
- [PASS] Resources advertised         (7 resources registered)
- [PASS] Tool descriptions            (avg 88 chars across 13 tools)
- [FAIL] Annotations                  (0/13 read tools annotated)
- [FAIL] Manifest discoverability     (no discovery tools)

## Details
### Tool naming convention
- Non-snake_case names: get-annotated-message, get-env, get-resource-links, get-resource-reference, get-structured-content, get-sum, get-tiny-image, gzip-file-as-resource, toggle-simulated-logging, toggle-subscriber-updates
### Annotations
- Missing readOnlyHint: echo, get-annotated-message, get-env, get-resource-links, get-resource-reference, get-structured-content, get-sum, get-tiny-image, gzip-file-as-resource, toggle-simulated-logging

## Suggested fixes
- Rename tools to lowercase snake_case (a-z, 0-9, _).
- Add a `privacy_mode` parameter (summary | structured | raw) on read tools so agents can request only what they need.
- Expose a `<prefix>_agent_manifest` tool that returns { recommended_first_calls, standard_tools, ... } so agents can self-onboard.
- Add `scripts/smoke-tools.mjs` that boots the server via StdioClientTransport and asserts the tool list.
- Add `annotations: { readOnlyHint: true, openWorldHint: false }` to every read tool definition.
- Expose discovery tools so agents can self-onboard: `*_agent_manifest`, `*_data_inventory`, `*_capabilities`, `*_connection_status`.

参考服务是功能展示项目，而非生产环境集成——得分 44 是预期之中的结果，这也正是约定检查存在的原因。采用 snake_case 命名、提供清单工具并使用只读注释的 Agent 导向型服务，得分可达 80 多分和 90 多分。

检查内容

十个质量维度，每项计 0-10 分。最终得分为各项分数之和，最高为 100 分。

1. 架构有效性 - 启动服务，列出工具，并使用 ajv 验证每个工具的 inputSchema。每个缺失架构或架构非对象的工具计零分。
2. 工具命名规范 - 鼓励使用统一前缀和 snake_case（例如 whoop_get_sleep）。混用大小写、使用连字符或缺少前缀都会扣分。
3. 隐私模式说明 - 检查是否有工具带 privacy_mode 参数，或其描述中提及 summary | structured | raw。
4. 变更操作门控 - 任何名称匹配 (set|update|delete|create|pause|resume|enable|disable|cancel|publish|send) 的工具，都必须在描述中说明门控条件（Gated by ALLOW_MUTATIONS、requires explicit user intent、dry-run、confirm）。
5. Agent 清单 - 调用 <prefix>_agent_manifest，并检查响应对象是否包含非空数组 recommended_first_calls 和非空数组 standard_tools。探测器绝不持久化有效载荷，只记录字段名称和长度。
6. 是否提供冒烟测试 - 检查包中是否有 scripts/smoke*.{mjs,js,ts}，或 package.json 中是否有实际的 test 脚本（而非 npm 默认的 echo-and-fail）。
7. 是否公布资源 - 统计 listResources() 返回的内容。返回零个计零分；返回一个或两个计 5 分；返回三个或更多计 10 分。
8. 工具描述 - 所有工具描述的平均长度。少于 30 个字符计 0 分；30-60 个字符计 5 分；60 个字符及以上计 10 分。
9. 注解 - 统计只读工具（任何非变更操作工具）中带有 annotations.readOnlyHint = true 的比例。分数按比例线性计算。
10. 清单可发现性 - 是否包含以下任一项：*_agent_manifest、*_data_inventory、*_capabilities、*_connection_status。包含两项或更多计 10 分；恰好一项计 7 分；没有则计 0 分。

输出格式

Markdown（默认）

# mcp-scorecard - whoop-mcp-unofficial @0.4.3

**Agent-readiness score:** 88/100

- [PASS] Schema validity              (28/28 tools have valid input schema)
- [PASS] Tool naming convention       (consistent `whoop_` prefix, snake_case)
- [PASS] Privacy modes documented     (privacy_mode parameter on 6 tool(s))
- [PASS] Mutation gating              (no write tools - n/a)
- [PASS] Agent manifest               (recommended_first_calls present, 5 entries)
- [PASS] Smoke test                   (scripts/smoke-tools.mjs found)
- [PASS] Resources advertised         (8 resources registered)
- [PASS] Tool descriptions            (avg 142 chars across 28 tools)
- [WARN] Annotations                  (20/28 read tools annotated)
- [PASS] Manifest discoverability     (4/4 discovery tools present (agent_manifest, data_inventory, capabilities, connection_status))

## Suggested fixes
- Add `annotations: { readOnlyHint: true, openWorldHint: false }` to every read tool definition.

_Generated by mcp-scorecard v0.1.0 at 2026-05-23T15:42:11.000Z_

JSON（--json）

{
  "target": {
    "displayName": "whoop-mcp-unofficial",
    "version": "0.4.3",
    "serverName": "whoop-mcp",
    "serverVersion": "0.4.3"
  },
  "totalScore": 88,
  "checks": [
    {
      "id": "schema_validity",
      "label": "Schema validity",
      "score": 10,
      "status": "pass",
      "summary": "28/28 tools have valid input schema",
      "details": [],
      "fixes": []
    }
  ],
  "generatedAt": "2026-05-23T15:42:11.000Z",
  "scorecardVersion": "0.1.0"
}

探测方式

评分卡会通过 stdio 启动目标 MCP 服务，并在子进程环境中设置 MCP_PROBE=1。只会继承 MCP SDK 的平台专属运行时环境允许列表（例如 Unix 系统上的 PATH 和 HOME）；不会转发 Shell API 密钥、身份验证套接字、代理设置以及 NODE_OPTIONS 等代码加载设置。**作者提示：**如果你的 MCP 需要 OAuth 或其他凭据才能列出工具，请检测此环境变量，并仍然返回工具／资源／提示词清单。评分卡预期 能够读取你的接口契约，而无需调用任何要求身份验证的 API。

stdio 审计会以当前 OS 用户身份执行目标代码，并可能调用 *_agent_manifest 工具。这并非只读或幂等操作，也不会对文件系统访问、网络访问或目标产生的影响进行沙箱隔离。仅审计可信目标；对于不可信代码，请使用单独的隔离环境。MCP_PROBE=1 只是请求目标配合，无法强制执行这些限制。

隐私模型

• 探测响应绝不持久化。只会将数量和字段名称记录到检查使用的内存快照中。
• 报告中的任何字符串都会经过脱敏处理，将 customer_id、email、phone、access_token、refresh_token、client_secret、developer_token 和 api_key 的值替换为 [REDACTED]。
• 评分卡不会发送遥测数据。解析 npm/GitHub 目标时可能会使用网络，托管 URL 审计会发送 HTTP 请求，执行的 stdio 目标也可能自行发起网络请求。探测器的环境允许列表无法阻止访问存储在文件或 OS 服务中的凭据。

用例

• CI 门禁——如果分数低于阈值，则阻止 PR： npx -y mcp-scorecard my-mcp --min-score 85。
• 目录筛选——对 MCP 列表运行审计，为目录或 清单挑选文档最完善、对 Agent 最友好的选项。
• 发布前自检——将其添加到 prepublishOnly，以免 意外发布不合规的契约。
• 对比评审——为两个表面上覆盖相同 API 的 MCP 评分， 看看哪个对 Agent 更友好。

局限性

• 无法探测在 listTools() 返回之前就要求身份验证的 MCP。如果 你的服务属于这类，请支持 MCP_PROBE 环境变量钩子，以便 评分卡仍能读取你的契约。
• 无法评估逻辑正确性——评分卡只检查结构、 元数据和可发现性。服务即使得分为 100/100，也仍可能 返回错误数据。
• 变更检测基于名称——如果你把写入工具命名为 prepare_thing 而不是 set_thing，检查就会漏掉它。这 是有意为之：我们鼓励使用清晰的命名。

路线图

• v0.2——针对 agent-rules-of-thumb 的规则包（输出结构稳定性、 分页模式、错误封装一致性）、性能基准测试 （listTools() 的中位延迟），以及使用模拟令牌的 OAuth 探测。

支持

• 问题反馈：https://github.com/davidmosiah/mcp-scorecard/issues
• 电子邮件：[email protected]

免责声明

这是一款质量审计工具。它不认证安全性、隐私性 或正确性；它只衡量服务是否遵循对 Agent 友好的 惯例。将 MCP 接入生产环境中的 Agent 之前，请务必自行审查。

许可证

MIT——参见 LICENSE。（行为准则。）

---

v0.3.0 新增功能——差异化特性

• 将其作为 MCP 服务运行，让 Agent 可以在任务中途调用它：

  { "mcpServers": { "mcp-scorecard": { "command": "npx", "args": ["-y", "mcp-scorecard", "serve"] } } }
  

  这样，你的 Agent 就可以在安装前调用 audit("some-mcp-server")。一个为 MCP 评分的 MCP。
• 按 URL 审计托管/远程服务（12 项安全性和 Agent 就绪度检查）：npx -y mcp-scorecard https://your-server
• 为你的 README 添加徽章： npx -y mcp-scorecard my-mcp --badge → 生成一个 shields.io markdown 徽章。
• GitHub Action：

  - uses: davidmosiah/[email protected]
    with:
      target: dist/index.js
      min-score: 80
  

v0.4.0

• mcp-scorecard compare a b c——并排排名。
• --profile security|quality|agent-ready——为单个类别评分。--baseline old.json——回归差异对比。--html——可分享的评分卡。
• 检查项说明：https://mcp-scorecard.vercel.app/checks.html