OpenAPI MCP Server

OpenAPI MCP 服务

这是 openapi-mcp-server v2 之前版本的一个分支，主要作为备份和故障保护，以备将来使用。

通过 Claude Desktop 与任何符合 OpenAPI (v3.1) 规范的 API 对话！

此工具会创建一个 Model Context Protocol (MCP) 服务，充当任何具有 OpenAPI v3.1 规范的 API 的代理。这样一来，你就可以使用 Claude Desktop 轻松与本地和远程服务 API 交互。

如果你遇到 Claude 崩溃或规范无法使用的问题，请通过我们的规范清理应用处理，它可以整理部分 OpenAPI 架构，帮助大模型读取。

它有什么作用？

此代理会自动将 OpenAPI 端点转换为 Claude 工具，让 Claude 能够：

1. 发现可用的 API 端点并了解其用途
2. 知道所需的参数及其类型
3. 代表你调用 API
4. 妥善处理响应

例如，如果你有一个 Petstore API，其中包含以下端点：

/pets/{petId}:
  get:
    operationId: getPetById
    summary: Returns a pet by ID
    parameters:
      - name: petId
        in: path
        description: ID of pet to return
        required: true
        schema:
          type: integer

Claude 会将其识别为可用工具：

然后，你可以向 Claude 提出自然语言问题，例如：

• “你能获取 ID 为 123 的宠物详情吗？”
• “ID 为 456 的宠物目前是什么状态？”

Claude 会理解上下文并进行相应的 API 调用。

文件上传支持

此代理支持使用 multipart/form-data 的 API 上传文件。当端点接受文件上传时（在 OpenAPI 规范中标记为 type: string, format: binary），你可以提供本地文件路径，代理会负责读取并上传文件。

示例用例

1. 上传个人资料图片

/users/{userId}/avatar:
  post:
    summary: Upload a user's profile picture
    requestBody:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              avatar:
                type: string
                format: binary
                description: Profile picture (JPEG/PNG)
              cropInfo:
                type: object
                properties:
                  x: { type: number }
                  y: { type: number }
                  width: { type: number }
                  height: { type: number }

你可以向 Claude 提出以下请求：

• “从 ~/Pictures/profile.jpg 上传我的新个人资料图片”
• “使用 ~/Downloads/photo.png 更新我的头像，并将其裁剪为 200x200”

2. 文档处理

/documents:
  post:
    summary: Upload documents for processing
    requestBody:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              document:
                type: string
                format: binary
                description: PDF or Word document
              language:
                type: string
                enum: [en, es, fr]
                description: Document language
              processOCR:
                type: boolean
                description: Whether to extract text using OCR

自然语言命令：

• “使用 OCR 处理 ~/Documents/contract.pdf 中的文档，语言设为英语”
• “上传 ~/Downloads/report.docx 并将语言设为法语”

3. 批量上传文件

/batch-upload:
  post:
    summary: Upload multiple files in one request
    requestBody:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              files:
                type: array
                items:
                  type: string
                  format: binary
              tags:
                type: array
                items:
                  type: string

你可以这样说：

• “上传以下三个文件：/data1.csv、/data2.csv 和 ~/data3.csv，并添加标签 'monthly-report'”
• “处理 ~/exports/ 中的文件，并添加标签 'raw-data'、'june-2023'”

重要注意事项

1. 安全性

   • 文件路径相对于当前工作目录进行解析
   • 只能访问用户有权读取的文件
   • 敏感文件（例如 ~/.ssh/id_rsa）需要用户明确确认
   • 只有在实际发起 API 请求时才会读取文件内容

2. 性能

   • 大文件会直接从磁盘流式传输到 API
   • 已针对大文件优化内存使用
   • 大文件上传时可查看进度

3. 限制

   • 最大文件大小由目标 API 决定
   • 仅支持本地文件（不支持远程 URL）
   • API 可能会限制某些文件类型

开始使用

1. 配置 Claude Desktop： 将以下内容添加到 claude_desktop_config.json：

   {
     "mcpServers": {
       "petstore-api": {
         "command": "npx",
         "args": ["openapi-mcp-server", "/abs/path/to/petstore-openapi.json"]
       }
     }
   }
   

2. 重启 Claude Desktop，然后开始与 API 交互！

示例

此代码库包含一个完整的 Petstore API 服务示例，可用于测试 OpenAPI MCP 服务。示例服务实现了用于管理宠物的基本 CRUD API，非常适合学习如何使用此工具。

请参阅 examples/README.md，了解如何运行示例服务。

CLI 工具

此代码库包含一个用于测试 OpenAPI 端点的命令行工具：

# List all available methods
pnpm tsx examples/cli/openapi-client.ts http://localhost:3000/openapi.json list

# Call a specific method
pnpm tsx examples/cli/openapi-client.ts http://localhost:3000/openapi.json call API-getPetById '{"id": 1}'

CLI 工具演示了如何使用 OpenAPIToMCPConverter 和 HttpClient 类，以编程方式与符合 OpenAPI 规范的服务交互。

使用场景

1. 本地开发

   • 通过自然对话测试 API
   • 无需编写代码即可调试端点
   • 以交互方式探索 API 功能

2. API 集成

   • 快速测试第三方 API
   • 编写代码前先对集成方案进行原型验证
   • 通过对话了解新 API

3. 文档

   • 询问有关 API 端点的问题
   • 获取端点用法示例
   • 了解错误情况

局限性

• 目前仅支持 OpenAPI v3.1 规范
• 响应处理针对 JSON/文本响应进行了优化
• 文件上传仅支持本地文件（不支持远程 URL）
• 尚未实现流式响应

开发

待办事项列于 TODO.md。

基础内容：

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the project
pnpm build

# Link the project to your global node_modules so that npx works
npm link

# Now start claude desktop to use

# After making changes run build again before restarting claude desktop
pnpm build

# Now restart claude desktop to run with latest changes

以编程方式使用 OpenAPIToMCPConverter

如果你想以编程方式将 OpenAPI 规范转换为 MCP 工具，可以使用 OpenAPIToMCPConverter 类：

import { OpenAPIToMCPConverter } from 'openapi-mcp-server'

// Initialize the converter with your OpenAPI spec
const converter = new OpenAPIToMCPConverter(openApiSpec)

// Convert to OpenAI tools format
const openAiTools = await converter.convertToOpenAITools()

// Convert to Anthropic tools format
const anthropicTools = await converter.convertToAnthropicTools()

// Convert to MCP tools format
const { tools, openApiLookup } = converter.convertToMCPTools()

转换器支持多种工具格式，因此可以轻松集成到不同的 LLM 提供商。转换后的工具会保留 OpenAPI 规范中的所有类型信息和描述，确保参数验证准确，并提供有用的文档。

以编程方式发起 API 调用

你可以使用 HttpClient 类直接发起 API 调用，无需经过 LLM：

import { HttpClient, OpenAPIToMCPConverter } from 'openapi-mcp-server'

// Initialize the converter and client
const converter = new OpenAPIToMCPConverter(openApiSpec)
const httpClient = new HttpClient({ baseUrl: 'https://api.example.com' }, openApiSpec)

// Get operation details from the converter
const { openApiLookup } = converter.convertToMCPTools()
const operation = openApiLookup['API-getPetById']

// Make the API call
const response = await httpClient.executeOperation(operation, {
  petId: 123
})

HttpClient 负责处理：

• 参数验证
• URL 路径参数替换
• 查询字符串格式化
• 请求正文格式化
• 文件上传（multipart/form-data）
• 错误处理

许可证

MIT

---

用 ❤️ 构建，让更多人可以通过自然语言轻松使用 API。