mcpware

Gateway MCP Server

智能地将 MCP 请求路由到多个后端服务。

🎯 主要功能

🚀 突破工具数量限制

• 挑战：MCP 客户端通常会限制一次加载的工具数量
• 解决方案：mcpware 仅公开 2 个路由工具，同时提供对无限量后端工具的访问
• 结果：通过单个网关即可连接 GitHub（50 多个工具）、数据库等！

🔧 其他优势

• 统一入口，连接多个 MCP 服务
• 自动管理后端服务进程
• 基于 Docker 的隔离与部署

快速开始

# Clone the repository
git clone https://github.com/delexw/mcpware.git
cd mcpware

# Build the Docker image
docker build -t mcpware . --no-cache

# Configure MCP client (see Installation section)

然后按照安装部分的说明配置 MCP 客户端。

工作原理

mcpware 以 Docker 容器的形式运行，并执行以下操作：

1. 通过 stdio 接收 MCP 客户端的请求
2. 将请求路由到相应的后端 MCP 服务（同样运行在 Docker 中）
3. 将响应返回给 MCP 客户端

重要：后端服务可以使用任何命令（docker、npx、node、python 等）。在 Docker 中运行 mcpware 时，使用 npx 或 node 等本地命令的后端将在 mcpware 容器内执行。

安装

前置条件

• Docker
• MCP 客户端（如 Cursor）

使用 MCP 客户端进行设置

1. 克隆此仓库：

   git clone https://github.com/delexw/mcpware.git
   cd mcpware
   

2. 在 config.json 中配置后端（请参阅下文的“配置”部分）

3. 设置环境变量：

   1. 复制示例文件：cp env.example .env
   2. 使用实际值编辑 .env：

      GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
      BUILDKITE_API_TOKEN=your_buildkite_token_here
      # 根据需要添加其他环境变量
      

4. 添加到 MCP 客户端配置中：

   **注意：**你可以直接在 mcpware 的 config.json 中配置密钥或令牌

   配置（直接运行 Docker）：

   {
     "mcpServers": {
       "mcpware": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-v",
           "/path/to/mcpware/config.json:/app/config.json:ro",
           "-v",
           "/var/run/docker.sock:/var/run/docker.sock",
           "--env-file",
           "/path/to/mcpware/.env",
           "mcpware"
         ]
       }
     }
   }
   

   重要：

   • 将 /path/to/mcpware 替换为克隆仓库的绝对路径
   • mcpware 需要 Docker 套接字挂载（/var/run/docker.sock）才能启动基于 Docker 的后端；否则无需挂载

   为什么要挂载 Docker 套接字？

   • mcpware 需要为后端 MCP 服务（例如 ghcr.io/github/github-mcp-server）启动 Docker 容器
   • Docker 套接字挂载使 mcpware 能够与 Docker 通信
   • 没有此挂载，mcpware 就无法启动以 Docker 容器方式运行的后端服务

特定平台的 Docker 套接字配置

网关需要访问 Docker 套接字才能启动后端容器。不同平台的挂载路径有所不同：

为什么需要访问 Docker 套接字？ mcpware 充当进程管理器，用于启动后端 MCP 服务。如果后端配置为以 Docker 容器运行（例如 ghcr.io/github/github-mcp-server），mcpware 需要：

• 创建并启动 Docker 容器
• 管理容器的生命周期（停止／重启）
• 通过 stdio 与容器通信

如果无法访问 Docker 套接字，mcpware 就无法启动基于 Docker 的后端，并会因权限错误而失败。

快速检查

运行此脚本以检查 Docker 配置：

python scripts/check_docker_socket.py

Linux/macOS/WSL2

无需更改。默认配置即可正常工作：

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

Windows（原生容器）

更新 Docker 套接字路径：

{
  "mcpServers": {
    "mcpware": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/mcpware/config.json:/app/config.json:ro",
        "-v",
        "//./pipe/docker_engine://./pipe/docker_engine",
        "--env-file",
        "/path/to/mcpware/.env",
        "mcpware"
      ]
    }
  }
}

请注意 Docker 套接字路径不同：使用 //./pipe/docker_engine 而不是 /var/run/docker.sock

检查 Docker 类型

要确认你在 Windows 上使用的是哪种 Docker 后端：

docker version --format '{{.Server.Os}}'

• linux = WSL2/Hyper-V 后端（使用默认配置）
• windows = Windows 容器（使用覆盖文件）

配置

创建一个 config.json，其中包含你的后端服务：

{
  "backends": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      },
      "description": "GitHub MCP Server",
      "timeout": 60
    },
    "database": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "bytebase/dbhub", "--transport", "stdio"],
      "description": "Database MCP Server"
    }
  }
}

配置说明：

• 后端命令可以是任何可执行文件（docker、npx、node、python 等）
• 使用 docker 命令时，确保已挂载 Docker 套接字（参阅安装说明）

参见 config.example.json，了解更多后端示例（数据库、API 等）。

用法

网关提供两个主要工具：

use_tool

将工具调用路由到指定的后端服务。

参数：

• backend_server：后端服务的名称
• server_tool：要调用的工具名称
• tool_arguments：要传递给工具的参数

示例：

{
  "backend_server": "github",
  "server_tool": "create_issue",
  "tool_arguments": {
    "owner": "myorg",
    "repo": "myrepo",
    "title": "New issue",
    "body": "Issue description"
  }
}

discover_backend_tools

发现可用的后端及其工具。

参数：

• backend_name：（可选）要查询的特定后端

在其他 MCP 服务旁使用 mcpware

mcpware 专为与 MCP 客户端配置中的其他 MCP 服务协同工作而设计。你可以：

1. 将 mcpware 用作网关，连接多个后端服务
2. 让部分 MCP 服务保持独立，以便直接访问
3. 根据需要灵活组合

混合配置示例：

{
  "mcpServers": {
    "mcpware": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/mcpware/config.json:/app/config.json:ro",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "--env-file", "/path/to/mcpware/.env",
        "mcpware"
      ]
    },
    "redis-direct": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "REDIS_HOST=localhost", "mcp/redis"]
    }
  }
}

这样你就可以：

• 需要路由时，通过 mcpware 访问多个服务
• 需要专用访问时，直接连接特定服务
• 根据工作流组织 MCP 服务

开发

先决条件

确保已安装 Python 3.10+：

python --version  # Should show Python 3.10 or higher

开发环境设置

1. 克隆仓库：

   git clone https://github.com/delexw/mcpware.git
   cd mcpware
   

2. 创建虚拟环境（推荐）：

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. 安装开发依赖项：

   pip install -r requirements.txt
   

开发依赖项

该项目使用最少的依赖项。所有核心功能均使用 Python 标准库实现。

测试依赖项（包含在 requirements.txt 中）：

• pytest - 测试框架
• pytest-asyncio - 异步测试支持
• pytest-cov - 代码覆盖率报告

可选开发工具（如有需要，请单独安装）：

# Code formatting
pip install black isort

# Linting
pip install flake8 pylint mypy

# Development convenience
pip install pytest-watch  # Auto-run tests on file changes

在本地运行

# Run the gateway server
python gateway_server.py --config config.json

# Run with debug logging
python gateway_server.py --config config.json --log-level DEBUG

代码风格

提交前请格式化代码：

# Format with black (if installed)
black src/ tests/ gateway_server.py

# Sort imports (if installed)
isort src/ tests/ gateway_server.py

# Run linting (if installed)
flake8 src/ tests/ gateway_server.py --max-line-length=120

运行测试

# Run all tests
pytest

# Run with coverage report
pytest --cov=src --cov=gateway_server --cov-report=html

# Run specific test file
pytest tests/test_config.py

# Run tests in watch mode (requires pytest-watch)
pytest-watch

Docker

使用 Docker 构建并运行：

# Build the image
docker build -t mcpware .

# Run interactively (for testing)
docker run -it --rm \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  mcpware

# Run with specific config file
docker run -it --rm \
  -v /path/to/your/config.json:/app/config.json:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  mcpware

环境变量

网关支持在后端配置中替换环境变量。请在 .env 文件中设置这些变量：

# Example .env file
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
# Add other tokens as needed

在 config.json 中使用 ${VAR_NAME} 语法引用的环境变量将自动替换。

测试

该项目包含全面的单元测试和集成测试。

运行测试

1. 安装测试依赖项：

   pip install -r requirements.txt
   

2. 运行所有测试：

   pytest
   

3. 运行测试并生成覆盖率报告：

   pytest --cov=src --cov=gateway_server --cov-report=html
   

4. 运行指定的测试模块：

   pytest tests/test_config.py
   pytest tests/test_backend.py
   pytest tests/test_protocol.py
   

5. 以监视模式运行测试：

   pytest-watch
   

许可证

MIT