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。