Hatago MCP Hub

🚀 🏮 Hatago MCP Hub

Hatago MCP Hub 是一個輕量級的中心樞紐，它能統一管理來自 Claude Code、Codex CLI、Cursor、Windsurf 和 VS Code 等工具對多個 MCP（模型上下文協議）服務器的訪問。

🚀 快速開始

無需安裝快速啟動

# 初始化配置
npx @himorishige/hatago-mcp-hub init

# 在 STDIO 模式下啟動（適用於 Claude Code）
# 注意：STDIO 需要配置文件路徑
npx @himorishige/hatago-mcp-hub serve --stdio --config ./hatago.config.json

# 或者在無配置的情況下以 HTTP 模式啟動（用於演示/開發）
npx @himorishige/hatago-mcp-hub serve --http

全局安裝

# 全局安裝
npm install -g @himorishige/hatago-mcp-hub

# 使用 hatago 命令
hatago init
hatago serve

作為項目依賴安裝

# 作為依賴安裝
npm install @himorishige/hatago-mcp-hub

# 添加到 package.json 腳本中
{
  "scripts": {
    "mcp": "hatago serve"
  }
}

✨ 主要特性

🚀 性能提升（v0.0.14）

• 啟動速度提升 8.44 倍：從 85.66ms 縮短至 10.14ms
• 包體積減小 17%：從 1.04MB 減小到 854KB
• 架構簡化：直接管理服務器，無需抽象層

🎯 簡單輕量

• 零配置啟動（HTTP 模式）：npx @himorishige/hatago-mcp-hub serve --http
• 對現有項目無侵入：不會汙染項目目錄

🔌 豐富的連接性

• 多傳輸協議支持：STDIO / HTTP / SSE
• 遠程 MCP 代理：透明連接基於 HTTP 的 MCP 服務器
• NPX 服務器集成：動態管理 npm 包 MCP 服務器

🏮 附加特性

配置更新

• 需要手動重啟：配置更改後需要重啟服務器
• 替代方案：
  • 使用進程管理器（PM2、nodemon）實現自動重啟
  • 示例：nodemon --exec "hatago serve --http" --watch hatago.config.json
  • 或者使用 PM2：pm2 start "hatago serve" --watch hatago.config.json
• 動態工具列表更新：支持 notifications/tools/list_changed 通知

進度通知轉發

• 子服務器通知轉發：透明轉發 notifications/progress
• 支持長時間運行的操作：即時更新進度
• 支持本地/遠程服務器：適用於多種 MCP 服務器類型

內置內部資源

• hatago://servers - 當前連接服務器的 JSON 快照（id、狀態、類型、工具、資源、提示）

增強特性

• 環境變量擴展：支持與 Claude Code 兼容的 ${VAR} 和 ${VAR:-default} 語法
• 配置驗證：使用 Zod 模式進行類型安全的配置
• 基於標籤的服務器過濾：使用標籤對服務器進行分組和過濾
• 配置繼承：使用 extends 字段擴展基礎配置，遵循 DRY 原則

最小化中心接口（IHub）

外部包（服務器/測試工具）使用輕量級的 IHub 接口，避免與具體類緊密耦合。

import type { IHub } from '@himorishige/hatago-hub';
import { createHub } from '@himorishige/hatago-hub/node';

const hub: IHub = createHub({
  preloadedConfig: { data: { version: 1, mcpServers: {} } }
}) as IHub;
await hub.start();
hub.on('tool:called', (evt) => {
  /* 指標、日誌 */
});
await hub.stop();

提取的輕量級中心模塊：

• RPC 處理程序：packages/hub/src/rpc/handlers.ts
• HTTP 處理程序：packages/hub/src/http/handler.ts

📁 項目結構

packages/
├── mcp-hub/        # 主 npm 包 (@himorishige/hatago-mcp-hub)
├── server/         # 服務器實現 (@himorishige/hatago-server)
├── hub/            # 中心核心 (@himorishige/hatago-hub)
├── core/           # 共享類型 (@himorishige/hatago-core)
├── runtime/        # 運行時組件 (@himorishige/hatago-runtime)
├── transport/      # 傳輸層 (@himorishige/hatago-transport)
├── cli/            # CLI 工具 (@himorishige/hatago-cli)
├── hub-management/ # 管理組件 (@himorishige/hatago-hub-management)
└── test-fixtures/  # 測試工具

💻 使用示例

Claude Code、Codex CLI、Gemini CLI

STDIO 模式（推薦）

Claude Code / Gemini CLI

添加到 .mcp.json：

{
  "mcpServers": {
    "hatago": {
      "command": "npx",
      "args": [
        "@himorishige/hatago-mcp-hub",
        "serve",
        "--stdio",
        "--config",
        "./hatago.config.json"
      ]
    }
  }
}

Codex CLI

添加到 ~/.codex/config.toml：

[mcp_servers.hatago]
command = "npx"
args = ["-y", "@himorishige/hatago-mcp-hub", "serve", "--stdio", "--config", "./hatago.config.json"]

HTTP 模式

Claude Code / Gemini CLI

添加到 .mcp.json：

{
  "mcpServers": {
    "hatago": {
      "url": "http://localhost:3535/mcp"
    }
  }
}

Codex CLI

添加到 ~/.codex/config.toml：

[mcp_servers.hatago]
command = "npx"
args = ["-y", "mcp-remote", "http://localhost:3535/mcp"]

MCP 檢查器

用於測試和調試：

# 以 HTTP 模式啟動
hatago serve --http --port 3535

# 使用 MCP 檢查器連接
# 端點：http://localhost:3535/mcp

訪問 MCP 檢查器

指標（可選）

啟用輕量級內存指標並暴露一個 HTTP 端點：

HATAGO_METRICS=1 hatago serve --http --port 3535
# 然後訪問：http://localhost:3535/metrics

注意事項：

• 指標默認禁用，禁用時幾乎不增加開銷。
• 當 HATAGO_LOG=json 時（遵循 HATAGO_LOG_LEVEL），可使用 JSON 日誌。

📚 詳細文檔

• 配置指南
• 架構概述
• API 參考
• 團隊開發用例

🔧 技術細節

配置

基本配置

創建 hatago.config.json：

{
  "$schema": "https://raw.githubusercontent.com/himorishige/hatago-mcp-hub/main/schemas/config.schema.json",
  "version": 1,
  "logLevel": "info",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

遠程服務器配置

{
  "mcpServers": {
    "deepwiki": {
      "url": "https://mcp.deepwiki.com/sse",
      "type": "sse"
    },
    "custom-api": {
      "url": "https://api.example.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

配置策略

策略 1：基於標籤的過濾

在單個配置文件中使用標籤對服務器進行分組：

{
  "mcpServers": {
    "filesystem-dev": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "tags": ["dev", "local"]
    },
    "github-prod": {
      "url": "https://api.github.com/mcp",
      "type": "http",
      "tags": ["production", "github"]
    },
    "database": {
      "command": "mcp-server-postgres",
      "tags": ["dev", "production", "database"]
    }
  }
}

使用特定標籤啟動：

# 僅啟動標記為 "dev" 的服務器
hatago serve --tags dev

# 啟動標記為 "dev" 或 "test" 的服務器
hatago serve --tags dev,test

# 支持日語標籤
hatago serve --tags 開発,テスト

策略 2：配置繼承

使用 extends 字段按環境拆分配置： 基礎配置 (~/.hatago/base.config.json)：

{
  "version": 1,
  "logLevel": "info",
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

工作配置 (./work.config.json)：

{
  "extends": "~/.hatago/base.config.json",
  "logLevel": "debug",
  "mcpServers": {
    "github": {
      "env": {
        "GITHUB_TOKEN": "${WORK_GITHUB_TOKEN}",
        "DEBUG": null
      }
    },
    "internal-tools": {
      "url": "https://internal.company.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_TOKEN}"
      }
    }
  }
}

特性：

• 繼承：子配置覆蓋父配置的值
• 多個父配置："extends": ["./base1.json", "./base2.json"]
• 路徑解析：支持 ~、相對和絕對路徑
• 環境變量刪除：使用 null 移除繼承的環境變量

選擇策略

環境變量擴展

支持與 Claude Code 兼容的語法：

• ${VAR} - 擴展為 VAR 的值（如果未定義則報錯）
• ${VAR:-default} - 如果 VAR 未定義，則使用默認值

命令

hatago init

通過交互式設置創建配置文件：

hatago init                    # 交互式模式
hatago init --mode stdio       # STDIO 模式配置
hatago init --mode http        # HTTP 模式配置
hatago init --force            # 覆蓋現有配置

hatago serve

啟動 MCP Hub 服務器：

hatago serve --stdio --config ./hatago.config.json  # STDIO 模式（默認，需要配置）
hatago serve --http                                     # HTTP 模式（配置可選）
hatago serve --config custom.json  # 自定義配置
hatago serve --verbose         # 調試日誌
hatago serve --tags dev,test   # 按標籤過濾服務器
hatago serve --env-file ./.env # 啟動前從 .env 文件加載變量（可重複使用）
hatago serve --env-override    # 使用 --env-file 時覆蓋現有環境變量

從文件加載環境變量

使用 --env-file <path...> 在解析配置之前加載變量。這有助於解析 ${VAR} 和 ${VAR:-default} 佔位符，而無需全局導出變量。

• 格式：KEY=VALUE、export KEY=VALUE、# 註釋、空行。
• 引號會被去除；支持轉義 \n、\r、\t。
• 路徑：相對於當前工作目錄，~/ 擴展為家目錄。
• 優先級：文件按指定順序應用；現有 process.env 鍵會被保留，除非提供 --env-override。

高級用法

編程式 API

import { startServer } from '@himorishige/hatago-mcp-hub';

// 以編程方式啟動服務器
await startServer({
  mode: 'stdio',
  config: './hatago.config.json',
  logLevel: 'info'
});

創建自定義中心

import { createHub } from '@himorishige/hatago-mcp-hub';

const hub = createHub({
  mcpServers: {
    memory: {
      command: 'npx',
      args: ['@modelcontextprotocol/server-memory']
    }
  }
});

// 在應用程序中直接使用中心
const tools = await hub.listTools();

架構

客戶端（Claude Code 等）
    ↓
Hatago 中心（路由器 + 註冊表）
    ↓
MCP 服務器（本地、NPX、遠程）

支持的 MCP 服務器

本地服務器

• 任何可執行的 MCP 服務器
• Python、Node.js 或二進制服務器
• 遵循 MCP 協議的自定義腳本

NPX 服務器

• @modelcontextprotocol/server-filesystem
• @modelcontextprotocol/server-github
• @modelcontextprotocol/server-memory
• 任何通過 npm 發佈的 MCP 服務器

遠程服務器

• DeepWiki MCP (https://mcp.deepwiki.com/sse)
• 任何基於 HTTP 的 MCP 端點
• 遵循 MCP 協議的自定義 API 服務器

故障排除

常見問題

1. “No onNotification handler set” 警告
   • 在使用 StreamableHTTP 傳輸的 HTTP 模式下正常
   • 中心會適當處理通知
2. 服務器連接失敗
   • 驗證環境變量是否已設置
   • 檢查遠程服務器 URL 是否可訪問
   • 使用 --verbose 標誌查看詳細日誌
3. 工具名稱衝突
   • Hatago 會自動使用服務器 ID 作為前綴
   • 原始名稱會保留在中心中

調試模式

# 啟用詳細日誌
hatago serve --verbose

# 檢查服務器狀態
hatago status

📄 許可證

MIT 許可證

🔗 鏈接

• npm 包
• GitHub 倉庫
• MCP 協議規範

🙏 致謝

使用 Hono 和 Anthropic 開發的 Model Context Protocol SDK 構建。