AI导哈

MCP服务器整合枢纽

MCP Knot 是一个集中式 MCP 服务器整合枢纽，将多个 MCP 服务器汇聚为专用 Streamable HTTP/SSE 端点，并提供分组路由、工具过滤、CLI 与 Web 管理能力，适用于需要统一管理和按场景访问 MCP 工具的开发者。

  • by yourtion
  • TypeScript
  • 混合部署
  • 更新于
在 GitHub 查看 yourtion/mcp-hub

使用说明

MCP Knot

English | 中文版

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

Tie your MCP servers together.

A centralized hub server engineered to consolidate multiple MCP servers into dedicated Streamable HTTP or SSE endpoints, each tailored to specific use scenarios — lightweight, zero-config, and leading on the 2026-07-28 stateless MCP protocol.

Features

  • Multi-server MCP Integration: Support for multiple MCP servers with centralized management
  • Group-based Routing: Access MCP services through group-specific endpoints (/:group/mcp)
  • Versioned Skills Distribution: Import selected skills from local directories, public Git repositories or the skills CLI, then publish fixed snapshots alongside tools through a Group endpoint. See the Skills guide.
  • CLI MCP Server: Standalone command-line MCP server for tool aggregation
  • Streamable Endpoints: Support for both HTTP and SSE endpoints
  • Tool Filtering: Groups support tool filtering and screening capabilities
  • Validation Support: Groups can set separate validation keys for security
  • Modular Architecture: Clean separation between core logic, API, and CLI packages

Architecture

MCP Knot follows a modular monorepo architecture with the following packages:

Core Packages

  • @mcp-core/mcp-knot-core - Core MCP service management, connection handling, and tool execution
  • @mcp-core/mcp-knot-api - Web API server with group-based routing and HTTP endpoints
  • @mcp-core/mcp-knot-cli - Command-line MCP server for standalone tool aggregation
  • @mcp-core/mcp-knot-protocol - Protocol compatibility layer: dual-era (modern/legacy) translation, normalized models, unified errors
  • @mcp-core/mcp-knot-share - Shared types and utilities across packages
  • @mcp-core/mcp-knot-web - Vue.js frontend interface (optional)

Package Structure

├── 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

Installation

Prerequisites

  • Node.js 22.20+ (Node 24 recommended)
  • pnpm package manager

Install Dependencies

# Install all dependencies
pnpm install

# Build all packages
pnpm build

Quick Start

1. API Server (Web Interface)

Start the API server for web-based MCP hub functionality:

# Development mode
pnpm dev:api

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

The API server will be available at http://localhost:8181 with the following endpoints:

  • /mcp - Global MCP endpoint (legacy, for management)
  • /:group/mcp - Group-specific MCP endpoints
  • /api/groups - Group management API
  • /api/skills - Administrator APIs for skill sources, synchronization and market search
  • /api/config - System configuration management API
  • /api/servers - MCP server management API
  • /api/tools - Tool management and execution API
  • /api/debug - Debugging and monitoring API

2. CLI MCP Server

Use the CLI package as a standalone MCP server:

# 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

Quick Configuration Initialization

MCP Knot CLI provides quick configuration initialization to help you get started quickly:

# 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

The default configuration includes these commonly used MCP servers:

  • fetch: Web fetching and HTTP requests
  • time: Time and date functionality
  • sequential-thinking: Sequential thinking capabilities

More available server presets:

  • filesystem: File system operations
  • memory: Persistent memory storage
  • brave-search: Brave search engine
  • github: GitHub repository management

The CLI server communicates via stdin/stdout using the MCP protocol, perfect for integration with MCP clients like Claude Desktop.

3. Frontend Interface (Optional)

Start the web interface for visual management:

# Development mode
pnpm dev:fe

# Production build
pnpm build:fe

The frontend will be available at http://localhost:8180 (development) or served through the backend in production.

Web Interface Features

The frontend provides a comprehensive web-based management interface with the following features:

1. Authentication & Security
  • JWT Authentication: Secure login system with token-based authentication
  • Automatic Token Refresh: Seamless session management without interruption
  • Route Guards: Protected pages requiring authentication
  • Persistent Sessions: Remember user login state across browser sessions
  • Default Credentials: Username: admin, Password: admin (change in production!)
2. Dashboard & Monitoring
  • System Overview: Real-time statistics of servers, tools, and groups
  • Live Status Updates: Server-Sent Events (SSE) for real-time monitoring
  • Performance Metrics: Request rates, response times, and error rates
  • Activity Feed: Recent system activities and events
  • Health Monitoring: System health checks and alerts
3. Server Management
  • Server List: View all configured MCP servers with status indicators
  • Add/Edit Servers: Visual forms for server configuration
  • Connection Control: Connect, disconnect, and test server connections
  • Status Monitoring: Real-time server connection status
  • Configuration Validation: Test server configurations before saving
4. Tool Management
  • Tool Browser: Browse all available MCP tools across servers
  • Tool Search & Filter: Find tools by name, server, or group
  • Tool Testing: Interactive tool execution with parameter input
  • Execution History: View past tool executions and results
  • Tool Details: Complete tool documentation and schema information
5. Group Management
  • Group Configuration: Create and manage server groups
  • Member Management: Assign servers to groups
  • Tool Filtering: Configure which tools are available per group
  • Validation Keys: Set and manage group-level authentication
  • Group Statistics: Usage statistics and performance metrics
6. API to MCP Integration
  • API Configuration: Convert REST APIs to MCP tools
  • Parameter Mapping: Visual editor for API-to-MCP parameter mapping
  • API Testing: Test API configurations before deployment
  • Import/Export: Share API configurations across environments
  • Auto-generation: Automatically generate MCP tools from API specs
7. Debug & Development Tools
  • MCP Protocol Monitor: View raw MCP protocol messages
  • Tool Debugger: Test tools with detailed execution logs
  • Performance Analyzer: Analyze tool performance and bottlenecks
  • Error Analysis: Intelligent error diagnosis and fix suggestions
  • Message Inspector: Inspect request/response payloads
8. Configuration Management
  • System Settings: Configure system-wide settings
  • Configuration Editor: Edit configurations with validation
  • Backup & Restore: Create and restore configuration backups
  • Configuration History: Track configuration changes over time
  • Validation: Real-time configuration validation

Authentication Setup

The frontend uses JWT-based authentication. To configure authentication:

  1. Default Credentials (Development):

    • Username: admin
    • Password: admin

  2. Production Setup:

    • Configure credentials, JWT secret, and server port in system.json (see backend/config/system.json.example and the schema at packages/share/src/config/schemas/system.schema.ts).
    • Set a strong password in root users.admin.password. The current backend hashes the configured password in memory; do not put a precomputed bcrypt hash in this field. Keep the config directory restricted to the deployment user.
    • JWT secret/expiry come from the auth.jwt block in system.json, not environment variables.

  3. Environment Variables:

    # 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

Accessing the Web Interface

  1. Start the Backend:

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

  2. Start the Frontend (Development):

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

  3. Login:

    • Navigate to http://localhost:8180
    • Enter credentials (default: admin/admin)
    • You'll be redirected to the dashboard

  4. Production Deployment:

    # Build frontend
pnpm build:fe

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

    The canonical production topology is a two-container stack. Use docker-compose.release.yml for published GHCR images, or docker-compose.yml to build from source:

    • mcp-knot-web (nginx, host port 8180) — serves the SPA and reverse-proxies /api/, /mcp, /:group/mcp to the backend. SPA fallback (try_files ... /index.html) is configured in frontend/nginx.conf, so refreshing any frontend route works.
    • mcp-knot-api (Node, internal 8181) — the API + MCP endpoint, not a SPA host.

    Always access the app via the nginx port (8180). Hitting the backend port (8181) directly with a frontend path returns 404 Not Found because the backend only serves /api/* and /:group/mcp — this is expected, not a bug.

    # 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

    Prepare the writable config directory first; it mounts at /app/config and defaults to ./config. Published images are ghcr.io/yourtion/mcp-knot-api and ghcr.io/yourtion/mcp-knot-web. The version variable is required; there is no implicit latest. Both v0.1.1 images are currently Public and anonymous pulls have passed. Actual GHCR amd64 images passed Compose startup, API/Web checks and configuration persistence after restart. arm64 was built and its manifest verified; application runtime on ARM was not tested. See the deployment guide for full initialization JSON, UID 1000 permissions, the localhost override and upgrades. Replace default admin/admin and the JWT secret before public access, then restart the API. API liveness is /api/ping; detailed service status is /api/health.

Configuration

MCP Server Configuration

Create a mcp_server.json file in the backend/config/ directory:

{
  "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"
      }
    }
  }
}

Group Configuration

Configure groups in 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"
    }
  }
}

Usage Examples

Group-based MCP Access

Access tools through group-specific endpoints:

# 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"
      }
    }
  }'

Connecting with the official MCP SDK (Node)

The /:group/mcp endpoint serves the modern 2026-07-28 protocol by default, and — since the protocol compatibility layer (P7) — also accepts legacy 2025-era clients. Inbound compatibility defaults to 全开 (modern + legacy): a modern client negotiates via server/discover, while a legacy client's bare initialize handshake is still served. This is configurable (see Protocol Compatibility).

For a modern client, the official @modelcontextprotocol/client should use versionNegotiation: { mode: 'auto' } so the SDK probes and adopts the server's 2026-07-28 version.

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' } });

Tools are namespaced as <serverId>_<toolName> (e.g. fetch_fetch, context7_query-docs) to avoid collisions across servers. Two built-in meta-tools (group_status, list_group_tools) are also exposed on every group endpoint.

Protocol Compatibility

Hub ships a protocol compatibility layer (@mcp-core/mcp-knot-protocol) that bridges the modern 2026-07-28 era and legacy 2025-era MCP on both directions:

  • Inbound (client → Hub): defaults to modern + legacy simultaneously — a modern client negotiates via server/discover, a legacy client's bare initialize is still served. Set compatibility.inbound.enabled: false (or CLI --no-legacy-inbound) to reject legacy clients and accept only modern.
  • Outbound (Hub → upstream server): era is auto-probed per server; Hub transparently bridges modern requests to legacy upstreams. Set compatibility.outbound.modernOnly: true (or CLI --modern-only-upstream) to connect only to modern upstreams in the backend. The CLI flag is reserved: its core service currently simulates upstream connections and does not enforce it.
  • MRTR & errors: cross-era InputRequiredResult (MRTR) state and protocol errors are normalized into a unified shape regardless of upstream era. A legacy upstream that cannot honor input_required degrades to a clear -32601 error rather than failing silently.

Defaults are intentionally permissive so existing clients keep working. The compatibility block in system.json is optional and partially overridable; omit it entirely for the default all-open behavior.

Testing coverage: cross-era bridging is covered by project-owned e2e (protocol-compliance.test.ts: outbound modern→legacy, inbound legacy→modern) plus unit tests for the adapter/codec/normalizer layers. The official @modelcontextprotocol/conformance TCK is wired as a regression gate (pnpm test:conformance) but, as of TCK v0.1.16, only covers the legacy (2025-11-25) era in server mode — modern-era (2026-07-28) conformance is pending upstream TCK support.

CLI MCP Server Integration

Configure the CLI server in your MCP client (e.g., Claude Desktop):

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

Development

Available Scripts

# 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

Package Development

Each package can be developed independently:

# 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

Documentation

User Guides

Technical Documentation

Development & Deployment

Release Process

The four public packages (share, protocol, core, cli) share one stable version. After changes are merged and main CI passes, run from a clean, up-to-date 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

Preparation validates the release, commits only the four version manifests, then creates a local tag. Push atomically sends only main and that tag. The tag-triggered publish.yml validates, builds and checks tarballs, publishes in dependency order with npm OIDC, then completes one GitHub Release. Exact versions already published are skipped on retry. Optional GHCR API/Web publishing is enabled by the repository variable DOCKER_PUBLISH=true, uses the Actions GITHUB_TOKEN with job-scoped packages: write, and publishes latest plus the full release tag for amd64/arm64. New GHCR packages default to private; the maintainer controls their visibility. The current API/Web packages are Public and v0.1.1 anonymous pulls are verified. See GHCR setup and verified results.

Use pnpm run release:validate for full local checks or pnpm run release:dry-run for build/package checks without publishing. Setup, first-publish authentication and retry instructions are in RELEASING.md.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with tests
  4. Run pnpm check to ensure code quality
  5. Submit a pull request

License

ISC License - see LICENSE file for details.

相关 MCP