MCP Hub

MCP Hub

MCP Hub は MCP サーバーとクライアントの中央コーディネーターとして機能し、次の 2 つの主要なインターフェースを提供します。

1. 管理インターフェース（/api/*）：統一された REST API とウェブ UI を通じて、複数の MCP サーバーを管理します
2. MCP サーバーインターフェース（/mcp）：任意の MCP クライアントを接続し、単一のエンドポイントからすべてのサーバー機能を利用できます

この 2 つのインターフェースにより、Hub の UI でサーバーを管理しながら、MCP クライアント（Claude Desktop、Cline など）は 1 つのエンドポイント（localhost:37373/mcp）に接続するだけで、すべての機能を利用できます。MCP 2025-03-26 仕様を実装しています。

機能のサポート

カテゴリ	機能	サポート	備考
トランスポート
	streamable-http	✅	リモートサーバー向けの主要なトランスポートプロトコル
	SSE	✅	リモートサーバー向けのフォールバックトランスポート
	STDIO	✅	ローカルサーバーの実行用
認証
	OAuth 2.0	✅	PKCE フロー対応
	ヘッダー	✅	API キー／トークン用
機能
	ツール	✅	ツールの一覧表示
	🔔 ツール一覧の変更	✅	リアルタイム更新
	リソース	✅	完全対応
	🔔 リソース一覧の変更	✅	リアルタイム更新
	リソーステンプレート	✅	URI テンプレート
	プロンプト	✅	完全対応
	🔔 プロンプト一覧の変更	✅	リアルタイム更新
	ルート	❌	非対応
	サンプリング	❌	非対応
	補完	❌	非対応
マーケットプレイス
	サーバーの検索	✅	利用可能なサーバーを閲覧
	インストール	✅	自動設定
リアルタイム
	ステータス更新	✅	サーバーと接続の状態
	機能の更新	✅	自動更新
	クライアントへのイベントストリーミング	✅	SSE ベース
	自動再接続	✅	バックオフ付き
開発
	ホットリロード	✅	dev モードでファイル変更時に MCP サーバーを自動再起動
設定
	${} 構文	✅	すべてのフィールドで環境変数とコマンド実行に対応
	VS Code との互換性	✅	servers キー、${env:}、${input:}、定義済み変数に対応
	JSON5 のサポート	✅	設定ファイル内のコメントと末尾のカンマに対応

クライアント設定の簡略化

1 つのエンドポイントだけで、すべての MCP クライアントを設定できます。

{
    "mcpServers" : {
        "Hub": {
            "url" : "http://localhost:37373/mcp"  
        }
    }
}

Hub は次の処理を自動で行います。

• 機能に名前空間を割り当てて競合を防止します（例：filesystem__search と database__search）
• リクエストを適切なサーバーにルーティングします
• サーバーの追加／削除時に機能をリアルタイムで更新します
• 認証と接続管理を処理します

主な機能

• 統合 MCP サーバーエンドポイント（/mcp）：

  • すべての MCP クライアントが接続できる単一のエンドポイント
  • 1 つの接続を通じて、管理対象のすべてのサーバーの機能にアクセス
  • 自動名前空間付与により、サーバー間の競合を防止
  • サーバーの変更時にリアルタイムで機能を更新
  • クライアント設定を簡素化。複数ではなく 1 つのエンドポイントだけで接続可能

• 動的なサーバー管理：

  • 必要に応じてサーバーを起動、停止、有効化／無効化
  • 自動サーバー再接続によるリアルタイムの設定更新
  • ローカル（STDIO）およびリモート（streamable-http/SSE）MCP サーバーに対応
  • ヘルスモニタリングと自動復旧
  • PKCE フローによる OAuth 認証
  • ヘッダーベースのトークン認証

• 統合 REST API：

  • 接続済みの任意のサーバーからツールを実行
  • リソースとリソーステンプレートにアクセス
  • Server-Sent Events（SSE）によるリアルタイムのステータス更新
  • サーバー管理のための完全な CRUD 操作

• リアルタイムイベントとモニタリング：

  • サーバーのステータスと機能をライブ更新
  • クライアント接続の追跡
  • ツールとリソースのリスト変更通知
  • ファイル出力に対応した構造化 JSON ロギング

• クライアント接続管理：

  • /api/events を介したシンプルな SSE ベースのクライアント接続
  • 切断時の接続の自動クリーンアップ
  • クライアントが未接続のときに自動シャットダウンするオプション
  • 接続状態をリアルタイムでモニタリング

• プロセスのライフサイクル管理：

  • 適切な起動とシャットダウンの処理
  • サーバー接続の適切なクリーンアップ
  • エラー復旧と再接続

• ワークスペース管理：

  • 異なる作業ディレクトリで稼働する MCP Hub インスタンスを追跡
  • XDG 準拠の状態ディレクトリにグローバルなワークスペースキャッシュを保存
  • SSE イベントによるリアルタイムのワークスペース更新
  • アクティブなワークスペースの一覧表示とモニタリング用 API エンドポイント

コンポーネント

Hub サーバー

管理を担うメインサーバーで、次の機能を提供します：

• 複数の MCP サーバーへの接続を維持
• サーバー機能への統合 API アクセスを提供
• サーバーのライフサイクルとヘルスモニタリングを処理
• SSE クライアントの接続とイベントを管理
• 設定更新とサーバー再接続を処理

MCP サーバー

接続されたサービスで、次の機能を提供します：

• ツール、リソース、テンプレート、プロンプトを提供
• 次の 2 種類の接続方式に対応：
  • ローカル操作向けのスクリプトベース STDIO サーバー
  • OAuth に対応したリモートサーバー（streamable-http/SSE）
• リアルタイムの機能更新を実装
• ステータスの自動復旧に対応
• トランスポートの種類を問わず一貫したインターフェースを維持

インストール

npm install -g mcp-hub

基本的な使い方

Hub サーバーを起動します：

mcp-hub --port 3000 --config path/to/config.json

# Or with multiple config files (merged in order)
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json

CLI オプション

Options:
  --port            Port to run the server on (required)
  --config          Path to config file(s). Can be specified multiple times. Merged in order. (required)
  --watch           Watch config file for changes, only updates affected servers (default: false)
  --auto-shutdown   Whether to automatically shutdown when no clients are connected (default: false)
  --shutdown-delay  Delay in milliseconds before shutting down when auto-shutdown is enabled (default: 0)
  -h, --help       Show help information

設定

MCP Hub では、管理対象サーバーを定義する JSON 設定ファイルを使用します。環境変数とコマンド実行には、汎用の ${} プレースホルダー構文を使用します。

VS Code の設定との互換性

MCP Hub は VS Code の .vscode/mcp.json 設定形式とのシームレスな互換性を備えているため、VS Code と MCP Hub の両方で同じ設定ファイルを使用できます。

対応機能

サーバー設定キー

mcpServers キーと servers キーの両方に対応しています：

{
  "servers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "perplexity": {
      "command": "npx", 
      "args": ["-y", "server-perplexity-ask"],
      "env": {
        "API_KEY": "${env:PERPLEXITY_API_KEY}"
      }
    }
  }
}

変数の置換

MCP Hub は VS Code 形式の変数置換に対応しています：

• 環境変数：${env:VARIABLE_NAME} または ${VARIABLE_NAME}
• ワークスペース変数：${workspaceFolder}、${userHome}、${pathSeparator}
• コマンド実行：${cmd: command args}

対応する定義済み変数：

• ${workspaceFolder} - mcp-hub が実行されているディレクトリ
• ${userHome} - ユーザーのホームディレクトリ
• ${pathSeparator} - OS のパス区切り文字（/ または \）
• ${workspaceFolderBasename} - フォルダー名のみ
• ${cwd} - workspaceFolder の別名
• ${/} - pathSeparator の VS Code 短縮形

VS Code の入力変数

VS Code の設定で使用される ${input:} 変数には、MCP_HUB_ENV 環境変数を使用します：

# Set input variables globally
export MCP_HUB_ENV='{"input:api-key":"your-secret-key","input:database-url":"postgresql://..."}'

# Then use in config
{
  "servers": {
    "myserver": {
      "env": {
        "API_KEY": "${input:api-key}"
      }
    }
  }
}

VS Code からの移行

既存の .vscode/mcp.json ファイルは、MCP Hub でそのまま使用できます。MCP Hub に VS Code の設定ファイルを指定するだけです。

mcp-hub --config .vscode/mcp.json --port 3000

複数の設定ファイル

MCP Hub では、複数の設定ファイルを読み込み、指定した順にマージできます。これにより、柔軟な設定管理が可能になります。

• グローバル設定：システム全体の設定（例：~/.config/mcphub/global.json）
• プロジェクト設定：プロジェクト固有の設定（例：./.mcphub/project.json）
• 環境設定：環境固有の上書き設定

複数の設定ファイルを指定すると、後のファイルが前のファイルを上書きする形でマージされます。

# Global config is loaded first, then project config overrides
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json

マージの動作：

• mcpServers セクションはマージされます（後のファイルのサーバー定義が前のファイルの定義を上書きします）
• その他のトップレベルプロパティは、後のファイルの内容で完全に置き換えられます
• 存在しない設定ファイルは警告なしでスキップされます

共通プレースホルダー構文

• ${ENV_VAR} または ${env:ENV_VAR} - 環境変数を解決します
• ${cmd: command args} - コマンドを実行し、その出力を使用します
• ${workspaceFolder} - mcp-hub が実行されているディレクトリ
• ${userHome} - ユーザーのホームディレクトリ
• ${pathSeparator} - OS のパス区切り文字
• ${input:variable-id} - MCP_HUB_ENV から解決します（VS Code との互換性）
• null または "" - process.env にフォールバックします

設定例

ローカル STDIO サーバー

{
  "mcpServers": {
    "local-server": {
      "command": "${MCP_BINARY_PATH}/server",
      "args": [
        "--token", "${API_TOKEN}",
        "--database", "${DB_URL}",
        "--secret", "${cmd: op read op://vault/secret}"
      ],
      "env": {
        "API_TOKEN": "${cmd: aws ssm get-parameter --name /app/token --query Parameter.Value --output text}",
        "DB_URL": "postgresql://user:${DB_PASSWORD}@localhost/myapp",
        "DB_PASSWORD": "${cmd: op read op://vault/db/password}",
        "FALLBACK_VAR": null
      },
      "dev": {
        "enabled": true,
        "watch": ["src/**/*.js", "**/*.json"],
        "cwd": "/absolute/path/to/server/directory"
      }
    }
  }
}

リモートサーバー

{
  "mcpServers": {
    "remote-server": {
      "url": "https://${PRIVATE_DOMAIN}/mcp",
      "headers": {
        "Authorization": "Bearer ${cmd: op read op://vault/api/token}",
        "X-Custom-Header": "${CUSTOM_VALUE}"
      }
    }
  }
}

設定オプション

MCP Hub は STDIO サーバーとリモートサーバー（streamable-http/SSE）の両方をサポートしています。サーバーの種類は設定から自動的に判別されます。すべてのフィールドで共通の ${} プレースホルダー構文を使用できます。

STDIO サーバーのオプション

スクリプトベースの MCP サーバーをローカルで実行する場合：

• command：MCP サーバーの実行ファイルを起動するコマンド（${VARIABLE} および ${cmd: command} をサポート）
• args：コマンドライン引数の配列（${VARIABLE} および ${cmd: command} プレースホルダーをサポート）
• env：プレースホルダーの解決とシステム環境へのフォールバックに対応する環境変数
• cwd：MCP サーバーを起動するプロセスの cwd
• dev：開発モードの設定（任意）
  • enabled：開発モードを有効／無効にします（デフォルト：true）
  • watch：変更を監視する glob パターンの配列（デフォルト：["/*.js", "/.ts", "**/.json"]）
  • cwd：ファイル監視に使用するサーバーの作業ディレクトリの絶対パス（必須）

グローバル環境変数（MCP_HUB_ENV）

MCP Hub は、自身のプロセス環境内の環境変数 MCP_HUB_ENV（JSON 文字列）を参照します。この変数が設定されている場合、そのキーと値のペアがすべて、管理対象の各 MCP サーバー（stdio とリモートの両方）の環境に追加されます。これは、各サーバーの設定に繰り返し記述せずに、シークレット、トークン、その他の共有設定をすべてのサーバーに渡す場合に便利です。

• サーバー固有の env フィールドは、常に MCP_HUB_ENV の値を上書きします。
• 使用例：

  MCP_HUB_ENV='{"DBUS_SESSION_BUS_ADDRESS":"/run/user/1000/bus","MY_TOKEN":"abc"}' mcp-hub --port 3000 --config path/to/config.json
  

リモートサーバーのオプション

リモート MCP サーバーに接続する場合：

• url：サーバーのエンドポイント URL（${VARIABLE} および ${cmd: command} プレースホルダーをサポート）
• headers：認証ヘッダー（${VARIABLE} および ${cmd: command} プレースホルダーをサポート）

サーバーの種類の判別

サーバーの種類は次のとおり判別されます。

• STDIO サーバー → command フィールドがある
• リモートサーバー → url フィールドがある

注：サーバー設定で STDIO とリモートサーバーのフィールドを混在させることはできません。

プレースホルダーの解決順序

1. コマンドを先に実行：${cmd: command args} を最初に実行します
2. 環境変数：${VAR} は、まず env オブジェクトから、次に process.env から解決されます
3. フォールバック：null または "" の値は process.env にフォールバックします
4. 複数回の処理：変数間の依存関係は自動的に解決されます

Nix

Nixpkgs のインストール

近日公開...

Flake によるインストール

NixOS の flake.nix または home-manager に追加するだけです：

inputs = {
  mcp-hub.url = "github:ravitemer/mcp-hub";
  ...
}

mcp-hub を NixOS/Home Manager の設定に統合するには、それぞれ environment.systemPackages または home.packages に以下を追加します：

inputs.mcp-hub.packages."${system}".default

インストールなしでの使用

mcp-hub サーバーを PATH に通さずに mcphub.nvim を使用したい場合は、プラグイン設定の cmd コマンドに mcp-hub の nix ストアパスを追加することで、内部的にサーバーをリンクできます。例えば次のようになります：

Nixvim の例：

{ mcphub-nvim, mcp-hub, ... }:
{
  extraPlugins = [mcphub-nvim];
  extraConfigLua = ''
    require("mcphub").setup({
        port = 3000,
        config = vim.fn.expand("~/mcp-hub/mcp-servers.json"),
        cmd = "${mcp-hub}/bin/mcp-hub"
    })
  '';
}

# where
{
  # For nixpkgs (not available yet)
  mcp-hub = pkgs.mcp-hub;

  # For flakes
  mcp-hub = inputs.mcp-hub.packages."${system}".default;
}

統合の例

Neovim との統合

ravitemer/mcphub.nvim プラグインは Neovim とのシームレスな統合を提供し、エディタから MCP Hub を直接操作できるようにします：

• Neovim から MCP ツールを直接実行
• 編集ワークフロー内で MCP リソースにアクセス
• Neovim でのリアルタイムなステータス更新
• マーケットプレイスへの追加による mcp サーバーの自動インストール

REST API

ヘルスとステータス

ヘルスチェック

GET /api/health

ヘルスエンドポイントは、以下を含む包括的なステータス情報を提供します：

• 現在のハブの状態（starting、ready、restarting、restarted、stopping、stopped、error）
• 接続されたサーバーのステータスと機能
• アクティブな SSE 接続の詳細
• 詳細な接続メトリクス
• 該当する場合のエラー状態の詳細

レスポンス：

{
  "status": "ok",
  "state": "ready",
  "server_id": "mcp-hub",
  "version": "4.1.1",
  "activeClients": 2,
  "timestamp": "2024-02-20T05:55:00.000Z",
  "servers": [],
  "connections": {
    "totalConnections": 2,
    "connections": [
      {
        "id": "client-uuid",
        "state": "connected",
        "connectedAt": "2024-02-20T05:50:00.000Z",
        "lastEventAt": "2024-02-20T05:55:00.000Z"
      }
    ]
  },
  "workspaces": {
    "current": "40123",
    "allActive": {
      "40123": {
        "cwd": "/path/to/project-a",
        "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
        "pid": 12345,
        "port": 40123,
        "startTime": "2025-01-17T10:00:00.000Z",
        "state": "active",
        "activeConnections": 2,
        "shutdownStartedAt": null,
        "shutdownDelay": null
      }
    }
  }
}

MCP サーバーの一覧表示

GET /api/servers

サーバー情報の取得

POST /api/servers/info
Content-Type: application/json

{
  "server_name": "example-server"
}

サーバー機能の更新

POST /api/servers/refresh
Content-Type: application/json

{
  "server_name": "example-server"
}

レスポンス：

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "capabilities": {
      "tools": ["tool1", "tool2"],
      "resources": ["resource1", "resource2"],
      "resourceTemplates": []
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

すべてのサーバーの更新

POST /api/refresh

レスポンス：

{
  "status": "ok",
  "servers": [
    {
      "name": "example-server",
      "capabilities": {
        "tools": ["tool1", "tool2"],
        "resources": ["resource1", "resource2"],
        "resourceTemplates": []
      }
    }
  ],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

サーバーの起動

POST /api/servers/start
Content-Type: application/json

{
  "server_name": "example-server"
}

レスポンス：

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "status": "connected",
    "uptime": 123
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

サーバーの停止

POST /api/servers/stop?disable=true|false
Content-Type: application/json

{
  "server_name": "example-server"
}

オプションの disable クエリパラメータを true に設定すると、設定内でサーバーを無効化できます。

レスポンス：

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "status": "disconnected",
    "uptime": 0
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

ワークスペース管理

アクティブなワークスペースの一覧表示

GET /api/workspaces

レスポンス：

{
  "workspaces": {
    "40123": {
      "cwd": "/path/to/project-a",
      "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
      "pid": 12345,
      "port": 40123,
      "startTime": "2025-01-17T10:00:00.000Z",
      "state": "active",
      "activeConnections": 2,
      "shutdownStartedAt": null,
      "shutdownDelay": null
    },
    "40567": {
      "cwd": "/path/to/project-b",
      "config_files": ["/home/user/.config/mcphub/global.json"],
      "pid": 54321,
      "port": 40567,
      "startTime": "2025-01-17T10:05:00.000Z",
      "state": "shutting_down",
      "activeConnections": 0,
      "shutdownStartedAt": "2025-01-17T10:15:00.000Z",
      "shutdownDelay": 600000
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

マーケットプレイスとの統合

利用可能なサーバーの一覧表示

GET /api/marketplace

クエリパラメータ：

• search: 名前、説明、またはタグでフィルタリング
• category: カテゴリでフィルタリング
• tags: カンマ区切りのタグでフィルタリング
• sort: 「newest」、「stars」、または「name」で並べ替え

レスポンス：

{
  "servers": [
    {
      "id": "example-server",
      "name": "Example Server",
      "description": "Description here",
      "author": "example-author",
      "url": "https://github.com/user/repo",
      "category": "search",
      "tags": ["search", "ai"],
      "stars": 100,
      "featured": true,
      "verified": true,
      "lastCommit": 1751257963,
      "updatedAt": 1751265038
    }
  ],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

サーバー詳細の取得

POST /api/marketplace/details
Content-Type: application/json

{
  "mcpId": "example-server"
}

レスポンス：

{
  "server": {
    "id": "example-server",
    "name": "Example Server",
    "description": "Description here",
    "author": "example-author",
    "url": "https://github.com/user/repo",
    "category": "search",
    "tags": ["search", "ai"],
    "installations": [],
    "stars": 100,
    "featured": true,
    "verified": true,
    "lastCommit": 1751257963,
    "updatedAt": 1751265038
  },
  "readmeContent": "# Server Documentation...",
  "timestamp": "2024-02-20T05:55:00.000Z"
}

MCP サーバーの操作

ツールの実行

POST /api/servers/tools
Content-Type: application/json

{
  "server_name": "example-server",
  "tool": "tool_name",
  "arguments": {},
  "request_options" : {}
}

リソースへのアクセス

POST /api/servers/resources
Content-Type: application/json

{
  "server_name": "example-server",
  "uri": "resource://uri",
  "request_options" : {}
}

プロンプトの取得

POST /api/servers/prompts
Content-Type: application/json

{
  "server_name": "example-server",
  "prompt": "prompt_name",
  "arguments": {},
  "request_options" : {}
}

レスポンス：

{
  "result": {
    "messages": [
      {
        "role": "assistant",
        "content": {
          "type": "text",
          "text": "Text response example"
        }
      },
      {
        "role": "assistant",
        "content": {
          "type": "image",
          "data": "base64_encoded_image_data",
          "mimeType": "image/png"
        }
      }
    ]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

ハブの再起動

POST /api/restart

設定ファイルを再読み込みし、すべての MCP サーバーを再起動します。

レスポンス：

{
  "status": "ok",
  "timestamp": "2024-02-20T05:55:00.000Z"
}

リアルタイムイベントシステム

MCP Hub は、/api/events において Server-Sent Events（SSE）を使用した包括的なリアルタイムイベントシステムを実装しています。このエンドポイントは、サーバーのステータス、設定の変更、機能の更新などに関するライブ更新を提供します。

ハブの状態

ハブサーバーは、そのライフサイクルの中でいくつかの状態を遷移します：

状態	説明
starting	初期起動中、設定を読み込み中
ready	サーバーが稼働しており、リクエストを処理する準備が完了
restarting	設定を再読み込み中/サーバーに再接続中
restarted	設定の再読み込みが完了
stopping	正常なシャットダウンを実行中
stopped	サーバーが完全に停止
error	エラー状態（エラーの詳細を含む）

これらの状態は、/health エンドポイントまたは SSE イベントを通じて監視できます。

イベントの種類

MCP Hub は、いくつかの種類のイベントを発行します：

コアイベント

1. heartbeat - 定期的な接続ヘルスチェック

{
  "connections": 2,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

2. hub_state - ハブサーバーの状態変化

{
  "state": "ready",
  "server_id": "mcp-hub",
  "version": "1.0.0",
  "pid": 12345,
  "port": 3000,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

3. log - サーバーのログメッセージ

{
  "type": "info",
  "message": "Server started",
  "data": {},
  "timestamp": "2024-02-20T05:55:00.000Z"
}

サブスクリプションイベント

1. config_changed - 設定ファイルの変更を検出

{
  "type": "config_changed",
  "newConfig": {},
  "isSignificant": true,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

2. servers_updating - サーバーの更新を実行中

{
  "type": "servers_updating",
  "changes": {
    "added": ["server1"],
    "removed": [],
    "modified": ["server2"],
    "unchanged": ["server3"]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

3. servers_updated - サーバーの更新が完了

{
  "type": "servers_updated",
  "changes": {
    "added": ["server1"],
    "removed": [],
    "modified": ["server2"],
    "unchanged": ["server3"]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

4. tool_list_changed - サーバーのツール一覧が更新

{
  "type": "tool_list_changed",
  "server": "example-server",
  "tools": ["tool1", "tool2"],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

5. resource_list_changed - サーバーのリソース/テンプレートが更新

{
  "type": "resource_list_changed",
  "server": "example-server",
  "resources": ["resource1", "resource2"],
  "resourceTemplates": [],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

6. prompt_list_changed - サーバーのプロンプト一覧が更新

{
  "type": "prompt_list_changed",
  "server": "example-server",
  "prompts": ["prompt1", "prompt2"],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

7. workspaces_updated - アクティブなワークスペースが変更

{
  "type": "workspaces_updated",
  "workspaces": {
    "40123": {
      "cwd": "/path/to/project-a",
      "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
      "pid": 12345,
      "port": 40123,
      "startTime": "2025-01-17T10:00:00.000Z",
      "state": "active",
      "activeConnections": 2,
      "shutdownStartedAt": null,
      "shutdownDelay": null
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

接続管理

• 各 SSE 接続には一意の ID が割り当てられます
• クライアントが切断されると、接続は自動的にクリーンアップされます
• 接続統計は /health エンドポイントから確認できます
• クライアントが接続されていない場合に、自動シャットダウンするオプションがあります

ロギング

MCP Hub は、すべてのイベントを構造化された JSON 形式で記録します。ログは XDG Base Directory Specification に従って、コンソールとファイルの両方に出力されます。

• XDG 準拠：$XDG_STATE_HOME/mcp-hub/logs/mcp-hub.log（通常は ~/.local/state/mcp-hub/logs/mcp-hub.log）
• 従来のフォールバック：~/.mcp-hub/logs/mcp-hub.log（後方互換性のため）

ログエントリの例：

{
  "type": "error",
  "code": "TOOL_ERROR",
  "message": "Failed to execute tool",
  "data": {
    "server": "example-server",
    "tool": "example-tool",
    "error": "Invalid parameters"
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

ログレベルは次のとおりです。

• info：通常の動作メッセージ
• warn：警告状態
• debug：詳細なデバッグ情報（設定の変更を含む）
• error：エラー状態（エラーコードとスタックトレースを含む）

ログは毎日ローテーションされ、デフォルトで30日間保存されます。

ワークスペースキャッシュ

MCP Hub はグローバルなワークスペースキャッシュを維持し、リアルタイムのライフサイクル管理を通じて、異なる作業ディレクトリにあるアクティブなインスタンスを追跡します。

• キャッシュの場所：$XDG_STATE_HOME/mcp-hub/workspaces.json（通常は ~/.local/state/mcp-hub/workspaces.json）
• 目的：ポートの競合を防ぎ、ワークスペースの検出を可能にし、リアルタイムのライフサイクル追跡を提供します
• 内容：ポート番号をキーとして、詳細なライフサイクル状態を含む Hub プロセス情報を対応付けます
• クリーンアップ：プロセスが実行されていない場合、古いエントリを自動的に削除します

キャッシュ構造

{
  "40123": {
    "cwd": "/path/to/project-a",
    "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
    "pid": 12345,
    "port": 40123,
    "startTime": "2025-01-17T10:00:00.000Z",
    "state": "active",
    "activeConnections": 2,
    "shutdownStartedAt": null,
    "shutdownDelay": null
  },
  "40567": {
    "cwd": "/path/to/project-b", 
    "config_files": ["/home/user/.config/mcphub/global.json"],
    "pid": 54321,
    "port": 40567,
    "startTime": "2025-01-17T10:05:00.000Z",
    "state": "shutting_down",
    "activeConnections": 0,
    "shutdownStartedAt": "2025-01-17T10:15:00.000Z",
    "shutdownDelay": 600000
  }
}

エラー処理

MCP Hub は、さまざまな種類のエラーに対応するカスタムエラークラスを備えた、包括的なエラー処理システムを実装しています。

エラークラス

• ConfigError：設定関連のエラー（無効な設定、不足しているフィールド）
• ConnectionError：サーバー接続の問題（接続失敗、トランスポートエラー）
• ServerError：サーバーの起動／初期化に関する問題
• ToolError：ツールの実行失敗
• ResourceError：リソースへのアクセスに関する問題
• ValidationError：リクエストの検証エラー

各エラーには次の情報が含まれます。

• 識別しやすいエラーコード
• 詳細なエラーメッセージ
• details オブジェクト内の追加コンテキスト
• デバッグ用のスタックトレース

エラー構造の例：

{
  "code": "CONNECTION_ERROR",
  "message": "Failed to communicate with server",
  "details": {
    "server": "example-server",
    "error": "connection timeout"
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

アーキテクチャ

Hub Server のライフサイクル

sequenceDiagram
    participant C as Client
    participant H as Hub Server
    participant M1 as MCP Server 1
    participant M2 as MCP Server 2

    Note over H: Server Start (state: starting)
    activate H
    
    Note over H: Config Loading
    H->>H: Load & Validate Config
    H->>H: Watch Config File
    H->>H: Initialize SSE Manager
    
    Note over H: Server Connections (state: ready)
    H->>+M1: Connect
    M1-->>-H: Connected + Capabilities
    H->>+M2: Connect
    M2-->>-H: Connected + Capabilities
    H-->>C: hub_state (ready)

    Note over C,H: Client Setup
    C->>H: Connect to /api/events (SSE)
    H-->>C: connection_opened
    
    Note over C,H: Client Operations
    C->>H: Execute Tool (HTTP)
    H->>M1: Execute Tool
    M1-->>H: Tool Result
    H-->>C: HTTP Response
    
    Note over H,C: Real-time Updates
    H->>H: Detect Config Change
    H-->>C: servers_updating (SSE)
    H->>M1: Reconnect with New Config
    M1-->>H: Updated Capabilities
    H-->>C: servers_updated (SSE)

    Note over H,C: Server Events
    M2->>H: Tool List Changed
    H-->>C: tool_list_changed (SSE)
    
    Note over H: Shutdown Process
    Note over C,H: Client Disconnects
    H-->>C: hub_state (stopping) (SSE)
    H->>M1: Disconnect
    H->>M2: Disconnect
    H-->>C: hub_state (stopped) (SSE)
    deactivate H

Hub Server は、クライアントと MCP サーバー間の通信を調整します。

1. 設定済みの MCP サーバーを起動して接続します
2. SSE クライアントの接続とイベントを処理します
3. ツールとリソースのリクエストを適切なサーバーにルーティングします
4. サーバーの健全性を監視し、機能を維持します
5. 適切な起動／シャットダウンのプロセスを管理します

MCP サーバー管理

flowchart TB
    A[Hub Server Start] --> B{Config Available?}
    B -->|Yes| C[Load Server Configs]
    B -->|No| D[Use Default Settings]
    
    C --> E[Initialize Connections]
    D --> E
    
    E --> F{For Each MCP Server}
    F -->|Enabled| G[Attempt Connection]
    F -->|Disabled| H[Skip Server]
    
    G --> I{Connection Status}
    I -->|Success| J[Fetch Capabilities]
    I -->|Failure| K[Log Error]
    
    J --> L[Store Server Info]
    K --> M[Mark Server Unavailable]
    
    L --> N[Monitor Health]
    M --> N
    
    N --> O{Health Check}
    O -->|Healthy| P[Update Capabilities]
    O -->|Unhealthy| Q[Attempt Reconnect]
    
    Q -->|Success| P
    Q -->|Failure| R[Update Status]
    
    P --> N
    R --> N

Hub Server は、次の方法で MCP サーバーを積極的に管理します。

1. 設定に基づくサーバーの初期化
2. 接続と機能の検出
3. 健全性の監視とステータスの追跡
4. 自動再接続の試行
5. サーバー状態の管理

リクエスト処理

sequenceDiagram
    participant C as Client
    participant H as Hub Server
    participant M as MCP Server
    
    Note over C,H: Tool Execution
    C->>H: POST /api/servers/tools (HTTP)
    H->>H: Validate Request & Server
    
    alt Server Not Connected
        H-->>C: 503 Server Unavailable (HTTP)
    else Server Connected
        H->>M: Execute Tool
        
        alt Success
            M-->>H: Tool Result
            H-->>C: Result Response (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end
    
    Note over C,H: Resource Access
    C->>H: POST /api/servers/resources (HTTP)
    H->>H: Validate URI & Template
    
    alt Invalid Resource
        H-->>C: 404 Not Found (HTTP)
    else Server Not Connected
        H-->>C: 503 Unavailable (HTTP)
    else Valid Request
        H->>M: Request Resource
        
        alt Success
            M-->>H: Resource Data
            H-->>C: Resource Content (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end
    
    Note over C,H: Prompt Execution
    C->>H: POST /api/servers/prompts (HTTP)
    H->>H: Validate Prompt & Args
    
    alt Invalid Prompt
        H-->>C: 404 Not Found (HTTP)
    else Server Not Connected
        H-->>C: 503 Unavailable (HTTP)
    else Valid Request
        H->>M: Execute Prompt
        
        alt Success
            M-->>H: Messages Array
            H-->>C: Messages Response (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end

すべてのクライアントリクエストは、標準化されたフローに従います。

1. リクエストの検証
2. サーバーステータスの確認
3. 適切な MCP サーバーへのリクエストのルーティング
4. レスポンスの処理とエラー管理

要件

• Node.js >= 18.0.0

MCP Registry

MCP Hub はマーケットプレイス機能に MCP Registry システムを使用するようになりました。これにより、次の機能が提供されます。

• 分散型サーバー検出：信頼性を高めるため、GitHub Pages でレジストリをホストします
• GitHub との直接連携：リポジトリから README のドキュメントを直接取得します
• 拡張されたメタデータ：スター数、カテゴリ、インストール手順など、サーバーに関する包括的な情報を提供します
• キャッシュの改善：頻繁な更新に対応する、TTL が1時間の改善されたキャッシュシステム
• フォールバック対応：fetch が失敗した場合に curl へ自動的にフォールバックします（プロキシ／VPN 環境で便利です）

レジストリは、新しいサーバーの追加や既存エントリの改善に合わせて定期的に更新されます。

Todo

• mcp-marketplace に依存せず、カスタムマーケットプレイスを実装する
• mcphub.nvim のような TUI
• サーバー管理用の Web UI

謝辞

• ravitemer/mcp-registry - MCP Hub のマーケットプレイス連携を支える MCP サーバーのマーケットプレイスエンドポイントを提供してくれたこと