Torna Mcp

torna-mcp

Torna API ドキュメントシステムと AI アシスタント（Cursor、Claude Desktop など）をつなぐ MCP サーバーです。自然言語を使って、Torna の API ドキュメントを照会、検索、閲覧できます。

できること

このサーバーは、Torna の API ドキュメントを MCP ツール、リソース、プロンプトとして公開します。AI アシスタントは次のことができます。

• キーワードや自然言語の要件で API を検索する
• 詳細な API 定義を取得する
• curl コマンドの例を生成する
• プロジェクトを切り替える
• プロジェクトのメタデータにアクセスする

特長

• 認証設定不要：認証情報は接続ごとにキャッシュされるため、繰り返し入力する必要はありません
• 一括操作：複数の API 詳細を並行して取得します
• スマートマッチング：自然言語の要件 → 一致する API
• プロジェクト切り替え：Torna のプロジェクトをその場で切り替えられます

クイックスタート

インストール

git clone https://github.com/chenqi146/torna-mcp.git
cd torna-mcp
npm install
npm run build

実行

npm start
# Server runs on http://localhost:3000

または Docker を使用します。

docker build -t torna-mcp .
docker run -p 3000:3000 torna-mcp

Cursor で設定する

~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "torna": {
      "transport": "http",
      "url": "http://localhost:3000/mcp",
      "heartbeat": true,
      "headers": {
        "username": "your_torna_username",
        "password": "your_torna_password",
        "projectid": "your_project_id",
        "torna-base-url": "http://your-torna-server:7700"
      }
    }
  }
}

Cursor を再起動し、torna MCP サーバーを選択します。

使用例

要件から API を探す

あなた：「ユーザー情報を照会する API が必要です」

AI：torna-find-apis-by-need を使って API を照合し、次を返します。

• ユーザー詳細 API（/api/user/detail）
• ユーザー一覧 API（/api/user/list）

キーワードで検索する

あなた：「『駐車』に関連する API をすべて探してください」

**AI：**キーワード「parking」を指定して torna-search-docs を使い、一致する API を返します。

API の詳細を取得する

あなた：「次の 3 つの API の詳細を取得してください：JzAM4Mzp,AbC123Xy,Def456Za」

**AI：**カンマ区切りの docIds を指定して torna-get-doc-detail を使い、すべてを並行して取得します。

プロジェクトを切り替える

あなた：「利用可能なプロジェクトを教えてください。user-center プロジェクトに切り替えてください」

AI：torna-list-projects でプロジェクト一覧を表示し、torna-select-project で切り替えます。

curl コマンドを生成する

あなた：「ユーザー詳細 API の curl コマンドを生成してください」

AI：torna-generate-request を使って、そのまま使える curl コマンドを生成します。

MCP ツール

すべてのツールは、接続ヘッダーからキャッシュ済みの認証情報を自動的に使用します。

ツール	説明
torna-project-info	現在のセッション情報を取得します（ユーザー名、プロジェクト ID／名前、トークンの状態、ドキュメント数）
torna-search-docs	キーワードで API を検索します。キーワードが空の場合はツリー全体を返します
torna-get-doc-detail	API の詳細を取得します。単一またはカンマ区切りの docIds に対応します（一括、並行処理）
torna-list-projects	アクセス可能なすべてのスペース／プロジェクトを一覧表示します
torna-select-project	以降の操作で使用するアクティブなプロジェクトを切り替えます

MCP リソース

• config://settings - サーバー設定の例
• torna://session/project - 現在のセッションのプロジェクト情報
• torna://projects - リアルタイムのプロジェクト一覧

MCP プロンプト

• torna-find-apis-by-need - 自然言語の要件に一致する API を探します。一致精度を高めるため、API が 30 件以下のプロジェクトでは詳細を自動取得します。
• torna-generate-request - API 定義から curl コマンドを生成します

開発

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Production
npm start

環境変数

• PORT - サーバーポート（デフォルト：3000）
• MCP_URL - MCP サーバーのベース URL（デフォルト：http://localhost:3000）

ログ

• [TornaExternal] - 実際の Torna API リクエスト／レスポンス
• [TornaAPI] - クライアントへの MCP レスポンス
• [MCPAuth] - 認証イベント
• [MCPCapture] - MCP リクエストのキャプチャ

アーキテクチャ

AI Assistant (Cursor/Claude) 
    ↓ MCP Protocol
torna-mcp Server (this project)
    ↓ HTTP Proxy
Torna API Server

このサーバーは MCP クライアントと Torna の間のプロキシとして動作し、次を処理します。

• 認証（ログイン、トークンのキャッシュ）
• リクエストのルーティング（MCP ツール → Torna エンドポイント）
• レスポンスの変換（Torna 形式 → MCP 形式）

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更を加えます
4. プルリクエストを送信します

シンプルに保ちましょう。不要な抽象化は避けてください。

ライセンス

MIT