Imported from majiayu000/claude-skill-registry-data (api/api-investigator/SKILL.md). Install upstream with npx skills add majiayu000/claude-skill-registry-data --skill api-investigator. Copyright stays with the author.

API Investigator スキル

このスキルは、note.com APIの動作を調査するためのinvestigatorモジュールの利用方法を提供します。

起動条件

以下の状況で起動します：

1. API動作の調査時: note.com APIのリクエスト/レスポンス形式を確認する際
2. 新機能の実装前調査: 未知のAPIエンドポイントの動作を理解する必要がある際
3. バグ調査時: API通信に関連する問題を診断する際
4. ProseMirrorエディタ調査時: note.comのエディタDOM構造やイベントを調査する際
5. 認証フロー調査時: ログイン・セッション管理の動作を確認する際

前提条件

必要なソフトウェア

• mitmproxy（mitmdumpコマンド）
• Playwright

インストール

# 開発依存関係のインストール（mitmproxy含む）
uv sync --group dev

# Playwrightブラウザのインストール
uv run playwright install chromium

使用方法

1. トラフィックキャプチャ

# 基本的なキャプチャ（セッション自動復元）
uv run python -m note_mcp.investigator capture

# ドメインフィルタ付きキャプチャ
uv run python -m note_mcp.investigator capture --domain api.note.com

# 出力ファイル指定
uv run python -m note_mcp.investigator capture -o my_capture.flow

# セッション復元なし（新規ログイン必要）
uv run python -m note_mcp.investigator capture --no-session

# カスタムポート
uv run python -m note_mcp.investigator capture --port 8888

2. キャプチャ分析

# 基本的な分析
uv run python -m note_mcp.investigator analyze traffic.flow

# パターンで検索
uv run python -m note_mcp.investigator analyze traffic.flow --pattern citation

# ドメインとメソッドでフィルタ
uv run python -m note_mcp.investigator analyze traffic.flow --domain api.note.com --method POST

3. JSONエクスポート

# JSON形式でエクスポート
uv run python -m note_mcp.investigator export traffic.flow -o api_calls.json

# ドメインフィルタ付きエクスポート
uv run python -m note_mcp.investigator export traffic.flow --domain api.note.com

セッション管理

自動セッション復元

note_login MCPツールでログイン済みの場合、保存されたセッションCookieが自動的にブラウザに注入されます。

captureコマンド実行
    ↓
SessionManagerからCookie読み込み
    ↓
PlaywrightブラウザにCookie注入
    ↓
ログイン状態でキャプチャ開始

セッションがない場合

1. ブラウザが開く
2. note.comに手動でログイン
3. 調査操作を実行
4. ブラウザを閉じてキャプチャ終了

調査ワークフロー例

例1: 引用（blockquote）出典APIの調査（実績あり）

# Step 1: note.comへのトラフィックをキャプチャ
uv run python -m note_mcp.investigator capture -d note.com -o citation.flow

# ブラウザで:
# 1. 新規記事作成画面（/notes/new）を開く
# 2. 引用ブロックを追加
# 3. 出典を入力
# 4. 下書き保存
# 5. ブラウザを閉じる

# Step 2: draft_save APIを分析
uv run python -m note_mcp.investigator analyze citation.flow --pattern draft_save

# Step 3: 詳細をJSONでエクスポート
uv run python -m note_mcp.investigator export citation.flow -o citation_api.json

# Step 4: Pythonで詳細確認
uv run python -c "
import json
with open('citation_api.json') as f:
    data = json.load(f)
for item in data:
    req = item.get('request', {})
    if 'draft_save' in req.get('url', ''):
        body = json.loads(req.get('body', '{}'))
        print(json.dumps(body, indent=2, ensure_ascii=False))
"

調査結果例（2024-12-30実施）

引用の出典はAPIで以下のHTML構造として送信されることが判明：

<figure name="UUID" id="UUID">
  <blockquote>
    <p name="UUID" id="UUID">引用テキスト<br>改行も可能</p>
  </blockquote>
  <figcaption>出典URL（例: example.com）</figcaption>
</figure>

• <figure> で全体をラップ
• <blockquote><p> 内に引用テキスト
• <figcaption> に出典情報
• 改行は <br> タグ

例2: 画像アップロードAPIの調査

# アップロード関連のトラフィックをキャプチャ
uv run python -m note_mcp.investigator capture -d note.com -o upload.flow

# ブラウザで画像をアップロード後、閉じる

# POSTリクエストのみ分析
uv run python -m note_mcp.investigator analyze upload.flow --method POST --pattern upload

例3: 新規ログインでの調査

# セッション復元なしでキャプチャ（認証フロー調査）
uv run python -m note_mcp.investigator capture --no-session -o auth.flow

# ブラウザでログイン操作を実行

# 認証関連のリクエストを分析
uv run python -m note_mcp.investigator analyze auth.flow --pattern "login\|session\|auth"

CLIオプション一覧

capture コマンド

analyze コマンド

export コマンド

MCPツール（AI自律調査用）

AI（Claude Code/Claude Desktop）がMCPツールを直接呼び出してAPI調査を自律実行できます。 Docker内でブラウザ操作とトラフィック分析が完結します。

前提条件

# Docker環境でinvestigatorサービスを起動
docker compose up -d investigator

# VNC経由でブラウザ動作を確認（オプション）
vncviewer localhost:5900

キャプチャ制御ツール

investigator_start_capture

キャプチャセッションを開始します。

investigator_start_capture(domain: str, port: int = 8080) -> str

戻り値: セッション開始の成功/失敗メッセージ

investigator_stop_capture

キャプチャセッションを停止します。

investigator_stop_capture() -> str

戻り値: セッション終了の成功/失敗メッセージ

investigator_get_status

現在のキャプチャセッション状態を取得します。

investigator_get_status() -> str

戻り値: セッション状態（アクティブ/非アクティブ、キャプチャ済みリクエスト数など）

ブラウザ操作ツール

investigator_navigate

指定URLに移動します。

investigator_navigate(url: str) -> str

戻り値: ナビゲーション結果（成功/失敗、ページタイトル）

investigator_click

セレクタで指定した要素をクリックします。

investigator_click(selector: str) -> str

戻り値: クリック結果（成功/失敗）

investigator_type

指定要素にテキストを入力します。

investigator_type(selector: str, text: str) -> str

戻り値: 入力結果（成功/失敗）

investigator_screenshot

現在のページのスクリーンショットを取得します。

investigator_screenshot() -> str

戻り値: Base64エンコードされた画像データ

investigator_get_page_content

現在のページのHTMLを取得します。

investigator_get_page_content() -> str

戻り値: ページのHTMLコンテンツ

トラフィック分析ツール

investigator_get_traffic

キャプチャしたトラフィック一覧を取得します。

investigator_get_traffic(pattern: str | None = None) -> str

戻り値: トラフィック一覧（JSON形式）

investigator_analyze

特定パターンのトラフィックを詳細分析します。

investigator_analyze(pattern: str, method: str | None = None) -> str

戻り値: 分析結果（リクエスト/レスポンス詳細）

investigator_export

キャプチャデータをJSONファイルにエクスポートします。

investigator_export(output_path: str) -> str

戻り値: エクスポート結果（ファイルパス、レコード数）

AI自律調査ワークフロー例

例1: note.com記事作成APIの調査

# 1. キャプチャ開始
→ investigator_start_capture(domain="note.com")

# 2. note.comにアクセス
→ investigator_navigate("https://note.com/")

# 3. ログインボタンをクリック
→ investigator_click("button.login")

# 4. 認証情報を入力（セッション復元される場合は不要）
→ investigator_type("input[name=email]", "...")
→ investigator_type("input[name=password]", "...")
→ investigator_click("button[type=submit]")

# 5. 記事作成画面に移動
→ investigator_navigate("https://note.com/notes/new")

# 6. 記事内容を入力
→ investigator_click(".editor-content")
→ investigator_type(".editor-content", "テスト記事")

# 7. 下書き保存（APIリクエスト発生）
→ investigator_click("button.save-draft")

# 8. draft_save APIを分析
→ investigator_analyze(pattern="draft_save", method="POST")

# 9. 結果をエクスポート
→ investigator_export(output_path="api_investigation.json")

# 10. キャプチャ終了
→ investigator_stop_capture()

例2: 画像アップロードAPIの調査

# 1. キャプチャ開始
→ investigator_start_capture(domain="note.com")

# 2. 記事編集画面に移動
→ investigator_navigate("https://note.com/notes/new")

# 3. 画像アップロードボタンをクリック
→ investigator_click("button.upload-image")

# 4. POSTリクエストを分析
→ investigator_analyze(pattern="upload", method="POST")

# 5. レスポンス形式を確認
→ investigator_get_traffic(pattern="upload")

# 6. キャプチャ終了
→ investigator_stop_capture()

ホストClaude Codeからの自律調査

アーキテクチャ

┌─────────────────────────────────────────────┐
│ Host                                        │
│  ┌─────────────────┐    ┌────────────────┐ │
│  │ Claude Code CLI │───►│ MCP Client     │ │
│  └─────────────────┘    └───────┬────────┘ │
└─────────────────────────────────┼───────────┘
                                  │ HTTP :9000
┌─────────────────────────────────┼───────────┐
│ Docker Container                ▼           │
│  ┌───────────────────────────────────────┐  │
│  │ Investigator MCP Server (FastMCP)    │  │
│  │ - investigator_start_capture          │  │
│  │ - investigator_navigate               │  │
│  │ - investigator_click                  │  │
│  │ - investigator_screenshot             │  │
│  │ - investigator_get_traffic            │  │
│  │ - investigator_analyze                │  │
│  └───────────────────────────────────────┘  │
│           │                                 │
│   ┌───────┴───────┐                        │
│   ▼               ▼                        │
│ ┌─────────┐  ┌───────────┐                 │
│ │mitmproxy│  │Playwright │                 │
│ │ :8080   │  │ Browser   │                 │
│ └─────────┘  └───────────┘                 │
│                  ▲                          │
│                  │ VNC :5900 / noVNC :6080 │
└──────────────────┼──────────────────────────┘
                   │
            [Visual Monitoring]

セットアップ

1. Dockerコンテナを起動

cd /home/driller/amplifier/note-mcp

# investigatorサービスを起動
docker compose up -d investigator

# ログを確認
docker compose logs -f investigator

2. 接続確認

# MCP HTTPサーバーの動作確認
curl http://localhost:9000/mcp

# VNCでブラウザ確認（オプション）
vncviewer localhost:5900
# または noVNC: http://localhost:6080/vnc.html

3. MCPクライアント設定

.mcp.json にHTTPトランスポート設定が追加済み：

{
  "mcpServers": {
    "note-investigator": {
      "url": "http://localhost:9000/mcp",
      "transport": "http"
    }
  }
}

利用可能なポート

技術的な注意事項

Docker内での動作

• mitmproxy、Playwright、MCPサーバーすべてがDocker内で動作
• VNC経由でブラウザ動作を視覚確認可能（port 5900）
• noVNCでブラウザ経由確認も可能（port 6080）

セッション管理

• Docker内ではkeyringが利用できないため、ファイルベースセッション管理を使用
• セッション情報は /app/data にマウントされたボリュームに永続化

HTTPS証明書

• --ignore-certificate-errors フラグでHTTPS通信をキャプチャ
• 証明書インストールは不要

Issue#15の教訓

• subprocess.PIPE → subprocess.DEVNULL（バッファブロッキング回避）
• localhost → 127.0.0.1（WSL2互換性）

トラブルシューティング

mitmproxyが見つからない

# 開発依存関係をインストール
uv sync --group dev

ブラウザが起動しない

# Playwrightブラウザをインストール
uv run playwright install chromium

セッションが復元されない

1. note_login MCPツールで先にログイン
2. note_check_auth で認証状態を確認
3. それでも復元されない場合は --no-session で手動ログイン

ポートが使用中

# 別のポートを使用
uv run python -m note_mcp.investigator capture --port 8888

WSL2環境でのネットワーク問題

WSL2では localhost の名前解決が不安定な場合があります。 investigatorは内部で 127.0.0.1 を使用するよう修正済みですが、 他のツールと連携する際は 127.0.0.1 を明示的に使用してください。

プロキシ経由でリクエストがタイムアウトする

過去に subprocess.PIPE によるバッファブロッキング問題がありました（Issue #15）。 現在は修正済みですが、同様の問題が発生した場合：

1. mitmproxyを直接起動してcurlでテスト

   uv run mitmdump --mode regular@8080 -w test.flow &
   curl -x http://127.0.0.1:8080 -k https://example.com

2. これが成功する場合、ProxyManagerのsubprocess処理に問題あり
3. 詳細は Issue #15 を参照

関連Issue

• #15 - subprocess.PIPEによるプロキシブロッキング問題
• #14 - 引用（blockquote）の出典入力機能

注意事項

• キャプチャデータにはセッション情報が含まれる可能性があるため、共有時は注意
• mitmproxyはHTTPSトラフィックを復号するため、開発・調査目的でのみ使用
• note.comの利用規約に従い、調査目的での使用に留める