MCP 工具参考

Twexapi MCP 工具：端点发现、认证 API 调用、工作流交接与安全AI Agent执行。

Twexapi API MCP 服务器暴露 2 个工具：explore 与 twexapi_request。使用 x-api-key 或 OAuth 2.1 Bearer 认证连接 https://api.twexapi.io/mcp。

Agent 应在调用 twexapi_request 前用 explore 检查 API 目录。这样端点选择更明确，便于保留请求 schema，并避免误调 MCP 不可用的路径。

工具

explore

搜索 API 端点目录。只读，不访问 X/Twitter 网络，不消耗端点额度。调用仍需要 API 密钥或 OAuth Bearer 令牌的 MCP 认证。

使用 explore 发现可用端点、检查参数、比较类别，并在执行调用前找到正确的 API 路径。

输入

目录结构

interface EndpointInfo {
  name: string;
  method: string;
  path: string;
  category: string;
  description: string;
  read_only: boolean;
  parameters_schema?: Record<string, unknown>;
  example?: {
    method: string;
    path: string;
    query?: Record<string, unknown>;
    body?: unknown;
  };
}

示例

查找趋势端点：

{
  "category": "trending"
}

按关键词搜索：

{
  "query": "advanced search tweets"
}

包含可写端点：

{
  "query": "create tweet",
  "include_writes": true
}

twexapi_request

对你的 Twexapi 账号执行 API 调用。认证从 MCP 请求自动注入，AI Agent只需传入端点方法、相对路径及可选的 query/body。

输入

响应契约

twexapi_request 返回 MCP 执行元数据及底层 REST 响应：

{
  "status_code": 200,
  "endpoint": "list_global_trending_countries",
  "method": "GET",
  "path": "/twitter/global-trending/countries",
  "result": {
    "code": 200,
    "msg": "success",
    "data": []
  }
}

从 result 保留持久化字段，包括 ID、游标、任务 ID、额度字段与写操作 ID。当页面包含 has_more 与 next_cursor 时，将游标传入 explore 返回的文档化后续端点或查询参数。

工作流示例

以下示例展示Agent 应产出的结构。实际使用时先运行 explore 以确认当前 schema。

带交接行的推文搜索

{
  "method": "POST",
  "path": "/twitter/advanced_search/page",
  "body": {
    "searchTerms": ["from:openai AI agents"],
    "maxItems": 20,
    "sortBy": "Latest"
  }
}

要求AI Agent返回紧凑交接对象：

{
  "source": "twexapi_mcp",
  "job": "tweet_search",
  "route_used": "/twitter/advanced_search/page",
  "query": "from:openai AI agents",
  "rows": [
    {
      "tweet_id": "1803006263529541838",
      "text": "...",
      "author_username": "openai",
      "created_at": "..."
    }
  ],
  "has_more": false,
  "next_cursor": null
}

获取趋势推文

{
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "query": {
    "country": "united-states",
    "topic": "technology",
    "content": "AI",
    "count": 20
  }
}

存在时存储 country、topic、content、推文 ID、作者用户名、互动字段、has_more 与 next_cursor。

导出粉丝到 CRM

{
  "method": "GET",
  "path": "/twitter/followers/openai/50"
}

存储 user_id、username、name、description、followers_count、源账号及分页/任务字段。若端点返回任务 ID，存储并轮询文档中的状态/下一页端点。

以 Markdown 读取 X 文章

{
  "method": "GET",
  "path": "/x/article/1803006263529541838/markdown"
}

存储文章 ID、标题、作者、Markdown 正文、提取的链接与源 URL。

发推或回复

{
  "method": "POST",
  "path": "/twitter/tweets/create",
  "body": {
    "tweet_content": "Hello from Twexapi MCP",
    "reply_tweet_id": null,
    "media_url": null
  }
}

存储 tweet_id、write_action_id、status、charged_credits、回复目标、媒体 URL 与用户确认记录。

AI Agent交接模式

MCP 返回 JSON。对AI Agent队列、CRM、电子表格、数仓与无代码工作流，返回包含原始任务、所用路由、待存储的规范化行或 ID，以及下一游标或待轮询任务的小型持久对象。

推文搜索到 JSON

调用 POST /twitter/advanced_search/page。存储推文 ID、正文、作者元数据、创建时间、链接、has_more、next_cursor 与原始查询。

抓取回复

有界页面调用 GET /twitter/tweets/{tweet_id}/replies/{count}，游标分页调用 GET /twitter/tweets/{tweet_id}/replies/page。存储回复 ID、作者用户名、正文、指标、has_more 与 next_cursor。

导出粉丝

调用 GET /twitter/followers/{screen_name}/{count} 或 explore 返回的 page/task 端点。存储用户 ID、用户名、名称、简介、粉丝数、源账号、任务 ID 与下一游标。

跟踪写操作

对写端点存储端点路径、请求体哈希或确认文本、返回的推文 ID 或写操作 ID、状态、扣费额度与媒体引用。

发送私信

仅在用户确认后调用私信端点。存储消息 ID、收件人用户 ID、账号、媒体引用与投递状态。共享 MCP 输出中勿包含完整私信正文。

端点类别

错误处理

MCP 认证失败时工具不会执行。客户端收到 JSON-RPC 错误：

{
  "jsonrpc": "2.0",
  "error": {
    "code": 401,
    "message": "Missing MCP API token"
  }
}

当 twexapi_request 已执行且底层 Twexapi API 返回非 2xx 时，保留 MCP 元数据与 Twexapi 错误：

{
  "status_code": 403,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "detail": "Credits exhausted or action not allowed."
  }
}

REST 与 MCP 恢复模式见 错误处理 与 速率限制。