verify-local-mcp

ローカル MCP を検証する

順番に 2 つのレイヤーで検証します。プロトコルレイヤーではサーバーとプロバイダーが正しく動作することを確認し、コンシューマーレイヤーではコードを見たことのないエージェントがツールを適切に使えることを確認します。それぞれ異なるバグを見つけます。プロトコルテストでは DataForSEO の癖（ズームレベルによって SERP が空になる）が見つかり、コンシューマープローブでは使い勝手の問題（9KB のプロバイダーの行データがクライアントのトークン予算を超える、端数入力が上流で拒否されてプロバイダーの生のエラーが返る）が見つかりました。両方実施してください。

1. 起動

• .env.local に AUTH_MODE=local_noauth と DATAFORSEO_API_KEY（login:password を base64 エンコードした値）が必要です。キーは絶対に表示しないでください。
• pnpm dev:agents をバックグラウンドで起動します。サーバー URL にはブランチの接頭辞が付きます：http://<branch-suffix>.open-seo.localhost:1355（正確な URL は起動時に表示されます。ログは .logs/dev-server.log に tee されます）。
• local_noauth では、/mcp にトークンは不要です。Vite はサーバーコードをホットリロードするため、修正したら再起動せずに再度呼び出せます。
• ツールの入力または出力スキーマを変更した後は、クライアントのツール検出を更新（tools/list）するか、MCP クライアントに再接続してから再度呼び出してください。クライアントは以前のツール一覧のバリデーターをキャッシュしている場合があり、その場合、プロバイダー呼び出しで課金された後に有効な結果を拒否することがあります。

2. プロトコルのスモークテスト（低コストで決定的）

/mcp に対して生の JSON-RPC を実行します。正確な形状の検証やエッジケース（タスク ID の再開、空の結果、無効な入力）のテストに使うレイヤーです：

curl -sS http://<url>/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# tools/call: {"method":"tools/call","params":{"name":"<tool>","arguments":{...}}}

• 初期化：list_projects を実行し、プロジェクトが空の場合は create_project を実行します。ほとんどのツールには projectId が必要です。
• 変更した各ツールについて、正常系に加えて少なくとも 1 つのエッジケースをテストします：空の結果（見つかりにくいクエリ）、無効な識別子、キューに登録されるツールの場合は、返された taskId を使った再開を含むライフサイクル全体。
• これらは実際に課金される DataForSEO の呼び出しです（local_noauth では計測処理自体がショートサーキットされるため、課金のテストには使わず、ユニットテストを実施してください）。深度は 10〜20 に抑えます。

3. コンシューマープローブ（使い勝手のテスト）

実際の MCP クライアントとして接続する、ヘッドレスの Claude サブプロセスを起動します。設定を書き込みます：

{
  "mcpServers": {
    "openseo-local": { "type": "http", "url": "http://<url>/mcp" }
  }
}

次に、自然なタスクを実行します。ツール名は絶対に指定しないでください。モデルが説明だけを頼りにツールを見つけられるかをテストします：

claude -p "<natural task a customer would ask>. Keep spend minimal: depths 10-20, one 3x3 grid max, ~10 paid calls.
Deliver two sections: 1. FINDINGS — the task result. 2. MCP FEEDBACK — critique the MCP as a first-time consumer:
were descriptions enough to pick tools without trial and error? confusing schemas, surprising output shapes or sizes,
unclear errors, credit-cost surprises? Did async/taskId flows behave as described? List anything that made you hesitate or retry." \
  --mcp-config mcp-local.json --strict-mcp-config \
  --allowedTools "mcp__openseo-local,mcp__openseo-local__*" \
  --model sonnet --max-turns 30

典型的なクライアントの代わりとして --model sonnet を使います。Sonnet が事前情報なしで使いこなせれば、性能の低いクライアントでも使える可能性が高いでしょう。正確さについては FINDINGS を確認し（実際の妥当なデータを取得できたか）、下記の評価基準については MCP FEEDBACK を確認します。

4. 使い勝手の評価基準 — 対応すべきフィードバック

• ツールの選択：プローブは最初の試行で適切なツールを選ぶ必要があります。再試行や誤ったツールへの寄り道がある場合は、「どんなときに使うか／使わないか」を説明に明確に記述する必要があります。
• スキーマ：プロバイダーが暗黙的に適用する制約はすべて、フィールドの .describe() に記載する必要があります（単位、整数である必要性、デフォルト値、無視される条件など）。プローブが入力を推測して再試行した場合は、サーバー側でルールを実装（強制変換／丸め）するか、説明に記載してください。強制変換を優先します。
• 出力サイズ：行ごとのサイズは数 KB 程度を目安にします。popular_times／属性ツリー／写真 URL を含むプロバイダーの行データは、ツールの目的に必要なフィールドだけに絞り、完全な形状が必要な場合は単一エンティティ用のツールを案内してください。
• エラー：対処方法がわかる内容にし、修正のヒントもなく上流のフィールド名だけを生で返すことは避けてください。課金済みの手順後に失敗した場合は、メッセージに復旧用の情報（例：taskId）を残す必要があります。
• 非同期処理の説明：説明は一般的な所要時間（「通常はこの呼び出し中に完了します」）と一致させます。プローブで実行した場合も、curl でのテストだけでなく、再開処理が実際に動作する必要があります。
• クレジットの正確さ：キャッシュヒットや再開処理を含め、各説明に記載されたクレジットに関する説明は実際の動作と一致する必要があります。

5. 繰り返し検証して整理する

指摘を修正し、ホットリロードで反映されたことを確認したら、変更した動作だけを curl で再検証します（低コスト）。その後、反復ごとにコンシューマープローブを 1 回実行します（修正箇所だけでなく、ツール選択と実行フローも再テストします）。完了したら、バックグラウンドの開発サーバータスクを停止し、リポジトリのテスト／ci:check を実行します。また、プロバイダー固有の実際の癖はコードコメントまたはテストに反映し、次のエージェントが同じ問題を再発見しなくて済むようにします。