使用说明

MCP-HUB-LITE

中文文档

一个为独立开发人员设计的轻量级MCP管理平台，提供MCP服务器网关、分组、模糊搜索和MCP HttpStream协议接口。

概述

MCP-HUB-LITE是专为独立开发人员设计的MCP服务器网关。它充当前端和多个后端MCP服务器之间的代理，提供支持MCP JSON-RPC 2.0协议的统一访问接口。

核心功能

MCP网关服务：多个后端MCP服务器的统一代理接口
MCP CLI工具：用于跨服务器列出和调用MCP工具的命令行工具
服务器管理：通过web界面管理多个MCP服务器
工具搜索：通过聚合在所有服务器上进行搜索和工具发现
流程管理：通过npx/uvx启动和管理MCP服务器进程
双模式会话：有状态（会话持久性、SSE、通知）和无状态（按请求）模式，具有UA/header/config优先级切换
MCP通知推送：推 notifications/tools/list_changed 和 notifications/resources/list_changed 连接到客户端
多实例支持：使用负载平衡运行同一MCP服务器的多个实例
实例选择策略：支持随机、循环和唯一标签选择
标签系统：按环境、类别、功能等组织多个MCP服务器。
容错：当单个服务器发生故障时，系统继续运行
双语界面：支持中英文界面切换
配置管理：支持热装和维护 .mcp-hub.json
MCP本地资源：将资源调用转发到后端MCP服务器
安全：屏蔽配置更改日志中的敏感值

快速开始

系统要求

Node.js 22.x或更高版本
npm或纱线
Windows、macOS或Linux

安装

从npm安装

# Install from npm
npm install -g @loop_ouroboros/mcp-hub-lite

# Start the service
mcp-hub-lite start

# Open UI
mcp-hub-lite ui

从源代码构建

# Install dependencies
npm install

# Run in development mode (frontend and backend hot reload)
npm run dev

# Build production version
npm run build

# Full check (build + tests + code check)
npm run full:check

# Run production version
npm start

# Check status
mcp-hub-lite status

# Open UI interface
mcp-hub-lite ui

服务器将在以下时间启动 http://localhost:7788.

服务器管理

在一个地方管理所有MCP服务器。通过直观的web界面添加、编辑、删除、连接和断开服务器。

网关和工具

通过统一的网关接口从所有连接的MCP服务器中发现和调用工具。聚合工具视图提供了一个搜索和使用所有可用工具的单一位置。

资源

从所有连接的服务器浏览和管理MCP资源。

测试

# Run all tests
npm test

# Backend tests
npm run test:backend

# Frontend tests
npm run test:frontend

CLI命令

MCP-HUB-LITE提供了一个用于管理服务的命令行界面。

# Start the service
npm start
# or
mcp-hub-lite start

# Check status
mcp-hub-lite status

# List all servers
mcp-hub-lite list

# Open web interface
mcp-hub-lite ui

# Help
mcp-hub-lite --help

工具使用命令

这 tool-use 命令提供MCP服务器工具操作：

# List system tools (default server: mcp-hub-lite)
mcp-hub-lite tool-use list-tools

# List tools from a specific server
mcp-hub-lite tool-use list-tools --server baidu-search

# Get tool schema
mcp-hub-lite tool-use get-tool --tool list_tools

# Call a system tool
mcp-hub-lite tool-use call-tool --tool list_tools --args '{}'

# Call a server tool
mcp-hub-lite tool-use call-tool --server baidu-search --tool search --args '{"query":"hello"}'

配置

MCP-HUB-LITE使用 .mcp-hub.json 配置文件。配置查找优先级：

环境变量 MCP_HUB_CONFIG_PATH
~/.mcp-hub-lite/config/.mcp-hub.json （用户主目录中的隐藏文件夹）

配置示例

Click to expand full .mcp-hub.json example

{
  "version": "1.1.0",
  "servers": [
    {
      "id": "server-1",
      "name": "My MCP Server",
      "description": "Example server",
      "transport": "streamable-http",
      "endpoint": "http://localhost:8080",
      "tags": {
        "env": "development",
        "category": "api-server",
        "function": "http-api",
        "priority": "medium"
      },
      "allowedTools": [],
      "instances": [
        {
          "index": 0,
          "displayName": "Instance 1",
          "enabled": true,
          "env": {}
        }
      ],
      "managedProcess": {
        "command": "npx my-mcp-server",
        "managedMode": "npx",
        "processType": "streamable-http"
      }
    }
  ],
  "settings": {
    "language": {
      "current": "en-US",
      "autoDetect": true,
      "fallback": "en-US"
    },
    "logging": {
      "level": "info"
    }
  },
  "system": {
    "session": {
      "defaultSessionMode": "stateful",
      "sessionModeRules": {
        "stateful": ["Claude"],
        "stateless": ["CherryStudio"]
      }
    }
  },
  "gateway": {
    "proxyTimeout": 30000,
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowMs": 60000
    }
  }
}

客户端配置

要将MCP客户端连接到MCP-HUB-LITE，请将以下内容添加到客户端的MCP配置中：

Claude Code / Claude Desktop (stateful mode — default)

{
  "mcpServers": {
    "mcp-hub-lite": {
      "type": "http",
      "url": "http://localhost:7788/mcp"
    }
  }
}

状态模式提供会话持久性、SSE流和实时通知。UA匹配不是自动的，需要手动添加 "ClaudeCode" 到 system.session.sessionModeRules.stateful 在 .mcp-hub.json标准MCP客户端（如Claude Code）使用默认的有状态模式，无需额外配置。

CherryStudio (stateless mode)

{
  "mcpServers": {
    "mcp-hub-lite": {
      "type": "http",
      "url": "http://localhost:7788/mcp",
      "headers": {
        "x-mcp-session-mode": "stateless"
      }
    }
  }
}

CherryStudio需要 x-mcp-session-mode: stateless header使用无状态模式。UA匹配不是自动的，需要手动添加 "CherryStudio" 到 system.session.sessionModeRules.stateless 在 .mcp-hub.json。标题方法是推荐的方法，具有最高优先级。

无状态模式使用每个请求的传输——每个POST创建一个独立的传输，没有会话持久性，GET返回405。

Manual session mode override

添加 x-mcp-session-mode header强制特定模式：

{
  "mcpServers": {
    "mcp-hub-lite": {
      "type": "http",
      "url": "http://localhost:7788/mcp",
      "headers": {
        "x-mcp-session-mode": "stateful"
      }
    }
  }
}

有效值： "stateful" 或 "stateless".Header的优先级高于UA匹配和配置默认值。

使用指南

添加MCP服务器

通过web界面：

打开 http://localhost:7788
导航到“服务器”页面
点击“添加服务器”
填写服务器详细信息并保存

流程管理

MCP-HUB-LITE支持使用本地环境启动和管理MCP服务器：

支持的启动方法

Node.js（npx）: npx package-name
Python（uvx）: uvx package-name
直接命令：自定义启动命令

流程管理功能

启动/停止/重新启动MCP服务器
监控CPU和内存使用情况
碰撞检测和自动重启
PID跟踪和健康检查

开发指南

项目结构

src/
├── api/              # API implementations
│   ├── mcp/          # MCP protocol handlers
│   ├── web/          # Web API routes (includes sessions.ts)
│   └── ws/           # WebSocket routes
├── models/           # Data models
├── services/         # Core business logic
│   ├── gateway/      # MCP gateway service
│   ├── connection/   # Connection management
│   └── hub-tools/    # Hub tools service
├── utils/            # Utility functions
│   ├── logger/       # Logging utilities
│   └── transports/   # MCP transport implementations
├── config/           # Configuration
├── cli/              # CLI commands
│   └── commands/     # CLI command implementations
├── pid/              # Process ID management
└── server/           # Server runtime

frontend/
├── src/
│   ├── components/   # Reusable UI components
│   ├── views/        # Page view components
│   ├── stores/       # Pinia state management
│   ├── composables/  # Vue composables
│   ├── router/       # Vue Router configuration
│   ├── i18n/         # Internationalization
│   └── types/        # Frontend type definitions

shared/
├── models/           # Shared models
└── types/           # Shared types

tests/
├── unit/            # Unit tests
├── integration/     # Integration tests
├── contract/        # Contract tests
├── helpers/         # Test helpers
└── types/          # Test types

添加新功能

创建模型（models/）
实施服务（服务/）
添加API路由（API/）
编写测试（tests/）
更新配置文件

详细的技术文档

完整的项目架构、约束和设计决策可以在以下文件中找到：

CLAUDE.md -项目AI背景和模块文档

许可证

麻省理工学院

贡献

欢迎提交请求和问题！

社区

感谢LinuxDo（linux.do）社区的讨论、分享和反馈。