MCP Server Hub / Gateway

MCP Server Hub / Gateway

目的： このプロジェクトは、複数の MCP（Model Context Protocol）サーバーを管理し、ハブネイティブのツールを公開する一元化されたゲートウェイを提供します。これにより、Cline、Cursor などの LLM クライアントごとに重複したサーバープロセスを設定して実行する必要がなくなります。動的な設定の再読み込みに対応しており、メインのゲートウェイサーバーを再起動せずに、管理対象のサーバーやハブのツール／サービスを更新できます。このプロジェクトが提供する単一の gateway-client エンドポイントに LLM クライアントを接続することで、すべての管理対象 MCP サーバーとハブ自体のツールに、単一のインターフェースからアクセスできます。

アーキテクチャ

このリポジトリのシステムは、次の 2 つの主要コンポーネントで構成されています。

1. ゲートウェイサーバー（src/server.ts）：

   • 継続的に実行される中核のハブプロセスです。
   • 起動時に初期設定ファイル（mcp_hub_config.json）を読み込みます。重要な点として、ビルドプロセスによってこのファイルは dist/ ディレクトリにコピーされ、実行中のサーバーは dist/mcp_hub_config.json ファイルの変更を監視します。
   • mcpServers 設定セクションで定義された基盤の MCP サーバーのライフサイクル（起動、停止、監視、再起動）を動的に管理します。
   • hubTools 設定セクションで定義されたハブネイティブのツールを動的に読み込み／アンロード／更新します。
   • 設定変更に応じて動作する設定可能な内部サービス（exampleService など）に対応しています。
   • ゲートウェイクライアントからの WebSocket 接続をリッスンします（デフォルトポートは 8081）。
   • 管理対象サーバーからツールを検出し、serverId__toolName 名前空間で公開します。
   • ハブネイティブのツールを hub__toolName 名前空間で公開します。
   • ゲートウェイクライアントから受信したツール呼び出しを、適切な管理対象サーバーまたは内部ハブツールのハンドラーにルーティングします。

2. ゲートウェイクライアント（src/client/client.ts）：

   • LLM クライアントが STDIO 経由で接続するプロキシサーバーとして動作します。
   • WebSocket 経由で実行中のゲートウェイサーバーに接続します（自動再接続対応）。
   • LLM クライアントからの MCP リクエスト（mcp_listTools、mcp_callTool など）をゲートウェイサーバーに転送します。
   • ゲートウェイサーバーからの応答を LLM クライアントに返します。
   • 動的な変更に対応するため、ゲートウェイサーバーに定期的にツール一覧の更新を問い合わせます（CLIENT_TOOL_REFRESH_INTERVAL_MS 環境変数で設定可能。デフォルトは 5 分です）。（Claude Desktop では動作しません）
   • ツール一覧を更新するには、MCP クライアントのプロセスを再起動してください。

ワークフロー図：

flowchart LR
    subgraph "User Machine"
        LLM_Client1["LLM Client (e.g., Cline)"]
        LLM_Client2["LLM Client (e.g., Cursor)"]

        subgraph "Gateway Client Process"
            style GatewayClientProcess fill:#f9f,stroke:#333,stroke-width:2px
            GatewayClient["Gateway Client App\n(client.ts)"]
        end

        subgraph "Gateway Server Process"
            style GatewayServerProcess fill:#ccf,stroke:#333,stroke-width:2px
            GatewayServer["Gateway Server\n(server.ts)"]
            ConfigFile["dist/mcp_hub_config.json"] --- Watcher["File Watcher"]
            Watcher -- "Triggers Reload" --> GatewayServer
            MCPServer1["Managed MCP Server 1"]
            MCPServer2["Managed MCP Server 2"]
            HubTool["Hub Tool\n(e.g., exampleHubTool.ts)"]
            HubService["Hub Service\n(e.g., ExampleConfigurableService.ts)"]
        end
    end

    LLM_Client1 -- "STDIO" --> GatewayClient
    LLM_Client2 -- "STDIO" --> GatewayClient
    GatewayClient -- "WebSocket" --> GatewayServer
    GatewayServer -- "Manages/Proxies" --> MCPServer1
    GatewayServer -- "Manages/Proxies" --> MCPServer2
    GatewayServer -- "Loads/Runs" --> HubTool
    GatewayServer -- "Uses" --> HubService
    GatewayServer -- "Reads/Watches" --> ConfigFile

はじめに

1. 前提条件

• Node.js（v20+ を推奨）
• npm
• 管理する対象の MCP サーバーがインストール済みで、アクセス可能であること。

2. インストールとビルド

# Clone the repository (if you haven't already)
# git clone ...
# cd mcp-server-hub-server

# Install dependencies
npm install

# Build the Gateway Server and Client code
# This compiles TypeScript AND copies mcp_hub_config.json to dist/
npm run build

3. 設定（mcp_hub_config.json）

プロジェクトのルートディレクトリにある mcp_hub_config.json ファイルを編集して、ハブを設定します。npm run build コマンドを実行すると、このファイルが dist/ ディレクトリにコピーされます。実行中のサーバーは、ライブ変更を反映するために dist/ 内のファイルを監視します。

mcp_hub_config.json の例：

{
  "mcpServers": {
    "thought-server": {
      "command": "node",
      "args": ["D:\\Projects\\mcp-thought-server\\build\\index.js"],
      "env": {},
      "autoRestart": true
    },
    "file-ops": {
      "command": "node",
      "args": ["D:/Projects/mcp-servers/Cline/MCP/file-operations-server/build/index.js"]
    }
    // Add entries for other managed MCP servers here...
  },
  "hubTools": {
    "example": {
      "description": "An example tool provided by the hub itself.",
      "modulePath": "./exampleHubTool.js", // Path relative to dist/tools/
      "handlerExport": "default", // Optional, defaults to 'default'
      "enabled": true // Optional, defaults to true
    }
    // Add entries for other hub-native tools here...
  },
  "exampleService": {
    "featureFlag": false,
    "messagePrefix": "INITIAL"
    // Add other settings specific to ExampleConfigurableService
  },
  "settings": {
    "logLevel": "info", // Optional: 'error', 'warn', 'info', 'debug'
    "wsPort": 8081,     // Port for Gateway Clients (WebSocket)
    "ssePort": null     // SSE interface port (null to disable)
  }
}

主な設定セクション：

• mcpServers：ハブが管理する外部 MCP サーバーを定義します。
  • キー：一意の serverId（ツールの名前空間に使用されます。例：thought-server）。
  • command、args、env、workingDir、autoRestart、maxRestarts：標準的なプロセス設定です。
• hubTools：このハブプロジェクト内（src/tools/）で直接実装するツールを定義します。
  • キー：ツールのベース名（例：example）。
  • description：ツールの説明です。
  • modulePath：コンパイル済み JS ファイルへのパス（dist/tools/ からの相対パス）。
  • handlerExport（任意）：ツールハンドラー関数を含む名前付きエクスポート（既定値は default）。このモジュールでは inputSchema（Zod スキーマ）もエクスポートする必要があります。
  • enabled（任意）：true または false（既定値：true）。
• exampleService：ExampleConfigurableService 固有の設定です。他の設定可能なハブサービスのセクションもここに追加します。
• settings：ゲートウェイの一般設定です。
  • wsPort：gateway-client が使用する WebSocket インターフェースのポートです。
  • logLevel：ログの詳細度です。
  • ssePort：Server-Sent Events インターフェースのポート（有効にした場合）です。

動的な再読み込み： サーバーの実行中に dist/mcp_hub_config.json に保存された変更は、自動的に検出され、適用されます。

• mcpServers の変更により、対応するサーバープロセスが停止、起動、または再起動されます。
• hubTools の変更により、指定されたツールモジュールが読み込み、読み込み解除、または再読み込みされます。
• settings またはサービス固有のセクション（exampleService など）の変更により、関連コンポーネントがリッスンするイベントが発生します。

4. ゲートウェイサーバーの実行

プロジェクトのルートディレクトリ（mcp-server-hub-server）でターミナルを開き、次を実行します。

# Ensure you have built the project first!
npm run build

# Start the server
npm start

これにより、dist/mcp_hub_config.json が読み込まれ、管理対象サーバーが起動し、ハブツールが読み込まれ、WebSocket リスナーが起動します。また、設定ファイルを監視し、手動で停止する（Ctrl+C）まで実行を続けます。

5. LLM クライアントの設定（例：Cline）

LLM クライアントで設定が必要な MCP サーバーは、gateway-client 1 つだけです。

クライアントの MCP サーバー設定ファイル（例：Cline の cline_mcp_settings.json）に次の項目を追加します。このプロジェクトの正しい絶対パスを指定してください。

{
  "mcpServers": {
    // Remove configurations for individual servers like thought-server, file-operations, etc.
    "gateway-client": {
      "command": "node",
      "args": [
        // Use the FULL, absolute path to the compiled client script
        "d:/Projects/mcp-server-hub-server/dist/client/client.js"
      ],
      "options": {
        // CWD should be the project root
        "cwd": "d:/Projects/mcp-server-hub-server"
      },
      "env": {
        // Optional: Configure client polling interval (default is 5 minutes)
        // "CLIENT_TOOL_REFRESH_INTERVAL_MS": "60000" // e.g., 60 seconds
      },
      "disabled": false,
      "autoApprove": []
    }
    // Only the gateway-client entry is needed here
  }
}

LLM クライアントが gateway-client に接続すると、クライアントプロセス（node dist/client/client.js）が自動的に起動し、実行中のゲートウェイサーバーに WebSocket 経由で接続します。

6. ツールの使用

ゲートウェイサーバーが実行中で、LLM クライアントが gateway-client に接続されると、次の操作ができます。

• LLM クライアントでツールを一覧表示します。名前空間付きのツール名が表示されます。
  • 管理対象サーバーのツール：serverId__toolName（例：thought-server__integratedThinking）
  • ハブ組み込みツール：hub__toolName（例：hub__example）
• これらの完全な名前空間付きツール名を使用して、ツールを呼び出します。
• 注： 設定が動的に変わるため、ツール一覧は時間の経過とともに変更される場合があります。gateway-client は定期的に更新を確認します（既定では 5 分ごと。クライアントプロセスの CLIENT_TOOL_REFRESH_INTERVAL_MS 環境変数で設定可能）。サーバー側の変更がクライアントに反映されるまで、短い遅延が発生する場合があります。詳細は docs/client-dynamic-tools-guide.md を参照してください。

トラブルシューティング

• LLM クライアントで gateway-client を起動すると ENOENT エラーが発生する： LLM クライアントの MCP 設定で、command（node）、args（dist/client/client.js の絶対パス）、および options.cwd（プロジェクトルートの絶対パス）が、ご使用のシステムに合っていることを確認してください。
• ツール名の検証エラー（String should match pattern...）： mcp_hub_config.json の serverId キーと hubTools キーに使用できる文字が a-zA-Z0-9_- のみであることを確認してください。
• ゲートウェイクライアントがサーバーに接続できない： ゲートウェイサーバー（npm start）が実行中であることを確認してください。dist/mcp_hub_config.json の wsPort が、クライアントで使用されている URL（デフォルトは ws://localhost:8081）と一致していることを確認してください。ファイアウォールも確認してください。
• LLM クライアントで最初の listTools が失敗する／タイムアウトする： LLM クライアントが、gateway-client プロセスのゲートウェイサーバーの WebSocket への接続が完了する前にリクエストを送信すると、この問題が発生することがあります。クライアントはリクエストをキューに入れるため、以降の呼び出しは成功するはずです。ゲートウェイクライアントのログでキューイングに関するメッセージを確認してください（ログを確認するには、別のターミナルで node dist/client/client.js を手動で実行する必要がある場合があります）。
• 管理対象サーバーのエラー（[serverId/ERR]）： 特定のサーバー ID のプレフィックスが付いたエラーは、ゲートウェイ自体ではなく、その下で動作する管理対象サーバー内の問題を示しています。そのサーバーを直接トラブルシューティングしてください。
• 動的設定が再読み込みされない： サーバーの実行中に dist/mcp_hub_config.json を変更していることを確認してください。ゲートウェイサーバーのログで、ファイル監視のメッセージや再読み込み時の検証エラーの可能性を確認してください。ビルドプロセスによって、ルートから dist/ に意図した設定が正常にコピーされていることも確認してください。

開発

• 開発サーバーを実行する： npm run dev（nodemon を使用して、src の変更時にゲートウェイサーバーを自動的に再起動します）。注：設定のビルドやコピー、クライアント／管理対象サーバーの再起動は自動では行われません。設定やクライアントを変更した場合は、npm run build を実行し、手動で再起動する必要があります。
• Lint／フォーマット： npm run lint、npm run format（コミット前フックでも実行されます）。
• テスト： npm test（現在は限定的です。tests/ を参照してください）。