AI导哈

OpenAPI转换MCP工具服务

一个将OpenAPI YAML规范转换为MCP工具使用的服务器，使AI助手能够与OpenAPI描述的REST API交互。

  • by SteffenHebestreit
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 steffenhebestreit/openapi_mcp_server

使用说明

OpenAPI MCP服务器

一个MCP（模型上下文协议）服务器，它导入OpenAPI YAML规范并将端点转换为MCP工具使用。这允许AI助手与OpenAPI规范描述的REST API进行交互。

特性

  • OpenAPI 导入：从本地文件或URL加载OpenAPI规范
  • 自动生成刀具：将API端点转换为MCP工具
  • 请求/响应处理：完全支持HTTP方法、参数和请求体
  • Docker支持：使用Docker容器轻松部署
  • 灵活的配置：环境变量和命令行参数

快速开始

使用Docker（推荐）

  1. 创建环境配置：

    cp .env.example .env
# Edit .env with your API keys and configuration

  2. 使用docker compose构建并运行： 这是最简单的开始方式。它使用中的设置 docker-compose.yml 和 .env.

    docker-compose up --build

    要使用其他规范文件，请编辑 volumes 部分在 docker-compose.yml.

  3. 或者手动构建并运行：

    # Build the Docker image using the Dockerfile in src/
docker build -t openapi-mcp-server -f src/Dockerfile .

# Run with environment file, mounting the template spec
docker run --rm -it --env-file .env -v ./template_openapi.yaml:/app/openapi.yaml openapi-mcp-server

地方发展

  1. 安装依赖项：

    pip install -r src/requirements.txt

  2. 创建环境配置：

    cp .env.example .env
# Edit .env with your API keys and configuration

  3. 运行服务器： 服务器将使用 OPENAPI_SPEC_PATH 或 OPENAPI_SPEC_URL 从你的 .env 文件。

    python -m src.openapi_mcp_server

配置

可以使用以下方式配置服务器：

环境变量

创建一个 .env 项目根目录中的文件（复制自 .env.example):

# OpenAPI specification source (use path or URL)
OPENAPI_SPEC_PATH=./template_openapi.yaml
# OPENAPI_SPEC_URL=https://petstore.swagger.io/v2/swagger.yaml

# Dynamic server configuration (replaces placeholders in OpenAPI spec)
SERVER_URL=https://petstore.swagger.io/v2
SERVER_DESCRIPTION=Pet Store Server

# API Authentication
API_KEY=your-api-key-here
PETSTORE_AUTH=Bearer your-auth-token-here

# Server configuration
LOG_LEVEL=INFO
DEBUG=false

OpenAPI规范占位符

您可以在OpenAPI规范中使用环境变量占位符：

servers:
  - url: ${SERVER_URL}
    description: ${SERVER_DESCRIPTION}

这些占位符将自动替换为您的 .env 服务器加载规范时的文件。

身份验证支持

服务器会自动包含来自环境变量的身份验证标头：

  • API_KEY：添加为 api_key 头球
  • PETSTORE_AUTH：添加为 Authorization 头球

在OpenAPI规范中定义身份验证：

components:
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: apiKey
      name: Authorization
      in: header

security:
  - api_key: []
  - petstore_auth: []

OpenAPI支持

服务器支持OpenAPI 3.0规范，具有以下功能：

支持的操作

  • GET、POST、PUT、DELETE、PATCH方法
  • 路径参数（例如。， /pet/{petId})
  • 查询参数
  • 标头参数
  • 请求正文（JSON）

工具生成

每个API端点都成为一个MCP工具，具有：

  • 名字：基于 operationId 或由方法和路径自动生成
  • 描述：来自 summary 或 description 字段
  • 输入架构：根据参数和请求体模式生成

工具生成示例

给定此OpenAPI端点：

/pet/{petId}:
  get:
    summary: Find pet by ID
    operationId: getPetById
    parameters:
      - name: petId
        in: path
        required: true
        schema:
          type: integer

服务器生成MCP工具：

  • 名字: getpetbyid
  • 描述：“通过ID查找宠物”
  • 输入: {"petId": 123}

OpenAPI文件示例

该存储库包括一个有用的OpenAPI规范示例：

  • template_openapi.yaml：简单的宠物店API用于基本测试

Docker使用

编译选项

# Build using the Dockerfile in the src directory
docker build -t openapi-mcp-server -f src/Dockerfile .

# Build with custom tag
docker build -t my-org/openapi-mcp-server:v1.0 -f src/Dockerfile .

运行时选项

# Mount a local OpenAPI file
# The container expects the file at /app/openapi.yaml
docker run --rm -it --env-file .env -v ./template_openapi.yaml:/app/openapi.yaml openapi-mcp-server

# Use environment variables to fetch a remote spec
docker run --rm -it -e OPENAPI_SPEC_URL=https://api.example.com/openapi.yaml openapi-mcp-server

发展

项目结构

openapi-mcp/
├── src/
│   ├── openapi_mcp_server/
│   │   ├── __init__.py
│   │   ├── __main__.py
│   │   └── server.py          # Main server implementation
│   ├── Dockerfile
│   └── requirements.txt
├── template_openapi.yaml      # Simple pet store example
├── docker-compose.yml
├── .env.example
├── LICENSE
└── README.md

关键组件

  • server.py：主MCP服务器实现

    • OpenAPI规范加载
    • 从API端点生成工具
    • HTTP请求执行
    • 响应格式

  • __main__.py：作为模块运行的入口点

添加功能

要扩展服务器，请执行以下操作：

  1. 自定义身份验证：修改 _execute_api_call 添加身份验证标头
  2. 响应格式：加强响应处理 _execute_api_call
  3. 参数验证：在中添加验证 _generate_input_schema
  4. 错误处理：改进错误消息和恢复

故障排除

常见问题

  1. 未找到OpenAPI文件

    • 确保文件路径正确
    • 检查文件权限
    • 验证Docker卷装载

  2. 网络错误

    • 检查远程URL的互联网连接
    • 验证API服务器的可用性
    • 检查防火墙设置

  3. OpenAPI规范无效

    • 使用在线验证器验证您的OpenAPI文件
    • 确保它遵循OpenAPI 3.0格式
    • 检查YAML中的语法错误

  4. 身份验证问题

    • 验证在.env文件中是否设置了API密钥
    • 检查是否加载了环境变量
    • 确保API密钥名称与OpenAPI安全方案匹配
    • 使用身份验证手动测试API端点

日志记录

服务器提供详细的日志记录。要增加详细程度，请设置 LOG_LEVEL=DEBUG 在你的 .env 文件。

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

许可证

本项目遵循知识共享署名-非商业4.0国际许可协议（CC BY-NC 4.0）。

版权所有（c）2025 Steffen Hebestreit

您可以自由地：

  • 分享 --以任何媒介或格式复制和重新分发材料
  • 适应 --仅出于非商业目的对材料进行混音、转换和构建

根据以下条款：

  • 归因 --您必须给予适当的信用，提供许可证的链接，并注明是否进行了更改
  • 非商业用途 --您不得将该材料用于商业目的

请参阅 许可证 文件以获取完整详细信息或访问 https://creativecommons.org/licenses/by-nc/4.0/

相关 MCP