围棋-MCP中心

Name: 围棋-MCP中心
Author: himorishige

作者：himorishige24 星标更新：2025-09-14

安装使用来源：spider==github.com

项目介绍

技术文档摘要

English | 日本語

🏮 Hatago MCP Hub

Hatago (旅籠) — 一个连接现代AI工具与MCP服务器的中继点。

概览

Hatago MCP Hub 是一个轻量级中心，统一了从工具（如 Claude Code、Codex CLI、Cursor、Windsurf 和 VS Code）访问多个 MCP（模型上下文协议）服务器的方式。

文档

文档索引：docs/README.md
官方CLI及中心指南：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, 状态, 类型, 工具, 资源, 提示）

增强功能

环境变量扩展 - 支持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) => {
  /* 度量, 日志 */
});
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/  # 测试工具

📦 安装

快速开始（无需安装）

# 初始化配置
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"
  }
}

🚀 使用

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

用于测试和调试：

# 在HTTP模式下启动
hatago serve --http --port 3535

# 使用MCP Inspector连接
# 端点：http://localhost:3535/mcp

访问MCP Inspector

度量（可选）

启用轻量级内存度量并暴露HTTP端点：

HATAGO_METRICS=1 hatago serve --http --port 3535
# 然后访问：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"]
    }
  }
}

使用特定标签启动：

# 只启动标记为“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移除继承的环境变量

选择策略

策略	基于标签	继承式
文件	单个配置文件	多个配置文件
切换	`--tags`选项	`--config`选项
管理	集中式	分布式
适合	团队共享，简单设置	复杂环境，个人定制

环境变量扩展

支持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。
路径：相对于当前工作目录，~/扩展为家目录。
优先级：文件按给定顺序应用；除非提供--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';

// 程序化启动服务器
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服务器

🐛 故障排除

常见问题

“没有onNotification处理器设置”警告
- 在HTTP模式和StreamableHTTP传输中正常
- 中心适当地处理通知
服务器连接失败
- 验证环境变量是否设置
- 检查远程服务器URL是否可访问
- 使用--verbose标志获取详细日志
工具名称冲突
- Hatago自动以前缀服务器ID
- 中心保留原始名称

调试模式

# 启用详细日志
hatago serve --verbose

# 检查服务器状态
hatago status

📚 文档

🤝 贡献

欢迎贡献！请参阅我们的GitHub仓库获取更多信息。

📄 许可

MIT许可

🔗 链接

npm包
[GitHub仓库](