Mini Openapi MCP

OpenAPI MCP 服务器（JavaScript）

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

特点/功能

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

安装

npm install

使用方法

快速入门

1. 验证您的OpenAPI规范：

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

1. 启动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]

Options:
  -s, --spec 
       Path to OpenAPI specification file (required)
  -b, --base-url     Base URL for API requests
  -t, --token      Bearer token for authentication
  --timeout           Request timeout in milliseconds (default: 30000)
  --transport       Transport type (stdio or http, default: stdio)
  --http-port 
      HTTP server port (when using http transport, default: 3000)
  --http-host       HTTP server host (when using http transport, default: localhost)

validate - 验证OpenAPI规范

node src/index.js validate -s 

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 （扩展）
• 必须至少包含一条路径/操作
• 在安全方案中应定义承载令牌认证

示例 OpenAPI 安全配置

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

工具生成

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

工具命名

1. 用途 operationId 如果可用
2. 返回操作 summary （已消毒/已净化）
3. 最后的手段/退路 {method}_{path} （已消毒）

参数映射

• 路径参数所需的字符串参数
• 查询参数基于OpenAPI规范的可选参数
• 头部参数以……为前缀 header_
• 请求体对象属性或 requestBody 参数

示例工具

对于UserQueueList.json规范：

// Tool: ListUsers (GET /domains/~/users/list)
{
  "name": "ListUsers",
  "description": "List Basic Info on Users in Domain",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

// Tool: ListCallqueues (GET /domains/~/callqueues/list)
{
  "name": "ListCallqueues", 
  "description": "Read Basic info on Call Queues in Domain",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

MCP 集成

与Claude桌面版配合使用

标准I/O传输（默认）

添加到您的Claude桌面配置中（~/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 response data
  }
}

错误响应：

{
  "error": true,
  "status": 404,
  "statusText": "Not Found",
  "message": "Domain not found",
  "data": {
    "code": 404,
    "message": "Domain example does not exist"
  }
}

传输协议

Stdio 传输

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

HTTP传输

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

API示例

基于UserQueueList.json规范：

列出用户

// Tool call
{
  "name": "ListUsers",
  "arguments": {}
}

// Response: Array of user objects with basic information

列出呼叫队列

// Tool call  
{
  "name": "ListCallqueues",
  "arguments": {}
}

// Response: Array of call queue objects with configuration

发展

项目结构

src/
├── index.js              # CLI entry point
├── server.js             # MCP server implementation
├── openapi-processor.js  # OpenAPI specification processor
├── http-client.js        # HTTP client for API requests
└── utils.js              # Utility functions

关键组件

• MCPServer（可译为“MCPS服务器”或根据具体上下文保持原样，若“MCPS”为特定项目或系统的缩写，则需根据实际情况翻译）主要MCP服务器类，负责处理工具注册和执行
• OpenAPI处理器解析OpenAPI规范并生成工具定义
• HttpClient（HTTP客户端）处理带有认证和错误处理的HTTP请求
• CLI（Command Line Interface）即命令行界面带有验证和配置选项的命令行界面

错误处理

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

• 验证错误根据OpenAPI模式进行参数验证
• HTTP 错误正确处理API错误响应
• 认证错误明确的认证失败消息
• 网络错误超时和连接错误处理

安全考虑事项

• 承载令牌（Bearer tokens）以安全方式处理，不会被记录
• 请求验证可防止注入攻击
• 错误信息不会泄露敏感信息
• 对于所有API通信，建议使用HTTPS

贡献；助力

1. 为仓库创建分支（或“克隆仓库”）
2. 创建一个特性分支
3. 进行你的更改
4. 如适用，请添加测试
5. 提交拉取请求

许可证

MIT 许可证 - 详情请参见 LICENSE 文件

故障排除

常见问题

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

调试模式

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

# The server logs to stderr for MCP compatibility
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信息