AISDK MCP Bridge

AISDK MCP Bridge

Model Context Protocol（MCP）と AI SDK をシームレスに統合し、MCP サーバーと AI モデル間の効率的な通信とツール実行を実現するブリッジパッケージです。

特長

• MCP サーバーと AI SDK のシームレスな統合
• さまざまな MCP サーバータイプ（Node.js、Python、UVX）をサポート
• 独立した設定によるマルチサーバー対応
• mcp.config.json による柔軟な設定
• 完全な型定義を備えた TypeScript 対応
• 堅牢なエラー処理とログ記録
• ツール実行に使いやすい API

インストール

npm install aisdk-mcp-bridge

クイックスタート

1. プロジェクトのルートに mcp.config.json ファイルを作成します。

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@enescinar/twitter-mcp"],
      "env": {
        "API_KEY": "your-twitter-api-key",
        "API_SECRET_KEY": "your-twitter-api-secret",
        "ACCESS_TOKEN": "your-twitter-access-token",
        "ACCESS_TOKEN_SECRET": "your-twitter-access-token-secret"
      }
    },
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "mcp-server-firecrawl"],
      "env": {
        "FIRE_CRAWL_API_KEY": "your-firecrawl-api-key",
        "FIRE_CRAWL_API_URL": "https://api.firecrawl.com"
      }
    }
  }
}

2. コードにブリッジをインポートして使用します。

import { generateText } from 'ai';
import { google } from '@ai-sdk/google';
import { getMcpTools, cleanupMcp, initializeMcp } from 'aisdk-mcp-bridge';
import dotenv from 'dotenv';
dotenv.config();

async function main() {
  try {
    // Initialize MCP
    await initializeMcp({ debug: true });

    // Get tools from all servers
    const allTools = await getMcpTools({ debug: true });

    // Or get tools from a specific server
    const twitterTools = await getMcpTools({
      debug: true,
      serverName: 'twitter-mcp',
    });

    // Use tools with AI SDK
    const result = await generateText({
      model: google('gemini-1.5-pro'),
      messages: [
        {
          role: 'system',
          content:
            'You are an AI assistant that uses various tools to help users.',
        },
        {
          role: 'user',
          content: 'Your task description here',
        },
      ],
      tools: twitterTools, // or allTools for all available tools
    });

    console.log('Result:', result.text);
  } finally {
    // Clean up resources
    await cleanupMcp();
  }
}

main().catch(error => {
  console.error('Error:', error);
  process.exit(1);
});

設定

mcp.config.json ファイルでは、複数のサーバーと通信モードを設定できます。各サーバーは個別に設定できます。

サーバー設定の例：

Twitter MCP サーバー

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@enescinar/twitter-mcp"],
      "env": {
        "API_KEY": "your-twitter-api-key",
        "API_SECRET_KEY": "your-twitter-api-secret",
        "ACCESS_TOKEN": "your-twitter-access-token",
        "ACCESS_TOKEN_SECRET": "your-twitter-access-token-secret"
      }
    }
  }
}

Firecrawl サーバー

{
  "mcpServers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "mcp-server-firecrawl"],
      "env": {
        "FIRE_CRAWL_API_KEY": "your-firecrawl-api-key",
        "FIRE_CRAWL_API_URL": "https://api.firecrawl.com"
      }
    }
  }
}

SSE サーバー

{
  "mcpServers": {
    "sse-server": {
      "command": "node",
      "args": ["./server.js"],
      "mode": "sse",
      "sseOptions": {
        "endpoint": "http://localhost:3000/events",
        "headers": {},
        "reconnectTimeout": 5000
      }
    }
  }
}

サーバーモード

ブリッジはさまざまな通信モードに対応しています。

1. stdio モード（デフォルト）

   • 標準入出力を介した直接通信
   • シンプルな統合やローカル開発に最適
   • 低レイテンシで、セットアップも最小限

2. SSE モード（Server-Sent Events）

   • サーバーからクライアントへのリアルタイムな一方向通信
   • ストリーミング更新や長時間実行される処理に最適
   • 再接続処理を内蔵

API リファレンス

コア関数

initializeMcp(options?: InitOptions): Promise<void>

指定したオプションで MCP サービスを初期化します。

interface InitOptions {
  configPath?: string; // Path to mcp.config.json
  debug?: boolean; // Enable debug logging
}

getMcpTools(options?: ToolOptions): Promise<ToolSet>

MCP サーバーから AI SDK 互換のツールを取得します。

interface ToolOptions {
  debug?: boolean; // Enable debug logging
  serverName?: string; // Optional server name to get tools from a specific server
}

executeMcpFunction(serverName: string, functionName: string, args: Record<string, unknown>): Promise<MCPToolResult>

MCP サーバー上の特定の関数を直接実行します。

// Example
const result = await executeMcpFunction('twitter-mcp', 'postTweet', {
  text: 'Hello from MCP!',
});

コア型

MCPConfig（MCPServersConfig のエイリアス）

MCP サーバーの設定型です。

interface MCPConfig {
  mcpServers: {
    [key: string]: ServerConfig;
  };
}

ServerConfig

個々の MCP サーバーの設定です。

interface ServerConfig {
  command: string;
  args?: string[];
  env?: Record<string, string>;
  mode?: 'stdio' | 'sse';
  sseOptions?: {
    endpoint: string;
    headers?: Record<string, string>;
    reconnectTimeout?: number;
  };
}

MCPToolResult

MCP ツール実行の結果型です。

interface MCPToolResult {
  success: boolean;
  data?: unknown;
  error?: string;
}

cleanupMcp(): Promise<void>

MCP リソースをクリーンアップし、すべてのサーバー接続を閉じます。

エラー処理

ブリッジは、以下のケースに対する包括的なエラー処理を備えています。

• サーバーの初期化失敗
• 通信エラー
• ツール実行の失敗
• 設定の問題
• サーバー接続の問題

ログ記録

ブリッジは、以下を通じて詳細なログを提供します。

• mcp-tools.log：サーバー側のツール実行ログ
• デバッグやエラーのためのコンソール出力

デバッグログ

DEBUG 環境変数を設定すると、詳細なデバッグログを有効にできます。

# Enable all debug logs
DEBUG=* npm start

# Enable MCP debug logs
DEBUG=mcp npm start

# Enable all MCP namespace logs
DEBUG=mcp:* npm start

デバッグログには、以下の情報が表示されます。

• サーバーの初期化イベントとシャットダウンイベント
• ツールの登録と実行の詳細
• MCP サーバーとの通信
• スキーマの変換と検証
• スタックトレースを含むエラーの詳細
• パフォーマンス指標と時間情報

ログの種類

ログシステムは、次の 3 種類のログに対応しています。

• info：一般的な運用情報
• debug：詳細なデバッグ情報（DEBUG 環境変数が必要）
• error：エラーメッセージとスタックトレース（常に記録）

ログファイル

すべてのログは、次の形式で logs/mcp-tools.log に書き込まれます。

[TIMESTAMP] [TYPE] Message
{Optional JSON data}

開発

前提条件

• Node.js 20.x 以降
• npm 7.x 以降

セットアップ

1. リポジトリをクローンします
2. 依存関係をインストールします。

npm install

テスト

テストスイートを実行します。

npm test

特定のテストを実行します。

npm run test:twitter
npm run test:firecrawl

コントリビューション

コントリビューションを歓迎します！詳細については、コントリビューションガイドをご覧ください。

• 開発環境のセットアップ
• コーディング規約
• プルリクエストの手順
• 新しい MCP サーバーの追加

このプロジェクトは行動規範に基づいて公開されています。このプロジェクトに参加することで、その規約に従うことに同意したものとみなされます。

サポート

サポートが必要な場合：

1. ドキュメントを確認してください
2. 既存のイシューを検索してください
3. 問題が解決しない場合は、新しいイシューを作成してください

変更履歴

変更内容と移行ガイドについては、CHANGELOG.mdをご覧ください。

セキュリティ

セキュリティに関する問題は、公開イシュートラッカーではなく、[email protected] にメールでお知らせください。

作者

• Ravi Kiran - 初期作業 - @vrknetha

このプロジェクトに参加したコントリビューターの一覧もご覧ください。

謝辞

• 優れた SDK を提供してくださった AI SDK チーム
• プロトコル仕様を策定してくださった MCP コミュニティ
• プロジェクトを支援してくださったすべてのコントリビューター

ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細については、LICENSEファイルをご覧ください。