MCP動作確認ガイド

このスキルは、orm-discovery-mcp-goサーバーの動作確認とデバッグ手法を提供します。

概要

MCPサーバーのテストは、標準入出力(stdio)モードまたはHTTPモードで行います。CLIコマンドは実装されていないため、すべての機能テストはMCPプロトコル経由で実施します。

提供するMCPエンドポイント

カテゴリ	エンドポイント
ツール	`search_content`, `ask_question`
リソース	`book-details`, `book-toc`, `book-chapter`, `answer`
プロンプト	`learn-technology`, `research-topic`, `debug-error`

クイックスタート

サーバー起動

bash

# ビルド
task build

# stdioモード(デフォルト)で起動
./bin/orm-discovery-mcp-go

# デバッグモードで起動(詳細ログ + スクリーンショット)
ORM_MCP_GO_DEBUG=true ./bin/orm-discovery-mcp-go

# HTTPモードで起動
TRANSPORT=http PORT=8080 ./bin/orm-discovery-mcp-go

環境変数

変数	説明	必須
`OREILLY_USER_ID`	O'Reillyアカウントのメールアドレス	✅
`OREILLY_PASSWORD`	O'Reillyパスワード	✅
`TRANSPORT`	トランスポートモード: `stdio` または `http`	❌ (デフォルト: stdio)
`PORT`	HTTPサーバーポート	❌ (デフォルト: 8080)
`ORM_MCP_GO_DEBUG`	デバッグモード有効化	❌
`ORM_MCP_GO_LOG_LEVEL`	ログレベル: `DEBUG`, `INFO`, `WARN`, `ERROR`	❌ (デフォルト: INFO)
`ORM_MCP_GO_DEBUG_DIR`	デバッグ用ディレクトリ(全パスを上書き)	❌

XDG Base Directory Specification

ファイル保存先はXDG Base Directory Specificationに準拠しています。

用途	XDG環境変数	デフォルトパス
ログ、Chrome一時データ、スクリーンショット	`$XDG_STATE_HOME`	`~/.local/state/orm-mcp-go/`
Cookie	`$XDG_CACHE_HOME`	`~/.cache/orm-mcp-go/`
将来の設定ファイル	`$XDG_CONFIG_HOME`	`~/.config/orm-mcp-go/`

保存ファイル詳細:

•StateHome: Chrome一時データ(chrome-user-data-{PID}/)、スクリーンショット(screenshots/)、ログ(orm-mcp-go.log)
•CacheHome: Cookie(cookies.json) - 再生成可能なデータのため

環境変数の優先度:

•ORM_MCP_GO_DEBUG_DIR (デバッグ用、最優先)
•XDG環境変数
•デフォルトパス

テスト手法

1. Claude Codeからのテスト(推奨)

最も簡単な方法は、Claude CodeをMCPクライアントとして使用することです。

手順:

•MCPサーバーを起動: ./bin/orm-discovery-mcp-go
•Claude Codeでツールとリソースにアクセス
•
各シナリオをテスト:
- •コンテンツ検索: "Search for books about machine learning"
- •Q&A: "Ask about Python best practices for beginners"
- •リソースアクセス: 書籍詳細やチャプター内容を取得
- •プロンプト: "learn-technologyプロンプトでKubernetesの学習パスを生成して"

2. JSON-RPCリクエストによるテスト

stdioモードのサーバーに対してJSON-RPCリクエストを送信します。

search_content ツールのテスト

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_content",
    "arguments": {
      "query": "Docker containers"
    }
  }
}

ask_question ツールのテスト

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "ask_question",
    "arguments": {
      "question": "What career paths are available for software engineers in their late 30s?",
      "max_wait_minutes": 5
    }
  }
}

リソースアクセスのテスト

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/read",
  "params": {
    "uri": "oreilly://book-details/9781098166298"
  }
}

プロンプトのテスト

prompts/list - 利用可能なプロンプト一覧

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "prompts/list",
  "params": {}
}

期待される応答:

•learn-technology: 技術の学習パス生成
•research-topic: 技術トピックの調査
•debug-error: エラーデバッグガイド

prompts/get - プロンプト内容の取得

json

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "prompts/get",
  "params": {
    "name": "learn-technology",
    "arguments": {
      "technology": "Docker",
      "experience_level": "beginner"
    }
  }
}

期待される応答:

•description: "Learning path for Docker (beginner level)"
•messages: userロールのメッセージ配列 (学習戦略とワークフローを含む)

debug-error プロンプトのテスト

json

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "prompts/get",
  "params": {
    "name": "debug-error",
    "arguments": {
      "error_message": "NullPointerException",
      "technology": "Java",
      "context": "データベース接続時"
    }
  }
}

3. デバッグモードでの検証

認証問題やAPIエラーのトラブルシューティングに使用します。

bash

# 基本的なデバッグモード
ORM_MCP_GO_DEBUG=true ./bin/orm-discovery-mcp-go

# 詳細なMCPプロトコルログ
ORM_MCP_GO_DEBUG=true \
ORM_MCP_GO_LOG_LEVEL=DEBUG \
./bin/orm-discovery-mcp-go

出力されるデバッグ情報:

•API呼び出し先URL
•送信Cookie数と詳細
•HTTPヘッダー情報
•認証フロー中のスクリーンショット
•MCPプロトコルレベルのJSON-RPCメッセージ(LOG_LEVEL=DEBUG時)

MCP Hooksによるログ出力

サーバーはmcp-goのHooks機能を使用して、MCPプロトコルレベルのイベントをログ出力します。

イベント	ログレベル	内容
JSON-RPC受信	DEBUG	method, id, payload
JSON-RPC送信	DEBUG/INFO	method, id, result
エラー発生	ERROR	method, id, error詳細
セッション登録	INFO	session_id
セッション解除	INFO	session_id
ツール呼び出し開始	DEBUG/INFO	tool名, arguments
リソース読み込み開始	DEBUG	URI

ログ出力例(LOG_LEVEL=DEBUG):

code

time=2026-01-24T12:00:00.000+09:00 level=DEBUG source=server.go:25 msg="MCP受信" method=tools/call id=1 payload="{...}"
time=2026-01-24T12:00:00.100+09:00 level=DEBUG source=server.go:85 msg="ツール呼び出し開始" tool=search_content id=1 arguments="{\"query\":\"Docker\"}"
time=2026-01-24T12:00:01.000+09:00 level=DEBUG source=server.go:49 msg="MCP成功" method=tools/call id=1 result_size=5432

ログファイル出力

ログはstderrとXDG準拠のログファイル(~/.local/state/orm-mcp-go/orm-mcp-go.log)の両方に出力されます。 stdioモードではstdoutはJSON-RPC専用なので、ログは必ずstderr/ファイルに出力されます。

bash

# ログファイルをリアルタイムで監視
tail -f ~/.local/state/orm-mcp-go/orm-mcp-go.log

ヘッダー検証例:

code

API呼び出し先URL: https://learning.oreilly.com/api/v1/miso-answers-relay-service/questions/
送信予定Cookie数: 20
送信Cookie: groot_sessionid=... (Domain: .oreilly.com, Path: /)

4. ブラウザライフサイクルの検証

ChromeDPが正しく管理されているか確認します。

bash

# 通常モード - 認証後にブラウザプロセスが終了するか確認
./bin/orm-discovery-mcp-go
ps aux | grep chrome  # chromeプロセスが存在しないこと

# デバッグモード - ブラウザが維持されているか確認
ORM_MCP_GO_DEBUG=true ./bin/orm-discovery-mcp-go
ps aux | grep chrome  # chromeプロセスが存在すること

5. Cookie認証の検証

Cookie保存先とChrome分離を確認します。

bash

# Cookie保存先の確認
ls -la /var/tmp/orm-discovery-mcp-go/cookies.json

# Chromeデータディレクトリの確認
ls -la /var/tmp/chrome-user-data

# ユーザーのChromeに影響がないことを確認
ls -la ~/.config/google-chrome/Default/  # 変更なし

利用可能なMCPエンドポイント

ツール

ツール	説明
`search_content`	コンテンツ検索 - 書籍/ビデオ/記事を検索
`ask_question`	O'Reilly Answers AIへの質問

リソース

リソースURI	説明
`oreilly://book-details/{product_id}`	書籍詳細情報
`oreilly://book-toc/{product_id}`	目次情報
`oreilly://book-chapter/{product_id}/{chapter_name}`	チャプターコンテンツ
`oreilly://answer/{question_id}`	回答の取得

プロンプト

プロンプト	説明	必須引数
`learn-technology`	技術の学習パス生成	`technology`
`research-topic`	技術トピックの調査	`topic`
`debug-error`	エラーデバッグガイド	`error_message`, `technology`

トラブルシューティング

401認証エラー

症状: APIリクエストが401/403エラーを返す

確認手順:

•デバッグモードでサーバーを起動
•ログでCookie送信状況を確認
•
必要なヘッダーが送信されているか確認:
- •Accept: */*
- •Referer: https://learning.oreilly.com/answers2/
- •Origin: https://learning.oreilly.com
- •Sec-Fetch-* セキュリティヘッダー

解決策:

•Cookieファイルを削除して再認証
•環境変数の認証情報を確認

サーバーが応答しない

症状: stdioモードでリクエストに応答がない

確認手順:

•初期化ログが出力されているか確認
•JSON-RPCリクエストの形式が正しいか確認
•改行でリクエストが終了しているか確認

ブラウザプロセスが残留

症状: 終了後もchromeプロセスが残る

確認手順:

bash

ps aux | grep chrome
pkill -f chromium  # 必要に応じて手動終了

解決策:

•デバッグモードが有効になっていないか確認
•main.goのdefer cleanup が正しく動作しているか確認

参考リンク

•MCP公式ドキュメント
•ChromeDPライフサイクル管理
•プロジェクトCLAUDE.md: テスト手法の詳細