hatago-mcp-hub

English | 日本語

🏮 Hatago MCP Hub

Hatago (旅籠) — 現代の AI ツールと MCP サーバーをつなぐ中継地点です。

概要

Hatago MCP Hub は、Claude Code、Codex CLI、Cursor、Windsurf、VS Code などのツールから、複数の MCP (Model Context Protocol) サーバーへのアクセスを一元化する軽量なハブです。

ドキュメント

• ドキュメント索引: docs/README.md
• 正式な CLI & Hub ガイド: packages/mcp-hub/README.md
• 公開ドキュメントサイト (デフォルトは日本語): https://hatago.dev/ja/ — 英語: https://hatago.dev/en/

Dev.to: Getting Started with Multi-MCP Using Hatago MCP Hub — One Config to Connect Them All

✨ 機能

🚀 パフォーマンス (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、status、type、tools、resources、prompts)

強化された機能

• 環境変数の展開 - Claude Code 互換の ${VAR} および ${VAR:-default} 構文
• 設定の検証 - Zod スキーマによる型安全な設定
• タグベースのサーバーフィルタリング - タグを使用したサーバーのグループ化とフィルタリング
• 設定の継承 - extends フィールドでベース設定を拡張し、DRY 原則を実現

最小限のハブインターフェース (IHub)

外部パッケージ (server/test-utils) は、具象クラスとの密結合を避けるために薄い 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) => {
  /* metrics, logs */
});
await hub.stop();

薄いハブ用に抽出されたモジュール:

• RPC ハンドラー: packages/hub/src/rpc/handlers.ts
• HTTP ハンドラー: packages/hub/src/http/handler.ts

📁 プロジェクト構成

packages/
├── mcp-hub/        # Main npm package (@himorishige/hatago-mcp-hub)
├── server/         # Server implementation (@himorishige/hatago-server)
├── hub/            # Hub core (@himorishige/hatago-hub)
├── core/           # Shared types (@himorishige/hatago-core)
├── runtime/        # Runtime components (@himorishige/hatago-runtime)
├── transport/      # Transport layer (@himorishige/hatago-transport)
├── cli/            # CLI tools (@himorishige/hatago-cli)
├── hub-management/ # Management components (@himorishige/hatago-hub-management)
└── test-fixtures/  # Test utilities

📦 インストール

クイックスタート (インストール不要)

# Initialize configuration
npx @himorishige/hatago-mcp-hub init

# Start in STDIO mode (for Claude Code)
# NOTE: STDIO requires a config file path
npx @himorishige/hatago-mcp-hub serve --stdio --config ./hatago.config.json

# Or start in HTTP mode without a config (demo/dev)
npx @himorishige/hatago-mcp-hub serve --http

グローバルインストール

# Install globally
npm install -g @himorishige/hatago-mcp-hub

# Use with hatago command
hatago init
hatago serve

プロジェクトの依存関係として

# Install as dependency
npm install @himorishige/hatago-mcp-hub

# Add to package.json scripts
{
  "scripts": {
    "mcp": "hatago serve"
  }
}

🚀 使用方法

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 Inspector

テストとデバッグ用:

# Start in HTTP mode
hatago serve --http --port 3535

# Connect with MCP Inspector
# Endpoint: http://localhost:3535/mcp

MCP Inspector にアクセスしてください。

メトリクス（オプトイン）

軽量なインメモリメトリクスを有効化し、HTTP エンドポイントを公開します：

HATAGO_METRICS=1 hatago serve --http --port 3535
# Then visit: http://localhost:3535/metrics

注意事項：

• メトリクスはデフォルトで無効になっており、オフのときはほぼゼロのオーバーヘッドしか追加しません。
• HATAGO_LOG=json の場合に JSON ログを利用できます（HATAGO_LOG_LEVEL に従います）。

⚙️ 設定

基本設定

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"]
    }
  }
}

特定のタグを指定して起動します：

# Only start servers tagged as "dev"
hatago serve --tags dev

# Start servers with either "dev" or "test" tags
hatago serve --tags dev,test

# Japanese tags are supported
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 を使用して継承した環境変数を削除します

戦略の選択

戦略	タグベース	継承ベース
ファイル	単一の設定	複数の設定
切り替え	--tags オプション	--config オプション
管理	集中管理	分散管理
最適な用途	チーム共有、シンプルな構成	複雑な環境、個人のカスタマイズ

環境変数の展開

Claude Code 互換の構文をサポートします：

• ${VAR} - VAR の値に展開されます（未定義の場合はエラー）
• ${VAR:-default} - VAR が未定義の場合にデフォルト値を使用します

📋 コマンド

hatago init

対話形式のセットアップで設定ファイルを作成します：

hatago init                    # Interactive mode
hatago init --mode stdio       # STDIO mode config
hatago init --mode http        # HTTP mode config
hatago init --force            # Overwrite existing

hatago serve

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

hatago serve --stdio --config ./hatago.config.json  # STDIO mode (default, requires config)
hatago serve --http                                     # HTTP mode (config optional)
hatago serve --config custom.json  # Custom config
hatago serve --verbose         # Debug logging
hatago serve --tags dev,test   # Filter servers by tags
hatago serve --env-file ./.env # Load variables from .env before start (repeatable)
hatago serve --env-override    # Override existing env vars when using --env-file

ファイルからの環境変数の読み込み

--env-file <path...> を使用して、設定の解析前に変数を読み込みます。これにより、変数をグローバルにエクスポートすることなく、${VAR} および ${VAR:-default} プレースホルダーを解決できます。

• 形式：KEY=VALUE、export KEY=VALUE、# コメント、空行。
• 引用符は削除されます。エスケープされた \n、\r、\t をサポートします。
• パス：CWD からの相対パス、~/ はホームディレクトリに展開されます。
• 優先順位：ファイルは指定された順序で適用されます。--env-override が指定されない限り、既存の process.env のキーは保持されます。

✨ パフォーマンスの改善（v0.0.14）

• 起動が 8.44 倍高速化：85.66ms → 10.14ms
• パッケージが 17% 縮小：1.04MB → 854KB（181KB 削減）
• アーキテクチャの簡素化：EnhancedHub と管理レイヤーを削除
• トレードオフ：組み込みの設定監視を削除（代わりに nodemon/PM2 を使用してください）

🔧 高度な使用方法

プログラマティック API

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

// Start server programmatically
await startServer({
  mode: 'stdio',
  config: './hatago.config.json',
  logLevel: 'info'
});

カスタム Hub の作成

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

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

// Use hub directly in your application
const tools = await hub.listTools();

🏗️ アーキテクチャ

Client (Claude Code, etc.)
    ↓
Hatago Hub (Router + Registry)
    ↓
MCP Servers (Local, NPX, Remote)

サポートされる 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 モードでは正常です
   • Hub は通知を適切に処理します

2. サーバー接続の失敗

   • 環境変数が設定されていることを確認してください
   • リモートサーバーの URL にアクセスできることを確認してください
   • 詳細なログには --verbose フラグを使用してください

3. ツール名の衝突

   • Hatago は自動的にサーバー ID をプレフィックスとして付けます
   • 元の名前は hub 内で保持されます

デバッグモード

# Enable verbose logging
hatago serve --verbose

# Check server status
hatago status

📚 ドキュメント

• 設定ガイド
• アーキテクチャの概要
• API リファレンス
• チーム開発のユースケース

🤝 コントリビューション

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

📄 ライセンス

MIT ライセンス

🔗 リンク

• npm パッケージ
• GitHub リポジトリ
• MCP プロトコル仕様

🙏 クレジット

Anthropic による Hono と Model Context Protocol SDK を使用して構築されています。