twist

Twist MCP サーバー

MCP についてまだご存じないですか？最新情報を簡単に把握するには、PulseMCP の週刊ニュースレターをご覧ください。

---

これは、MCP クライアントと Twist のチームメッセージングおよびコラボレーションプラットフォームを連携する MCP（Model Context Protocol）サーバーです。統一されたインターフェースを通じて、チャンネル、スレッド、メッセージを管理できます。

Twist は、整理されたスレッドを通じた非同期コミュニケーションを重視するチーム向けコミュニケーションアプリです。従来のチャットアプリとは異なり、会話をチャンネルとスレッドに整理することで、情報過多を軽減するよう設計されています。このサーバーは、Twist の REST API に直接接続します。利用を開始するには、Twist のベアラートークンが必要です。

このプロジェクトは Twist と公式に提携しているものではありません。

目次

• 主な特長
• 機能
• 使い方のヒント
• 例
• セットアップ
  • チートシート
  • Claude Desktop
    • 手動セットアップ

主な特長

チャンネル管理：チャンネルの一覧表示や情報の取得により、チームのコミュニケーション構造を把握できます。

スレッド操作：新しいスレッドを作成し、既存のスレッドにアクセスして、整理されたトピック別の議論を行えます。

メッセージ投稿：プログラムからスレッドにメッセージを追加し、更新や通知を自動化できます。

非同期コミュニケーションを優先：即時の返信を必要としない、落ち着いた整理されたコミュニケーションを重視する Twist の理念に沿って設計されています。

機能

このサーバーは macOS と Claude Desktop で構築およびテストされています。他の MCP クライアントでも動作するはずです。

ツール名	説明
get_channels	ワークスペース内のすべてのチャンネルの一覧を取得します。
get_channel	ID を指定して、特定のチャンネルの詳細情報を取得します。
get_threads	オプションのフィルターを指定して、チャンネル内のスレッド一覧を取得します。
get_thread	メッセージを含む、特定のスレッドの詳細情報を取得します。
create_thread	タイトルと初期コンテンツを指定して、チャンネル内に新しいスレッドを作成します。
add_message_to_thread	既存のスレッドに新しいメッセージを追加します。

使い方のヒント

• まず get_channels を使って、ワークスペースで利用できるチャンネルを確認します
• スレッドを作成するときは、整理しやすいように、明確で内容が分かりやすいタイトルを付けます
• 関連する議論はスレッドにまとめ、同じトピックで複数のスレッドを作成しないようにします
• ほとんどの操作でワークスペース ID が必要です。環境変数で設定できます
• スレッドとメッセージのコンテンツは、リッチテキスト表示のための Markdown 形式に対応しています
• すべての一覧表示操作は、項目数の多いワークスペース向けにページネーションに対応しています

例

チャンネルを確認してスレッドを作成する

User: "Show me all channels in my Twist workspace"
Assistant: I'll get the list of channels in your workspace.

[Uses get_channels tool]

I found 5 channels in your workspace:
1. #general (ID: ch_123) - General discussions
2. #engineering (ID: ch_456) - Engineering team channel
3. #product (ID: ch_789) - Product discussions
...

User: "Create a thread in the engineering channel about the new API design"
Assistant: I'll create a new thread in the #engineering channel.

[Uses create_thread tool with channel_id: ch_456]

I've created a new thread titled "API Design Discussion - v2.0" in the #engineering channel. The thread ID is th_999.

既存のスレッドに追加する

User: "Add a message to thread th_999 with the latest API documentation link"
Assistant: I'll add that message to the thread.

[Uses add_message_to_thread tool]

I've added your message with the API documentation link to the thread.

開発

テスト

このプロジェクトでは、単体テストに Vitest を使用しています。テストは、プルリクエスト時と main ブランチへのプッシュ時に自動的に実行されます。

ローカルでテストを実行する

# Install dependencies
npm run install-all

# Run tests once
npm run test:run

# Run tests in watch mode (recommended for development)
npm test

# Run tests with UI
npm run test:ui

テストの構成

テストは tests/ ディレクトリにあります。

• tests/functional/ - 個々のコンポーネントの機能テスト
• tests/integration/ - Twist API をモックした統合テスト
• tests/manual/ - 実際の Twist API にアクセスする手動テスト（CI では実行されません）
• tests/mocks/ - モック実装とテストデータ

テスト方法の詳細については、tests/README.md をご覧ください。

手動テスト

手動テストは、実際の Twist API との完全な統合を検証するエンドツーエンドのシステムテストです。これらのテストは次のとおりです。

• 実際の API 認証情報が必要です（TWIST_BEARER_TOKEN と TWIST_WORKSPACE_ID の環境変数）
• 実際の Twist 本番 API にアクセスします（モックではありません）
• 現実的なワークフローで実際の API 呼び出しを連続して実行します
• API のレート制限や外部サービスへの依存を避けるため、CI では実行しません
• TwistClient のコード、または外部 API とやり取りするコードを変更する際に実行してください

手動テストを実行するには：

# Copy .env.example to .env and add your credentials
cp .env.example .env
# Edit .env to add your real bearer token and workspace ID

# Run manual tests
npm run test:manual

# Run manual tests in watch mode
npm run test:manual:watch

セットアップ

前提条件

• Node.js v24.2.0（nvm がインストールされている場合は nvm use を使用してください）
• Twist のベアラートークン
• Twist ワークスペース ID

クイックリファレンス

環境変数	説明	必須	デフォルト値	例
TWIST_BEARER_TOKEN	Twist のベアラートークンです。twist.com から取得できます	Y	N/A	oauth2:4238438234..
TWIST_WORKSPACE_ID	Twist ワークスペース ID	Y	N/A	12345

Claude Desktop

Twist のベアラートークン とワークスペース ID を用意してください。

次に、以下からお好みのサーバー設定方法に進んでください。MCP サーバーを初めて使用する場合は、Claude Desktop アプリケーションを用意し、MCP の公式セットアップ手順に従ってください。

手動セットアップ

ターミナルで npx コマンドを実行できるよう、お使いのマシンで Node が動作する必要があります。Node がインストールされていない場合は、nodejs.org からインストールできます。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json ファイルを編集して、以下を追加してください。

{
  "mcpServers": {
    "twist": {
      "command": "npx",
      "args": ["-y", "twist-mcp-server"],
      "env": {
        "TWIST_BEARER_TOKEN": "Bearer your-token-here",
        "TWIST_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

Claude Desktop を再起動すれば、準備完了です！

実装計画

フェーズ 1：初期セットアップ ✅

• テンプレートからプロジェクト構成を作成
• 包括的な README ドキュメントを作成
• API 統合の方針を計画

フェーズ 2：コアインフラストラクチャ

• TypeScript の設定
• 適切な認証を備えた Twist API クライアントを作成
• エラー処理と再試行ロジックを実装
• テストインフラストラクチャを設定（機能テスト、統合テスト、手動テスト）

フェーズ 3：ツールの実装

• get_channels を実装 — ワークスペース内のすべてのチャンネルを一覧表示
• get_channel を実装 — 特定のチャンネルの詳細を取得
• get_threads を実装 — フィルタリングオプションを使ってスレッドを一覧表示
• get_thread を実装 — メッセージを含むスレッドを取得
• create_thread を実装 — 新しいディスカッションスレッドを作成
• add_message_to_thread を実装 — スレッドにメッセージを投稿

フェーズ 4：テストと仕上げ

• 包括的なユニットテストを作成
• モック API を使った統合テストを作成
• 実際の API 検証用の手動テストを実装
• 適切なエラーメッセージとユーザーへのフィードバックを追加
• API の制限や特有の挙動を文書化

フェーズ 5：今後の機能強化（MVP 後）

• スレッド検索に対応
• メッセージの編集／削除を実装
• ファイル添付に対応
• リアクションとメンションに対応
• ワークスペースのユーザー管理ツール

技術的な決定事項

API 統合

• REST API を使用（https://developer.twist.com/v3/）
• レート制限と再試行ロジックを実装
• リスト操作のページネーションに対応
• ネットワークの問題を適切に処理

認証

• Authorization ヘッダーを使用したベアラートークン認証
• ほとんどの操作でワークスペース ID が必要です
• 認証情報は環境変数を使用して安全に保存してください

ツールの設計

• ツールの用途を絞り、単一の目的にします
• 一貫した命名規則を使用します（get**、create*_、add__）
• 使いやすい構造化データを返します
• よくある問題に役立つエラーメッセージを含めます