OpenAPI MCP Server (JavaScript)

一个纯JavaScript实现的Model Context Protocol (MCP)服务器，它将OpenAPI 3.x规范转换为MCP工具，使大型语言模型（LLMs）能够通过标准化的MCP协议与REST API进行交互。

特性

• 纯JavaScript：使用Node.js和ES模块构建
• 支持OpenAPI 3.x：自动将OpenAPI规范转换为MCP工具
• Bearer Token认证：支持API请求的Bearer Token认证
• 所有HTTP方法：支持GET、POST、PUT、DELETE、PATCH、OPTIONS和HEAD
• 可配置的基础URL：接受自定义API基础URL
• 参数验证：根据OpenAPI模式验证工具参数
• 错误处理：全面的错误处理和报告
• 命令行界面：易于使用的命令行界面

安装

npm install

使用

快速开始

1. 验证您的OpenAPI规范：

node src/index.js validate -s UserQueueList.json

2. 启动MCP服务器：

node src/index.js serve -s UserQueueList.json -b https://api.example.com -t your-bearer-token

命令行选项

serve - 启动MCP服务器

node src/index.js serve [options]

选项:
  -s, --spec <path>       OpenAPI规范文件路径（必需）
  -b, --base-url <url>    API请求的基础URL
  -t, --token <token>     认证的Bearer Token
  --timeout <ms>          请求超时时间（毫秒，默认：30000）
  --transport <type>      传输类型（stdio或http，默认：stdio）
  --http-port <port>      HTTP服务器端口（当使用http传输时，默认：3000）
  --http-host <host>      HTTP服务器主机（当使用http传输时，默认：localhost）

validate - 验证OpenAPI规范

node src/index.js validate -s <path-to-spec>

info - 显示服务器信息

node src/index.js info

环境变量

您可以使用环境变量代替命令行参数：

export OPENAPI_BASE_URL=https://api.example.com
export OPENAPI_BEARER_TOKEN=your-bearer-token
node src/index.js serve -s UserQueueList.json

node src/index.js serve -s UserQueueList.json --transport=http --http-port=8020

配置

OpenAPI规范要求

• 必须是OpenAPI 3.x格式
• JSON格式（.json扩展名）
• 必须包含至少一个路径/操作
• 在安全方案中应定义Bearer Token认证

示例OpenAPI安全配置

{
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "bearer": []
    }
  ]
}

工具生成

服务器会自动将OpenAPI操作转换为MCP工具：

工具命名

1. 如果可用，则使用operationId
2. 回退到操作summary（已清理）
3. 最后选择：{method}_{path}（已清理）

参数映射

• 路径参数：必需的字符串参数
• 查询参数：基于OpenAPI模式的可选参数
• 头部参数：以header_前缀
• 请求体：对象属性或requestBody参数

示例工具

对于UserQueueList.json规范：

// 工具：ListUsers (GET /domains/~/users/list)
{
  "name": "ListUsers",
  "description": "列出域中的用户基本信息",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

// 工具：ListCallqueues (GET /domains/~/callqueues/list)
{
  "name": "ListCallqueues", 
  "description": "读取域中的呼叫队列基本信息",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

MCP集成

与Claude Desktop一起使用

Stdio传输（默认）

添加到您的Claude Desktop配置（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "openapi-server": {
      "command": "node",
      "args": [
        "/path/to/your/project/src/index.js",
        "serve",
        "-s", "/path/to/UserQueueList.json",
        "-b", "https://your-api-domain.com",
        "-t", "your-bearer-token"
      ]
    }
  }
}

HTTP传输

对于HTTP传输，配置服务器URL：

{
  "mcpServers": {
    "openapi-server": {
      "url": "http://localhost:3000/message"
    }
  }
}

然后单独启动服务器：

node src/index.js serve -s UserQueueList.json --transport http --http-port 3000

工具响应

服务器返回结构化的JSON响应：

成功响应：

{
  "status": 200,
  "statusText": "OK",
  "data": {
    // API响应数据
  }
}

错误响应：

{
  "error": true,
  "status": 404,
  "statusText": "未找到",
  "message": "域未找到",
  "data": {
    "code": 404,
    "message": "示例域不存在"
  }
}

传输协议

Stdio传输

• 默认传输方式
• 使用标准输入/输出流进行通信
• 最适合与Claude Desktop和其他MCP客户端集成
• 自动进程管理

HTTP传输

• 使用HTTP服务器发送事件（SSE）进行通信
• 允许远程连接和调试
• 对于开发和测试非常有用
• 可配置主机和端口

API示例

基于UserQueueList.json规范：

列出用户

// 工具调用
{
  "name": "ListUsers",
  "arguments": {}
}

// 响应：包含基本信息的用户对象数组

列出呼叫队列

// 工具调用
{
  "name": "ListCallqueues",
  "arguments": {}
}

// 响应：包含配置的呼叫队列对象数组

开发

项目结构

src/
├── index.js              # CLI入口点
├── server.js             # MCP服务器实现
├── openapi-processor.js  # OpenAPI规范处理器
├── http-client.js        # API请求的HTTP客户端
└── utils.js              # 实用函数

关键组件

• MCPServer：主要的MCP服务器类，负责工具注册和执行
• OpenAPIProcessor：解析OpenAPI规范并生成工具定义
• HttpClient：处理带有认证和错误处理的HTTP请求
• CLI：具有验证和配置选项的命令行界面

错误处理

服务器提供全面的错误处理：

• 验证错误：针对OpenAPI模式的参数验证
• HTTP错误：正确处理API错误响应
• 认证错误：清晰的认证失败消息
• 网络错误：超时和连接错误处理

安全考虑

• 安全处理Bearer Tokens且不记录
• 请求验证防止注入攻击
• 错误消息不会暴露敏感信息
• 推荐使用HTTPS进行所有API通信

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如适用，请添加测试
5. 提交拉取请求

许可

MIT许可 - 查看LICENSE文件获取详细信息

故障排除

常见问题

1. “工具未找到”错误：检查您的OpenAPI规范是否有效，并包含预期的操作
2. 认证失败：验证您的Bearer Token是否正确且具有适当的权限
3. 网络超时：增加超时时间或检查API端点的可用性
4. 模式验证错误：确保您的OpenAPI规范遵循3.x标准

调试模式

为了详细的日志记录，您可以修改服务器以启用调试输出：

# 服务器将日志输出到stderr以兼容MCP
node src/index.js serve -s UserQueueList.json -b https://api.example.com -t token 2>debug.log

验证

在使用之前始终验证您的OpenAPI规范：

node src/index.js validate -s UserQueueList.json

这将显示：

• ✅ 验证状态
• 📄 规范详情
• 🔧 可用工具
• 🔐 安全方案
• 🌐 基础URL信息