OpenAPI Mcp Server

OpenAPI MCP 服务

此应用可根据 OpenAPI 架构，将任何 REST API 暴露为 MCP（Model Context Protocol）服务。它会根据 OpenAPI 操作自动生成 MCP 工具，并全面支持 OpenAPI 3.0+。

功能

• 全面支持 OpenAPI 3.0+：解析 JSON 和 YAML 格式的架构
• 高级架构处理：完整解析 $ref、组合架构（oneOf、anyOf、allOf）
• 丰富的工具生成：自动生成带有详细描述、验证和元数据的 MCP 工具
• 多种内容类型：支持 JSON、XML、表单数据和 multipart 上传
• 参数处理：支持路径、查询和标头参数，并进行类型转换和验证
• 身份验证：支持 HTTP Basic 身份验证和自定义标头
• 增强的错误处理：提供包含请求上下文的详细错误消息
• 类型安全：使用 TypeScript 完整实现，并提供全面验证
• 测试：包含覆盖率超过 90% 的完整测试套件

安装

npm install
npm run build

用法

npm start -- --schema <path-to-openapi-schema> [options]

选项

• -s, --schema <path> - OpenAPI 架构文件的路径（JSON 或 YAML）[必需]
• -b, --base-url <url> - 覆盖架构中的基础 URL
• -h, --headers <headers> - 以 JSON 字符串形式提供额外标头
• -u, --username <username> - Basic 身份验证的用户名
• -p, --password <password> - Basic 身份验证的密码

示例

# Basic usage with a local schema file
npm start -- --schema ./api-schema.yaml

# Override base URL
npm start -- --schema ./api-schema.json --base-url https://api.example.com

# Add authentication headers
npm start -- --schema ./api-schema.yaml --headers '{"Authorization": "Bearer your-token"}'

# Use basic authentication
npm start -- --schema ./api-schema.yaml --username myuser --password mypass

# Combine basic auth with custom base URL
npm start -- --schema ./api-schema.yaml --base-url https://api.example.com --username admin --password secret123

身份验证

HTTP Basic 身份验证

此服务支持通过命令行参数提供用户名和密码来进行 HTTP Basic 身份验证：

npm start -- --schema ./api-schema.yaml --username myuser --password mypassword

提供 Basic 身份验证凭据时：

• 必须同时指定用户名和密码（不能只提供其中一项）
• 凭据会进行 Base64 编码，并通过 Authorization: Basic <encoded> 标头发送
• 所有 API 请求都会自动包含身份验证标头

额外标头

你也可以使用 --headers 选项提供额外标头（包括自定义身份验证）：

npm start -- --schema ./api-schema.yaml --headers '{"Authorization": "Bearer token", "X-API-Key": "key123"}'

注意：Basic 身份验证（--username/--password）和额外标头可以同时使用。如果两者都包含 Authorization 标头，则以额外标头为准。

添加到 Claude Desktop

若要在 Claude Desktop 中使用此 MCP 服务，需要将其添加到 Claude Desktop 配置文件中。

配置文件位置

配置文件位于：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

配置步骤

1. 构建服务（如果尚未构建）：

   npm install
   npm run build
   

2. 打开或创建 Claude Desktop 配置文件，文件位置如上所示。

3. 添加 MCP 服务配置：

   {
     "mcpServers": {
       "openapi-server": {
         "command": "node",
         "args": [
           "/path/to/your/openapi-mcp-server/dist/index.js",
           "--schema",
           "/path/to/your/openapi-schema.yaml"
         ]
       }
     }
   }
   

4. 将路径替换为实际路径：

   • 将 /path/to/your/openapi-mcp-server/ 替换为你克隆或下载此项目所在位置的完整路径
   • 将 /path/to/your/openapi-schema.yaml 替换为你的 OpenAPI 架构文件的完整路径

配置示例

以下示例展示了不同身份验证方式的配置：

Basic 身份验证

{
  "mcpServers": {
    "secure-api": {
      "command": "node",
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/openapi-mcp-server/api-schema.yaml",
        "--username",
        "apiuser",
        "--password",
        "secret123"
      ]
    }
  }
}

Bearer 令牌身份验证

{
  "mcpServers": {
    "xmpt-api": {
      "command": "node",
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/openapi-mcp-server/schema.yaml",
        "--base-url",
        "https://api.your.service",
        "--headers",
        "{\"Authorization\": \"Bearer your-api-token\"}"
      ]
    }
  }
}

多个 API 配置

{
  "mcpServers": {
    "secure-api": {
      "command": "node",
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/schemas/secure-api.yaml",
        "--username",
        "admin",
        "--password",
        "password123"
      ]
    },
    "public-api": {
      "command": "node", 
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/schemas/public-api.json"
      ]
    }
  }
}

配置选项

将服务添加到 Claude Desktop 时，可以使用所有相同的命令行选项：

• --schema <path> - OpenAPI 架构文件的路径（必需）
• --base-url <url> - 覆盖架构中的基础 URL
• --headers <json> - 以 JSON 字符串形式添加身份验证或其他标头
• --username <username> - Basic 身份验证的用户名
• --password <password> - Basic 身份验证的密码

重启 Claude Desktop

修改配置文件后，请重启 Claude Desktop 以使更改生效。

验证

配置并重启后，你应该能够在与 Claude 的对话中使用 API 工具。这些工具会根据你的 OpenAPI 架构自动生成，并包含已配置的身份验证。

工作原理

1. 架构加载：从 JSON 或 YAML 文件加载并验证 OpenAPI 3.0+ 架构
2. 工具生成：为每个 API 操作自动创建 MCP 工具
3. 身份验证设置：如果提供了凭据，则配置 HTTP Basic 身份验证
4. 参数映射：将 OpenAPI 参数映射到 MCP 工具输入架构
5. 请求执行：使用提供的参数和身份验证执行 HTTP 请求
6. 响应处理：返回格式化的响应，包括状态、标头和数据

支持的 OpenAPI 功能

• ✅ 完整的参数支持：路径、查询和标头参数，支持验证
• ✅ 所有内容类型：JSON、XML、form-urlencoded、multipart/form-data 等
• ✅ 高级架构功能：$ref 解析、oneOf/anyOf/allOf 组合、嵌套对象
• ✅ 类型验证：完整的 JSON Schema 验证，支持格式（email、uuid 等）
• ✅ 身份验证：支持 HTTP Basic Auth 和自定义标头
• ✅ 丰富的描述：工具描述包含摘要、标签和响应代码
• ✅ 错误处理：提供详细的错误信息和请求上下文
• ✅ 类型转换：自动转换参数类型（字符串转为数字/布尔值/数组）
• ✅ 架构规范化：自动生成缺失的 operationId 和响应
• ✅ 多种 HTTP 方法：GET、POST、PUT、PATCH、DELETE、OPTIONS、HEAD

改进内容

与基本实现相比，此增强版本进行了显著改进：

架构处理

• 完整的 $ref 解析：支持所有引用类型，包括嵌套和循环引用
• 组合架构：全面支持 oneOf、anyOf、allOf，并提供描述性错误信息
• 验证约束：最小/最大值、字符串长度、模式、枚举，并提供增强的描述
• 格式支持：内置格式验证（email、uuid、date-time 等）

工具生成

• 丰富的描述：整合摘要、描述、标签和响应信息
• 增强的元数据：存储操作元数据，以改善工具执行上下文
• 内容类型检测：智能优先选择内容类型（JSON > XML > 其他）
• 参数验证：全面验证，并提供详细的错误信息

API 客户端

• 类型转换：自动将字符串输入转换为适当的类型
• 内容类型处理：智能检测内容类型并处理请求体
• 错误增强：详细的错误信息包括请求 URL、方法和响应数据
• 参数处理：高级参数验证和类型强制转换

测试与质量

• 全面的测试套件：测试覆盖率达 90% 以上，并包含集成测试
• TypeScript：整个代码库具备完整的类型安全性
• ESLint 配置：强制执行代码质量要求
• Jest 配置：采用现代化测试设置，并提供覆盖率报告

安全注意事项

• 命令行凭据：使用基本身份验证时，凭据会通过命令行参数传递，可能会显示在系统进程列表中
• Base64 编码：按照标准，HTTP Basic Authentication 使用 Base64 编码（而非加密）
• 建议使用 HTTPS：传输身份验证凭据时，始终使用 HTTPS 端点
• 环境变量：在生产环境中，建议使用环境变量存储敏感凭据

开发

# Install dependencies
npm install

# Development mode with auto-reload
npm run dev -- --schema ./example-schema.yaml

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint the code
npm run lint

# Fix linting issues
npm run lint:fix

测试

项目包含全面的测试，涵盖：

• 单元测试：针对架构加载、工具生成和 API 客户端的单个组件测试
• 集成测试：使用复杂 OpenAPI 架构进行端到端工作流测试
• 边缘情况：错误处理、循环引用、格式错误的架构
• 类型安全：全面的 TypeScript 覆盖，并进行严格的类型检查

运行测试：

npm test                 # Run all tests
npm run test:watch       # Run tests in watch mode  
npm run test:coverage    # Generate coverage report

架构

增强版实现由以下几个关键组件构成：

• SchemaLoader：验证并规范化 OpenAPI 架构，同时提供全面的错误报告
• ToolGenerator：将 OpenAPI 操作转换为 MCP 工具，并提供丰富的元数据和验证
• APIClient：执行 HTTP 请求，并自动进行类型转换和详细的错误处理
• Server：集成工具元数据的 MCP 服务实现

许可证

MIT