Openapi Dynamic MCP

openapi-dynamic-mcp

Connect AI clients to OpenAPI APIs quickly, with one MCP server, direct CLI access, and built-in auth support.

目录

• 概述
• 亮点
• 需求
• 快速开始
• 配置
• 客户端设置
• 命令行界面
• 认证
• 环境变量
• 处理响应
• 文件和二进制数据
• MCP工具
• 发展
• 许可证

概述

openapi-dynamic-mcp 允许MCP客户端和shell用户使用OpenAPI API，而无需为每个服务编写自定义粘合代码。将其指向一个或多个OpenAPI规范，然后列出API，检查端点，进行身份验证，并通过一致的接口发出请求。

它专为常见的用户工作流程而设计：

• 通过一个MCP服务器连接多个API
• 使用本地规范或托管 specUrl 定义
• 使用OpenAPI 3.0, 3.1和斯瓦格 2.0
• 处理API密钥、承载、基本和OAuth2身份验证
• 跨会话重用存储的令牌
• 将大型响应筛选到所需的字段
• 在发送请求之前安全预览请求

亮点

• 快速从规范到可用工具：从YAML配置开始，立即浏览端点或从MCP或CLI调用端点。
• 按照API期望的方式进行身份验证：使用PKCE支持API密钥、承载/基本身份验证和OAuth2客户端凭据、密码、设备代码和身份验证代码。
• 避免重复登录工作：存储令牌一次，以后再使用。
• 干净地处理交互式OAuth：设备代码和基于浏览器的身份验证返回代理可以呈现给用户的指令。
• 保持反应集中：使用JSONPath选择器投影大型输出。
• 发送前检查：使用模拟运行预览请求形状，无需网络I/O。
• 需要时上传文件：支持多部分表单上传和原始二进制体。
• 保持对利率限制的弹性：可配置的重试次数 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

配置

添加要在下使用的每个API apis每个条目都可以指向本地规范文件或远程规范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配置

使用 oauth2Schemes 当API定义一个或多个OAuth2安全方案，并且您希望为特定方案设置令牌URL、作用域或交互式身份验证首选项时。

方案名称必须与OpenAPI规范中的名称匹配。常见选项包括：

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

如果你只需要凭据，环境变量通常就足够了。使用 oauth2Schemes 当您希望将可重用的配置签入项目时。

客户端设置

克劳德桌面/克劳德代码

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

光标

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

命令行界面

服务器模式可用作root命令或显式命令 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对象
• --fields ：用于过滤成功输出的可重复选择器
• --describe：打印命令模式和帮助元数据
• `--auth-file

`：重写身份验证存储路径

身份验证命令

使用 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密钥和承载认证， --token 直接提供秘密。对于OAuth2，该命令使用您配置的凭据，完成流程，并存储结果以供以后使用。

认证

支持的身份验证类型：

• API密钥
• HTTP承载
• HTTP基本
• 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代理可以将其转发给用户。典型的设备代码输出如下：

{
  "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代理特别有用，因为身份验证步骤成为用户工作流的正常部分，而不是死胡同错误。

环境变量

环境变量对于机密、基本URL覆盖和CI设置很有用。

名称来源于规范化的API和方案名称：

• 大写字母
• 非字母数字字符变为 _
• 重复的 _ 坍塌
• 领先和落后 _ 已删除

示例：

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

API级别变量

• _BASE_URL
• _HEADERS 作为JSON对象字符串
• OPENAPI_DYNAMIC_MCP_AUTH_FILE

API密钥

• __API_KEY

HTTP身份验证

• __TOKEN
• __USERNAME
• __PASSWORD

OAuth2

• __ACCESS_TOKEN
• __CLIENT_ID
• __CLIENT_SECRET
• __TOKEN_URL
• __SCOPES 以空格分隔的列表形式
• __TOKEN_AUTH_METHOD 作为 client_secret_basic 或 client_secret_post
• __USERNAME
• __PASSWORD
• __AUTH_METHOD 作为 device_code 或 authorization_code
• __DEVICE_AUTHORIZATION_ENDPOINT
• __REDIRECT_PORT
• __PKCE 作为 true 或 false

有用的行为：

• _ACCESS_TOKEN 完全绕过OAuth授权流。
• _AUTH_METHOD 力量 device_code 或 authorization_code 当两者都有可能时。
• _USERNAME 和 _PASSWORD 根据安全方案，用于HTTP基本身份验证和OAuth密码授予。

处理响应

JSONPath过滤

命令行界面 --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 添加a _sizeWarning 当响应非常大时，会提示您缩小JSON指针的范围。

演习

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"
}

多部分示例：

{
  "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工具

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

发展

npm install
npm run build
npm test

有用的命令：

npm run lint
npm run format
npm run test:watch

许可证

麻省理工学院