AI导哈

OpenAPI代理服务

该服务通过Model Context Protocol (MCP)服务器将OpenAPI v3.1规范转换为Claude工具，使Claude能够发现、理解并调用API端点，支持文件上传和自然语言交互。

  • by asabya
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 asabya/openapi-mcp-server

使用说明

OpenAPI MCP服务器

这是openapi-mcp服务器v2之前的一个分支。它主要是为将来使用提供备份/故障保护

通过Claude Desktop与任何符合OpenAPI（v3.1）的API对话！

此工具创建 模型上下文协议（MCP） 作为任何具有OpenAPI v3.1规范的API的代理的服务器。这允许您使用Claude Desktop轻松地与本地和远程服务器API进行交互。

如果你遇到克劳德崩溃或规格不工作的问题，请通过我们的 spec清洁器应用程序 这整理了一些开放的api模式，以帮助它们具有LLM可读性。

它有什么作用？

此代理自动将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将此视为一个可以使用的工具：

然后，你可以问克劳德一些自然的问题，比如：

  • “你能获取宠物ID 123的详细信息吗？”
  • “ID为456的宠物的状态如何？”

Claude将理解上下文并进行适当的API调用。

文件上传支持

该代理支持接受多部分/表单数据的API的文件上传。当端点接受文件上传时（由表示 type: string, format: binary 在OpenAPI规范中），您可以提供本地文件路径，代理将处理读取和上传文件。

示例用例

  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 }

你可以问克劳德：

  • “从~/Pictures/profile.jpg上传我的新个人资料图片”
  • “用~/Downloads/photo.png更新我的头像，并将其裁剪为200x200”
  1. 文档处理
/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并将语言设置为法语”
  1. 批量文件上传
/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，并标记为“月度报告”
  • 处理~/exports/中带有“原始数据”、“june-2023”标签的文件

重要注意事项

  1. 安全

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

  2. 演出

    • 大型文件直接从磁盘流式传输到API
    • 内存使用针对大文件进行了优化
    • 进度报告可用于大型上传

  3. 局限性

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

入门指南

  1. 配置Claude桌面： 将此添加到您的 claude_desktop_config.json:

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

  2. 重新启动克劳德桌面 并开始与您的API交互！

例子

此存储库包含Petstore API服务器的完整示例，您可以使用它来测试OpenAPI MCP服务器。示例服务器实现了用于管理宠物的基本CRUD API，非常适合学习如何使用此工具。

看 示例/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 类，以便在不经过LLM的情况下直接进行API调用：

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路径参数替换
  • 查询字符串格式
  • 请求正文格式
  • 文件上传（多部分/表单数据）
  • 错误处理

许可证

麻省理工学院

内置于❤️ 使API更易于通过自然语言访问。

相关 MCP