OpenAPI MCP 服务器

这是一个将 OpenAPI 端点暴露为 MCP 资源的模型上下文协议（MCP）服务器。该服务器允许大型语言模型通过 MCP 协议发现并与 OpenAPI 规范定义的 REST API 进行交互。

概述

该 MCP 服务器支持两种传输方式：

Stdio 传输（默认）：用于与通过标准输入/输出管理 MCP 连接的 AI 系统（如 Claude Desktop）直接集成。
可流式 HTTP 传输：用于通过 HTTP 连接到服务器，允许 Web 客户端和其他支持 HTTP 的系统使用 MCP 协议。

用户快速入门

选项 1：与 Claude Desktop 一起使用（Stdio 传输）

无需克隆此仓库。只需配置 Claude Desktop 以使用此 MCP 服务器：

找到或创建您的 Claude Desktop 配置文件：
- 在 macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json
添加以下配置：

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}

用您的实际 API 配置替换环境变量：
- API_BASE_URL：您的 API 的基础 URL
- OPENAPI_SPEC_PATH：您的 OpenAPI 规范的 URL 或路径
- API_HEADERS：用于 API 认证头的逗号分隔的键值对

选项 2：与 HTTP 客户端一起使用（HTTP 传输）

要与 HTTP 客户端一起使用服务器：

无需安装！使用 npx 直接运行包：

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123" \
  --transport http \
  --port 3000

使用 HTTP 请求与服务器交互：

# 初始化会话（第一个请求）
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'

# 响应包括一个 Mcp-Session-Id 头，您必须在后续请求中使用
# 并且 InitializeResult 直接在 POST 响应体中。

# 发送请求以列出工具
# 此请求的响应也直接在此 POST 请求上接收。
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: your-session-id" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 打开流式连接以接收其他服务器响应（例如，工具执行结果）
# 此操作使用服务器发送事件（SSE）。
curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

# 示例：执行工具（响应将通过 GET 流到达）
# curl -X POST http://localhost:3000/mcp \
#  -H "Content-Type: application/json" \
#  -H "Mcp-Session-Id: your-session-id" \
#  -d '{"jsonrpc":"2.0","id":2,"method":"tools/execute","params":{"name":"yourToolName", "arguments": {}}}'

# 完成后终止会话
curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

传输类型

Stdio 传输（默认）

Stdio 传输专为与通过标准输入/输出管理 MCP 连接的 AI 系统（如 Claude Desktop）直接集成而设计。这是最简单的设置，无需网络配置。

何时使用：当与 Claude Desktop 或其他支持基于 stdio 的 MCP 通信的系统集成时。

可流式 HTTP 传输

HTTP 传输允许通过 HTTP 访问 MCP 服务器，使 Web 应用程序和其他支持 HTTP 的客户端能够与 MCP 协议交互。它支持会话管理、流式响应和标准 HTTP 方法。

主要功能：

使用 Mcp-Session-Id 头进行会话管理
initialize 和 tools/list 请求的 HTTP 响应在 POST 上同步发送。
其他服务器到客户端的消息（例如，tools/execute 结果、通知）通过 GET 连接使用服务器发送事件（SSE）进行流式传输。
支持 POST/GET/DELETE 方法

何时使用：当您需要将 MCP 服务器暴露给 Web 客户端或通过 HTTP 而不是 stdio 通信的系统时。

配置选项

服务器可以通过环境变量或命令行参数进行配置：

环境变量

API_BASE_URL - API 端点的基础 URL
OPENAPI_SPEC_PATH - OpenAPI 规范的路径或 URL
OPENAPI_SPEC_FROM_STDIN - 设置为 "true" 以从标准输入读取 OpenAPI 规范
OPENAPI_SPEC_INLINE - 直接提供 OpenAPI 规范内容作为字符串
API_HEADERS - 用于 API 头的逗号分隔的键值对
SERVER_NAME - MCP 服务器的名称（默认："mcp-openapi-server"）
SERVER_VERSION - 服务器的版本（默认："1.0.0"）
TRANSPORT_TYPE - 使用的传输类型："stdio" 或 "http"（默认："stdio"）
HTTP_PORT - HTTP 传输的端口（默认：3000）
HTTP_HOST - HTTP 传输的主机（默认："127.0.0.1"）
ENDPOINT_PATH - HTTP 传输的端点路径（默认："/mcp"）
TOOLS_MODE - 工具加载模式："all"（加载所有基于端点的工具）或 "dynamic"（仅加载元工具）（默认："all"）
DISABLE_ABBREVIATION - 禁用名称优化（当名称超过 64 个字符时可能会抛出错误）

命令行参数

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --name "my-mcp-server" \
  --server-version "1.0.0" \
  --transport http \
  --port 3000 \
  --host 127.0.0.1 \
  --path /mcp \
  --disable-abbreviation true

OpenAPI 规范加载

MCP 服务器支持多种加载 OpenAPI 规范的方法，为不同的部署场景提供了灵活性：

1. URL 加载（默认）

从远程 URL 加载 OpenAPI 规范：

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json

2. 本地文件加载

从本地文件加载 OpenAPI 规范：

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./path/to/openapi.yaml

3. 标准输入加载

从标准输入读取 OpenAPI 规范（适用于管道或容器化环境）：

# 从文件管道
cat openapi.json | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

# 从 curl 管道
curl -s https://api.example.com/openapi.json | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

# 使用环境变量
export OPENAPI_SPEC_FROM_STDIN=true
echo '{"openapi": "3.0.0", ...}' | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com

4. 内联规范

直接提供 OpenAPI 规范内容作为命令行参数：

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-inline '{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0.0"}, "paths": {}}'

# 使用环境变量
export OPENAPI_SPEC_INLINE='{"openapi": "3.0.0", ...}'
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com

支持的格式

所有加载方法都支持 JSON 和 YAML 格式。服务器会自动检测格式并进行相应解析。

Docker 和容器使用

对于容器化部署，您可以挂载 OpenAPI 规范或使用 stdin：

# 挂载本地文件
docker run -v /path/to/spec:/app/spec.json your-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec /app/spec.json

# 使用 stdin 与 docker
cat openapi.json | docker run -i your-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

错误处理

服务器为规范加载失败提供了详细的错误消息：

URL 加载：HTTP 状态码和网络错误
文件加载：文件系统错误（未找到、权限等）
Stdin 加载：空输入或读取错误
内联加载：缺少内容错误
解析错误：详细的 JSON/YAML 语法错误消息

验证

一次只能使用一个规范来源。服务器将验证是否提供了以下之一：

--openapi-spec（URL 或文件路径）
--spec-from-stdin
--spec-inline

如果指定了多个来源，服务器将退出并显示错误消息。

OpenAPI 模式处理

引用解析

该 MCP 服务器实现了强大的 OpenAPI 引用（$ref）解析，以确保 API 模式的准确表示：

参数引用：完全解析 OpenAPI 规范中参数组件的 $ref 指针
模式引用：处理参数和请求体中的嵌套模式引用
递归引用：通过检测和处理循环引用来防止无限循环
嵌套属性：保留复杂嵌套对象和数组结构及其所有属性

输入模式组合

服务器智能地将参数和请求体合并为每个工具的统一输入模式：

参数 + 请求体合并：将路径、查询和体参数合并为单个模式
冲突处理：通过为与参数名称冲突的体属性添加前缀来解决命名冲突
类型保留：保留所有模式元素的原始类型信息
元数据保留：保留描述、格式、默认值、枚举和其他模式属性

复杂模式支持

MCP 服务器处理各种 OpenAPI 模式的复杂性：

原始类型体：将非对象请求体包装在 "body" 属性中
对象体：将对象属性展平到工具的输入模式中
数组体：正确处理带有嵌套项目定义的数组模式
必需属性：跟踪并保留哪些参数和属性是必需的

工具加载和过滤选项

根据 Stainless 的文章 "What We Learned Converting Complex OpenAPI Specs to MCP Servers" (https://www.stainless.com/blog/what-we-learned-converting-complex-openapi-specs-to-mcp-servers)，添加了以下标志以控制加载哪些 API 端点（工具）：

--tools <all|dynamic>：选择加载所有工具（默认）或仅加载动态元工具（list-api-endpoints、get-api-endpoint-schema、invoke-api-endpoint）。
--tool <toolId>：仅导入指定的工具 ID 或名称。可以多次使用。
--tag <tag>：仅导入具有指定 OpenAPI 标签的工具。可以多次使用。
--resource <resource>：仅导入在指定资源路径前缀下的工具。可以多次使用。
--operation <method>：仅导入指定 HTTP 方法（get、post 等）的工具。可以多次使用。

示例：

# 仅加载动态元工具
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools dynamic

# 仅加载 GET /users 端点工具
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tool GET-users

# 加载标记为 "user" 且在 "/users" 资源下的工具
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tag user --resource users

# 仅加载 POST 操作
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --operation post

安全注意事项

HTTP 传输验证 Origin 头以防止 DNS 重绑定攻击
默认情况下，HTTP 传输仅绑定到 localhost（127.0.0.1）
如果暴露给其他主机，请考虑实施额外的身份验证

调试

要查看调试日志：

当使用 stdio 传输与 Claude Desktop 时：
- 日志出现在 Claude Desktop 日志中

当使用 HTTP 传输时：

npx @ivotoby/openapi-mcp-server --transport http &2>debug.log

开发者指南

开发工具

npm run build - 构建 TypeScript 源代码
npm run clean - 删除构建工件
npm run typecheck - 运行 TypeScript 类型检查
npm run lint - 运行 ESLint
npm run dev - 监视源文件并在更改时重新构建
npm run inspect-watch - 运行检查器并在更改时自动重新加载

开发工作流程

克隆仓库
安装依赖：npm install
启动开发环境：npm run inspect-watch
对 src/ 中的 TypeScript 文件进行更改
服务器将自动重新构建并重新启动

贡献

分叉仓库
创建功能分支
进行更改
运行测试和 linting：npm run typecheck && npm run lint
提交拉取请求

常见问题

问：什么是“工具”？
答：工具对应于从您的 OpenAPI 规范派生的单个 API 端点，暴露为 MCP 资源。

问：如何过滤加载哪些工具？
答：使用 --tool、--tag、--resource 和 --operation 标志，或设置 TOOLS_MODE=dynamic 以仅加载元工具。

问：何时应使用动态模式？
答：动态模式提供元工具（list-api-endpoints、get-api-endpoint-schema、invoke-api-endpoint）以检查端点并与之交互，而无需预加载所有操作，这对于大型或不断变化的 API 非常有用。

问：如何为 API 请求指定自定义头？
答：使用 --headers 标志或 API_HEADERS 环境变量，键值对用逗号分隔。

问：支持哪些传输方法？
答：服务器支持 stdio 传输（默认）用于与 AI 系统集成，以及 HTTP 传输（通过 SSE 进行流式传输）用于 Web 客户端。

问：服务器如何处理带有引用的复杂 OpenAPI 模式？
答：服务器完全解析参数和模式中的 $ref 引用，保留嵌套结构、默认值和其他属性。有关引用解析和模式组合的详细信息，请参阅 "OpenAPI 模式处理" 部分。

问：当参数名称与请求体属性冲突时会发生什么？
答：服务器检测命名冲突并自动为体属性名称添加 body_ 前缀以避免冲突，确保所有属性都可访问。

问：在哪里可以找到开发和贡献指南？
答：请参阅上面的 "开发者指南" 部分，了解命令（npm run build、npm run dev 等）和拉取请求工作流程。

许可证

MIT