# fxtwitter-mcp

[FxTwitter / FxEmbed API](https://docs.fxembed.com/api/introduction/) を Model Context Protocol（MCP）から利用する、Cloudflare Workers + Hono製のリモートMCPサーバーです。

FxTwitter API v2の読み取り系GET APIを16個のMCPツールとして公開します。MCPエンドポイントはステートレスなStreamable HTTPで、認証はありません。

> [!IMPORTANT]
> このプロジェクトはFxTwitter / FxEmbedの非公式クライアントです。公開デプロイすると、URLを知っている第三者も上流APIを呼び出せます。必要に応じてCloudflare Accessや独自認証を追加してください。

## 構成

- Cloudflare Workers
- Hono
- Cloudflare Agents SDK `createMcpHandler`
- MCP TypeScript SDK v2
- TypeScript
- Vitest + Cloudflare Workers runtime

## エンドポイント

| パス | メソッド | 用途 |
| --- | --- | --- |
| `/` | GET | サービス情報 |
| `/health` | GET | ヘルスチェック |
| `/mcp` | GET / POST / DELETE | MCP Streamable HTTP |

## MCPツール

すべて読み取り専用・非破壊・冪等なツールです。

| ツール | FxTwitter API |
| --- | --- |
| `get_post` | 投稿を取得 |
| `list_post_reposters` | 投稿をリポストしたユーザーを取得 |
| `list_post_quotes` | 引用投稿を取得 |
| `get_thread` | スレッドを展開して取得 |
| `get_conversation` | スレッドと返信を取得 |
| `list_user_statuses` | ユーザーの投稿を取得 |
| `list_user_articles` | ユーザーの記事を取得 |
| `get_user_about` | About Account統計を取得 |
| `list_user_media` | ユーザーのメディア投稿を取得 |
| `list_user_followers` | フォロワーを取得 |
| `list_user_following` | フォロー中ユーザーを取得 |
| `get_user_profile` | プロフィールを取得 |
| `search_posts` | 投稿を検索 |
| `search_users` | ユーザーを検索 |
| `get_typeahead` | 検索候補を取得 |
| `get_trends` | トレンドを取得 |

カーソルが返るAPIは自動で全ページを取得しません。レスポンスの `cursor.bottom` を次の呼び出しの `cursor` に指定してください。

## ローカル実行

Node.js 20以降が必要です。PowerShellでプロジェクトのルートから実行します。

```powershell
npm install
npm run dev
```

起動後のMCP URLは `http://localhost:8787/mcp` です。

MCP Inspectorで接続確認する場合:

```powershell
npx @modelcontextprotocol/inspector@latest
```

InspectorでTransportにStreamable HTTP、URLに `http://localhost:8787/mcp` を指定します。

## 検証

```powershell
npm test
npm run typecheck
npm run types:check
npm run deploy:dry-run
```

すべてを順番に実行する場合:

```powershell
npm run check
```

テストではURLエンコード、タイムアウト、JSON不正、5 MiB上限、APIエラー、全16ツールのルーティング、MCPツール一覧、Origin検証をCloudflare Workersランタイム上で確認します。外部API通信はモックされます。

## 制限と安全対策

- 上流は `https://api.fxtwitter.com` に固定しています。
- FxTwitterが要求する識別用User-Agentを送信します。
- パス要素とクエリはURL APIでエンコードし、任意URLへのアクセスは受け付けません。
- 上流リクエストは10秒でタイムアウトします。
- 上流レスポンスは5 MiBまで読み込みます。
- FxTwitter APIのレート制限や利用条件に従ってください。
- 検索結果などはMCPへ整形せず、上流JSONをそのまま返します。

## ライセンス

[MIT License](./LICENSE) © 2026 Tomoya Ogawa