openapi-dynamic

目录

• 概述
• 亮点
• 要求
• 快速开始
• 配置
• 客户端设置
• CLI
• 身份验证
• 环境变量
• 处理响应
• 文件和二进制数据
• MCP 工具
• 开发
• 许可证

概述

openapi-dynamic-mcp 让 MCP 客户端和 shell 用户无需为每个服务编写自定义衔接代码，即可使用 OpenAPI API。将其指向一个或多个 OpenAPI 规范，即可通过统一的接口列出 API、检查端点、进行身份验证并发送请求。

它针对常见的用户工作流设计：

• 通过一个 MCP 服务连接多个 API
• 使用本地规范或托管的 specUrl 定义
• 支持 OpenAPI 3.0、3.1 和 Swagger 2.0
• 处理 API 密钥、Bearer、Basic 和 OAuth2 身份验证
• 在多个会话间复用已存储的令牌
• 将大型响应筛选为所需字段
• 在发送请求前安全地预览请求

亮点

• 快速将规范转化为可用工具：从 YAML 配置开始，即可立即浏览端点，或通过 MCP 或 CLI 调用端点。
• 按照 API 要求进行身份验证：支持 API 密钥、Bearer/Basic 身份验证，以及 OAuth2 客户端凭据、密码、设备代码和带 PKCE 的授权代码模式。
• 避免重复登录：只需存储一次令牌，即可在之后重复使用。
• 顺畅处理交互式 OAuth：设备代码和基于浏览器的身份验证会返回说明，供 Agent 呈现给用户。
• 聚焦响应内容：使用 JSONPath 选择器筛选大型输出。
• 发送前先检查：使用试运行预览请求格式，而不执行网络 I/O。
• 按需上传文件：支持 multipart 表单上传和原始二进制请求体。
• 从容应对速率限制：可配置针对 429 Too Many Requests 的重试行为。

要求

• Node.js 20+

快速开始

直接运行 MCP 服务：

npx -y openapi-dynamic-mcp@latest --config ./config.yaml

最简配置：

version: 1
apis:
  - name: pet-api
    specPath: ./pet-api.yaml

也可以指向远程规范：

version: 1
apis:
  - name: pet-api
    specUrl: https://api.example.com/openapi.json

配置

在 apis 下添加要使用的每个 API。每项都可以指向本地规范文件或远程规范 URL。

version: 1

apis:
  - name: pet-api
    specPath: ./pet-api.yaml
    # specUrl: https://api.example.com/openapi.yaml
    baseUrl: https://api.example.com/v1
    timeoutMs: 30000
    headers:
      X-Client: openapi-dynamic-mcp
    retry429:
      maxRetries: 2
      baseDelayMs: 250
      maxDelayMs: 5000
      jitterRatio: 0.2
      respectRetryAfter: true
    oauth2Schemes:
      OAuthCC:
        tokenUrl: https://auth.example.com/oauth2/token
        scopes: [read:pets, write:pets]
        tokenEndpointAuthMethod: client_secret_basic
      UserAuth:
        authMethod: device_code
        deviceAuthorizationEndpoint: https://auth.example.com/oauth/device
        pkce: true

常用选项：

• name：在 MCP 和 CLI 命令中显示的 API 名称
• specPath 或 specUrl：OpenAPI 规范的加载位置
• baseUrl：覆盖规范中的服务端 URL
• headers：每次请求都要发送的请求头
• timeoutMs：默认请求超时时间
• retry429：针对速率受限 API 的重试行为
• oauth2Schemes：规范定义 OAuth 安全方案时，按方案配置 OAuth 设置

按方案配置 OAuth2

当某个 API 定义了一个或多个 OAuth2 安全方案，并且你想为特定方案设置令牌 URL、作用域或交互式身份验证偏好时，请使用 oauth2Schemes。

方案名称必须与 OpenAPI 规范中的名称一致。常用选项包括：

• tokenUrl
• scopes
• tokenEndpointAuthMethod
• authMethod
• deviceAuthorizationEndpoint
• pkce

如果只需要配置凭据，通常仅使用环境变量就足够了。若想将可复用配置纳入项目版本控制，请使用 oauth2Schemes。

客户端设置

Claude Desktop / Claude Code

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": [
        "-y",
        "openapi-dynamic-mcp@latest",
        "--config",
        "/absolute/path/to/config.yaml"
      ],
      "env": {
        "PET_API_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": [
        "-y",
        "openapi-dynamic-mcp@latest",
        "--config",
        "/absolute/path/to/config.yaml"
      ]
    }
  }
}

CLI

服务模式可以通过根命令或显式的 serve 子命令启动：

openapi-dynamic-mcp --config ./config.yaml
openapi-dynamic-mcp serve --config ./config.yaml

如果你想在 MCP 客户端之外使用相同的 API 访问能力进行脚本编写、调试或身份验证设置，请使用 CLI。

工具命令

每个 MCP 工具也都可以作为 CLI 子命令使用，接受一个 JSON 对象并输出 JSON：

openapi-dynamic-mcp list_apis --config ./config.yaml --input '{}'
openapi-dynamic-mcp list_api_endpoints --config ./config.yaml --input '{"apiName":"pet-api"}'
openapi-dynamic-mcp get_api_endpoint --config ./config.yaml --input '{"apiName":"pet-api","endpointId":"listPets"}'
openapi-dynamic-mcp get_api_schema --config ./config.yaml --input '{"apiName":"pet-api","pointer":"/info"}'
openapi-dynamic-mcp make_endpoint_request --config ./config.yaml --input '{"apiName":"pet-api","endpointId":"listPets","dryRun":true}'

通用标志：

• --input <json>：包含命令参数的 JSON 对象
• --fields <jsonpath>：可重复使用的选择器，用于筛选成功的输出
• --describe：打印命令架构和帮助元数据
• --auth-file <path>：覆盖身份验证存储路径

身份验证命令

使用 auth 对一个已配置的安全方案进行预身份验证，并保存其令牌，以供之后的 MCP 或 CLI 调用使用：

openapi-dynamic-mcp auth --config ./config.yaml --api pet-api --scheme OAuthCC
openapi-dynamic-mcp auth --config ./config.yaml --api pet-api --scheme ApiKeyAuth --token secret

对于 API 密钥和 bearer 身份验证，--token 可直接提供密钥。对于 OAuth2，命令会使用你配置的凭据完成流程，并保存结果以供之后使用。

身份验证

支持的身份验证类型：

• API 密钥
• HTTP bearer
• HTTP basic
• OAuth2 客户端凭据
• OAuth2 密码授权（ROPC）
• OAuth2 设备代码
• 使用 PKCE 的 OAuth2 授权码

典型的身份验证流程：

1. 通过环境变量或配置提供凭据
2. 如果该方案需要保存令牌，则运行一次 auth
3. 从 MCP 或 CLI 重用该令牌，直到令牌过期或发生变化

身份验证存储

默认情况下，令牌会存储在配置文件旁边的以下位置：

.openapi-dynamic-mcp-auth.json

你可以通过以下任一方式覆盖该路径：

• --auth-file
• OPENAPI_DYNAMIC_MCP_AUTH_FILE

这样可以显著简化重复使用 API 的操作，尤其适用于需要频繁重新连接的 MCP 客户端。

交互式 OAuth2 流程

当请求需要用户交互时，工具会返回结构化指引，供 MCP Agent 转达给用户。典型的设备代码输出如下：

{
  "status": "authorization_required",
  "method": "device_code",
  "message": "User authorization required. Ask the user to visit the URL and enter the code.",
  "verificationUri": "https://auth.example.com/device",
  "userCode": "ABCD-1234",
  "instruction": "After the user confirms, call this endpoint again."
}

这对 MCP Agent 尤其有用，因为身份验证步骤会成为用户工作流中的常规环节，而不是无路可走的错误。

环境变量

环境变量适用于密钥、基础 URL 覆盖和 CI 设置。

变量名根据规范化后的 API 和方案名称生成：

• 转换为大写
• 非字母数字字符替换为 _
• 连续的 _ 合并为一个
• 移除开头和结尾的 _

示例：

• pet-api -> PET_API
• OAuth2 -> OAUTH2

API 级变量

• <API>_BASE_URL
• <API>_HEADERS，值为 JSON 对象字符串
• OPENAPI_DYNAMIC_MCP_AUTH_FILE

API 密钥

• <API>_<SCHEME>_API_KEY

HTTP 身份验证

• <API>_<SCHEME>_TOKEN
• <API>_<SCHEME>_USERNAME
• <API>_<SCHEME>_PASSWORD

OAuth2

• <API>_<SCHEME>_ACCESS_TOKEN
• <API>_<SCHEME>_CLIENT_ID
• <API>_<SCHEME>_CLIENT_SECRET
• <API>_<SCHEME>_TOKEN_URL
• <API>_<SCHEME>_SCOPES>，以空格分隔的列表
• <API>_<SCHEME>_TOKEN_AUTH_METHOD，值为 client_secret_basic 或 client_secret_post
• <API>_<SCHEME>_USERNAME
• <API>_<SCHEME>_PASSWORD
• <API>_<SCHEME>_AUTH_METHOD，值为 device_code 或 authorization_code
• <API>_<SCHEME>_DEVICE_AUTHORIZATION_ENDPOINT
• <API>_<SCHEME>_REDIRECT_PORT
• <API>_<SCHEME>_PKCE，值为 true 或 false

实用行为：

• _ACCESS_TOKEN 会完全绕过 OAuth 授权流程。
• 如果两种方式都可用，_AUTH_METHOD 会强制使用 device_code 或 authorization_code。
• 根据安全方案的不同，_USERNAME 和 _PASSWORD 可用于 HTTP basic 身份验证或 OAuth 密码授权。

处理响应

JSONPath 筛选

CLI 的 --fields 和 MCP 的 fields: string[] 可让你只保留所需的成功响应部分。如果规范或载荷过大，难以轻松查看，这会很有帮助。

示例：

openapi-dynamic-mcp list_apis --config ./config.yaml --fields '$.apis[*].name'
openapi-dynamic-mcp get_api_endpoint --config ./config.yaml --input '{"apiName":"pet-api","endpointId":"listPets"}' --fields '$.responses'

选择器支持带引号的成员转义、数组索引和通配符。

大型架构警告

当响应非常大时，get_api_schema 会添加一个 _sizeWarning 提示字段，建议你缩小 JSON Pointer 的范围。

试运行

make_endpoint_request 支持 dryRun: true，因此你可以在发送实际请求前确认 URL、标头、身份验证和序列化后的请求体。

文件和二进制数据

make_endpoint_request 同时支持 multipart/form-data 和原始二进制上传。

每个文件条目必须且只能提供一种内容来源：base64、text 或 filePath。

{
  "name": "avatar.png",
  "contentType": "image/png",
  "filePath": "/absolute/path/to/avatar.png"
}

Multipart 示例：

{
  "apiName": "pet-api",
  "endpointId": "uploadProfile",
  "contentType": "multipart/form-data",
  "body": {
    "description": "A photo of Fido"
  },
  "files": {
    "profileImage": {
      "name": "fido.jpg",
      "contentType": "image/jpeg",
      "filePath": "/Users/local/images/fido.jpg"
    }
  }
}

原始二进制示例：

{
  "apiName": "pet-api",
  "endpointId": "uploadRaw",
  "contentType": "application/octet-stream",
  "files": {
    "body": {
      "filePath": "/Users/local/data.bin"
    }
  }
}

MCP 工具

这 5 个工具涵盖了主要的用户工作流：

工具	用途
list_apis	列出已配置的 API
list_api_endpoints	搜索或分页列出一个 API 中的端点
get_api_endpoint	检查端点元数据、参数、响应和安全性
get_api_schema	从规范中返回架构对象或 JSON Pointer 目标
make_endpoint_request	预览或执行端点请求

开发

npm install
npm run build
npm test

常用命令：

npm run lint
npm run format
npm run test:watch

许可证

MIT