Mastra

Construisez des agents Mastra TypeScript pour la recherche de tweets, les profils, les tendances et les écritures X revues via TwexAPI MCP.

Construisez un agent Twitter API Mastra via le serveur MCP de TwexAPI. Recherchez des tweets, inspectez des profils, lisez les tendances et revoyez les actions d’écriture. Préservez les ID de tweet, les curseurs et les noms de route en JSON typé plutôt que des résumés uniquement dans le chat.

Pourquoi utiliser Mastra avec TwexAPI ?

Mastra est un framework d’agents TypeScript. TwexAPI fournit la découverte d’endpoints et les appels authentifiés via explore et twexapi_request.

Tâche agent	Route TwexAPI	Préserver pour l’étape suivante
Rechercher des tweets	`POST /twitter/advanced_search/page`	Requête, ID de tweet, auteurs, `created_at`, curseur
Inspecter un profil	`GET /twitter/{screen_name}/about`	ID utilisateur, username, biographie, nombre d’abonnés
Lire les tendances	`GET /twitter/global-trending/tweets`	Pays, sujet, lignes de tweet
Publier ou répondre	`POST /twitter/tweets/create`	ID de tweet, route, approbation humaine, confirmation cookie

Utilisez Mastra pour les apps TypeScript qui utilisent déjà les modèles Vercel AI SDK. Utilisez le SDK TypeScript ou le CLI pour les jobs planifiés sans modèle.

Prérequis

Node.js 20 ou plus récent
Une clé API TwexAPI
Une clé de fournisseur de modèle supporté par Mastra
Un cookie Twitter ou auth_token pour les actions d’écriture — consultez

Les lectures X publiques ne nécessitent pas des identifiants X Developer. Authentifiez avec TwexAPI.

Installation

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

TWEXAPI_API_KEY=YOUR_API_KEY
OPENAI_API_KEY=sk-...

Connecter 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!,
        },
      },
    },
  },
});

Le serveur expose explore pour la découverte et twexapi_request pour les appels authentifiés. Les requêtes MCP non authentifiées renvoient 401.

Exemple complet

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"
);

Validez le JSON avant qu’un autre workflow le consomme. L’historique de conversation n’est pas une base de données de jobs.

Préserver le contrat de réponse MCP

Passez uniquement les champs query et body documentés de explore dans twexapi_request.

Arrêtez la pagination lorsqu’une condition devient vraie :

L’agent collecte le total demandé.
has_more ou has_next_page devient false.
next_cursor est absent ou se répète.
Le plafond de page configuré est atteint.

Dédupliquez les tweets et utilisateurs par tweet_id ou user_id.

Maintenir un handoff agent résilient

Pages de tweets

Stockez tweet_id, text, author_username, created_at, has_more, next_cursor et la requête originale.

Lignes de profil

Stockez user_id, username, name, description, les compteurs d’abonnés et l’entrée de lookup.

Lignes de tendances

Stockez le pays, le sujet, les ID de tweet et les métriques d’engagement.

Actions d'écriture

Stockez la route, le texte de prévisualisation et l’approbation humaine. Gardez les cookies hors du fichier de handoff. Consultez.

Consultez Agent MCP Handoff pour la checklist complète.

Construire la gestion des erreurs

Statut	Signification	Décision agent
`400`	Route ou paramètres invalides	Corrigez la requête avant de réessayer
`401`	Clé API manquante ou invalide	Arrêtez et remplacez l’identifiant
`403`	Accès refusé ou crédits	Pausez les écritures ; consultez Get Balance
`429`	Limite de débit atteinte	Ralentissez, puis reprenez le même curseur
`5xx`	Défaillance serveur temporaire	Appliquez un backoff borné aux lectures sûres

Ne jamais réessayer une écriture après un timeout sans vérification de lecture. Consultez Gestion des erreurs et Limites de débit.

Exiger une approbation avant les actions 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.

Prévisualisez avec le CLI --dry-run, puis exécutez via REST ou le SDK TypeScript après approbation.

Connecter plusieurs serveurs 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"),
    },
  },
});

Gardez le nom du serveur TwexAPI stable. Donnez à l’agent uniquement les outils requis pour le job actuel.

Versions des packages

Package	Plage supportée
Node.js	`>=20`
`@mastra/core`	`>=0.10`
`@mastra/mcp`	`>=0.10`