MCP Hub

MCP Knot

英文 | 中文版

Knot —— 纽带、交织点。多个 MCP 服务像散落的线，MCP Knot 把它们打成一个结，成为所有工具交汇的轻量枢纽。

将你的 MCP 服务连接在一起。

一个集中式枢纽服务，旨在将多个 MCP 服务整合到专用的 Streamable HTTP 或 SSE 端点，每个端点都针对特定使用场景量身打造——轻量、零配置，并在 2026-07-28 的无状态 MCP 协议中处于领先地位。

功能特性

• 多服务 MCP 集成：支持集中管理多个 MCP 服务
• 基于分组的路由：通过分组专属端点（/:group/mcp）访问 MCP 服务
• 版本化技能分发：从本地目录、公开 Git 仓库或 skills CLI 导入所选技能，然后创建固定快照，并通过分组端点与工具一同发布。请参阅技能指南。
• CLI MCP 服务：用于工具聚合的独立命令行 MCP 服务
• 流式端点：支持 HTTP 和 SSE 端点
• 工具筛选：分组支持工具筛选和过滤功能
• 验证支持：分组可设置独立的验证密钥以确保安全
• 模块化架构：清晰分离核心逻辑、API 和 CLI 包

架构

MCP Knot 采用模块化单体仓库架构，包含以下软件包：

核心软件包

• @mcp-core/mcp-knot-core - 核心 MCP 服务管理、连接处理和工具执行
• @mcp-core/mcp-knot-api - 提供基于分组路由和 HTTP 端点的 Web API 服务
• @mcp-core/mcp-knot-cli - 用于独立工具聚合的命令行 MCP 服务
• @mcp-core/mcp-knot-protocol - 协议兼容层：双时代（现代/旧版）转换、规范化模型、统一错误
• @mcp-core/mcp-knot-share - 各软件包共享的类型和实用工具
• @mcp-core/mcp-knot-web - Vue.js 前端界面（可选）

软件包结构

├── backend/              # API server (@mcp-core/mcp-knot-api)
├── frontend/             # Vue.js web interface
├── packages/
│   ├── core/            # Core MCP logic (@mcp-core/mcp-knot-core)
│   ├── cli/             # CLI package (@mcp-core/mcp-knot-cli)
│   ├── protocol/        # Protocol compatibility layer (@mcp-core/mcp-knot-protocol)
│   └── share/           # Shared types (@mcp-core/mcp-knot-share)
└── docs/                # Documentation

安装

先决条件

• Node.js 22.20+（推荐 Node 24）
• pnpm 包管理器

安装依赖

# Install all dependencies
pnpm install

# Build all packages
pnpm build

快速开始

1. API 服务（Web 界面）

启动 API 服务以启用基于 Web 的 MCP 枢纽功能：

# Development mode
pnpm dev:api

# Production build and start
pnpm build
cd backend && pnpm start

API 服务将在 http://localhost:8181 上提供以下端点：

• /mcp - 全局 MCP 端点（旧版，用于管理）
• /:group/mcp - 分组专属 MCP 端点
• /api/groups - 分组管理 API
• /api/skills - 用于管理技能来源、同步和市场搜索的 API
• /api/config - 系统配置管理 API
• /api/servers - MCP 服务管理 API
• /api/tools - 工具管理和执行 API
• /api/debug - 调试和监控 API

2. CLI MCP 服务

将 CLI 软件包用作独立 MCP 服务：

# Install CLI globally (optional)
npm install -g @mcp-core/mcp-knot-cli

# Or run directly from workspace
cd packages/cli
pnpm build
node dist/cli.js

# Or use the executable
./bin/mcp-knot.js

快速初始化配置

MCP Knot CLI 提供快速配置初始化，帮助你快速开始使用：

# View all available commands
mcp-knot --help

# Initialize default configuration (includes common server examples)
mcp-knot --init

# Initialize all configurations (includes group configuration)
mcp-knot --init-all

# List all available server presets
mcp-knot --list-presets

# Overwrite existing configuration files
mcp-knot --init-all --overwrite

默认配置包含以下常用 MCP 服务：

• fetch：网页抓取和 HTTP 请求
• time：时间和日期功能
• sequential-thinking：顺序思考能力

更多可用的服务预设：

• filesystem：文件系统操作
• memory：持久化内存存储
• brave-search：Brave 搜索引擎
• github：GitHub 仓库管理

CLI 服务通过 MCP 协议使用 stdin/stdout 进行通信，非常适合与 Claude Desktop 等 MCP 客户端集成。

3. 前端界面（可选）

启动 Web 界面以进行可视化管理：

# Development mode
pnpm dev:fe

# Production build
pnpm build:fe

前端将在 http://localhost:8180 上提供服务（开发环境），或在生产环境中通过后端提供服务。

Web 界面功能

前端提供了全面的 Web 管理界面，包含以下功能：

1. 身份验证与安全

• JWT 身份验证：采用基于令牌的安全登录系统
• 自动刷新令牌：无缝管理会话，不受中断
• 路由守卫：受保护的页面需要身份验证
• 持久会话：在不同浏览器会话间保留用户登录状态
• 默认凭据：用户名：admin，密码：admin（请在生产环境中更改！）

2. 仪表板与监控

• 系统概览：服务器、工具和组的实时统计数据
• 实时状态更新：使用服务器发送事件（SSE）进行实时监控
• 性能指标：请求率、响应时间和错误率
• 活动动态：近期系统活动和事件
• 运行状况监控：系统运行状况检查和警报

3. 服务器管理

• 服务器列表：查看所有已配置的 MCP 服务及其状态指示器
• 添加/编辑服务器：使用可视化表单配置服务器
• 连接控制：连接、断开服务器并测试连接
• 状态监控：实时监控服务器连接状态
• 配置验证：保存前测试服务器配置

4. 工具管理

• 工具浏览器：浏览各个服务器上的所有可用 MCP 工具
• 工具搜索与筛选：按名称、服务器或组查找工具
• 工具测试：通过输入参数交互式执行工具
• 执行历史记录：查看以往的工具执行记录和结果
• 工具详情：完整的工具文档和架构信息

5. 组管理

• 组配置：创建和管理服务器组
• 成员管理：将服务器分配到各组
• 工具筛选：配置各组可用的工具
• 验证密钥：设置和管理组级别的身份验证
• 组统计数据：使用统计数据和性能指标

6. API 到 MCP 集成

• API 配置：将 REST API 转换为 MCP 工具
• 参数映射：用于 API 到 MCP 参数映射的可视化编辑器
• API 测试：部署前测试 API 配置
• 导入/导出：在不同环境间共享 API 配置
• 自动生成：根据 API 规范自动生成 MCP 工具

7. 调试与开发工具

• MCP 协议监视器：查看原始 MCP 协议消息
• 工具调试器：使用详细的执行日志测试工具
• 性能分析器：分析工具性能和瓶颈
• 错误分析：智能诊断错误并提供修复建议
• 消息检查器：检查请求/响应负载

8. 配置管理

• 系统设置：配置系统范围的设置
• 配置编辑器：编辑并验证配置
• 备份与恢复：创建和恢复配置备份
• 配置历史记录：跟踪配置随时间发生的更改
• 验证：实时验证配置

身份验证设置

前端使用基于 JWT 的身份验证。配置身份验证的方法如下：

1. 默认凭据（开发环境）：

   • 用户名：admin
   • 密码：admin

2. 生产环境设置：

   • 在 system.json 中配置凭据、JWT 密钥和服务器端口（参见 backend/config/system.json.example 以及架构文件 packages/share/src/config/schemas/system.schema.ts）。
   • 在根配置 users.admin.password 中设置强密码。当前后端会在内存中对已配置的密码进行哈希处理；请勿在此字段中填写预先计算的 bcrypt 哈希值。请限制配置目录的访问权限，仅允许部署用户访问。
   • JWT 密钥/有效期来自 system.json 中的 auth.jwt 区块，而非 环境变量。

3. 环境变量：

   # Backend (.env) — only env vars the code actually reads; see .env.production.example
   NODE_ENV=production
   CONFIG_PATH=/path/to/config      # directory containing system.json, mcp_server.json, group.json
   VALIDATION_KEY_SECRET='<your-existing-secret-at-least-32-characters>'  # required when group validation is enabled
   

访问 Web 界面

1. 启动后端：

   pnpm dev:api
   # Backend runs on http://localhost:8181
   

2. 启动前端（开发环境）：

   pnpm dev:fe
   # Frontend runs on http://localhost:8180
   

3. 登录：

   • 前往 http://localhost:8180
   • 输入凭据（默认值：admin/admin）
   • 系统会将你重定向到控制面板

4. 生产环境部署：

   # Build frontend
   pnpm build:fe
   
   # Frontend static files will be in frontend/dist
   # Serve the output with nginx (included in the Web image)
   

   标准生产拓扑为双容器堆栈。使用 docker-compose.release.yml 拉取已发布的 GHCR 镜像，或使用 docker-compose.yml 从源代码构建：

   • mcp-knot-web（nginx，主机端口 8180）——提供 SPA 服务，并将 /api/、/mcp、/:group/mcp 反向代理到后端。SPA 回退（try_files ... /index.html） 配置在 frontend/nginx.conf 中，因此刷新任何前端路由都能正常工作。
   • mcp-knot-api（Node，内部端口 8181）——API + MCP 端点，不是 SPA 主机。

   始终通过 nginx 端口（8180）访问应用。使用前端路径直接访问后端端口（8181） 会返回 404 Not Found，因为后端只提供 /api/* 和 /:group/mcp——这是预期行为，并非错误。

   # v0.1.1 is published; prepare config and the localhost override per the guide
   export MCP_KNOT_VERSION=v0.1.1
   docker compose -f docker-compose.release.yml -f docker-compose.localhost.yml pull
   docker compose -f docker-compose.release.yml -f docker-compose.localhost.yml up -d --no-build --wait
   curl -f http://localhost:8180/api/ping
   

   请先准备可写的配置目录；该目录会挂载到 /app/config，默认为 ./config。已发布的镜像为 ghcr.io/yourtion/mcp-knot-api 和 ghcr.io/yourtion/mcp-knot-web。必须设置版本变量；不会隐式使用 latest。目前两个 v0.1.1 镜像均为 Public，匿名拉取已通过验证。 实际 GHCR amd64 镜像已通过 Compose 启动、API/Web 检查以及重启后的配置持久化验证。arm64 已构建并验证清单；尚未测试应用在 ARM 上的运行情况。完整的初始化 JSON、UID 1000 权限、本地主机覆盖配置和升级说明，请参阅部署指南。公开访问前请更改默认的 admin/admin 凭据和 JWT 密钥，然后重启 API。API 存活状态端点为 /api/ping；详细服务状态端点为 /api/health。

配置

MCP 服务配置

在 backend/config/ 目录中创建 mcp_server.json 文件：

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
      "env": {}
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    }
  }
}

分组配置

在 backend/config/group.json 中配置分组：

{
  "groups": {
    "development": {
      "name": "Development Tools",
      "description": "Tools for software development",
      "servers": ["filesystem", "git"],
      "allowedTools": ["read_file", "write_file", "git_status"],
      "validationKey": "dev-key-123"
    },
    "research": {
      "name": "Research Tools",
      "description": "Tools for research and information gathering",
      "servers": ["brave-search", "wikipedia"],
      "allowedTools": ["search", "lookup"],
      "validationKey": "research-key-456"
    }
  }
}

使用示例

基于分组的 MCP 访问

通过特定分组的端点访问工具：

# List tools for development group（MCP 2026-07-28 JSON-RPC）
curl -X POST http://localhost:8181/development/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# Call a tool in the research group
curl -X POST http://localhost:8181/research/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Method: tools/call" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {
        "query": "MCP protocol documentation"
      }
    }
  }'

使用官方 MCP SDK（Node）进行连接

默认情况下，/:group/mcp 端点提供现代 2026-07-28 协议；自协议兼容层（P7）上线以来，也接受旧版 2025 年客户端。入站兼容性默认为全开（现代 + 旧版）：现代客户端通过 server/discover 协商，而旧版客户端仍可使用不带参数的 initialize 握手。此设置可配置（参见 协议兼容性）。

对于现代客户端，官方 @modelcontextprotocol/client 应使用 versionNegotiation: { mode: 'auto' }，以便 SDK 探测并采用服务端的 2026-07-28 版本。

import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const transport = new StreamableHTTPClientTransport(new URL('http://localhost:8181/default/mcp'));
const client = new Client(
  { name: 'my-client', version: '1.0.0' },
  {
    capabilities: { tools: {} },
    // Recommended: lets the SDK probe and adopt the server's 2026-07-28 version.
    versionNegotiation: { mode: 'auto' },
  },
);

await client.connect(transport); // initialize
const { tools } = await client.listTools(); // tools/list
await client.callTool({ name: 'fetch_fetch', arguments: { url: 'https://example.com' } });

工具的命名空间格式为 <serverId>_<toolName>（例如 fetch_fetch、 context7_query-docs），以避免不同服务之间发生冲突。每个分组端点还会公开两个内置元工具 （group_status、list_group_tools）。

协议兼容性

Hub 提供协议兼容层（@mcp-core/mcp-knot-protocol），可双向桥接现代 2026-07-28 时代与旧版 2025 时代的 MCP：

• 入站（客户端 → Hub）：默认同时支持现代协议和旧版协议——现代客户端通过 server/discover 协商，旧版客户端不带参数的 initialize 仍可正常使用。设置 compatibility.inbound.enabled: false（或 CLI --no-legacy-inbound）即可拒绝旧版客户端，仅接受现代客户端。
• 出站（Hub → 上游服务）：按服务自动探测所属时代；Hub 会透明地将现代请求桥接到旧版上游服务。设置 compatibility.outbound.modernOnly: true（或 CLI --modern-only-upstream），即可在后端仅连接现代上游服务。CLI 标志目前仅作保留：其核心服务当前会模拟上游连接，不会强制执行该设置。
• MRTR 与错误：跨时代的 InputRequiredResult（MRTR）状态和协议错误会统一规范化为相同格式，不受上游所属时代影响。无法处理 input_required 的旧版上游会返回明确的 -32601 错误，而不会静默失败。

默认设置有意保持宽松，以确保现有客户端继续正常工作。system.json 中的 compatibility 配置块为可选项，且可部分覆盖；如需默认的完全开放行为，可将其整个省略。

测试覆盖：跨时代桥接由项目自有的端到端测试（protocol-compliance.test.ts：出站现代→旧版、入站旧版→现代）以及适配器／编解码器／规范化器层的单元测试覆盖。官方 @modelcontextprotocol/conformance TCK 已接入，作为回归测试门槛（pnpm test:conformance）；但截至 TCK v0.1.16，它在服务端模式下仅覆盖旧版（2025-11-25）时代，现代时代（2026-07-28）的兼容性测试仍待上游 TCK 支持。

CLI MCP 服务集成

在 MCP 客户端（例如 Claude Desktop）中配置 CLI 服务：

{
  "mcpServers": {
    "mcp-knot": {
      "command": "/path/to/mcp-knot/packages/cli/bin/mcp-knot.js",
      "args": ["--config", "/path/to/mcp_server.json"]
    }
  }
}

开发

可用脚本

# Development
pnpm dev:api          # Start API server in development mode
pnpm dev:fe           # Start frontend in development mode

# Building
pnpm build            # Build all packages
pnpm check            # Run linting and formatting

# Testing
pnpm test             # Run all tests
pnpm test:coverage    # Run tests with coverage
pnpm test:e2e         # Run end-to-end tests

# Utilities
pnpm inspector        # Launch MCP inspector for debugging

软件包开发

每个软件包都可以独立开发：

# Core package
cd packages/core
pnpm dev              # Watch mode compilation
pnpm test:watch       # Watch mode testing

# CLI package
cd packages/cli
pnpm dev              # Watch mode compilation
pnpm test:e2e         # End-to-end testing

# API package
cd backend
pnpm dev              # Development server
pnpm test:mcp         # MCP protocol tests

文档

用户指南

• Web UI 指南 - 完整的 Web 界面使用指南
• CLI 使用指南 - 详细的 CLI 使用和配置说明
• 故障排除 - 常见问题与故障排除

技术文档

• API 参考 - 完整的 API 文档
• 分组路由指南 - 基于分组的路由文档

开发与部署

• 开发指南 - 开发环境设置与贡献指南
• 发布流程 - 统一版本与基于标签的发布
• 部署指南 - 生产环境部署说明
• 故障排除 - 常见问题与解决方案

发布流程

四个公开包（share、protocol、core、cli）共用一个稳定版本。 更改合并且 main CI 通过后，在干净且最新的 main 上运行：

pnpm run release:prepare patch  # minor, major, or an explicit X.Y.Z also work
# Review the version-only commit and local vX.Y.Z tag
pnpm run release:push

准备步骤会验证发布内容，仅提交四个版本清单，然后创建本地标签。推送操作会以原子方式仅推送 main 和该标签。标签触发的 publish.yml 会进行验证、构建并检查 tarball，使用 npm OIDC 按依赖顺序发布，然后完成一个 GitHub Release。 重试时会跳过已发布的确切版本。可选的 GHCR API/Web 发布功能由仓库变量 DOCKER_PUBLISH=true 启用，使用 Actions 的 GITHUB_TOKEN 和按作业范围配置的 packages: write 权限，并为 amd64/arm64 发布 latest 和完整发布标签。 新的 GHCR 包默认设为私有；其可见性由维护者控制。 当前 API/Web 包为公开状态，且已验证 v0.1.1 可匿名拉取。 请参阅 GHCR 设置和验证结果。

使用 pnpm run release:validate 执行完整的本地检查，或使用 pnpm run release:dry-run 执行构建/打包检查而不发布。设置、首次发布身份验证和重试说明请参阅 RELEASING.md。

贡献

1. Fork 此仓库
2. 创建功能分支
3. 编写更改并添加测试
4. 运行 pnpm check 确保代码质量
5. 提交拉取请求

许可证

ISC 许可证——详情请参阅 LICENSE 文件。