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