Mastra

通过 TwexAPI MCP 构建 TypeScript Mastra AI Agent，实现推文搜索、资料查询、趋势读取与经审核的 X 写操作。

通过 TwexAPI 的 MCP 服务器构建 Mastra Twitter API AI Agent。搜索推文、查看资料、读取趋势并审核写操作。将 tweet ID、游标与路由名保留为类型化 JSON，而非仅聊天摘要。

为何将 Mastra 与 TwexAPI 搭配使用？

Mastra 是 TypeScript AI Agent框架。TwexAPI 通过 explore 与 twexapi_request 提供端点发现与认证调用。

已使用 Vercel AI SDK 模型的 TypeScript 应用用 Mastra。无需模型的定时作业请用 TypeScript SDK 或 CLI。

前置条件

• Node.js 20 或更高版本
• TwexAPI API 密钥
• Mastra 支持的模型提供商密钥
• 写操作所需的 Twitter cookie 或 auth_token — 见

公开 X 读取无需 X Developer 凭证，使用 TwexAPI 认证即可。

安装

npm install @mastra/core @mastra/mcp @ai-sdk/openai dotenv

TWEXAPI_API_KEY=YOUR_API_KEY
OPENAI_API_KEY=sk-...

连接 TwexAPI MCP

import "dotenv/config";
import { MCPClient } from "@mastra/mcp";

export const twexapiMcp = new MCPClient({
  servers: {
    twexapi: {
      url: new URL("https://api.twexapi.io/mcp"),
      requestInit: {
        headers: {
          "x-api-key": process.env.TWEXAPI_API_KEY!,
        },
      },
    },
  },
});

服务器暴露 explore 用于发现、twexapi_request 用于认证调用。未认证 MCP 请求返回 401。

完整示例

import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { writeFile } from "node:fs/promises";
import { twexapiMcp } from "./mcp";

type TweetRow = {
  tweet_id: string;
  text: string;
  author_username?: string;
  created_at?: string;
};

type TweetSearchHandoff = {
  query: string;
  route_used: string;
  tweets: TweetRow[];
  has_more: boolean;
  next_cursor: string | null;
  stop_reason: "complete" | "requested_limit" | "cursor_stalled" | "page_cap";
};

const tools = await twexapiMcp.listTools();

export const twexapiAgent = new Agent({
  name: "twexapi-agent",
  instructions: `
    Use TwexAPI MCP for Twitter API requests.
    Call explore before twexapi_request.
    Preserve exact IDs and cursors. Never invent missing tweet fields.
    Ask for confirmation before read_only: false actions.
    Return only valid JSON matching the handoff contract.
  `,
  model: openai("gpt-4o-mini"),
  tools,
});

const result = await twexapiAgent.generate(
  `Search 25 recent tweets about Mastra MCP.
Return JSON with query, route_used, tweets[{tweet_id,text,author_username,created_at}],
has_more, next_cursor, and stop_reason.`
);

const handoff = JSON.parse(result.text) as TweetSearchHandoff;
await writeFile(
  "twexapi-mastra-handoff.json",
  JSON.stringify(handoff, null, 2),
  "utf8"
);

另一工作流消费前校验 JSON。对话历史不是作业数据库。

保留 MCP 响应契约

仅将 explore 中文档化的 query 与 body 字段传入 twexapi_request。

满足以下任一条件时停止分页：

• AI Agent已收集请求总量。
• has_more 或 has_next_page 为 false。
• next_cursor 缺失或重复。
• 达到配置的页面上限。

按 tweet_id 或 user_id 对推文与用户去重。

保持可恢复的AI Agent handoff

完整清单见 Agent MCP Handoff。

构建错误处理

超时后重试写操作前须 read-back 检查。见 Error Handling 与 Rate Limits。

X 操作前要求审批

Call explore with include_writes true only when the user asked to post, like, follow, or DM.
Stop before any read_only: false call.
Show method, path, tweet text or target username, and media URLs.
Do not send cookie values in the model output.

用 CLI --dry-run 预览，审批后通过 REST 或 TypeScript SDK 执行。

连接多个 MCP 服务器

export const mcp = new MCPClient({
  servers: {
    twexapi: {
      url: new URL("https://api.twexapi.io/mcp"),
      requestInit: {
        headers: { "x-api-key": process.env.TWEXAPI_API_KEY! },
      },
    },
    twexapiDocs: {
      url: new URL("https://docs.twexapi.io/mcp"),
    },
  },
});

保持 TwexAPI 服务器名稳定。仅向AI Agent提供当前任务所需工具。

包版本

下一步

• MCP Tools
• Agent MCP Handoff
• TypeScript SDK
• Advanced Twitter Search