Snaggle Ai Openapi MCP Server

🚀 OpenAPI MCP 服务器

OpenAPI MCP 服务器可创建一个 Model Context Protocol (MCP) 服务器，作为任何具有 OpenAPI v3.1 规范的 API 的代理。借助它，你能使用 Claude Desktop 轻松与本地和远程服务器上的 API 进行交互，实现通过自然语言与 API 对话的便捷操作。

🚀 快速开始

配置 Claude Desktop

将以下内容添加到您的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "petstore-api": {
      "command": "npx",
      "args": ["openapi-mcp-server", "/绝对/路径/to/petstore-openapi.json"]
    }
  }
}

重启并交互

重新启动 Claude Desktop，即可开始与您的 API 进行交互！

✨ 主要特性

自动转换端点

此代理能够自动将 OpenAPI 端点转换为 Claude 工具，让 Claude 可以发现可用的 API 端点并了解其目的，知晓所需的参数及其类型，代表您进行 API 调用，还能适当处理响应。例如，对于 Petstore API 的 /pets/{petId} 端点：

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

Claude 能够通过自然语言理解并执行此端点，返回有关宠物的详细信息。

文件上传支持

除了处理标准 API 请求外，OpenAPI MCP 服务器还支持文件上传。具体配置方式如下：

1. 在 OpenAPI 规范中定义 FormData 参数：

parameters:
  - name: file
    in: formData
    required: true
    schema:
      type: string
      format: binary

2. 在服务器端处理文件上传：

const uploadedFile = await request.file('file');
// 处理上传的文件

💻 使用示例

此仓库包含一个完整的 Petstore API 服务器示例，可用于测试 OpenAPI MCP 服务器。该示例服务器实现了一个基本的 CRUD API 来管理宠物，是学习使用此工具的理想选择。有关如何运行示例服务器，请参阅 examples/README.md。

📚 详细文档

使用场景

本地开发

• 通过自然对话测试您的 APIs。
• 在编写代码之前调试端点。
• 交互式探索 API 功能。

API 集成

• 快速测试第三方 API。
• 在编写代码之前进行原型设计。
• 通过对话了解新的 API。

文档

• 提问关于 API 端点的问题。
• 获取使用端点的示例。
• 理解错误条件。

局限性

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

🔧 技术细节

开发操作

未完成的任务列在 TODO.md 中。基础操作如下：

# 安装依赖项
pnpm install

# 运行测试
pnpm test

# 构建项目
pnpm build

# 将项目链接到全局 node_modules 以便使用 npx
npm link

# 现在启动 Claude Desktop 开始使用

# 在进行更改后再次运行构建以更新 Claude Desktop
pnpm build

# 现在重新启动 Claude Desktop 使用最新更改

📄 许可证

本项目采用 MIT 许可证。

本项目由 ❤️ 打造，旨在通过自然语言使 API 更具 accessibility。

⚠️ 重要提示

如果您遇到 Claude 崩溃或规范无法使用的问题，请通过我们的 规格清理应用程序 进行处理，该工具会整理一些 OpenAPI 模式以帮助其成为 LLM 可读格式。