AI导哈

OpenAPI-MCP服务器

OpenAPI-MCP服务器是一个强大的桥梁，将OpenAPI规范与使用模型上下文协议（MCP）的AI助手连接起来，自动将OpenAPI/Swagger API规范转换为MCP工具，使AI助手能够无缝地与您的API交互。

  • by sotayamashita
  • TypeScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 sotayamashita/openapi-mcp-server

使用说明

@openapi mcp/服务器

openapi-mcp服务器是openapi规范和使用模型上下文协议（mcp）的AI助手之间的强大桥梁。它自动将任何OpenAPI/Swagger API规范转换为MCP工具，这些工具可供Claude Desktop等人工智能助手使用。这使AI助手能够与您的API无缝交互，使其能够通过您的服务执行真实世界的操作，而不需要自定义集成。

特性

⚠️ 注： 此服务器 需要 OpenAPI/Swagger规范中的每个操作都有一个 operationId.如果缺少任何操作 operationId，服务器将无法启动或处理规范。始终确保所有操作都明确地分配了唯一的描述性操作 operationId.

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

局限性

⚠️ 版本支持:

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

⚠️ 身份验证限制:

  • []不支持OAuth 2.0身份验证
  • []不支持OpenID连接发现
  • []不支持基于查询参数的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

  • HEADERS

    • 必填：否
    • 违约： {"Content-Type": "application/json","User-Agent": "openapi-mcp-server"}
    • 说明：将覆盖默认标头的自定义标头

Claude桌面集成

要将此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快速入门指南.

光标集成

要将此MCP服务器与游标设置为全局，请执行以下操作：

  1. 打开的游标
  2. 打开光标设置>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 领域

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

  • 工具命名：The operationId 直接用作MCP工具名称
  • 清晰度：描述性 operationId 值使人工智能助手更容易理解和使用您的API
  • 一致性：使用一致的命名模式（例如。， getUser, createUser, updateUserPassword)

定义良好的操作示例：

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

包括详细的操作说明

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

  • 工具选择：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.

如果没有详细的描述，人工智能助手可能很难为用户请求识别正确的操作，或者可能会错误地使用它们。API描述的质量直接影响人工智能如何有效利用您的工具。

发展

开发命令

# 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. Bump版本和更新变更日志： 此命令使用变更集文件（在 .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标签。

    # Replace X.Y.Z with the actual version number, e.g., 0.1.0
git tag @openapi-mcp/server@X.Y.Z

  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

有关使用变更集的更多详细信息，请参阅 官方变更集文档.

相关 MCP