Xcatcher MCP Manifest

🚀 Xcatcher MCP (遠程版)

Xcatcher 是一款以代理為優先的 遠程 MCP 服務器（支持流式 HTTP），可對大量 X（原 Twitter）用戶名的 最新帖子 進行高吞吐量爬取。它支持在 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 規範：提供 OpenAPI 規範，方便代理構建者直接導入。

📦 安裝指南

文檔中未提及具體安裝步驟，你可以參考上述快速開始部分的命令進行操作。

💻 使用示例

基礎用法

Google ADK 端到端使用

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

curl 端到端使用

cd curl && cp env.example .env && sed -i.bak 's/xc_live_xxx/xc_live_xxx/' .env && bash mcp_x402_e2e.sh

高級用法

報價與充值

# 請求報價
curl -s "https://xcatcher.top/api/v1/x402/quote?points=100" | jq .
# 充值
# ...（根據不同鏈的充值步驟進行操作）

📚 詳細文檔

目錄列表（發現）

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

端點信息

身份驗證

所有 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（更快，“最新帖子” 監控延遲更低）。

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）

當你創建任務時積分不足，可能會收到 HTTP 402 響應，其中包含 PAYMENT-REQUIRED 頭（base64 JSON）和包含報價的主體（quote_id，payTo，maxAmountRequired 等）。

實際工作流程：

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 上支付:
# - 向報價中的 quote.accepts.base.payTo 地址發送 USDC
# - 金額 >= 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 上支付:
# - 向報價中的 quote.accepts.solana.payTo 地址發送 USDC SPL
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 端點總結

錯誤處理（代理分支）

• 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。