mcp4openapi/mcp4openapi

从OpenAPI3.x规范生成的通用MCP服务器

镜像概述

该镜像运行mcp4openapi服务器，接收OpenAPI3.x规范文件（YAML/JSON格式）和MCP配置文件，将规范中定义的API操作暴露为MCP工具（及可选的复合工作流）。它支持两种运行模式：stdio（MCP原生）和HTTP服务器，同时提供OAuth、多认证方式、限流HTTP传输、指标监控和结构化日志等功能。

核心功能

• 兼容任意OpenAPI3.x规范：支持YAML/JSON格式，启动时自动验证规范有效性。
• 配置与工具化：通过MCP配置文件选择、分组和重命名API操作，生成有意义的工具（对不规范命名给出警告）。
• 复合操作：定义DAG/复合工作流，支持按顺序或并行调用多个API操作。
• 多传输方式：支持stdio（MCP原生）和HTTP服务器模式，且HTTP模式支持流传输。
• 认证与安全：提供令牌认证、OAuth流程、多认证配置、来源白名单及可选的令牌验证辅助功能。
• 可观测性：支持结构化日志、可选Prometheus指标端点和基础健康检查端点。
• 开箱即用：基于TypeScript开发，经过全面测试，内置配置/schema验证器和OpenAPI解析器。

使用场景

• 希望从OpenAPI规范快速生成MCP工具，而非手动编写MCP服务器的开发者。
• 管理多个API和用户配置（管理员/开发者/只读），需要统一MCP网关的团队。
• LLM/Agent集成场景中，需要提供经过筛选、配置化的工具集，而非暴露数百个原始API操作的用户。

快速开始

拉取镜像

bash
docker pull docker.xuanyuan.run/mcp4openapi/mcp4openapi

创建配置文件

创建.env文件（或使用环境变量），至少包含以下内容：

bash
# 必填项
OPENAPI_SPEC_PATH=/data/openapi.yaml
MCP_PROFILE_PATH=/data/profile.json

# 认证示例（可选，取决于配置文件）
API_TOKEN=your_secret_token

# 传输方式：'stdio' 或 'http'
MCP_TRANSPORT=http
MCP_PORT=3003

# HTTP模式下的CORS/来源限制
ALLOWED_ORIGINS=*

# 日志与指标
LOG_LEVEL=info
METRICS_ENABLED=false

运行容器（HTTP模式示例）

bash
docker run \
  --rm \
  -p 3003:3003 \
  --env-file .env \
  -v /绝对路径/到/配置目录:/data \
  docker.xuanyuan.run/mcp4openapi/mcp4openapi

健康检查

bash
curl http://localhost:3003/health

stdio模式使用

若需作为MCP stdio服务器运行，设置MCP_TRANSPORT=stdio，并配置兼容MCP的客户端通过stdio与容器交互。

配置与使用注意事项

• OPENAPI_SPEC_PATH：容器内OpenAPI3.x文件的路径，需通过-v挂载本地文件到容器。
• MCP_PROFILE_PATH：描述需暴露的操作和复合工作流的MCP配置JSON文件路径（参考仓库中的profiles/目录及文档）。
• HTTP模式下，服务器暴露HTTP端点（包括健康检查，若启用则暴露Prometheus格式的/metrics端点）。
• stdio模式下，作为标准MCP服务器供本地工具/Agent使用。
• 生产环境建议：在代理层配置HTTPS/TLS，限制ALLOWED_ORIGINS，根据配置文件设置强认证机制。

许可证与源码

该镜像基于MIT许可证发布。完整文档、示例配置文件和环境变量选项可在GitHub仓库查看：
https://github.com/davidruzicka/mcp4openapi