---
title: "Mastra"
description: "Tweet araması, profiller, trendler ve incelenen X yazıları için TwexAPI MCP aracılığıyla TypeScript Mastra aracıları oluşturun."
---

TwexAPI'nin MCP sunucusu aracılığıyla bir Mastra Twitter API aracısı oluşturun. Tweet'leri arayın, profilleri inceleyin, eğilimleri okuyun ve yazma işlemlerini inceleyin. Tweet kimliklerini, imleçleri ve rota adlarını yalnızca sohbet özetleri yerine JSON olarak yazıldığı gibi koruyun.

## Mastra'yı neden TwexAPI ile kullanmalısınız?

Mastra bir TypeScript aracı çerçevesidir. TwexAPI, "explore" ve `twexapi_request` yoluyla uç nokta keşfi ve kimliği doğrulanmış çağrılar sağlar.

| Temsilci görevi | TwexAPI rotası | Bir sonraki adım için saklayın |
| --- | --- | --- |
| Tweet'lerde ara | `POST /twitter/advanced_search/page` | Sorgu, tweet kimlikleri, yazarlar, "created_at", imleç |
| Bir profili inceleme | `GET /twitter/{screen_name}/about` | Kullanıcı kimliği, kullanıcı adı, biyografi, takipçi sayısı |
| Trendleri okuyun | `GET /twitter/global-trending/tweets` | Ülke, konu, tweet satırları |
| Gönder veya yanıtla | `POST /twitter/tweets/create` | Tweet kimliği, rota, insan onayı, çerez onayı |

Zaten Vercel AI SDK modellerini kullanan TypeScript uygulamaları için Mastra'yı kullanın. Model gerektirmeyen zamanlanmış işler için [TypeScript SDK](/sdks/typescript) veya [CLI](/sdks/cli) kullanın.

## Önkoşullar

- Node.js 20 veya üzeri
- Bir [TwexAPI API anahtarı](https://twexapi.io/dashboard)
- Mastra destekli bir model sağlayıcı anahtarı
Public docs focus on API-key reads.

Genel X okumalarının X Developer kimlik bilgilerine ihtiyacı yoktur. TwexAPI ile kimlik doğrulaması yapın.

## Kurulum

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

```txt .env
TWEXAPI_API_KEY=YOUR_API_KEY
OPENAI_API_KEY=sk-...
```

## TwexAPI MCP'ye bağlanın

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

Sunucu keşif için `explore` ve kimliği doğrulanmış çağrılar için `twexapi_request` sunar. Kimliği doğrulanmamış MCP istekleri `401` döndürür.

## Tam örnek

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

Başka bir iş akışı tüketmeden önce JSON'u doğrulayın. Konuşma geçmişi bir iş veritabanı değildir.

## MCP yanıt sözleşmesini koruyun

`explore` çıktısındaki yalnızca belgelenmiş `query` ve `body` alanlarını `twexapi_request`'e iletin.

Aşağıdaki koşullardan biri doğru olduğunda sayfalandırmayı durdurun:

- Agent istenen toplamı toplar.
- `has_more` veya `has_next_page` false olur.
- `next_cursor` eksik veya tekrarlanır.
- Yapılandırılmış sayfa sınırına ulaşılır.

Tweet ve kullanıcıları `tweet_id` veya `user_id` ile tekilleştirin.

## Devam ettirilebilir agent devrini sürdürün

<CardGroup cols={2}>
  <Card title="Tweet sayfaları" icon="message-square">
    `tweet_id`, `text`, `author_username`, `created_at`, `has_more`, `next_cursor` ve orijinal sorguyu saklayın.
  </Card>
  <Card title="Profil satırları" icon="user-round">
    `user_id`, `username`, `name`, `description`, takipçi sayıları ve arama girdisini saklayın.
  </Card>
  <Card title="Trend satırları" icon="radio">
    Ülke, konu, tweet kimlikleri ve etkileşim metriklerini saklayın.
  </Card>
  <Card title="Yazma işlemleri" icon="send">
    Rotayı, önizleme metnini ve insan onayını saklayın. Çerezleri devir dosyasının dışında tutun. Bkz..
  </Card>
</CardGroup>

Tam kontrol listesi için bkz. [Agent MCP Handoff](/mcp/agent-handoff).

## Hata işleme oluşturun

| Durum | Anlam | Agent kararı |
| --- | --- | --- |
| `400` | Geçersiz rota veya parametreler | Yeniden denemeden önce isteği düzeltin |
| `401` | Eksik veya geçersiz API anahtarı | Durdurun ve kimlik bilgisini değiştirin |
| `403` | Erişim reddedildi veya kredi | Yazmaları duraklatın; [Get Balance](/api-reference/balance-endpoints/get-balance-api-balance-get) kontrol edin |
| `429` | Hız sınırına ulaşıldı | Geri çekilin, ardından aynı imleçle devam edin |
| `5xx` | Geçici sunucu hatası | Güvenli okumalara sınırlı geri çekilme uygulayın |

Okuma kontrolü yapmadan zaman aşımından sonra bir yazmayı asla yeniden denemeyin. Bkz. [Error Handling](/guides/error-handling) ve [Rate Limits](/guides/rate-limits).

## X işlemlerinden önce onay isteyin

```txt
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.
```

Onaydan sonra [CLI](/sdks/cli) `--dry-run` ile önizleyin, ardından REST veya TypeScript SDK üzerinden yürütün.

## Birden fazla MCP sunucusuna bağlanın

```ts
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 sunucu adını sabit tutun. Temsilciye yalnızca mevcut iş için gerekli araçları verin.

## Paket versiyonları

| Paket | Desteklenen aralık |
| --- | --- |
| Node.js | `>=20` |
| `@mastra/core` | `>=0.10` |
| `@mastra/mcp` | `>=0.10` |

## Sonraki adımlar

- [MCP Araçları](/mcp/tools)
- [Ajan MCP Aktarımı](/mcp/agent-handoff)
-
- [TypeScript SDK'sı](/sdks/typescript)
- [Gelişmiş Twitter Araması](/api-reference/search-endpoints/get-data-page-twitter-advanced-search-page-post)