hatago-mcp-hub

English | 日本語

🏮 Hatago MCP Hub

Hatago（旅籠）——连接现代 AI 工具与 MCP 服务的中转站。

概述

Hatago MCP Hub 是一款轻量级 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：使用 Hatago MCP Hub 开始多 MCP——用一份配置连接所有服务

✨ 功能

🚀 性能（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 原则

最小化 Hub 接口（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();

用于轻量级 Hub 的拆分模块：

• 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 构建。