--- title: "Référence des outils MCP" description: "Outils Twexapi MCP pour la découverte d'endpoints, les appels API authentifiés, le transfert de workflow et l'exécution agent sûre." --- Le serveur MCP API Twexapi expose 2 outils : `explore` et `twexapi_request`. Connectez-vous à `https://api.twexapi.io/mcp` avec `x-api-key` ou l'authentification Bearer OAuth 2.1. Les agents doivent utiliser `explore` pour inspecter le catalogue API avant d'appeler `twexapi_request`. Cela garde la sélection d'endpoint explicite, aide l'agent à préserver les schémas de requête et empêche les appels accidentels à des chemins non disponibles via MCP. ## Outils | Outil | Objectif | | --- | --- | | `explore` | Recherchez le catalogue d'endpoints API et renvoyez méthodes, chemins, catégories, paramètres, exemples et indicateurs de sécurité. | | `twexapi_request` | Exécutez des appels API Twexapi authentifiés contre des chemins relatifs sur liste blanche. | ## `explore` Recherchez le catalogue d'endpoints API. Lecture seule, aucun appel réseau X/Twitter, et aucun crédit d'endpoint consommé. L'appel nécessite toujours l'authentification MCP via une clé API ou un jeton Bearer OAuth. Utilisez `explore` pour découvrir les endpoints disponibles, vérifier les paramètres, comparer les catégories et trouver le bon chemin API avant d'exécuter des appels. ### Entrée | Nom | Type | Requis | Description | | --- | --- | --- | --- | | `query` | string | Non | Recherche par mot-clé sur le nom d'endpoint, la méthode, le chemin, la catégorie, la description et les exemples. | | `category` | string | Non | Filtre de catégorie exact, tel que `trending`, `search`, `users`, `articles` ou `write`. | | `include_writes` | boolean | Non | Inclure les endpoints avec effets de bord. Les endpoints d'écriture sont marqués `read_only: false`. | ### Forme du catalogue ```ts interface EndpointInfo { name: string; method: string; path: string; category: string; description: string; read_only: boolean; parameters_schema?: Record; example?: { method: string; path: string; query?: Record; body?: unknown; }; } ``` ### Exemples Trouver les endpoints de tendances : ```json { "category": "trending" } ``` Rechercher par mot-clé : ```json { "query": "advanced search tweets" } ``` Inclure les endpoints capables d'écriture : ```json { "query": "create tweet", "include_writes": true } ``` ## `twexapi_request` Exécutez des appels API contre votre compte Twexapi. L'authentification est injectée automatiquement depuis la requête MCP, les agents ne passent donc que la méthode d'endpoint, le chemin relatif et les données query/body optionnelles. ### Entrée | Nom | Type | Requis | Description | | --- | --- | --- | --- | | `method` | string | Oui | Méthode HTTP renvoyée par `explore`, telle que `GET` ou `POST`. | | `path` | string | Oui | Chemin API Twexapi relatif. Les URL absolues sont rejetées. | | `query` | object | Non | Paramètres de requête pour la requête. | | `body` | object, array ou scalaire | Non | Corps de requête JSON pour les requêtes non-GET. | :::warning Appelez `explore` d'abord et utilisez le chemin relatif exact renvoyé par le catalogue. N'appelez pas `/openapi.json`, les pages de docs, les tableaux de bord ou les routes framework cachées via `twexapi_request`. ::: ### Contrat de réponse `twexapi_request` renvoie les métadonnées d'exécution MCP plus la réponse REST sous-jacente : ```json { "status_code": 200, "endpoint": "list_global_trending_countries", "method": "GET", "path": "/twitter/global-trending/countries", "result": { "code": 200, "msg": "success", "data": [] } } ``` Préservez les champs durables de `result`, y compris les ID, curseurs, ID de tâche, champs de crédits et ID d'action d'écriture. Lorsqu'une page inclut `has_more` et `next_cursor`, passez le curseur dans l'endpoint de suivi documenté ou le paramètre de requête renvoyé par `explore`. ## Exemples de workflow Ces exemples montrent la forme qu'un agent devrait produire. Exécutez `explore` d'abord en usage réel pour que l'agent puisse confirmer le schéma actuel. ### Rechercher des tweets avec lignes de transfert ```json { "method": "POST", "path": "/twitter/advanced_search/page", "body": { "searchTerms": ["from:openai AI agents"], "maxItems": 20, "sortBy": "Latest" } } ``` Demandez à l'agent de renvoyer un objet de transfert compact : ```json { "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 } ``` ### Récupérer les tweets tendance ```json { "method": "GET", "path": "/twitter/global-trending/tweets", "query": { "country": "united-states", "topic": "technology", "content": "AI", "count": 20 } } ``` Stockez `country`, `topic`, `content`, ID de tweets, noms d'utilisateur des auteurs, champs d'engagement, `has_more` et `next_cursor` lorsqu'ils sont présents. ### Exporter des abonnés vers un CRM ```json { "method": "GET", "path": "/twitter/followers/openai/50" } ``` Stockez `user_id`, `username`, `name`, `description`, `followers_count`, le compte source et les champs de pagination/tâche. Si l'endpoint renvoie un ID de tâche, stockez-le et interrogez l'endpoint de statut/suivant documenté. ### Lire un article X en Markdown ```json { "method": "GET", "path": "/x/article/1803006263529541838/markdown" } ``` Stockez l'ID de l'article, le titre, l'auteur, le corps Markdown, les liens extraits et l'URL source. ### Publier un tweet ou une réponse ```json { "method": "POST", "path": "/twitter/tweets/create", "body": { "tweet_content": "Hello from Twexapi MCP", "reply_tweet_id": null, "media_url": null } } ``` :::warning Traitez tout endpoint avec `read_only: false` comme une action de production. Exigez une confirmation utilisateur explicite avant de publier, répondre, suivre, bloquer, supprimer, mettre en signet ou envoyer des DM. ::: Stockez `tweet_id`, `write_action_id`, `status`, `charged_credits`, la cible de réponse, les URL média et l'enregistrement de confirmation utilisateur. ## Modèles de transfert agent MCP renvoie du JSON. Pour les files d'agents, CRM, feuilles de calcul, entrepôts et workflows no-code, renvoyez un petit objet durable avec la tâche d'origine, la route utilisée, les lignes ou ID normalisés à stocker, et le curseur ou la tâche suivante à interroger. ### Recherche de tweets vers JSON Appelez `POST /twitter/advanced_search/page`. Stockez les ID de tweets, le texte, les métadonnées d'auteur, l'heure de création, les liens, `has_more`, `next_cursor` et la requête d'origine. ### Extraire des réponses Appelez `GET /twitter/tweets/{tweet_id}/replies/{count}` pour une page bornée ou `GET /twitter/tweets/{tweet_id}/replies/page` pour la pagination par curseur. Stockez les ID de réponses, noms d'utilisateur des auteurs, texte, métriques, `has_more` et `next_cursor`. ### Exporter des abonnés Appelez `GET /twitter/followers/{screen_name}/{count}` ou les endpoints page/tâche renvoyés par `explore`. Stockez les ID utilisateur, noms d'utilisateur, noms, bios, compteurs d'abonnés, compte source, ID de tâche et curseur suivant. ### Suivre les actions d'écriture Pour les endpoints d'écriture, stockez le chemin d'endpoint, le hash du corps ou le texte de confirmation, l'ID de tweet ou d'action d'écriture renvoyé, le statut, les crédits facturés et les références média. ### Envoyer des DM Appelez l'endpoint DM uniquement après confirmation utilisateur. Stockez l'ID de message, l'ID utilisateur destinataire, le compte, les références média et le statut de livraison. Gardez les corps complets de DM hors des sorties MCP partagées. ## Catégories d'endpoints | Catégorie | Usages courants | | --- | --- | | `trending` | Pays, sujets, tags de contenu et tweets tendance. | | `search` | Recherche avancée, recherche par hashtag, recherche par cashtag et recherche paginée. | | `users` | Consultation utilisateur, vérification de compte, recherche d'utilisateurs et statut de compte. | | `tweets` | Réponses, fils, consultation de tweets, tweets similaires, sentiment, citations, retweeters et favorisateurs. | | `followers` | Abonnés, abonnements, derniers abonnés et données relationnelles paginées. | | `communities` | Métadonnées de communauté, membres, tweets, recherche et recherche de tweets de communauté. | | `lists` | Création de listes, tweets de listes, membres, abonnés et recherche de listes. | | `dm` | Statut DM, envoi DM et historique DM. | | `articles` | Consultation d'articles X, récupérations Markdown, brouillons, couvertures, mises à jour de contenu et publication. | | `timeline` | Timelines utilisateur et pages tweets/réponses. | | `accounts` | Validation de cookie, infos de compte, vérification de compte et statut de compte. | | `write` | Actions à effet de bord telles que publication, réponse, j'aime, retweet, abonnement, blocage, signet, suppression et envoi de DM. | ## Gestion des erreurs Lorsque l'authentification MCP échoue, l'outil ne s'exécute pas. Le client reçoit une erreur JSON-RPC : ```json { "jsonrpc": "2.0", "error": { "code": 401, "message": "Missing MCP API token" } } ``` Lorsque `twexapi_request` s'exécute et que l'API Twexapi sous-jacente renvoie une réponse non-2xx, préservez les métadonnées MCP et l'erreur Twexapi : ```json { "status_code": 403, "endpoint": "get_global_trending_tweets", "method": "GET", "path": "/twitter/global-trending/tweets", "result": { "detail": "Credits exhausted or action not allowed." } } ``` | Statut | Signification | | --- | --- | | `401` | L'authentification MCP a échoué avant l'exécution de l'outil ; vérifiez `x-api-key` ou l'authentification Bearer. | | `403` | La clé API est indisponible, les crédits sont épuisés ou l'action n'est pas autorisée. | | `429` | Limite de débit dépassée. Réessayez après la fenêtre de limite. | | `5xx` | Défaillance côté service ou problème de récupération X/Twitter en amont. | Consultez [Error Handling](/guides/error-handling) et [Rate Limits](/guides/rate-limits) pour les modèles de récupération REST et MCP.