Drunk MCP Proxy

醉酒mcp代理


文档

• 深度维基

一个强大的、可用于生产的动态代理服务器，用于模型上下文协议（MCP）和LLM API，使用Python和FastMCP构建。此服务使MCP客户端和LLM兼容应用程序能够通过统一、可扩展的接口无缝连接到多个后端MCP服务器和LLM提供商，该接口具有高级功能，包括身份验证、CORS支持和基于环境的配置。

diagram

🎯 概述

drunk mcp代理充当模型上下文协议（mcp）服务和LLM提供者的中央网关，提供：

• 统一接口：多个后端MCP服务器和LLM提供商的单端点
• 动态路由：自动路由到配置的后端服务
• 命名空间隔离：防止工具名称与每服务器命名空间冲突
• OpenAPI集成：OpenAPI规范自动转换为MCP工具
• LLM 代理：具有与OpenAI兼容的终结点的多提供商LLM API网关
• 人类相容性：通过与OpenAI兼容的后端代理人类消息API请求
• WebSocket响应API：本机WebSocket支持OpenAI响应API流
• 企业身份验证：14多个可插拔的身份验证提供者（JWT、OAuth、GitHub、Azure等）
• 生产就绪：健康检查、CORS、结构化日志、Docker支持

✨ 主要特点

• 🚀 动态代理管理：通过YAML配置多个MCP和OpenAPI服务
• 🤖 LLM网关：将请求路由到多个LLM提供商（OpenAI、Ollama、LM Studio等）
• 🔄 人类API兼容性：将Anthropic/Claude客户端与任何OpenAI兼容的后端一起使用
• 🔌 WebSocket响应API：对OpenAI响应API的完全WebSocket支持
• 🐳 Docker支持：带有健康检查的多阶段生产Docker镜像
• 🔐 企业认证：JWT、GitHub、谷歌、Discord、Azure OAuth和自定义身份验证提供商
• 🌐 CORS就绪：用于web客户端集成的完整CORS中间件
• 🎨 OpenAPI支持：自动将OpenAPI规范转换为MCP工具
• 🔍 健康监测：内置健康检查端点
• 📊 结构化日志记录：可配置的日志级别
• 🛡️ JSON模式验证：自动配置验证

🚀 快速开始

使用Docker Hub中的预构建Docker镜像，启动并运行drunk mcp代理。

步骤1：准备配置文件

创建一个 data/ 包含所需配置文件的目录：

mkdir -p data/mcp data/openapi data/skills

data/config.yaml -统一配置

在单个文件中定义身份验证、LLM提供程序和MCP/OpenAPI服务：

# Authentication configuration (optional)
auth:
  defaultProvider: basic
  basic:
    base_url: null
    token: $API_KEY
  jwt:
    base_url: null
    jwks_uri: "https://login.microsoftonline.com/common/discovery/keys"
    issuer: "https://sts.windows.net/$AZURE_TENANT_ID/"
    audience: "api://your-client-id"

# LLM provider configuration (optional)
llm:
  - enabled: true
    websocket: true
    provider: openai
    base_url: "https://api.openai.com/v1"
    api_key: $OPENAI_API_KEY

# MCP and OpenAPI service configuration
mcp:
  - path: /
    spec_type: mcp
    skill_dir: skills
    mcp_servers:
      my-server:
        enabled: true
        command: npx
        args: ["@playwright/mcp@0.0.64"]
        transport: stdio

  - path: /api
    spec_file: openapi/petstore.yaml
    spec_type: openapi
    base_url: "https://api.example.com"

备注: - 承载者身份验证 (defaultProvider: "bearer")是API密钥身份验证的最简单选项，通常由API代理和网关使用。 - 环境变量，如 $API_KEY 或 $AZURE_CLIENT_ID 加载配置时会自动解析。

请参阅 存储库中的示例 更多配置示例。

第二步：准备Docker Compose

创建一个 docker-compose.yml 文件：

services:
  mcp-proxy:
    image: baoduy2412/mcp-proxy:latest
    container_name: mcp-proxy-server
    ports:
      - "${FASTMCP_PORT:-9123}:${FASTMCP_PORT:-9123}"
    volumes:
      - ./data:/drunk-proxy/data
    env_file:
      - .env
    environment:
      - FASTMCP_HOST=0.0.0.0
      - FASTMCP_PORT=${FASTMCP_PORT:-9123}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9123/health"]
      interval: 30s
      timeout: 10s
      retries: 3

备注：The ./data 目录已装载到 /drunk-proxy/data 在容器中。所有配置文件都应放置在此目录中。

步骤3：配置环境并运行

创建一个 .env 示例中的文件：

cp .env.sample .env

编辑 .env 使用您的设置。关键环境变量：

# Server Configuration
FASTMCP_PORT=9123
FASTMCP_LOG_LEVEL=INFO
FASTMCP_AUTH_ENABLED=false

# Bearer Authentication (API Key)
API_KEY=your-api-key-here

# OAuth Storage (required if using OAuth)
FASTMCP_OAUTH_STORAGE_ENCRYPTION_KEY=your-44-character-encryption-key

# Azure Authentication (if using Azure OAuth)
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=your-tenant-id

小贴士：参见 .env.sample 查看可用环境变量的完整列表。

现在启动服务器：

docker-compose up -d

验证它是否正在运行：

curl http://localhost:9123/health

附加服务（可选）

完整的 存储库中包括可选服务：

• MCP检查员 -调试和检查MCP服务器
• OpenWeb用户界面 -LLM交互的Web界面

______________________________________________________________________

🛠️ 本地开发

使用Docker（从源代码构建）

git clone https://github.com/baoduy/drunk-mcp-proxy.git
cd drunk-mcp-proxy

docker build -t drunk-mcp-proxy .
docker run -d -p 9123:9123 -v $(pwd)/data:/drunk-proxy/data drunk-mcp-proxy

本地运行

# Setup environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

# Run the server
python src/main.py

服务器将于启动 http://0.0.0.0:9123 默认情况下。

📖 配置

配置目录结构

data/
├── config.yaml       # Unified configuration (auth, LLM, and MCP/OpenAPI services)
├── mcp/              # MCP server specifications (optional, for external spec files)
│   ├── stock.mcp.json
│   └── wiki.mcp.json
├── openapi/          # OpenAPI specifications
│   └── petstore.yaml
└── skills/           # Skill directories (optional)

配置(config.yaml)

代理使用统一的YAML配置文件来定义身份验证、LLM提供程序和MCP/OpenAPI服务：

# Authentication configuration
auth:
  defaultProvider: basic
  basic:
    token: $API_KEY

# MCP service configuration
mcp:
  - path: /stock
    spec_file: mcp/stock.mcp.json
    spec_type: mcp

  - path: /api
    spec_file: openapi/petstore.yaml
    spec_type: openapi
    base_url: "https://api.example.com"
    filters:
      methods: ["GET", "POST"]
      tags: ["public"]

环境变量

关键环境变量（参见 .env.sample 完整列表）：

看 环境变量 查看完整列表。

📚 文档

• 入门指南

- 安装指南 - 快速入门指南 - 第一步

• 配置

- 配置文件 - 环境变量 - 模式验证

• 特性

- MCP代理管理 - OpenAPI集成 - 认证 - 直通认证

• 建筑

- 系统架构 - 组件概述 - 请求流

• API 参考

- REST API端点 - Python模块

• 部署

- - 生产设置 - 健康检查和监测

• 发展

- 开发指南 - 测试 - 故障排除

有关综合文档，请参阅 文档索引.

🏗️ 架构概述

MCP Client / LLM Client / Anthropic Client
        ↓ (HTTP/SSE/WebSocket + Authorization)
        ↓
┌──────────────────────────────────────────────┐
│  drunk-mcp-proxy Server                      │
│ ┌────────────────────────────────────────┐  │
│ │ Starlette ASGI Application             │  │
│ │ • CORS Middleware                      │  │
│ │ • Auth Validation                      │  │
│ │ • Rate Limiting                        │  │
│ │ • Health Check: /health                │  │
│ │ • Root FastMCP Server (/)              │  │
│ │ • MCP Sub-services:                    │  │
│ │   - /stock (MCP)                       │  │
│ │   - /wiki (MCP)                        │  │
│ │   - /api (OpenAPI)                     │  │
│ │ • LLM Proxy (/api/v1):                │  │
│ │   - POST /chat/completions             │  │
│ │   - POST /messages (Anthropic API)     │  │
│ │   - WS   /responses (WebSocket)        │  │
│ │   - POST /embeddings                   │  │
│ │   - POST /images/generations           │  │
│ │   - POST /audio/transcriptions         │  │
│ │   - POST /audio/translations           │  │
│ │   - GET  /models                       │  │
│ │   - GET  /providers                    │  │
│ └────────────────────────────────────────┘  │
└──────────────────────────────────────────────┘
        ↓ ↓ ↓
   [Backend MCP/OpenAPI/LLM Services]

看 系统架构 查看详细图表。

🔐 认证

drunk mcp代理支持14个以上的身份验证提供程序：

• 基于代用券：承载器（API密钥），JWT
• OAuth 2.0：Azure AD、GitHub、谷歌、Discord、Auth0
• 企业：WorkOS、Scalekit、Descope
• 自定义：通过，反省

承载身份验证（API密钥）

API密钥身份验证的最简单选项，通常由API代理和网关使用：

auth:
  defaultProvider: basic
  basic:
    token: $API_KEY

设置 API_KEY 您的环境变量 .env 文件。

OAuth 2.0身份验证（Azure AD示例）

auth:
  defaultProvider: azure
  azure:
    client_id: $AZURE_CLIENT_ID
    client_secret: $AZURE_CLIENT_SECRET
    tenant_id: $AZURE_TENANT_ID

看 身份验证指南 了解详情。

🧪 测试

# Run all tests
python -m pytest

# Run specific test file
python -m pytest tests/test_server.py

# Run with coverage
python -m pytest --cov=src --cov-report=html

🤖 LLM 代理

配置LLM提供程序后，醉mcp代理在以下位置公开了一个完全兼容OpenAI的LLM网关 /api/v1。所有端点都使用模型ID格式 provider_modelname （例如。， openai_gpt-4o, lms_llama3.2)将请求路由到适当的后端。

LLM提供程序配置

将提供者添加到 llm 部分 config.yaml:

llm:
  - enabled: true
    websocket: true       # Enable for providers that support native WebSocket Responses API
                          # When false, HTTP Responses API is used as fallback
    provider: openai      # Short provider name used as prefix in model IDs
    base_url: "https://api.openai.com/v1"
    api_key: $OPENAI_API_KEY

  - enabled: true
    websocket: false
    provider: lms         # LM Studio
    base_url: "http://host.docker.internal:1234/v1"

  - enabled: false
    provider: oll         # Ollama
    base_url: "http://host.docker.internal:11434/v1"

型号ID格式

所有LLM端点都希望模型ID包含一个由下划线分隔的提供程序前缀：

{provider}_{model_name}

示例：

• openai_gpt-4o → 路线到 openai 供应商，型号 gpt-4o
• lms_llama3.2 → 路线到 lms （LM Studio）提供商，型号 llama3.2
• ort_claude-3-5-sonnet → 路线到 ort （OpenRouter）提供商，型号 claude-3-5-sonnet

可用端点

所有端点都安装在 /api/v1 （可通过以下方式配置 FASTMCP_LLM_ROUTE_PREFIX):

聊天补全

标准OpenAI兼容聊天完成：

curl -X POST http://localhost:9123/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "openai_gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": false
  }'

人类信息API兼容性

这 /messages endpoint接受Anthropic Messages API格式，并透明地转换为OpenAI格式，允许Anthropic/Claude客户端使用任何与OpenAI兼容的后端：

curl -X POST http://localhost:9123/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "lms_llama3.2",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 1024
  }'

支持的转换：

• 系统提示（字符串和块数组）
• 多模式内容（文本、base64图像、URL图像）
• 工具使用和工具结果
• 以Anthropic格式流式传输SSE事件
• stop_sequences → stop, metadata.user_id → user，完成原因映射

与Claude Code CLI一起使用

将Claude Code CLI指向代理，以使用具有Anthropic兼容端点的任何后端模型：

export ANTHROPIC_BASE_URL=http://localhost:9123/api/v1
export ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY_HERE
claude --model lms_llama3.2

WebSocket响应API

这 /responses WebSocket端点提供OpenAI响应API流。客户端通过WebSocket连接，并使用OpenAI Responses API协议交换JSON消息。

连接URL: ws://localhost:9123/api/v1/responses

消息流：

1. 客户端连接到 Authorization: Bearer 头球
2. 客户端发送 response.create 活动与 model: "provider_modelname"
3. 代理将路由到配置的后端，并将响应事件流式传输回来
4. 对于具有以下条件的提供商 websocket: true，原生WebSocket用于最低延迟
5. 对于其他提供程序，使用HTTP响应API作为回退

const ws = new WebSocket("ws://localhost:9123/api/v1/responses", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});

ws.send(JSON.stringify({
  type: "response.create",
  response: {
    model: "openai_gpt-4o",
    instructions: "You are a helpful assistant.",
    input: [{ type: "message", role: "user", content: "Hello!" }]
  }
}));

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.type, data);  // response.created, response.output_text.delta, response.done, etc.
};

提供程序WebSocket支持： 集 websocket: true 在本机支持的提供者的提供者配置中 /responses WebSocket端点（例如OpenAI）。对于所有其他提供程序，使用HTTP响应API作为回退。

注： 这 previous_response_id 仅支持具有本机WebSocket的提供程序的延续功能(websocket: true).将其与HTTP回退提供程序一起使用会返回错误。

列出型号和供应商

# List all models across all configured providers
curl http://localhost:9123/api/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by provider
curl "http://localhost:9123/api/v1/models?provider=openai" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List configured providers
curl http://localhost:9123/api/v1/providers \
  -H "Authorization: Bearer YOUR_API_KEY"

🤝 贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

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

🙏 致谢

• 内置于 FastMCP 框架
• 由...驱动 斯塔雷特 ASGI框架
• 通过FastMCP的可插拔身份验证系统进行身份验证

📞 支持

• 📖 文档
• 🐛 问题追踪器
• 💬 讨论

______________________________________________________________________

备注：有关详细的技术文档、API参考资料和高级配置，请参阅 全面的文件.