Xcatcher MCP Manifest

🚀 Xcatcher MCP (リモート)

Xcatcherは、多数のX（Twitter）ユーザー名にまたがる最新の投稿を高スループットでクロールするための、エージェント指向のリモートMCPサーバー（ストリーミング可能なHTTP）です。BaseとSolana上のUSDCを使用したx402の従量制トップアップをサポートし、エージェントビルダーが直接インポートできるOpenAPI仕様を備えています。

🚀 クイックスタート

コピー&ペーストによるクイックスタート（3つのコマンド）

# 1) Google ADK エンドツーエンド (リモートMCP + x402)
cd google-adk && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && \
XCAT_BASE="https://xcatcher.top" XCAT_API_KEY="xc_live_xxx" XCAT_MODE="normal" python adk_mcp_e2e.py

# 2) curl エンドツーエンド (リモートMCP作成 -> 402 -> 見積もりデコード -> トップアップ -> 再試行 -> ダウンロード)
cd curl && cp env.example .env && sed -i.bak 's/xc_live_xxx/xc_live_xxx/' .env && bash mcp_x402_e2e.sh

# 3) 見積もり (ポイント -> USDC請求書) + (支払い後) トップアップ
curl -s "https://xcatcher.top/api/v1/x402/quote?points=100" | jq .

✨ 主な機能

• 多数のX（Twitter）ユーザー名にまたがる最新投稿の高スループットクローリング
• BaseとSolana上のUSDCを使用したx402の従量制トップアップサポート
• エージェントビルダーが直接インポートできるOpenAPI仕様の提供

📚 ドキュメント

ディレクトリリスト (探索)

• Glama: https://glama.ai/mcp/servers/@lvpiggyqq/xcatcher-remote-mcp
• Smithery: https://smithery.ai/search?q=xcatcher

エンドポイント

• ベースURL: https://xcatcher.top
• リモートMCP (ストリーミング可能なHTTP): https://xcatcher.top/mcp/
• REST APIベース: https://xcatcher.top/api/v1
• ドキュメント: https://xcatcher.top/docs/
• ヘルスチェック (公開): https://xcatcher.top/mcp/health

認証

すべてのMCPおよびREST呼び出しには、以下が必要です。

• Authorization: Bearer xc_live_...

RESTを介してAPIキーを取得します。

• POST /api/v1/auth/register (アカウントを作成し、api_keyを返す)
• POST /api/v1/auth/login (api_keyを返し、古いキーを取り消すことがある)

重要事項:

• 結果ファイルは公開の直接リンクではありません。常に同じBearerトークンを使用して認証済みのエンドポイントからダウンロードしてください。

OpenAPIインポート

生の仕様 (エージェントビルダー / APIツールにコピー):

• https://raw.githubusercontent.com/lvpiggyqq/xcatcher-mcp-manifest/main/openapi/xcatcher.yaml

推奨使用方法:

• OpenAPI仕様をインポートして、REST呼び出し（ポイント、見積もり/トップアップ、ダウンロード）をすばやく設定します。
• リモートMCPをツールスタイルのオーケストレーション（作成 → ポーリング → ダウンロード）に使用します。特にエージェントフレームワークでの使用に適しています。

出力形式

• デフォルトエクスポート: XLSX
• CSVが必要な場合は、ダウンロードしたXLSXをクライアント側でCSVに変換してください。

モード: normalとdeep

デフォルトの推奨設定: normal （「最新投稿」のモニタリングにおいて、より高速で低遅延）

normal (推奨)

• 目的: 大規模な「最新投稿」のスナップショットを高速で取得
• 最適用途: モニタリング、アラート、新しい投稿を繰り返し取得するパイプライン

deep (オプション)

• 目的: ユーザーごとのより深い収集/エンリッチメント
• 最適用途: 遅延がそれほど重要でない、より深い履歴/コンテキストの取得

注意事項:

• タスクを作成したときに、サーバーから正確なコストと残高が返されます（例: cost_points, balance_after）。

リモートMCPツール (エージェントフレンドリーなコア)

Xcatcherは、エージェントフレンドリーな小さなコアを公開しています。

• create_crawl_task (副作用: ポイントを消費する)
• x402_topup (副作用: オンチェーンの支払い証明後にポイントを加算する)
• get_task_status (完了するまでポーリングする)
• get_result_download_url (認証済みのダウンロードURLを返す)
• cancel_task (キューに入っているタスクをキャンセルする; ポリシーによっては返金されることがある)

エージェントは、正確な入力フィールド、制約、およびサーバー側の検証ルールについて、ツールスキーマ (tools/list) に依存する必要があります。

リモートMCP JSON-RPC (cURL)

MCPはHTTP上のJSON-RPCです。Accept: application/jsonを含める必要があります。

BASE="https://xcatcher.top"
API_KEY="xc_live_xxx"

curl -sS -X POST "$BASE/mcp/" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq .

クイックスタート (Google ADK → リモートMCP)

詳細は: ./google-adk/README.md を参照してください。

ワンライナー:

cd google-adk
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
XCAT_BASE="https://xcatcher.top" XCAT_API_KEY="xc_live_xxx" XCAT_MODE="normal" python adk_mcp_e2e.py

クイックスタート (REST API)

ワークフロー: タスクを作成 → ポーリング → ダウンロード

BASE="https://xcatcher.top"

# 1) 登録 -> api_key (xc_live_...) を返す
curl -s -X POST "$BASE/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

# 2) ログイン -> api_key を返す (古いキーを取り消すことがある)
curl -s -X POST "$BASE/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

API_KEY="xc_live_xxx"

# 3) ポイントを確認
curl -s "$BASE/api/v1/me" -H "Authorization: Bearer $API_KEY"

# 4) タスクを作成 (副作用: ポイントを消費する; 不足している場合は402を返す)
curl -s -X POST "$BASE/api/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"normal","users":["elonmusk","naval"],"idempotency_key":"rest-req-001"}'

ポーリング + ダウンロード:

BASE="https://xcatcher.top"
API_KEY="xc_live_xxx"
TASK_ID=10136

# ポーリング
curl -s "$BASE/api/v1/tasks/$TASK_ID" -H "Authorization: Bearer $API_KEY"

# ダウンロード (xlsxストリーム)
curl -L -o "task_${TASK_ID}.xlsx" \
  -H "Authorization: Bearer $API_KEY" \
  "$BASE/api/v1/tasks/$TASK_ID/download"

x402トップアップ (Base / Solana)

ポイントが不足している状態でタスクを作成すると、PAYMENT-REQUIREDヘッダー（base64 JSON）と見積もり（quote_id, payTo, maxAmountRequiredなど）を含む本文とともに、HTTP 402が返されることがあります。

実用的なワークフロー:

1. 見積もりをリクエストする（または402をトリガーして受け取る）
2. 返されたpayToにUSDCを支払う
3. 結果のtxHash / signatureをPAYMENT-SIGNATUREに貼り付け、トップアップする

最小支払いに関する注意:

• 最小トップアップは0.5 USDCです（少ない金額を支払うと検証に失敗する可能性があります）。

PAYMENT-SIGNATURE形式

トップアップの証拠はHTTPヘッダーとして送信されます: PAYMENT-SIGNATURE

値 = base64(UTF-8 JSON):

• Baseの証拠はtxHashを使用します
• Solanaの証拠はsignatureを使用します

Baseの例:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": { "txHash": "0x...base_transaction_hash..." }
}

Solanaの例:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "solana:mainnet",
  "payload": { "signature": "5v...solana_tx_signature...pQ" }
}

Base: 見積もり → USDC支払い → トップアップ → /me

BASE="https://xcatcher.top"
API_KEY="xc_live_xxx"
POINTS=100

# 1) 見積もり
curl -s "$BASE/api/v1/x402/quote?points=$POINTS" | jq .

# 2) Baseで支払う:
# - USDCをquote.accepts.base.payToに送信する
# - 金額 >= quote.accepts.base.maxAmountRequired (原子単位、小数点以下6桁)
QUOTE_ID="q_xxx"
BASE_TXHASH="0x...your_base_tx_hash..."

# 3) PAYMENT-SIGNATURE = base64(json)
PAYMENT_SIGNATURE_B64=$(jq -nc --arg tx "$BASE_TXHASH" \
  '{"x402Version":1,"scheme":"exact","network":"eip155:8453","payload":{"txHash":$tx}}' \
  | base64 -w 0)

# macOSのフォールバック:
# PAYMENT_SIGNATURE_B64=$(jq -nc --arg tx "$BASE_TXHASH" \
#   '{"x402Version":1,"scheme":"exact","network":"eip155:8453","payload":{"txHash":$tx}}' \
#   | base64 | tr -d '\n')

# 4) 現在のキーをトップアップする
curl -s -X POST "$BASE/api/v1/x402/topup" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE_B64" \
  -d "{\"quote_id\":\"$QUOTE_ID\"}" | jq .

# 5) ポイントを確認する
curl -s "$BASE/api/v1/me" -H "Authorization: Bearer $API_KEY" | jq .

Solana: 見積もり → SPL転送 → トップアップ → /me

BASE="https://xcatcher.top"
API_KEY="xc_live_xxx"
POINTS=100

# 1) 見積もり
curl -s "$BASE/api/v1/x402/quote?points=$POINTS" | jq .

# 2) Solanaで支払う:
# - USDC SPLをquote.accepts.solana.payToに送信する
QUOTE_ID="q_xxx"
SOL_TX_SIG="5v...your_solana_signature...pQ"

# 3) PAYMENT-SIGNATURE = base64(json)
PAYMENT_SIGNATURE_B64=$(jq -nc --arg sig "$SOL_TX_SIG" \
  '{"x402Version":1,"scheme":"exact","network":"solana:mainnet","payload":{"signature":$sig}}' \
  | base64 -w 0)

# 4) 現在のキーをトップアップする
curl -s -X POST "$BASE/api/v1/x402/topup" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE_B64" \
  -d "{\"quote_id\":\"$QUOTE_ID\"}" | jq .

# 5) ポイントを確認する
curl -s "$BASE/api/v1/me" -H "Authorization: Bearer $API_KEY" | jq .

トップアップ後:

• 402をトリガーした**同じidempotency_key**を使用して、create_crawl_task / POST /api/v1/tasksを再試行してください。

RESTエンドポイントの概要

• POST /api/v1/auth/register — アカウントを作成し、api_keyを発行する
• POST /api/v1/auth/login — ログインし、api_keyを発行する (古いキーを取り消すことがある)
• GET /api/v1/me — 現在のユーザーとBearerキーのポイントを確認する
• POST /api/v1/tasks — タスクを作成する (ポイントを消費する; 不足している場合は402を返す)
• GET /api/v1/tasks/<id> — タスクのステータスを読み取る
• GET /api/v1/tasks/<id>/download — 結果ファイルをダウンロードする (Bearerが必要)
• POST /api/v1/tasks/<id>/cancel — キューに入っているタスクをキャンセルする (ポリシーによっては返金されることがある)
• GET /api/v1/x402/quote?points=<n> — ポイントによるx402見積もりを取得する
• POST /api/v1/x402/topup — PAYMENT-SIGNATUREを使用して現在のBearerキーをトップアップする

エラーハンドリング (エージェントの分岐)

• 401 AUTH_MISSING / AUTH_INVALID: Bearerトークンが不足している/無効です
• 402 PAYMENT_REQUIRED: 支払い + トップアップしてから、同じidempotency_keyで再試行してください
• 409 RESULT_NOT_READY: ポーリングを続けてください
• 429 RATE_LIMITED: バックオフし、Retry-Afterを遵守してください
• 599 UPSTREAM_UNREACHABLE: 内部依存関係に到達できません
• 5xx: 一時的なエラーです; 指数関数的なバックオフで再試行してください

サポート

• ドキュメント: https://xcatcher.top/docs/
• 問題/リクエスト: このリポジトリにissueを作成してください。