@openapi-mcp/server

@openapi-mcp/server

openapi-mcp-server 是一个强大的桥梁，通过模型上下文协议（MCP）连接 OpenAPI 规范与 AI 助手。它会自动将任何 OpenAPI/Swagger API 规范转换为 MCP 工具，供 Claude Desktop 等 AI 助手使用。借助它，AI 助手可以与您的 API 无缝交互，通过您的服务执行现实世界中的操作，而无需自定义集成。

功能

⚠️ 注意： 此服务要求 OpenAPI/Swagger 规范中的每个操作都必须有 operationId。如果任何操作缺少 operationId，服务将无法启动或处理该规范。请务必为所有操作明确指定唯一且描述性的 operationId。

• 🔌 OpenAPI 集成
  • 自动将 OpenAPI/Swagger 规范转换为 MCP 工具
• 📚 多个 OpenAPI 版本
  • 支持 OpenAPI v3.0.0 和 v3.1.0
• 🔐 身份验证支持：
  • HTTP 身份验证方案：
    • Basic 身份验证
    • Bearer 令牌身份验证（静态令牌，例如个人访问令牌）
    • RFC 7235 中定义的其他 HTTP 方案
  • API 密钥：
    • 基于请求头的 API 密钥

限制

⚠️ 版本支持：

• 当前不支持 OpenAPI v2.0（Swagger）

⚠️ 身份验证限制：

• 不支持 OAuth 2.0 身份验证
• 不支持 OpenID Connect Discovery
• 不支持基于查询参数的 API 密钥
• 不支持基于 Cookie 的身份验证
• 不支持动态 JWT 身份验证（登录生成的令牌）

安装

# Clone the repository
git clone https://github.com/sotayamashita/openapi-mcp-server.git
cd openapi-mcp-server

# Install dependencies
bun install

使用方法

您可以通过提供 OpenAPI 规范 URL 或文件路径来运行服务：

# Using a local file
bun run src/index.ts ./path/to/openapi.yml

# Using a URL
bun run src/index.ts --api https://example.com/api-spec.json

配置

环境变量

• BASE_URL

  • 必需：是
  • 描述：API 端点。Server Object 的 URL

• HEADERS

  • 必需：否
  • 默认值：{"Content-Type": "application/json","User-Agent": "openapi-mcp-server"}
  • 描述：将覆盖默认请求头的自定义请求头

Claude Desktop 集成

要将此 MCP 服务与 Claude Desktop 配合使用：

1. 打开 Claude Desktop 配置文件：

   # macOS/Linux
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. 添加以下配置：

   {
     "mcpServer": {
       "openapi-mcp-server": {
         "command": "bun",
         "args": [
           "/path/to/openapi-mcp-server/src/index.ts",
           "/path/to/openapi-mcp-server/demo/openapi.yml"
         ],
         "env": {
           "BASE_URL": "https://api.example.com/v1/",
           "HEADERS": "{\"Authorization\": \"Bearer ****\"}"
         }
       }
     }
   }
   

如需查看详细说明，请参阅 MCP 快速入门指南。

Cursor 集成

要将此 MCP 服务作为全局服务与 Cursor 配合使用：

1. 打开 Cursor
2. 打开 Cursor 设置 > MCP
3. 点击“+ 添加新的全局 MCP 服务”
4. 添加以下配置：

   {
     "mcpServer": {
       "openapi-mcp-server": {
         "command": "bun",
         "args": [
           "/path/to/openapi-mcp-server/src/index.ts",
           "/path/to/openapi-mcp-server/demo/openapi.yml"
         ],
         "env": {
           "BASE_URL": "https://api.example.com/v1/",
           "HEADERS": "{\"Authorization\": \"Bearer ****\"}"
         }
       }
     }
   }
   

如需查看详细说明，请参阅 Cursor 的模型上下文协议。

最佳实践

OpenAPI/Swagger 规范

使用描述清晰的 operationId 字段

OpenAPI/Swagger 规范中的 operationId 字段对工具如何呈现给 AI 助手起着至关重要的作用。将 API 转换为 MCP 工具时：

• 工具命名：operationId 会直接用作 MCP 工具名称
• 清晰度：描述清晰的 operationId 值有助于 AI 助手理解和使用 API
• 一致性：采用一致的命名模式（例如，getUser、createUser、updateUserPassword）

定义完善的操作示例：

paths:
  /users/{userId}:
    get:
      operationId: getUserById
      summary: Retrieve user information
      description: Returns detailed information about a specific user

提供详细的操作描述

每个操作的 description 字段同样重要：

• 工具选择：AI 助手会使用此描述，判断哪种工具适用于给定任务
• 理解：全面的描述有助于 AI 准确理解操作的作用
• 上下文：包含参数、预期响应和潜在错误的相关信息

描述清晰的操作示例：

paths:
  /users:
    post:
      operationId: createUser
      summary: Create a new user account
      description: |
        Creates a new user in the system. Requires a unique email address and a 
        password that meets security requirements (min 8 chars, including uppercase, 
        lowercase, number). Returns the created user object with an assigned user ID.

如果缺少详尽的描述，AI 助手可能难以为用户请求找到合适的操作，或可能会错误地使用这些操作。API 描述的质量会直接影响 AI 利用工具的效果。

开发

开发命令

# Run tests
bun vitest run

# Run tests with watch mode
bun vitest

# Run tests with coverage
bun vitest run --coverage

# Format code
bun prettier . --write

手动发布流程（使用发布分支）

本节介绍如何使用专用发布分支手动创建新版本。此方法有助于在发布之前将发布流程与 main 分支隔离。

前提条件：

• 所有计划纳入此次发布的更改都已合并到 main 分支。
• 你已登录 npm 账户（npm login）。
• 可以使用 Changesets CLI（本指南使用 bunx）。

步骤：

1. 确保 main 已是最新状态：

   git checkout main
   git pull origin main
   

2. **创建发布分支：**根据计划发布的版本为分支命名（例如，v0.1.0）。

   git checkout -b release/vX.Y.Z main
   

   将 vX.Y.Z 替换为目标版本。

3. **更新版本号和变更日志：**此命令会使用变更集文件（位于 .changeset/），更新 package.json 中的版本号，并更新 CHANGELOG.md。

   bunx @changesets/cli version
   

   检查对 package.json 和 CHANGELOG.md 所做的更改，确保无误。

4. 提交版本更新：

   git add .
   git commit -m "chore: update versions and changelogs for vX.Y.Z"
   

   将 vX.Y.Z 替换为目标版本。

5. **构建项目：**确保生成的分发文件包含最新更改。

   bun run build
   

6. **发布到 npm：**将新版本发布到 npm 注册表。

   npm publish
   

   确保 package.json 中包含 "publishConfig": { "access": "public" }，以便发布公开的作用域包。 （你也可以使用 bun publish，但如果选择此方式，请确认它对公开的作用域包的处理方式。）

7. **在 Git 中为发布打标签：**创建与发布到 npm 的版本相匹配的 Git 标签。

   # 将 X.Y.Z 替换为实际版本号，例如 0.1.0
   git tag @openapi-mcp/[email protected]
   

8. **将发布分支合并回 main：**这会将版本更新和 CHANGELOG 更改带回主分支。

   git checkout main
   git merge --no-ff release/vX.Y.Z
   

   （使用 --no-ff 会创建合并提交，这有助于在 Git 历史记录中追踪发布。）

9. 将 main 和新标签推送到远程仓库：

   git push origin main --tags
   

10. **（可选）清理：**如果不再需要，可删除本地和远程的发布分支。

    git branch -d release/vX.Y.Z
    git push origin --delete release/vX.Y.Z
    

如需了解使用 Changesets 的更多详细信息，请参阅 Changesets 官方文档。