OpenAPI MCP 服务器

smithery 徽章

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

📖 文档

用户指南 - 适用于希望将本 MCP 服务器与 Claude Desktop、Cursor 或其他 MCP 客户端配合使用的用户
库使用 - 适用于使用本包作为库创建自定义 MCP 服务器的开发者
开发者指南 - 适用于代码库贡献者和开发人员
认证提供者指南 - 详细的认证模式和示例

用户指南

本节介绍如何作为终端用户将 MCP 服务器与 Claude Desktop、Cursor 或其他兼容 MCP 的工具配合使用。

概述

本 MCP 服务器可通过两种方式使用：

CLI 工具：直接使用 npx @ivotoby/openapi-mcp-server 配合命令行参数快速设置
库：在您自己的 Node.js 应用程序中导入并使用 OpenAPIServer 类进行自定义实现

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

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

用户快速入门

选项 1：与 Claude Desktop 配合使用（标准输入输出传输）

无需克隆此仓库。只需配置 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 头，您必须在后续请求中使用
# 以及 POST 响应体中的 InitializeResult 直接返回

# 发送请求列出工具
# 此请求也会在此 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"

配置选项

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

环境变量

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"（仅加载元工具）或 "explicit"（仅加载 includeTools 中指定的工具）（默认："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

# 使用 docker 的 stdin
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

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

工具加载和过滤选项

根据 Stainless 文章《将复杂 OpenAPI 规范转换为 MCP 服务器的经验》（https://www.stainless.com/blog/what-we-learned-converting-complex-openapi-specs-to-mcp-servers），添加了以下标志来控制加载哪些 API 端点（工具）：

--tools <all|dynamic|explicit>：选择工具加载模式：
- all（默认）：从 OpenAPI 规范加载所有工具，应用任何指定的过滤器
- dynamic：仅加载动态元工具（list-api-endpoints、get-api-endpoint-schema、invoke-api-endpoint）
- explicit：仅加载 --tool 选项中明确列出的工具，忽略所有其他过滤器
--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

# 仅加载显式指定的工具（忽略其他筛选条件）
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools explicit --tool GET::users --tool POST::users

# 仅加载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

传输类型

标准输入输出传输（默认）

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

使用场景：当需要与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通信的系统时。

健康检查端点

使用HTTP传输时，可通过/health端点进行健康检查和服务发现：

# 检查服务器健康状态
curl http://localhost:3000/health

# 响应：
# {
#   "status": "healthy",
#   "activeSessions": 2,
#   "uptime": 3600
# }

健康响应字段：

status：服务器运行时始终返回"healthy"
activeSessions：活跃MCP会话数
uptime：服务器运行时间（秒）

主要特性：

无需认证
支持任何HTTP方法（GET、POST等）
适合负载均衡器、Kubernetes探针和监控系统

集成示例：

# Kubernetes存活探针
livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 3
  periodSeconds: 10

# Docker健康检查
HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:3000/health || exit 1

安全注意事项

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

调试

查看调试日志：

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

使用HTTP传输时：

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

库使用指南

本节面向希望将此包作为库来创建自定义MCP服务器的开发者。

🚀 作为库使用

通过导入和配置OpenAPIServer类，为特定API创建专用的MCP服务器。此方法适用于：

自定义认证：通过AuthProvider接口实现复杂认证模式
API特定优化：筛选端点、自定义错误处理、针对特定用例优化
分发：将服务器打包为独立的npm模块以便共享
集成：将服务器嵌入大型应用程序或添加自定义中间件

基础库用法

import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"

const config = {
  name: "my-api-server",
  version: "1.0.0",
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  specInputMethod: "url" as const,
  headers: {
    Authorization: "Bearer your-token",
    "X-API-Key": "your-api-key",
  },
  transportType: "stdio" as const,
  toolsMode: "all" as const, // 选项："all"、"dynamic"、"explicit"
}

const server = new OpenAPIServer(config)
const transport = new StdioServerTransport()
await server.start(transport)

工具加载模式

toolsMode配置选项控制从OpenAPI规范加载哪些工具：

// 从规范加载所有工具（默认）
const config = {
  // ... 其他配置
  toolsMode: "all" as const,
  // 可选：应用筛选器控制加载哪些工具
  includeTools: ["GET::users", "POST::users"], // 仅这些工具
  includeTags: ["public"], // 仅带有这些标签的工具
  includeResources: ["users"], // 仅这些资源下的工具
  includeOperations: ["get", "post"], // 仅这些HTTP方法
}

// 仅加载用于API探索的动态元工具
const config = {
  // ... 其他配置
  toolsMode: "dynamic" as const,
  // 提供：list-api-endpoints、get-api-endpoint-schema、invoke-api-endpoint
}

// 仅加载显式指定的工具（忽略其他筛选条件）
const config = {
  // ... 其他配置
  toolsMode: "explicit" as const,
  includeTools: ["GET::users", "POST::users"], // 仅这些精确工具
  // includeTags、includeResources、includeOperations在显式模式下被忽略
}

使用AuthProvider实现高级认证

对于需要令牌过期处理、刷新或复杂认证的API：

import { OpenAPIServer, AuthProvider } from "@ivotoby/openapi-mcp-server"
import { AxiosError } from "axios"

class MyAuthProvider implements AuthProvider {
  async getAuthHeaders(): Promise<Record<string, string>> {
    // 每个请求前调用 - 返回最新的头部
    if (this.isTokenExpired()) {
      await this.refreshToken()
    }
    return { Authorization: `Bearer ${this.token}` }
  }

  async handleAuthError(error: AxiosError): Promise<boolean> {
    // 出现401/403错误时调用 - 返回true以重试
    if (error.response?.status === 401) {
      await this.refreshToken()
      return true // 重试请求
    }
    return false
  }
}

const authProvider = new MyAuthProvider()
const config = {
  // ... 其他配置
  authProvider: authProvider, // 使用AuthProvider替代静态头部
}

📁 查看examples/目录获取完整可运行的示例，包括：

带静态认证的基础库用法
不同场景下的AuthProvider实现
真实世界的Beatport API集成
生产就绪的打包模式

🔐 使用AuthProvider实现动态认证

AuthProvider接口支持静态头部无法处理的复杂认证场景：

主要特性

动态头部：为每个请求提供最新的认证头部
令牌过期处理：自动检测和处理过期令牌
认证错误恢复：可恢复认证失败的重试逻辑
自定义错误消息：向用户提供清晰、可操作的指导

AuthProvider接口

interface AuthProvider {
  /**
   * 获取当前请求的认证头部
   * 每个API请求前调用以获取最新头部
   */
  getAuthHeaders(): Promise<Record<string, string>>

  /**
   * 处理API响应中的认证错误
   * 当API返回401或403错误时调用
   * 返回true以重试请求，false则否
   */
  handleAuthError(error: AxiosError): Promise<boolean>
}

常见模式

自动令牌刷新

class RefreshableAuthProvider implements AuthProvider {
  async getAuthHeaders(): Promise<Record<string, string>> {
    if (this.isTokenExpired()) {
      await this.refreshToken()
    }
    return { Authorization: `Bearer ${this.accessToken}` }
  }

  async handleAuthError(error: AxiosError): Promise<boolean> {
    if (error.response?.status === 401) {
      await this.refreshToken()
      return true // 使用新令牌重试
    }
    return false
  }
}

手动令牌管理（如Beatport）

class ManualTokenAuthProvider implements AuthProvider {
  async getAuthHeaders(): Promise<Record<string, string>> {
    if (!this.token || this.isTokenExpired()) {
      throw new Error(
        "令牌已过期。请从浏览器获取新令牌：\n" +
          "1. 访问API网站并登录\n" +
          "2. 打开浏览器开发者工具（F12）\n" +
          "3. 从任意API请求复制Authorization头部\n" +
          "4. 使用updateToken()更新您的令牌",
      )
    }
    return { Authorization: `Bearer ${this.token}` }
  }

  updateToken(token: string): void {
    this.token = token
    this.tokenExpiry = new Date(Date.now() + 3600000) // 1小时
  }
}

API密钥认证

class ApiKeyAuthProvider implements AuthProvider {
  constructor(private apiKey: string) {}

  async getAuthHeaders(): Promise<Record<string, string>> {
    return { "X-API-Key": this.apiKey }
  }

  async handleAuthError(error: AxiosError): Promise<boolean> {
    throw new Error("API密钥认证失败。请检查您的密钥。")
  }
}

📖 详细AuthProvider文档和示例见docs/auth-provider-guide.md

OpenAPI 模式处理

引用解析

本 MCP 服务器实现了强大的 OpenAPI 引用 ($ref) 解析功能，确保 API 模式的准确表示：

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

输入模式组合

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

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

复杂模式支持

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

基本类型主体：将非对象请求体包装在 "body" 属性中
对象主体：将对象属性扁平化为工具的输入模式
数组主体：正确处理带有嵌套项定义的数组模式
必需属性：跟踪并保留必需的参数和属性

开发者信息

开发者指南

开发工具

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 文件
服务器将自动重建并重启

贡献指南

Fork 仓库
创建特性分支
进行更改
运行测试和 lint：npm run typecheck && npm run lint
提交拉取请求

📖 完整的开发者文档请参阅 docs/developer-guide.md

常见问题

问：什么是 "工具"？ 答：工具对应于从 OpenAPI 规范派生的单个 API 端点，作为 MCP 资源公开。

问：如何在自己的项目中使用这个包？ 答：您可以导入 OpenAPIServer 类并将其作为库用于 Node.js 应用程序。这允许您为特定 API 创建定制的 MCP 服务器，具有自定义身份验证、过滤和错误处理。完整实现请参阅 examples/ 目录。

问：使用 CLI 和作为库使用有什么区别？ 答：CLI 适用于快速设置和测试，而库方法允许您为特定 API 创建专用包，使用 AuthProvider 实现自定义身份验证，添加自定义逻辑，并将服务器作为独立的 npm 模块分发。

问：如何处理带有过期令牌的 API？ 答：使用 AuthProvider 接口而不是静态标头。AuthProvider 允许您实现动态身份验证，包括令牌刷新、过期处理和自定义错误恢复。不同模式的 AuthProvider 示例请参阅相关文档。

问：什么是 AuthProvider，何时使用它？ 答：AuthProvider 是用于动态身份验证的接口，它在每个请求前获取新的标头并处理身份验证错误。当您的 API 有过期令牌、需要令牌刷新或需要静态标头无法处理的复杂身份验证逻辑时使用它。

问：如何过滤加载的工具？ 答：使用 --tool、--tag、--resource 和 --operation 标志与 --tools all（默认），设置 --tools dynamic 仅用于元工具，或使用 --tools explicit 仅加载 --tool 指定的工具（忽略其他过滤器）。

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

问：如何为 API 请求指定自定义标头？ 答：对于 CLI 使用，使用 --headers 标志或 API_HEADERS 环境变量，键值对用逗号分隔。对于库使用，使用 headers 配置选项或实现 AuthProvider 以获取动态标头。

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

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

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

问：我可以打包 MCP 服务器以进行分发吗？ 答：可以！使用库方法时，您可以为 API 创建专用的 npm 包。完整实现请参阅 Beatport 示例，可以打包并分发为 npx your-api-mcp-server。

问：在哪里可以找到开发和贡献指南？ 答：全面的架构、关键概念、开发流程和贡献指南请参阅开发者指南。

许可证

MIT