pytestの失敗をMCPサーバーでClaudeに解析させる — 9原則デバッグの使い方

pytest-mcp-serverは、pytestで失敗したテストを構造化して記録し、決まった9段階のデバッグ原則を1つずつ適用させるための非公式MCPサーバーです。pytest本体やAnthropicが提供するものではなく、個人開発者(GitHubアカウントtosin2013)が公開しているnpmパッケージです。ログをそのまま貼り付けて「原因を教えて」と頼むのとの違いは、失敗の記録とデバッグの進行状況がサーバー側のファイルに残り、セッションをまたいでも「どこまで調べたか」が引き継がれる点にあります。原則をすべて踏むかどうかはClaude次第ですが、少なくとも記録の器としては同じ土台を使い続けられます。

提供される8つのツール

サーバーが公開するツールは、次の8つです。

中心になるのはregister_pytest_failureとdebug_with_principleの組み合わせで、残りのツールは記録の参照・横断分析・動作確認の補助に回ります。

骨格になっている9つのデバッグ原則

debug_with_principleが適用する原則は、ソースコード内に固定の9項目として定義されています。README単体では「9原則」としか説明されていませんが、実装を確認すると次の内容でした。

debug_with_principleをprinciple_numberなしで呼び出すと、その失敗のcurrent_debug_step(今どの原則まで進んだか)を自動で参照し、次の原則を適用します。1つの原則を終えるたびにサーバー側が次のステップ番号を記録するため、Claudeに「続きから調べて」と頼むだけで、9つの原則を順番に踏んでいく進行管理が成立します。「なぜこの修正に至ったか」という調査過程が、単発の質問応答と違って9ステップの記録としてサーバー側に残る点が、このツールの特徴です。

Claude Codeに接続する

前提はNode.js 18.19.0以上です。この条件を満たしたうえで、npmコマンドでグローバルインストールします。

npm install -g pytest-mcp-server

READMEのセットアップ例はClaude Desktopの設定ファイルに書く形式で示されていますが、Claude Codeではclaude mcp addコマンドで同じ内容を登録します。標準入出力(stdio)モードでサーバーを起動するstartサブコマンドを、そのままClaude Codeに登録します。失敗記録の保存先はDATA_DIR環境変数で明示的に指定します。

claude mcp add --env DATA_DIR=/path/to/pytest-data --transport stdio pytest \
  -- pytest-mcp-server start

登録後は/mcpでConnectedになっているか確認します。start-httpサブコマンドを使うとHTTPサーバーとして起動する選択肢もあります(既定ポート3001、PORT環境変数で変更可能)。ただしこの場合はstdio接続とは別に、Claude Code側もHTTPトランスポートで登録し直す必要があります。

いきなりClaude Codeに登録する前に、8つのツールがどう応答するかを確認したいときはMCP Inspectorが使えます。グローバルインストール済みならpytest-mcp-server startをそのままInspectorに渡します。

npx @modelcontextprotocol/inspector pytest-mcp-server start

ブラウザ上でツール一覧を開くと、example_toolという動作確認専用のサンプルツールも並んでいます。これを1回呼んでみて応答が返ってくれば、サーバー自体は正常に起動できているとわかります。8つのツールすべてを個別に叩けるので、実際のテスト失敗を登録する前段階の疎通確認として使えます。

失敗を登録してから原則を進める

典型的な使い方は、失敗したテストの情報をそのまま渡すところから始まります。

test_user_authenticationがAssertionError: Expected status 200, got 401で落ちた。
ファイルはtests/test_auth.pyの45行目。この失敗を登録して

Claudeはregister_pytest_failureに次のような形式で情報を渡し、テスト名・ファイルパス・行番号・エラーメッセージ・トレースバックを記録します。

{
  "name": "register_pytest_failure",
  "arguments": {
    "test_name": "test_user_authentication",
    "file_path": "/tests/test_auth.py",
    "line_number": 45,
    "error_message": "AssertionError: Expected status 200, got 401",
    "traceback": "Full traceback here..."
  }
}

続けて「原則1から順に見て」と頼むと、debug_with_principleが「Understand the System」から順番に呼ばれます。各ステップではanalysisという引数にClaude自身の分析内容を渡す必要があり、この分析結果がそのままdebug_sessions.jsonに積み上がっていきます。原則を1つ終えるたびに、サーバー側は次に適用すべき原則の番号と名前を返すので、Claudeは「次はDivide and Conquerです」といった形で自然に次の一手を提示できます。

複数の失敗が溜まってきたらanalyze_failuresでパターン分析にかけると、同じ原因が別のテストケースにも波及していないかを横断的に確認できます。generate_debug_promptは、失敗1件(failure_id)または失敗グループ(group_id)を指定して、detailed・concise・step_by_step・root_causeの4形式でデバッグ用プロンプトを生成するツールです。detailedは根本原因の分析・修正方針・検証手順の3点をまとめて求める形式、conciseは原因と解決策を手短に求める形式、step_by_stepはパターン分析→根本原因の特定→修正案→検証手順の4手順を順に進めるよう指示する形式、root_causeは修正を求めず根本原因の特定だけに絞る形式です。失敗1件を指定した場合はstep_by_stepはdetailedと同じ内容になります。他の担当者への引き継ぎや、別のAIツールに続きを頼むときなど、記録の中身を目的に応じた粒度に整形して取り出す用途に使えます。どの形式が適しているかは渡す相手次第なので、まずはconciseで試して、情報が足りなければdetailedに切り替えるのが手早いやり方です。

登録済みの失敗を一覧・参照する

原則を進める以外にも、記録した失敗を後から見返すためのlist_failuresとget_failure_infoがあります。

今登録されている失敗を全部一覧して

test_user_authenticationの失敗の詳細を教えて

list_failuresは登録済みの全件を返すシンプルなツールで、複数のテストを並行して調べているときに「どれがまだ手を付けていないか」を確認する用途に使えます。get_failure_infoはcurrent_debug_stepを含む詳細情報を返すため、数日空けて作業を再開したときに「前回どこまで進んでいたか」をすぐに思い出す起点になります。テストスイート全体を一度に流して複数の失敗が出た場合でも、1件ずつregister_pytest_failureで登録しておけば、あとからlist_failuresで全体を見渡しながら優先度を付け直せます。pytest自体の使い方に迷ったときのために、pytestのドキュメントガイドを返すpytest_docs_guideというツールも用意されています。

導入前に確認しておきたいこと

npmレジストリを見ると、pytest-mcp-serverの最新バージョンは1.1.6で、2025年5月15日に公開され、5月18日の更新を最後に動きが止まっています。README自体は「Production Ready」と明記していますが、パッケージとしての更新はしばらく止まっている状態です。導入前に、自分の使い方が壊れていないかを軽く動作確認しておくと安心です。

もう1つ知っておくべきなのが、README内に明記されている既知の不具合です。依存しているライブラリmcp-frameworkのバージョン0.2.13に、バリデーションエラーをMCP仕様どおりの"type": "text"ではなく"type": "error"として返してしまう挙動があります。pytest-mcp-server自体のコードではなく、依存先ライブラリの挙動に起因する問題です。これは自動テストフレームワーク(MCP Testing Framework)でサーバーを検証したときにだけ表面化する問題で、README自身も「実際の利用には影響しない」としています。Claude Codeから通常どおり使う分にはこの問題を意識する必要はありませんが、CI等でこのサーバー自体をテストしようとして原因不明のバリデーション失敗に遭遇した場合は、この既知の問題が該当していないか、まず疑ってみるとよいでしょう。

データの保存先はDATA_DIR配下のJSONファイル(failures.jsonとdebug_sessions.json)です。複数人で同時に書き込む前提の排他制御は見当たらないため、個人の開発マシン上で、自分がいま追っている失敗の進行状況を残しておくための手元ツールと捉えておくのが実態に近い理解です。

よくあるつまずき

• DATA_DIRを指定し忘れて記録がバラバラになる: 未設定時は実行時のカレントディレクトリからの相対パス./dataが使われます。プロジェクトディレクトリを行き来しながら使うと、記録が複数の./dataに分散してしまうため、登録コマンドの時点で絶対パスを指定して固定しておくのが安全です
• principle_numberに1〜9の範囲外を渡してエラーになる: ツールは範囲外の値を明示的にエラーとして返します。何も指定しなければ現在のステップから自動で進むので、通常は省略して問題ありません
• 同じ原則をやり直したいのに次に進んでしまう: debug_with_principleは1回の呼び出しごとに次のステップへcurrent_debug_stepを進める設計です。同じ原則を再検討したい場合はprinciple_numberを明示的に指定して呼び出します
• MCP Testing Frameworkでバリデーションエラーが出て動かないと思い込む: 前述のmcp-framework 0.2.13起因の既知の問題です。実際のMCPクライアント(Claude Code含む)からの利用には影響しません
• start-httpで立てたのにstdio接続の設定のまま使おうとする: トランスポートが違うため、HTTPで起動した場合はClaude Code側もHTTPサーバーとして登録し直す必要があります

まとめ

pytest-mcp-serverは、失敗したテストの記録と9段階のデバッグ原則の適用状況をサーバー側に保持することで、「前回どこまで調べたか」をClaudeとの対話をまたいで引き継げるようにする非公式ツールです。原則そのものは特別な発明ではなく、システム理解から再現、絞り込み、修正の検証まで、地道なデバッグの定石を順序立てて踏ませる仕組みに価値があります。個人が公開しているnpmパッケージであり更新も止まり気味なので、本番のCIパイプラインに組み込む前に手元での動作確認は挟んでおきます。まずはMCP Inspectorでexample_toolを叩いて疎通を確認し、実際のテスト失敗の登録はそのあとに回すくらいの慎重さが安全です。

Claude CodeでTDDを回す前提の運用はClaude Codeでテスト駆動開発を回す手順、渡す情報の質でデバッグの精度がどう変わるかはClaude Codeデバッグの精度は渡す情報の質で決まるにまとめています。自作・非公式のMCPサーバーの動作を事前に確認する方法はMCP Inspectorの使い方を参照してください。