yonglelaoren-openapi-mcp 0.4.0

OpenAPI MCP Server - 基于 Model Context Protocol 的 OpenAPI 规范解析服务器

OpenAPI MCP Server

基于 Model Context Protocol 的 OpenAPI 规范解析服务器。

功能特性

• 解析 OpenAPI 3.0 规范（支持本地文件和远程 URL）
• 列出规范中的所有接口
• 获取接口的详细信息（参数、请求体、响应等）
• 自动展开 $ref 引用
• 支持循环引用处理
• 支持深层嵌套结构解析
• 可选的 server URL 拼接功能

安装

使用 uvx：

uvx yonglelaoren-openapi-mcp

或使用 pip：

pip install yonglelaoren-openapi-mcp

MCP 工具

list_endpoints

列出 OpenAPI 规范中的所有接口。

参数：

• spec_source: OpenAPI 规范来源（文件路径或 URL）

返回：

• 接口列表，包含路径、方法、摘要和描述

get_endpoint_details

获取指定接口的详细信息，包括参数、请求体、响应等，所有 $ref 引用已展开为具体字段结构。

参数：

• spec_source: OpenAPI 规范来源（文件路径或 URL）
• path: 接口路径（例如：/users/{id}）
• method: HTTP 方法（GET, POST, PUT, DELETE 等）

返回：

• 接口详细信息，包含参数、请求体、响应、解析后的 schemas 等

环境变量

INCLUDE_SERVER_URL

控制是否在返回的接口路径中包含 server URL 前缀。

默认值： false

作用：

• 当设置为 true 时，如果 OpenAPI 规范中定义了 servers 字段，返回的接口路径会包含第一个 server 的 URL 前缀
• 当设置为 false 或未设置时，返回原始的接口路径

支持的值（启用）：

• true
• True
• 1
• yes

支持的值（禁用）：

• false
• False
• 0
• no

示例：

假设 OpenAPI 规范中定义：

servers:
  - url: /video-service

paths:
  /mvc/test/hello:
    get:
      summary: 测试接口

• 默认行为（INCLUDE_SERVER_URL=false）：

  {
    "path": "/mvc/test/hello"
  }
  

• 启用 server URL（INCLUDE_SERVER_URL=true）：

  {
    "path": "/video-service/mvc/test/hello"
  }
  

使用场景： 在微服务架构中，不同的服务可能有不同的 URL 前缀。启用此功能可以在返回的接口路径中自动包含服务前缀，便于区分不同服务的接口地址。

配置示例

在 Claude Desktop 中配置

编辑 Claude Desktop 的配置文件（通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "openapi-extraction": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/openapi-mcp",
        "yonglelaoren-openapi-mcp"
      ],
      "env": {
        "INCLUDE_SERVER_URL": "true"
      }
    }
  }
}

使用 uvx

uvx -e INCLUDE_SERVER_URL=true yonglelaoren-openapi-mcp

使用环境变量

export INCLUDE_SERVER_URL=true
uvx yonglelaoren-openapi-mcp

不启用 server URL（默认行为）

uvx yonglelaoren-openapi-mcp

或显式禁用：

uvx -e INCLUDE_SERVER_URL=false yonglelaoren-openapi-mcp

开发

安装依赖

uv sync

运行测试

# 运行所有测试
uv run pytest

# 运行测试并查看覆盖率
uv run pytest --cov

# 运行特定测试文件
uv run pytest tests/test_parsers/test_openapi_parser.py

代码质量检查

# 代码格式化
uv run ruff format src/

# 代码检查
uv run ruff check src/

# 类型检查
uv run mypy src/

构建

uv build

技术栈

• Python 3.11+
• MCP/FastMCP - Model Context Protocol 框架
• Prance - OpenAPI 规范解析器
• Pydantic - 数据验证
• httpx - HTTP 客户端

许可证

MIT License

作者

yongle [e-mail]

版本历史

• 0.4.0 - 新增 server URL 拼接功能（INCLUDE_SERVER_URL 环境变量）
• 0.3.0 - 修复循环引用处理和 schema 递归解析
• 0.2.1 - 新增循环引用处理和 schema 递归解析功能
• 0.2.0 - 初始版本