使用说明

自动化代码代理工作流测试/不打算表示一个完整的功能仓库（但如果它这样做，那将非常酷ദ്ദി・ᴗ・)✧ )

MCP工具包

生产准备就绪 用于管理容器化模型上下文协议（MCP）服务器的Python CLI工具包。该系统使大型语言模型（LLM）能够通过可扩展的容器化基础设施与外部工具和服务安全地交互。

🎯 什么是MCP工具包？

MCP ToolKit是一个全面的基础设施解决方案，通过 **模型上下文协议（MCP）**它提供：

🐳 容器管理：将MCP服务器部署和管理为具有资源控制的隔离Docker容器
🛡️ 企业安全：内置敏感数据过滤和运行时安全控制
🌐 网关代理：为多个MCP服务器提供集中JSON-RPC路由和请求过滤
🔧 客户端集成：用于Claude Desktop、Cursor IDE和其他LLM客户端的预构建配置模板
📊 生产特点：健康监测、全面日志记录和错误处理

🏗️ 系统架构

┌─────────────────────────┐    ┌─────────────────────────┐    ┌─────────────────────────┐
│      LLM Clients        │    │     MCP Gateway         │    │     MCP Servers         │
│   Claude Desktop        │    │      (Proxy)            │    │    (Docker Containers)  │
│   Cursor IDE            │◄───┤   JSON-RPC Router       ├───►│   • Echo Server         │
│   Custom Clients        │    │   Security Filter       │    │   • GitHub API Server   │
│                         │    │   Request Validation    │    │   • Custom Servers      │
└─────────────────────────┘    └─────────────────────────┘    └─────────────────────────┘
                                           │
                                ┌─────────────────────────┐
                                │    Docker Manager       │
                                │   • Container Lifecycle │
                                │   • Resource Controls   │
                                │   • Health Monitoring   │
                                └─────────────────────────┘

🔄 请求流可视化

下图显示了请求如何从LLM客户端通过网关流向容器化的MCP服务器：

flowchart TD
    A[LLM Client<br/>Claude Desktop/Cursor] --> B[JSON-RPC Request<br/>POST /mcp/server-name]
    B --> C{MCP Gateway<br/>:8000}
    C --> D[Security Filter<br/>Sensitive Data Detection]
    D --> E[Request Validation<br/>JSON-RPC 2.0 Format]
    E --> F[Server Router<br/>Route by Method/Name]
    F --> G[Echo Server<br/>Container :8081]
    F --> H[GitHub API Server<br/>Container :8082]
    F --> I[Custom Server<br/>Container :8083]
    G --> J[JSON-RPC Response]
    H --> J
    I --> J
    J --> K[Response Filter<br/>Remove Sensitive Data]
    K --> L[JSON-RPC 2.0<br/>Formatted Response]
    L --> A

    style C fill:#e1f5fe
    style D fill:#f3e5f5
    style E fill:#f3e5f5
    style F fill:#e8f5e8
    style G fill:#fff3e0
    style H fill:#fff3e0
    style I fill:#fff3e0
    style K fill:#f3e5f5

流程步骤：

客户端请求：LLM向网关端点发送JSON-RPC请求
安全层：针对敏感数据筛选的传入请求（API密钥、令牌）
验证：JSON-RPC 2.0格式和方法验证
路由：请求被路由到适当的MCP服务器容器
处理：服务器执行方法并返回结果
响应筛选器：出于安全考虑过滤了传出的响应
客户端响应：已格式化的JSON-RPC响应返回给客户端

🚀 快速开始

先决条件

Python 3.8+ 使用pip
Docker引擎 （桌面或CLI）
Git 用于存储库管理

安装

# Clone the repository
git clone <repository-url>
cd mcp-toolkit

# Install in development mode
pip install -e .[dev]

# Or install from PyPI (when available)
pip install mcp-toolkit

基本工作流程

启动网关代理:
```
mcp-toolkit gateway --port 8000
```

构建并添加MCP服务器:

# Build the echo server example
cd examples/servers/echo
docker build -t mcp-echo:latest .
cd ../../..

# Add the server to your toolkit
mcp-toolkit add echo-demo --image mcp-echo:latest --port 8081

验证服务器是否正在运行:

mcp-toolkit list
# Expected output:
# NAME       STATUS   PORT  IMAGE           CREATED
# echo-demo  running  8081  mcp-echo:latest 2 minutes ago

生成LLM客户端配置:

# For Claude Desktop
mcp-toolkit config claude --output ~/.config/claude/claude_desktop_config.json

# For Cursor IDE
mcp-toolkit config cursor --output ~/.cursor/settings.json

测试系统:

# Test gateway health
curl http://localhost:8000/health

# Send JSON-RPC request through gateway
curl -X POST http://localhost:8000/mcp/echo-demo \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"echo","params":{"message":"Hello MCP!"},"id":1}'

📋 命令参考

服务器管理

命令	描述	示例
`add <name>`	添加并启动新的MCP服务器	`mcp add github --image mcp-github:latest --port 8082`
`list`	列出所有正在运行的MCP服务器	`mcp list`
`stop <name>`	停止正在运行的MCP服务器	`mcp stop github`
`remove <name>`	删除MCP服务器容器	`mcp remove github`

网关操作

命令	描述	示例
`gateway`	启动MCP网关代理服务器	`mcp gateway --port 8000 --host 0.0.0.0`

配置生成

命令	描述	示例
`config claude`	生成Claude桌面配置	`mcp config claude --output config.json`
`config cursor`	生成游标IDE配置	`mcp config cursor --output settings.json`

🔄 CLI工作流可视化

下图显示了服务器生命周期管理工作流：

flowchart TD
    subgraph "CLI Commands"
        A[mcp-toolkit add<br/>server-name]
        B[mcp-toolkit list]
        C[mcp-toolkit stop<br/>server-name]
        D[mcp-toolkit remove<br/>server-name]
        E[mcp-toolkit gateway]
        F[mcp-toolkit config<br/>client-type]
    end
    
    subgraph "Docker Operations"
        G[Pull/Build Image]
        H[Create Container<br/>with Security Config]
        I[Start Container<br/>Health Check]
        J[List Containers<br/>with mcp- prefix]
        K[Stop Container<br/>Graceful Shutdown]
        L[Remove Container<br/>and Resources]
    end
    
    subgraph "Server States"
        M[Image Available<br/>Repository/Local]
        N[Container Created<br/>Not Started]
        O[Container Running<br/>Health: Healthy]
        P[Container Stopped<br/>Exit Code: 0]
        Q[Container Removed<br/>Resources Cleaned]
    end
    
    A --> G --> H --> I
    I --> M --> N --> O
    
    B --> J --> O
    
    C --> K --> P
    
    D --> L --> Q
    
    E --> R[Start Flask App<br/>Port 8000]
    R --> S[Register Routes<br/>/health, /servers, /mcp/*]
    
    F --> T[Scan Running Containers]
    T --> U[Generate JSON Config]
    
    style A fill:#e3f2fd
    style B fill:#e3f2fd
    style C fill:#e3f2fd
    style D fill:#e3f2fd
    style E fill:#e3f2fd
    style F fill:#e3f2fd
    style O fill:#e8f5e8

服务器生命周期：

📦 添加：拉取图像→ 创建容器→ 从健康检查开始
📋 列表：查询Docker API→ 过滤MCP容器→ 显示状态
⏹️ 停止：优雅的关机→ 容器停止状态
🗑️ 移除：运行时停止→ 删除容器和资源

高级选项

# Add server with custom resource limits
mcp add heavy-server --image custom:latest --port 8083 --memory 4g --cpus 2

# Start gateway with debug logging
mcp-toolkit --debug gateway --port 8000

# List servers with detailed information
mcp list --format detailed

🛡️ 安全功能

数据保护

敏感数据过滤：自动检测和筛选API密钥、令牌、密码和凭据
请求消毒：验证JSON-RPC格式并清理方法名
响应滤波：确保通过响应不会泄露敏感信息

集装箱安全

资源限制：默认2GB内存和每个容器1个CPU核（可配置）
安全选项: no-new-privileges 旗帜和投掷能力
网络隔离：受控的港口映射和集装箱网络访问
非根执行：容器以最低权限运行

运行时控件

输入验证：对所有端点进行全面的参数验证
错误处理：无信息披露的结构化错误响应
审计日志：记录的安全事件没有敏感数据

🔒 安全模型可视化

下图说明了多层安全架构：

flowchart TB
    subgraph "Host Environment"
        A[MCP Gateway Process<br/>Port 8000]
        B[Docker Manager<br/>Container Control]
    end
    
    subgraph "Security Layers"
        C[Request Filter<br/>API Keys, Tokens<br/>Passwords, URLs]
        D[Response Filter<br/>Sensitive Data<br/>Error Information]
        E[Method Validation<br/>JSON-RPC 2.0<br/>Schema Validation]
    end
    
    subgraph "Container Isolation"
        direction TB
        F[Resource Limits<br/>Memory: 2GB<br/>CPU: 1 Core]
        G[Security Options<br/>--no-new-privileges<br/>--cap-drop=ALL]
        H[Network Isolation<br/>Specific Port Mapping<br/>No Host Network]
        I[Non-Root User<br/>UID: 1000<br/>Minimal Permissions]
    end
    
    subgraph "Container 1: Echo Server"
        J[MCP Server Process<br/>Port 8080 Internal]
        K[Health Endpoint<br/>/health]
    end
    
    subgraph "Container 2: GitHub API"
        L[GitHub MCP Server<br/>Port 8080 Internal]
        M[Token Management<br/>Environment Only]
    end
    
    A --> C
    C --> E
    E --> D
    D --> A
    
    B --> F
    B --> G
    B --> H
    B --> I
    
    F --> J
    G --> J
    H --> J
    I --> J
    
    F --> L
    G --> L
    H --> L
    I --> L
    
    style C fill:#ffebee
    style D fill:#ffebee
    style E fill:#ffebee
    style F fill:#e8f5e8
    style G fill:#e8f5e8
    style H fill:#e8f5e8
    style I fill:#e8f5e8
    style J fill:#fff3e0
    style L fill:#fff3e0

安全层：

🔍 数据筛选：基于Regex的API密钥、令牌、密码检测
✅ 架构验证：根据规范验证所有JSON-RPC请求
🐳 集装箱隔离：资源限制、特权删除、网络分段
👤 用户安全：非root执行，文件系统访问权限最小

🔧 用例和示例

1.LLMs的GitHub集成

# Set up GitHub API server
cd examples/servers/github-api
docker build -t mcp-github:latest .
mcp-toolkit add github --image mcp-github:latest --port 8082

# Configure with authentication
docker run -d --name mcp-github \
  -p 8082:8080 \
  -e GITHUB_TOKEN=your_token_here \
  mcp-github:latest

可用GitHub操作：

存储库信息和文件访问
问题创建和管理
拉取请求列表和分析
具有速率限制的安全身份验证

2.自定义工具集成

# Create your custom MCP server
mkdir my-custom-server
cd my-custom-server

# Use the echo server as a template
cp -r ../examples/servers/echo/* .
# Modify server.py to implement your tools

# Build and deploy
docker build -t mcp-custom:latest .
mcp-toolkit add custom --image mcp-custom:latest --port 8083

3.多服务器环境

# Deploy multiple specialized servers
mcp-toolkit add database --image mcp-postgres:latest --port 8084
mcp-toolkit add analytics --image mcp-analytics:latest --port 8085
mcp-toolkit add notifications --image mcp-slack:latest --port 8086

# Single gateway routes to all servers
mcp-toolkit gateway --port 8000

# Generate unified client configuration
mcp-toolkit config claude --output multi_server_config.json

🧪 开发与测试

开发设置

# Install development dependencies
make dev-setup

# Run code formatting
make format

# Run linting and type checking
make lint

# Run security scanning
make security

测试

# Run all tests
make test

# Run tests with coverage report
make test-cov

# Run specific test categories
pytest tests/test_security.py -v           # Security tests
pytest -m "integration" -v                 # Integration tests
pytest -k "test_docker" -v                 # Docker-related tests

代码质量标准

类型提示：所有代码都包含全面的类型注释
代码格式化：黑色和异色，风格一致
安全扫描：Bandit用于安全分析
测试覆盖率：核心模块的覆盖率目标>80%

📁 项目结构

mcp_toolkit/
├── cli.py                    # Click-based command interface
├── gateway.py               # Flask proxy server with JSON-RPC routing
├── docker_manager.py        # Container lifecycle management
├── security.py             # Data filtering and security controls
├── utils.py                 # Logging, validation, error handling
└── config_templates/        # Client configuration templates

examples/servers/
├── echo/                   # Simple echo server for testing
│   ├── server.py          # 4 JSON-RPC methods (echo, uppercase, reverse, info)
│   ├── Dockerfile         # Multi-stage build with security hardening
│   └── README.md          # Complete usage documentation
└── github-api/            # GitHub API integration server
    ├── server.py          # 6 GitHub methods (repos, files, issues, PRs)
    ├── Dockerfile         # Secure container with token management
    └── README.md          # Authentication and API documentation

tests/                     # Comprehensive test suite (67% coverage)
├── test_cli.py           # CLI command testing
├── test_gateway.py       # Gateway proxy testing
├── test_docker_manager.py # Container management testing
├── test_security.py      # Security filtering testing
└── test_utils.py         # Utility function testing

🔄 生产部署

🏗️ 部署架构

下图显示了从开发到生产的不同部署场景：

flowchart TD
    subgraph "Development Environment"
        A[Developer Machine<br/>Windows/Linux/macOS]
        B[Docker Desktop<br/>Container Runtime]
        C[MCP ToolKit CLI<br/>mcp-toolkit]
    end
    
    subgraph "Container Registry"
        D[Docker Hub<br/>or Private Registry]
        E[mcp-echo:latest<br/>Echo Server Image]
        F[mcp-github:latest<br/>GitHub API Image]
        G[Custom Images<br/>User-built Servers]
    end
    
    subgraph "Production Deployment Options"
        subgraph "Single Server"
            L[Production Host<br/>Linux Server]
            M[Docker Engine<br/>Container Runtime]
            N[MCP Gateway<br/>:8000]
            O[Load Balancer<br/>nginx/traefik]
        end
        
        subgraph "Docker Compose"
            P[docker-compose.yml<br/>Multi-container Setup]
            Q[Gateway Service<br/>Port 8000]
            R[MCP Services<br/>Ports 8081-8090]
        end
        
        subgraph "Kubernetes (Roadmap)"
            T[K8s Cluster<br/>Container Orchestration]
            U[Gateway Deployment<br/>Service + Ingress]
            V[MCP Server Pods<br/>Auto-scaling]
        end
    end
    
    subgraph "Client Integration"
        X[Claude Desktop<br/>claude_desktop_config.json]
        Y[Cursor IDE<br/>cursor_settings.json]
        Z[Custom LLM Clients<br/>JSON-RPC Compatible]
    end
    
    A --> C --> B
    D --> E & F & G
    
    C --> L --> M --> N --> O
    C --> P --> Q & R
    C --> T --> U --> V
    
    N --> X & Y & Z
    Q --> X & Y & Z
    U --> X & Y & Z
    
    style A fill:#e3f2fd
    style L fill:#e8f5e8
    style P fill:#fff3e0
    style T fill:#f3e5f5
    style N fill:#ffebee
    style Q fill:#ffebee
    style U fill:#ffebee

部署选项：

💻 发展：具有CLI管理的本地Docker桌面
🖥️ 单服务器：带反向代理的生产Linux服务器
🐳 Docker Compose：具有依赖关系的多容器编排
☸️ 库贝内特斯：具有自动扩展功能的容器编排（路线图）

Docker编写示例

version: '3.8'
services:
  mcp-gateway:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - LOG_LEVEL=INFO
      - GATEWAY_PORT=8000

  mcp-echo:
    build: ./examples/servers/echo
    ports:
      - "8081:8080"
    environment:
      - LOG_LEVEL=INFO

  mcp-github:
    build: ./examples/servers/github-api
    ports:
      - "8082:8080"
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
      - LOG_LEVEL=INFO

健康监测

# Gateway health
curl http://localhost:8000/health

# Individual server health
curl http://localhost:8081/health

# Server list through gateway
curl http://localhost:8000/servers

🤝 贡献

我们欢迎捐款！请按照以下步骤操作：

分叉存储库
创建要素分支: git checkout -b feature/amazing-feature
进行更改 遵循我们的规范标准
运行测试套件: make ci
提交您的更改: git commit -m 'Add amazing feature'
推到分支: git push origin feature/amazing-feature
打开拉取请求

开发指南

遵循现有的代码模式和架构
添加新功能的测试
更新面向用户的更改文档
确保所有CI检查通过
所有变更的安全第一方法

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🆘 支持与社区

🐛 错误报告: GitHub问题
💡 功能请求: GitHub讨论
📖 文档: 全部文件
💬 社区: Discord服务器

🗺️ 路线图

v0.2.0版本：基于Web的管理界面
v0.3.0：Kubernetes部署支持
v0.4.0：内置服务器市场
v1.0.0：企业功能和SLA支持

📊 可视化文档

有关详细的技术图表和可视化，请参阅我们的综合文档：

系统流程图 -完整的请求路由可视化
安全模型图 -多层安全架构
部署架构 -生产部署场景
CLI工作流图 -服务器生命周期管理
JSON-RPC协议流 -协议示例和错误处理

🔄 JSON-RPC协议示例

成功的请求流

// Request to Echo Server
POST /mcp/echo-server
{
  "jsonrpc": "2.0",
  "method": "echo",
  "params": {"message": "Hello MCP!"},
  "id": 1
}

// Filtered Response
{
  "jsonrpc": "2.0", 
  "id": 1,
  "result": {
    "echo": {"message": "Hello MCP!"},
    "timestamp": "2024-01-01T12:00:00Z"
  }
}

安全过滤示例

// Original Request (with sensitive data)
{
  "jsonrpc": "2.0",
  "method": "github_create_issue", 
  "params": {
    "title": "Bug Report",
    "api_key": "ghp_abcdef123456"
  },
  "id": 1
}

// Filtered Request (sent to server)
{
  "jsonrpc": "2.0",
  "method": "github_create_issue",
  "params": {
    "title": "Bug Report", 
    "api_key": "[FILTERED]"
  },
  "id": 1
}