MCP Doctor

MCP Doctor

あらゆる MCP サーバーのコントラクト品質を、人間、エージェント、プラットフォーム向けに確認・改善します。

問題

ほとんどの MCP サーバーは、単一の利用者（通常は README を読む人間の開発者）だけを想定して構築されています。しかし、成功する MCP サーバーは、次の 3 つの利用者を同時に満たす必要があります。

• 配布プラットフォーム（Registry、Smithery、PulseMCP、Glama）には、構造化されたメタデータが必要です
• 人間のユーザーには、明確な目的、信頼性を示す情報、手間の少ないインストールが必要です
• AI エージェントには、曖昧さのないツールの説明、宣言された副作用、トークン効率の高い応答が必要です

MCP Doctor は「コントラクト品質」の 6 つの側面すべてを確認し、実行可能な改善案を提示します。

クイックスタート

pip install mcp-doctor
mcp-doctor check /path/to/your-mcp-server

チェック項目

項目	質問
タスクの明確さ	サーバーの目的はすぐにわかりますか？
信頼性と安全性	副作用、権限、安全上の境界が明示されていますか？
インターフェース品質	ツールの名前、説明、型は適切ですか？
トークン効率	ツールの応答はエージェントのコンテキスト予算に収まりますか？
インストールの手間	見つけてから最初に使うまで、どれくらい時間がかかりますか？
クロスプラットフォーム対応	Registry、Smithery、PulseMCP、Glama 向けのメタデータは揃っていますか？

使い方

CLI

# Terminal output (default, rule-based)
mcp-doctor check /path/to/server

# JSON output (for CI/CD)
mcp-doctor check /path/to/server --format json

# Markdown output (for README badges or reports)
mcp-doctor check /path/to/server --format markdown

# AI-enhanced evaluation (requires OPENAI_API_KEY)
mcp-doctor check /path/to/server --mode ai

# AI mode with a specific model
mcp-doctor check /path/to/server --mode ai --model gpt-4o

MCP サーバーとして

MCP Doctor 自体も MCP サーバーであるため、AI エージェントからほかのサーバーをチェックできます。

{
  "mcpServers": {
    "mcp-doctor": {
      "command": "python",
      "args": ["-m", "mcp_doctor.mcp_server"]
    }
  }
}

ツール：

• check_server(path, format, mode, model) — 6 つのチェックをすべて実行します。LLM によるレビューを強化するには、mode="ai" を使用します。
• list_dimensions() — MCP Doctor の評価項目を一覧表示します

AI エージェント向け：簡単なインストール

ワンライナー（AI エージェントに貼り付けてください）：

mcp-doctor（pip install mcp-doctor）をインストールし、コマンド python -m mcp_doctor.mcp_server を使って MCP 設定に追加してください。その後、check_server ツールを使って、任意の MCP サーバーの品質をチェックしてください。

手順：

1. インストール：pip install mcp-doctor
2. MCP 設定に追加します：

   {
     "mcpServers": {
       "mcp-doctor": {
         "command": "python",
         "args": ["-m", "mcp_doctor.mcp_server"]
       }
     }
   }
   

3. 任意の MCP サーバーリポジトリへのパスを指定して、check_server ツールを使います
4. MCP を利用できない場合は、CLI に切り替えます：mcp-doctor check /path/to/server --format json

エージェントのワークフロー： サーバーをチェック -> スコアを確認 -> 最も低い項目を特定 -> 改善案に従う

スコアリング

各項目は 0～100 点で採点され、A／B／C／D で評価されます。

• A（90+）：模範的
• B（75-89）：良好、軽微な不足あり
• C（55-74）：許容範囲、目立つ不足あり
• D（<55）：大幅な改善が必要

理論的基盤

MCP Doctor は コントラクト品質フレームワークに基づいています。このフレームワークの原則は、成功する MCP 製品の約束（何をするのか、費用はいくらか、どのようなリスクがあるか）が、プラットフォーム、人間、エージェントのいずれにも同じように解析できるべきだというものです。

このフレームワークは、次の内容を参考にしています。

• Anthropic の「エージェント向けの効果的なツールの作成」（ツール説明の設計、名前空間、トークン効率）
• 公式 MCP Registry の要件（server.json スキーマ、名前空間の検証）
• Smithery、PulseMCP、Glama のランキングシグナルに関するクロスプラットフォーム分析

評価モード

モード	フラグ	決定性	ネットワーク	API キー
ルールベース（デフォルト）	--mode rule	あり	なし	なし
AI 強化	--mode ai	なし	あり（LLM API）	OPENAI_API_KEY

ルールベースモードは完全にオフラインで動作し、結果は決定的です。ネットワーク呼び出し、LLM、API キーは必要ありません。

AI モードでは、メタデータの概要（サーバー名、ツール定義、README のプレビュー、ルールベースのスコア）を OpenAI 互換 API に送信し、定性的なレビューを行います。ソースコードは送信されません。レポートには、再現性を確保するためモデル名とバージョンが含まれます。

AI モードは、次の OpenAI 互換プロバイダーに対応しています：

• OPENAI_API_KEY — API キー（AI モードで必須）
• OPENAI_BASE_URL — カスタムエンドポイント（Ollama、vLLM、LM Studio、Azure など）
• MCP_DOCTOR_MODEL — モデル名（デフォルト：gpt-4o-mini）

AI サポートをインストールするには：pip install mcp-doctor[ai]

信頼と権限

MCP Doctor は読み取り専用です。ファイルの変更、削除、作成は一切行いません。

アクセス対象	理由
server.json	MCP メタデータを解析するため
README.md	ドキュメントの品質を確認するため
LICENSE	ライセンスの存在を確認するため
src/ 内の *.py、*.json	ツール定義を検出するため

すべての MCP ツールには、readOnlyHint: true と destructiveHint: false の注釈があります。

フィードバック

バグを見つけましたか？提案がありますか？ぜひお知らせください：

• GitHub Issues：https://github.com/Jiansen/mcp-doctor/issues
• 簡単な報告（gh CLI をお持ちの場合）：

  gh issue create --repo Jiansen/mcp-doctor --title "Bug: ..." --body "..."
  

エージェントの場合は、報告のコンテキストとして check_server の JSON 出力を含めてください。

コントリビューション

git clone https://github.com/Jiansen/mcp-doctor.git
cd mcp-doctor
pip install -e ".[dev,ai]"
ruff check src/ tests/
pytest tests/ -v

---

MCP Doctor がサーバーの改善に役立った場合は、GitHub でスターを付けることをご検討ください。他の人がこのツールを見つけやすくなります。

ライセンス

MIT