mcp-scorecard

mcp-scorecard

あらゆる MCP サーバーのエージェント対応度を評価するスコアカードです。
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 の命名、マニフェストツール、読み取り専用アノテーションを採用したエージェント向けサーバーは、80 点台から 90 点台になります。

チェック項目

10 の品質項目をそれぞれ 0〜10 点で評価します。最終スコアは合計点で、上限は 100 点です。

1. スキーマの妥当性 - サーバーを起動してツールを一覧表示し、各ツールの inputSchema を ajv で検証します。スキーマがない場合、またはオブジェクトでない場合、そのツールのスコアは 0 点です。
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. エージェントマニフェスト - <prefix>_agent_manifest を呼び出し、応答オブジェクトに recommended_first_calls（空でない配列）と standard_tools（空でない配列）の両方があることを確認します。プローブはペイロードを決して永続化しません。記録されるのはフィールド名と配列の長さのみです。
6. スモークテストの有無 - パッケージ内の scripts/smoke*.{mjs,js,ts}、または package.json の実際の test スクリプトを確認します（npm のデフォルトである echo-and-fail は対象外です）。
7. リソースの公開 - listResources() が返す数を数えます。0 件は 0 点、1〜2 件は 5 点、3 件以上は 10 点です。
8. ツールの説明 - すべてのツールの説明の平均文字数を評価します。30 文字未満は 0 点、30〜60 文字は 5 点、60 文字以上は 10 点です。
9. アノテーション - 読み取りツール（変更操作でないツール）のうち、annotations.readOnlyHint = true を持つものの割合を数えます。スコアは割合に応じて線形に変化します。
10. マニフェストの見つけやすさ - *_agent_manifest、*_data_inventory、*_capabilities、*_connection_status のいずれかがあるかを確認します。2 つ以上は 10 点、1 つは 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"
}

プローブの仕組み

スコアカードは、子プロセスの環境変数に MCP_PROBE=1 を設定して、対象の MCP サーバーを stdio 経由で起動します。継承されるのは、MCP SDK のプラットフォーム固有のランタイム環境許可リスト（Unix の PATH や HOME など）のみです。シェルの 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 のリストに対して監査を実行し、ディレクトリやカタログに掲載する、最もドキュメントが充実していてエージェントにとって使いやすい選択肢を選びます。
• 公開前のセルフチェック - prepublishOnly に追加すれば、コントラクトに問題が再発した状態で誤ってリリースするのを防げます。
• 比較レビュー - 同じ API を対象としていると思われる 2 つの MCP を採点し、どちらがエージェントにとって使いやすいかを確認します。

制限事項

• listTools() が返される前に認証を必須とする MCP はプローブできません。このようなサーバーをお使いの場合は、スコアカードがコントラクトを読み取れるよう、MCP_PROBE 環境フックをサポートしてください。
• ロジックの正しさは評価できません。スコアカードが調べるのは構造、メタデータ、検出可能性のみです。サーバーは 100/100 を獲得しても、誤ったデータを返すことがあります。
• 変更の検出は名前に基づきます。書き込みツールを set_thing ではなく prepare_thing と名付けた場合、チェックでは検出できません。これは意図的なものです。明確な命名を評価します。

ロードマップ

• v0.2 - agent-rules-of-thumb のルールパック（出力形式の安定性、ページネーションのパターン、エラーエンベロープの一貫性）、パフォーマンスベンチマーク（listTools() のレイテンシ中央値）、モックトークンを使った OAuth プローブ。

サポート

• 課題：https://github.com/davidmosiah/mcp-scorecard/issues
• メール：[email protected]

免責事項

これは品質監査ツールです。セキュリティ、プライバシー、正しさを認証するものではなく、サーバーがエージェントにとって使いやすい慣例に従っているかどうかを測定するだけです。MCP を本番環境のエージェントに接続する前に、必ずご自身でレビューしてください。

ライセンス

MIT - LICENSE を参照してください。行動規範。

---

v0.3.0 の新機能 — 差別化ポイント

• MCP サーバーとして実行し、エージェントがタスクの途中で呼び出せるようにします：

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

  これにより、エージェントはインストール前に audit("some-mcp-server") を実行できます。MCP を採点する MCP です。
• URL を指定してホスト型／リモートサーバーを監査します（セキュリティとエージェント対応状況を 12 項目でチェック）：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 — 1 つのカテゴリを採点します。--baseline old.json — 回帰差分を表示します。--html — 共有可能なスコアカードを作成します。
• チェックの解説：https://mcp-scorecard.vercel.app/checks.html