STARWARCLOUD STARWAR.AI
返回市场
开放API-MCP

开放API-MCP

作者：jedisct177 星标更新：2025-06-13
安装使用来源：spider==github.com

项目介绍

<img src="https://raw.githubusercontent.com/jedisct1/openapi-mcp/main/.github/banner.png" alt="openapi-mcp" width="600"/>

openapi-mcp

将任何 OpenAPI 3.x API 快速转换为强大的、适合代理使用的 MCP 工具服务器！

Go 版本 构建状态 许可证 GoDoc

openapi-mcp 将任何 OpenAPI 3.x 规范转换为强大的、适合 AI 使用的 MCP（模型上下文协议）工具服务器。在几秒钟内，它会验证您的 OpenAPI 规范，为每个操作生成 MCP 工具，并通过标准 I/O 或 HTTP 提供服务，具有结构化且机器可读的输出。

📋 目录

✨ 功能

  • 即时 API 到 MCP 转换：解析任何 OpenAPI 3.x YAML/JSON 规范并生成 MCP 工具
  • 多种传输选项：支持标准 I/O（默认）和 HTTP 服务器模式
  • 完整的参数支持：路径、查询、头部、Cookie 和正文参数
  • 认证：API 密钥、Bearer 令牌、基本认证和 OAuth2 支持
  • 结构化输出：所有响应都有统一、结构良好的格式，带有类型信息
  • 验证及检查：全面的 OpenAPI 验证和检查，提供可操作的建议
    • validate 命令用于关键问题（缺少 operationIds、模式错误）
    • lint 命令用于最佳实践（摘要、描述、标签、参数建议）
  • 安全特性：危险操作（PUT/POST/DELETE）需要确认
  • 文档：内置的 Markdown 或 HTML 文档生成
  • AI 优化：独特的功能专门设计以增强 AI 代理交互：
    • 使用 OutputFormat 和 OutputType 的一致输出结构，便于可靠解析
    • 丰富的机器可读模式信息，包括约束和示例
    • 精简、适合代理的响应格式，最小冗余
    • 智能错误消息，带有纠正建议
    • 自动处理认证、分页和复杂数据结构
  • 交互式客户端：包含一个带有 readline 支持和命令历史的 MCP 客户端
  • 灵活配置：环境变量或命令行标志
  • CI/测试支持：摘要选项、退出代码和预览模式

🤖 AI 代理集成

openapi-mcp 设计用于无缝集成到 AI 编码代理、LLMs 和自动化工具中，其独特功能使其区别于其他 API 到工具转换器：

  • 结构化的 JSON 响应：每个响应都包含 OutputFormat 和 OutputType 字段，以便一致解析
  • 丰富的模式信息：所有工具都提供了详细的参数约束和示例，帮助 AI 代理理解 API 要求
  • 可操作的错误消息：验证错误包括详细信息和建议，引导代理正确使用
  • 安全确认：标准化的确认工作流程防止意外后果
  • 自描述 API：describe 工具提供所有操作的完整、机器可读文档
  • 最小冗余：没有冗余警告或消息混淆代理——输出已针对机器消费进行了优化
  • 智能参数处理：自动转换 OpenAPI 参数类型和 MCP 工具参数
  • 情境示例：每个工具都基于 OpenAPI 规范包含情境感知示例
  • 智能默认值：尽可能提供合理的默认值以简化 API 使用

🔧 安装

先决条件

  • Go 1.21+
  • OpenAPI 3.x YAML 或 JSON 规范文件

从源码构建

# 克隆仓库
git clone <repo-url>
cd openapi-mcp

# 构建二进制文件
make

# 这将创建：
# - bin/openapi-mcp (主工具)
# - bin/mcp-client (交互式客户端)

⚡ 快速开始

1. 运行 MCP 服务器

# 基本使用（标准 I/O 模式）
bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# 使用 API 密钥
API_KEY=your_api_key bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# 作为 HTTP 服务器
bin/openapi-mcp --http=:8080 examples/fastly-openapi-mcp.yaml

# 覆盖基础 URL
bin/openapi-mcp --base-url=https://api.example.com examples/fastly-openapi-mcp.yaml

2. 使用交互式客户端

# 启动客户端（通过标准 I/O 连接到 openapi-mcp）
bin/mcp-client bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# 客户端命令
mcp> list                              # 列出可用工具
mcp> schema <tool-name>                # 显示工具模式
mcp> call <tool-name> {arg1: value1}   # 使用参数调用工具
mcp> describe                          # 获取完整 API 文档

🔒 认证

openapi-mcp 支持通过命令行标志、环境变量或 HTTP 头的所有标准 OpenAPI 认证方法：

命令行标志 & 环境变量

# API 密钥认证
bin/openapi-mcp --api-key=your_api_key examples/fastly-openapi-mcp.yaml
# 或使用环境变量
API_KEY=your_api_key bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# Bearer 令牌 / OAuth2
bin/openapi-mcp --bearer-token=your_token examples/fastly-openapi-mcp.yaml
# 或使用环境变量
BEARER_TOKEN=your_token bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# 基本认证
bin/openapi-mcp --basic-auth=username:password examples/fastly-openapi-mcp.yaml
# 或使用环境变量
BASIC_AUTH=username:password bin/openapi-mcp examples/fastly-openapi-mcp.yaml

HTTP 头认证（仅限 HTTP 模式）

当使用 HTTP 模式（--http=:8080）时，您可以通过 HTTP 请求中的头提供认证：

# 通过头传递 API 密钥
curl -H "X-API-Key: your_api_key" http://localhost:8080/mcp -d '...'
curl -H "Api-Key: your_api_key" http://localhost:8080/mcp -d '...'

# Bearer 令牌
curl -H "Authorization: Bearer your_token" http://localhost:8080/mcp -d '...'

# 基本认证
curl -H "Authorization: Basic base64_credentials" http://localhost:8080/mcp -d '...'

支持的认证头：

  • X-API-Key 或 Api-Key - 用于 API 密钥认证
  • Authorization: Bearer <token> - 用于 OAuth2/Bearer 令牌认证
  • Authorization: Basic <credentials> - 用于基本认证

认证会自动应用于您 OpenAPI 规范中定义的适当端点。HTTP 头认证在整个请求期间优先于环境变量。

当使用 HTTP 模式时，openapi-mcp 默认提供一个基于 StreamableHTTP 的 MCP 服务器。对于正在构建 HTTP 客户端的开发者，该包提供了方便的 URL 辅助函数：

import "github.com/jedisct1/openapi-mcp/pkg/openapi2mcp"

// 获取 Streamable HTTP 端点 URL
streamableURL := openapi2mcp.GetStreamableHTTPURL(":8080", "/mcp")
// 返回： "http://localhost:8080/mcp"

// 对于 SSE 模式（当使用 --http-transport=sse 时），您可以使用：
sseURL := openapi2mcp.GetSSEURL(":8080", "/mcp")
// 返回： "http://localhost:8080/mcp/sse"

messageURL := openapi2mcp.GetMessageURL(":8080", "/mcp", sessionID)
// 返回： "http://localhost:8080/mcp/message?sessionId=<sessionID>"

StreamableHTTP 客户端连接流程：

  1. 发送 POST 请求到 Streamable HTTP 端点进行请求/通知
  2. 发送 GET 请求到同一端点监听通知
  3. 发送 DELETE 请求终止会话

示例使用 curl：

# 第一步：初始化会话
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26"}}'

# 响应将包含 Mcp-Session-Id 头

# 第二步：发送 JSON-RPC 请求
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 第三步：监听通知
curl -N http://localhost:8080/mcp \
  -H "Mcp-Session-Id: <session-id>"

SSE 客户端连接流程（当使用 --http-transport=sse 时）：

  1. 连接到 SSE 端点建立持久连接
  2. 接收一个包含会话 ID 的 endpoint 事件
  3. 使用会话 ID 向消息端点发送 JSON-RPC 请求
  4. 通过 SSE 流接收响应和通知

示例使用 curl（SSE 模式）：

# 第一步：连接到 SSE 端点（保持连接打开）
curl -N http://localhost:8080/mcp/sse

# 输出：event: endpoint
#       data: /mcp/message?sessionId=<session-id>

# 第二步：发送 JSON-RPC 请求（在另一个终端）
curl -X POST http://localhost:8080/mcp/message?sessionId=<session-id> \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

🛠️ 使用示例

与 AI 代码编辑器集成

您可以轻松地将 openapi-mcp 与支持 MCP 工具的 AI 代码编辑器集成，例如 Roo Code：

{
    "fastly": {
        "command": "/opt/bin/openapi-mcp",
        "args": [
            "-api-key",
            "YOUR_API_KEY",
            "/opt/etc/openapi/fastly-openapi-mcp.yaml"
        ]
    }
}

将此配置添加到编辑器的 MCP 工具配置中，以向 AI 助手提供直接访问 API 的权限。助手可以发现并使用 API 操作而无需额外设置。

OpenAPI 验证和检查

openapi-mcp 包含强大的 OpenAPI 验证和检查功能，帮助您改进 API 规范：

# 验证 OpenAPI 规范并检查关键问题
bin/openapi-mcp validate examples/fastly-openapi-mcp.yaml

# 综合检查，提供详细建议
bin/openapi-mcp lint examples/fastly-openapi-mcp.yaml

# 启动 HTTP 验证服务
bin/openapi-mcp --http=:8080 validate

# 启动 HTTP 检查服务
bin/openapi-mcp --http=:8080 lint

validate 命令执行必要的检查：

  • 缺少 operationId 字段（生成 MCP 工具所需）
  • 模式验证错误
  • 基本结构问题

lint 命令提供综合分析，带有建议：

  • 缺少摘要和描述
  • 未标记的操作
  • 参数命名和类型建议
  • 安全方案验证
  • API 设计的最佳实践

两个命令在发现问题时都会返回非零状态码，非常适合 CI/CD 管道。

用于验证和检查的 HTTP API

验证和检查命令都可以作为 HTTP 服务运行，使用 --http 标志，允许您通过 REST API 验证 OpenAPI 规范。请注意，这些端点仅在使用 validate 或 lint 命令时可用，而不是在正常 MCP 服务器操作期间：

# 启动验证 HTTP 服务
bin/openapi-mcp --http=:8080 validate

# 启动检查 HTTP 服务
bin/openapi-mcp --http=:8080 lint

API 端点：

  • POST /validate - 验证 OpenAPI 规范的关键问题
  • POST /lint - 综合检查，提供详细建议
  • GET /health - 健康检查端点

请求格式：

{
  "openapi_spec": "openapi: 3.0.0\ninfo:\n  title: My API\n  version: 1.0.0\npaths: {}"
}

响应格式：

{
  "success": false,
  "error_count": 1,
  "warning_count": 2,
  "issues": [
    {
      "type": "error",
      "message": "操作缺少 operationId",
      "suggestion": "添加 operationId 字段",
      "operation": "GET_/users",
      "path": "/users",
      "method": "GET"
    }
  ],
  "summary": "OpenAPI 检查完成，存在问题：1 个错误，2 个警告。"
}

示例使用：

curl -X POST http://localhost:8080/lint \
  -H "Content-Type: application/json" \
  -d '{"openapi_spec": "..."}'

预览工具作为 JSON

bin/openapi-mcp --dry-run examples/fastly-openapi-mcp.yaml

生成文档

bin/openapi-mcp --doc=tools.md examples/fastly-openapi-mcp.yaml

按标签、描述或函数列表过滤操作

bin/openapi-mcp filter --tag=admin examples/fastly-openapi-mcp.yaml
bin/openapi-mcp filter --include-desc-regex="user|account" examples/fastly-openapi-mcp.yaml
bin/openapi-mcp filter --exclude-desc-regex="deprecated" examples/fastly-openapi-mcp.yaml
bin/openapi-mcp filter --function-list-file=funcs.txt examples/fastly-openapi-mcp.yaml

您可以使用 --function-list-file=funcs.txt 限制输出仅为 operationId 在给定文件中列出的操作（每行一个）。此过滤器在标签和描述过滤器之后应用。

打印摘要

bin/openapi-mcp --summary --dry-run examples/fastly-openapi-mcp.yaml

使用外部命令后处理模式

bin/openapi-mcp --doc=tools.md --post-hook-cmd='jq . | tee /tmp/filtered.json' examples/fastly-openapi-mcp.yaml

禁用危险操作确认

bin/openapi-mcp --no-confirm-dangerous examples/fastly-openapi-mcp.yaml

🎮 命令行选项

命令

|