Описание
Централизованный менеджер для серверов Model Context Protocol (MCP), обеспечивающий динамическое управление серверами, REST API и отслеживание состояния в реальном времени.
Тип
MCP Hub
A centralized manager for Model Context Protocol (MCP) servers that provides:
- Dynamic MCP server management and monitoring
- REST API for tool execution and resource access
- MCP Server marketplace (using Cline marketplace)
- Real-time server status tracking
- Client connection management
- Process lifecycle handling
Overview
Hub Server vs MCP Servers
-
Hub Server (MCP Hub)
- Central management server that connects to and manages multiple MCP servers
- Provides unified API endpoints for clients to access MCP server capabilities
- Handles server lifecycle, health monitoring, and client connections
- Routes requests between clients and appropriate MCP servers
-
MCP Servers
- Individual servers that provide specific tools and resources
- Each server has its own capabilities (tools, resources, templates)
- Connected to and managed by the Hub server
- Process requests from clients through the Hub
Installation
npm install -g mcp-hub
Basic Usage
Start the hub server:
mcp-hub --port 3000 --config path/to/config.json
CLI Options
Options:
--port Port to run the server on (default: 3000)
--config Path to config file (required)
--watch Watch config file for changes (default: false)
--shutdown-delay Delay in milliseconds before shutting down when no clients are connected (default: 0)
-h, --help Show help information
The server outputs JSON-formatted status messages on startup and state changes:
{
"status": "ready",
"server_id": "mcp-hub",
"version": "1.0.0",
"port": 3000,
"pid": 12345,
"servers": [],
"timestamp": "2024-02-20T05:55:00.000Z"
}
Nix
Nixpkgs install
comming...
Flake install
Just add it to your NixOS flake.nix or home-manager:
inputs = { mcp-hub.url = "github:ravitemer/mcp-hub"; ... }
To integrate mcp-hub to your NixOS/Home Manager configuration, add the following to your environment.systemPackages or home.packages respectively:
inputs.mcp-hub.packages."${system}".default
Usage without install
If you want to use mcphub.nvim without having mcp-hub server in your PATH you can link the server under the hood adding
the mcp-hub nix store path to the cmd
command in the plugin config like
Nixvim example:
{ mcphub-nvim, mcp-hub, ... }: { extraPlugins = [mcphub-nvim]; extraConfigLua = '' require("mcphub").setup({ port = 3000, config = vim.fn.expand("~/mcp-hub/mcp-servers.json"), cmd = "${mcp-hub}/bin/mcp-hub" }) ''; } # where { # For nixpkgs (not available yet) mcp-hub = pkgs.mcp-hub; # For flakes mcp-hub = inputs.mcp-hub.packages."${system}".default; }
Configuration
MCP Hub uses a JSON configuration file to define managed servers:
{
"mcpServers": {
"example-server": {
"command": "npx",
"args": ["example-server"],
"env": {
"API_KEY": "", // Will use process.env.API_KEY
"DEBUG": "true", // Will use this value
"SECRET_TOKEN": null // Will use process.env.SECRET_TOKEN
},
"disabled": false
}
}
}
Configuration Options
- command: Command to start the MCP server
- args: Array of command line arguments
- env: Environment variables for the server. If a variable is specified with a falsy value (empty string, null, undefined), it will fall back to using the corresponding system environment variable if available.
- disabled: Whether the server is disabled (default: false)
Example Integrations
Neovim Integration
The ravitemer/mcphub.nvim plugin provides seamless integration with Neovim, allowing direct interaction with MCP Hub from your editor:
- Execute MCP tools directly from Neovim
- Access MCP resources within your editing workflow
- Real-time status updates in Neovim
- Auto install mcp servers with marketplace addition
Logging
MCP Hub uses structured JSON logging for all events:
{
"type": "error",
"code": "TOOL_ERROR",
"message": "Failed to execute tool",
"data": {
"server": "example-server",
"tool": "example-tool",
"error": "Invalid parameters"
},
"timestamp": "2024-02-20T05:55:00.000Z"
}
Log levels include:
info
: Normal operational messageswarn
: Warning conditionsdebug
: Detailed debug informationerror
: Error conditions (includes error code and details)
REST API
Health and Status
Health Check
GET /api/health
Response:
{
"status": "ok",
"server_id": "mcp-hub",
"version": "1.0.0",
"activeClients": 2,
"timestamp": "2024-02-20T05:55:00.000Z",
"servers": []
}
List MCP Servers
GET /api/servers
Get Server Info
GET /api/servers/:name/info
Refresh Server Capabilities
POST /api/servers/:name/refresh
Response:
{
"status": "ok",
"server": {
"name": "example-server",
"capabilities": {
"tools": ["tool1", "tool2"],
"resources": ["resource1", "resource2"],
"resourceTemplates": []
}
},
"timestamp": "2024-02-20T05:55:00.000Z"
}
Refresh All Servers
POST /api/refresh
Response:
{
"status": "ok",
"servers": [
{
"name": "example-server",
"capabilities": {
"tools": ["tool1", "tool2"],
"resources": ["resource1", "resource2"],
"resourceTemplates": []
}
}
],
"timestamp": "2024-02-20T05:55:00.000Z"
}
Start Server
POST /api/servers/:name/start
Response:
{
"status": "ok",
"server": {
"name": "example-server",
"status": "connected",
"uptime": 123
},
"timestamp": "2024-02-20T05:55:00.000Z"
}
Stop Server
POST /api/servers/:name/stop?disable=true|false
The optional disable
query parameter can be set to true
to disable the server in the configuration.
Response:
{
"status": "ok",
"server": {
"name": "example-server",
"status": "disconnected",
"uptime": 0
},
"timestamp": "2024-02-20T05:55:00.000Z"
}
Client Management
Register Client
POST /api/client/register
{
"clientId": "unique_client_id"
}
Unregister Client
POST /api/client/unregister
{
"clientId": "unique_client_id"
}
Marketplace Integration
List Available Servers
GET /api/marketplace
Query Parameters:
search
: Filter by name, description, or tagscategory
: Filter by categorytags
: Filter by comma-separated tagssort
: Sort by "newest", "stars", or "name"
Response:
{
"items": [
{
"mcpId": "github.com/user/repo/server",
"name": "Example Server",
"description": "Description here",
"category": "search",
"tags": ["search", "ai"],
"githubStars": 100,
"isRecommended": true,
"createdAt": "2024-02-20T05:55:00.000Z"
}
],
"timestamp": "2024-02-20T05:55:00.000Z"
}
Get Server Details
POST /api/marketplace/details
Content-Type: application/json
{
"mcpId": "github.com/user/repo/server"
}
Response:
{
"server": {
"mcpId": "github.com/user/repo/server",
"name": "Example Server",
"description": "Description here",
"githubUrl": "https://github.com/user/repo",
"readmeContent": "# Server Documentation...",
"llmsInstallationContent": "Installation guide..."
},
"timestamp": "2024-02-20T05:55:00.000Z"
}
MCP Server Operations
Execute Tool
POST /api/servers/:name/tools
{
"tool": "tool_name",
"arguments": {}
}
Access Resource
POST /api/servers/:name/resources
{
"uri": "resource://uri"
}
Real-time Updates
The Hub Server provides real-time updates via Server-Sent Events (SSE) at /api/events
. Connect to this endpoint to receive real-time updates about server status, client connections, and capability changes.
Event Types
- server_info - Initial connection information
{
"server_id": "mcp-hub",
"version": "1.0.0",
"status": "connected",
"pid": 12345,
"port": 3000,
"activeClients": 1,
"timestamp": "2024-02-20T05:55:00.000Z"
}
- server_ready - Server started and ready
{
"status": "ready",
"server_id": "mcp-hub",
"version": "1.0.0",
"port": 3000,
"pid": 12345,
"servers": [],
"timestamp": "2024-02-20T05:55:00.000Z"
}
- client_registered/unregistered - Client connection events
{
"activeClients": 2,
"clientId": "client_123",
"timestamp": "2024-02-20T05:55:00.000Z"
}
- tool_list_changed - Server's tools list has changed
{
"type": "TOOL",
"server": "example-server",
"tools": ["tool1", "tool2"],
"timestamp": "2024-02-20T05:55:00.000Z"
}
- resource_list_changed - Server's resources list has changed
{
"type": "RESOURCE",
"server": "example-server",
"resources": ["resource1", "resource2"],
"resourceTemplates": [],
"timestamp": "2024-02-20T05:55:00.000Z"
}
Error Handling
MCP Hub implements a comprehensive error handling system with custom error classes for different types of errors:
Error Classes
- ConfigError: Configuration-related errors (invalid config, missing fields)
- ConnectionError: Server connection issues (failed connections, transport errors)
- ServerError: Server startup/initialization problems
- ToolError: Tool execution failures
- ResourceError: Resource access issues
- ValidationError: Request validation errors
Each error includes:
- Error code for easy identification
- Detailed error message
- Additional context in the details object
- Stack trace for debugging
Example error structure:
{
"code": "CONNECTION_ERROR",
"message": "Failed to communicate with server",
"details": {
"server": "example-server",
"error": "connection timeout"
},
"timestamp": "2024-02-20T05:55:00.000Z"
}
Error Categories
-
Configuration Errors
- Invalid config format
- Missing required fields
- Environment variable issues
-
Server Management Errors
- Connection failures
- Lost connections
- Capability fetch issues
- Server startup problems
-
Request Processing Errors
- Invalid parameters
- Server availability
- Tool execution failures
- Resource access issues
-
Client Management Errors
- Registration failures
- Duplicate registrations
- Invalid client IDs
Architecture
Hub Server Lifecycle
sequenceDiagram participant H as Hub Server participant M1 as MCP Server 1 participant M2 as MCP Server 2 participant C as Client Note over H: Server Start activate H H->>+M1: Connect M1-->>-H: Connected + Capabilities H->>+M2: Connect M2-->>-H: Connected + Capabilities Note over C,H: Client Interactions C->>H: Register Client H-->>C: Servers List & Capabilities C->>H: Call Tool (M1) H->>M1: Execute Tool M1-->>H: Tool Result H-->>C: Response C->>H: Access Resource (M2) H->>M2: Get Resource M2-->>H: Resource Data H-->>C: Response Note over H: Server Management H->>H: Monitor Server Health H->>H: Track Server Status H->>H: Update Capabilities Note over H: Shutdown Process C->>H: Unregister H->>M1: Disconnect H->>M2: Disconnect deactivate H
The Hub Server coordinates communication between clients and MCP servers:
- Starts and connects to configured MCP servers
- Manages client registrations
- Routes tool execution and resource requests
- Handles server monitoring and health checks
- Performs clean shutdown of all connections
MCP Server Management
flowchart TB A[Hub Server Start] --> B{Config Available?} B -->|Yes| C[Load Server Configs] B -->|No| D[Use Default Settings] C --> E[Initialize Connections] D --> E E --> F{For Each MCP Server} F -->|Enabled| G[Attempt Connection] F -->|Disabled| H[Skip Server] G --> I{Connection Status} I -->|Success| J[Fetch Capabilities] I -->|Failure| K[Log Error] J --> L[Store Server Info] K --> M[Mark Server Unavailable] L --> N[Monitor Health] M --> N N --> O{Health Check} O -->|Healthy| P[Update Capabilities] O -->|Unhealthy| Q[Attempt Reconnect] Q -->|Success| P Q -->|Failure| R[Update Status] P --> N R --> N
The Hub Server actively manages MCP servers through:
- Configuration-based server initialization
- Connection and capability discovery
- Health monitoring and status tracking
- Automatic reconnection attempts
- Server state management
Request Handling
sequenceDiagram participant C as Client participant H as Hub Server participant M as MCP Server Note over C,H: Tool Execution Flow C->>H: POST /api/servers/{name}/tools H->>H: Validate Request H->>H: Check Server Status alt Server Not Connected H-->>C: Error: Server Unavailable else Server Connected H->>M: Execute Tool alt Tool Success M-->>H: Tool Result H-->>C: Success Response else Tool Error M-->>H: Error Details H-->>C: Error Response end end Note over C,H: Resource Access Flow C->>H: POST /api/servers/{name}/resources H->>H: Validate URI H->>H: Check Server Status alt Valid Resource H->>M: Request Resource M-->>H: Resource Data H-->>C: Resource Content else Invalid Resource H-->>C: 404 Not Found end
All client requests follow a standardized flow:
- Request validation
- Server status verification
- Request routing to appropriate MCP server
- Response handling and error management
Requirements
- Node.js >= 18.0.0
Todo
- [ ] Implement custom marketplace rather than depending on mcp-marketplace
Acknowledgements
- Cline mcp-marketplace - For providing the MCP server marketplace endpoints that power MCP Hub's marketplace integration