使用说明

OpenAPI MCP服务器

此应用程序基于其OpenAPI模式将任何REST API公开为MCP（模型上下文协议）服务器。它通过OpenAPI操作自动生成MCP工具，并提供全面的OpenAPI 3.0+支持。

特性

完整的OpenAPI 3.0+支持：从JSON和YAML格式解析模式
高级模式处理：完整的$ref解析，组合模式（oneOf、anyOf、allOf）
丰富的工具生成：具有详细描述、验证和元数据的自动MCP工具
多种内容类型：支持JSON、XML、表单数据和多部分上传
参数处理：具有类型转换和验证的路径、查询、标头参数
认证：HTTP基本身份验证和自定义标头支持
增强的错误处理：包含请求上下文的详细错误消息
类型安全：具有全面验证的完整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> -基本身份验证的用户名
-p, --password <password> -基本身份验证密码

例子

# 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基本认证

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

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

当提供基本身份验证凭据时：

必须同时指定用户名和密码（不能只提供一个）
凭据经过base64编码并发送到 Authorization: Basic <encoded> 头球
所有API请求将自动包含身份验证头

附加标题

您还可以使用 --headers 选项：

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

备注：基本身份验证（--username/--password）和其他标头可以一起使用。如果两者都包含授权标头，则其他标头将优先。

添加到Claude桌面

要将此MCP服务器与Claude Desktop一起使用，您需要将其添加到Claude Desktop配置文件中。

配置文件位置

配置文件位于：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

配置步骤

构建服务器 （如果你还没有）：
```
npm install
npm run build
```
打开或创建Claude Desktop配置文件 在上面的位置。

添加MCP服务器配置:

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

替换路径 根据您的实际路径：
- 替换 /path/to/your/openapi-mcp-server/ 包含克隆/下载此项目的完整路径
- 替换 /path/to/your/openapi-schema.yaml 带有OpenAPI模式文件的完整路径

示例配置

以下是显示不同身份验证方法的示例配置：

基本身份验证

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

承载令牌身份验证

{
  "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> -基本身份验证的用户名
--password <password> -基本身份验证密码

重新启动克劳德桌面

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

验证

一旦配置并重新启动，您应该能够在与Claude的对话中使用API工具。这些工具将根据您的OpenAPI模式自动生成，并将包括配置的身份验证。

运作原理

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

支持的OpenAPI功能

✅ 完整的参数支持：带验证的路径、查询、标头参数
✅ 所有内容类型：JSON、XML、表单url编码、多部分/表单数据等
✅ 高级架构功能：$ref解析，oneOf/anyOf/allOf组合，嵌套对象
✅ 类型验证：完整的JSON模式验证，支持格式（电子邮件、uuid等）
✅ 认证：HTTP基本身份验证和自定义标头支持
✅ 丰富的描述：工具描述包括摘要、标签、响应代码
✅ 错误处理：包含请求上下文的详细错误消息
✅ 类型转换：自动参数类型转换（字符串到数字/布尔值/数组）
✅ 模式规范化：自动生成缺失的操作ID和响应
✅ 多种HTTP方法：获取、发布、放置、修补、删除、选项、头部

所做的改进

此增强版本包括对基本实现的重大改进：

模式处理

完整的$ref解决方案：支持所有引用类型，包括嵌套引用和循环引用
组合模式：完全支持oneOf、anyOf、allOf，并显示描述性错误消息
验证约束条件：最小/最大值、字符串长度、模式、带有增强描述的枚举
格式支持：内置格式验证（电子邮件、uuid、日期时间等）

工具生成

丰富的描述：组合摘要、描述、标记和响应信息
增强元数据：存储操作元数据以改进工具执行上下文
内容类型检测：智能地确定内容类型的优先级（JSON>XML>其他）
参数验证：具有详细错误消息的全面验证

API客户端

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

测试与质量

综合测试套件：集成测试的测试覆盖率超过90%
TypeScript：整个代码库的完全类型安全
ESLint配置：代码质量执行
Jest配置：具有覆盖率报告功能的现代测试设置

安全考虑

命令行凭据：使用基本身份验证时，凭据通过命令行参数传递，这些参数可能在系统进程列表中可见
Base64编码：HTTP基本身份验证根据标准使用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

建筑

增强的实施包括几个关键组成部分：

模式加载器：通过全面的错误报告验证和规范OpenAPI模式
工具生成器：将OpenAPI操作转换为具有丰富元数据和验证的MCP工具
API客户端：执行带有自动类型转换和详细错误处理的HTTP请求
服务器：MCP服务器实现与工具元数据集成

许可证

麻省理工学院