从 OpenAPI 到 AI 助手：我开发了一个让 API 文档"活"起来的工具

背景

最近在做一个内部项目时遇到了一个有趣的问题：如何让 Cursor、Cherry Studio 这样的 AI 编程助手能够直接调用我们的 REST API？

传统的做法是写一堆工具函数，手动处理 HTTP 请求，然后让 AI 调用这些函数。但这种方式有个问题：每次 API 更新，都要手动维护这些工具函数。作为一个"懒惰"的程序员，我想着能不能直接从 OpenAPI 文档自动生成这些工具？

经过几周的研究和开发，mcp-swagger-server 诞生了。

什么是 Model Context Protocol (MCP)？

在介绍我的工具之前，先聊聊 MCP。它是 Anthropic 推出的一个标准协议，用于让 AI 助手与外部工具进行交互。简单来说，就是给 AI 助手提供了一套"插件系统"。

但是配置 MCP 服务器还是挺繁琐的，特别是对于已有 OpenAPI 文档的项目。

解决方案：一行命令搞定

我的思路很简单：既然 OpenAPI 文档已经完整描述了 API 的结构，为什么不直接把它转换成 MCP 格式？

于是有了这个工具：

css 复制代码

npm install -g mcp-swagger-server

# 推荐使用 streamable 协议，性能更好，支持双向流式传输
mcp-swagger-server --transport streamable --port 3322 --openapi http://product.com/openapi.json

就这么简单，API 的所有端点都变成了 AI 助手可以直接调用的工具。

实际体验

让我用 GitHub API 做个演示。对于 Cursor 用户，可以在设置中配置 MCP 服务器：

arduino 复制代码

// 首先需要全局安装脚手架
npm install -g mcp-swagger-server

json 复制代码

{
  "mcp.servers": {
    "github-api": {
      "command": "mcp-swagger-server",
      "args": [
        "--transport", "streamable",
        "--port", "3322",
        "--openapi", "https://api.github.com/openapi.json"
      ]
    }
  }
}

Cherry Studio 用户可以在插件管理中添加：

json 复制代码

{
  "name": "GitHub API",
  "type": "mcp-streamable",
  "endpoint": "http://localhost:3322",
  "config": {
    "openapi": "http://products/openapi.json"
  }
}

配置完成后，你可以直接对 AI 助手说："帮我看看我的商品列表"，它就能自动调用 product项目 API 获取数据。

为什么不用现有方案？

市面上确实有一些类似的工具，但都有各自的问题：

配置复杂：需要写大量配置文件
功能单一：只支持特定的传输协议
缺乏灵活性：不支持文件监控、自动重启等开发友好的功能

我希望做一个真正开箱即用的工具。

核心特性

多种传输协议

根据不同场景选择最合适的协议，强烈推荐使用 streamable 协议：

css 复制代码

# Streamable - 双向流式传输（推荐）✨
# 性能最佳，支持实时通信，适合现代 AI 编程工具
mcp-swagger-server --transport streamable --port 3322 --openapi ./api.yaml

# STDIO - AI 客户端集成（如传统工具）
mcp-swagger-server --transport stdio --openapi ./api.yaml

# HTTP - Web 应用集成
mcp-swagger-server --transport http --port 3323 --openapi ./api.yaml

# SSE - 单向流式传输
mcp-swagger-server --transport sse --port 3324 --openapi ./api.yaml

💡 为什么推荐 streamable？

更好的性能：双向流式传输，减少连接开销
实时响应：支持长连接，响应更快
现代化：更适合现代 AI 编程工具的架构
扩展性强：未来功能扩展的最佳基础

开发友好

支持文件监控，OpenAPI 文档一更新，服务器自动重启：

css 复制代码

# 推荐在开发环境使用 streamable + watch
mcp-swagger-server --transport streamable --port 3322 --openapi ./api.yaml --watch

错误恢复

生产环境中的自动重启和错误恢复：

css 复制代码

mcp-swagger-server --transport streamable --openapi ./api.yaml --auto-restart --max-retries 10

技术实现的一些思考

CLI 设计

花了不少时间优化 CLI 的用户体验。使用 chalk 实现了一套视觉设计系统，让终端输出更加专业和友好：

csharp 复制代码

class CliDesign {
  static readonly brand = {
    primary: chalk.hex('#00D4FF'),    // 科技感的青色
    success: chalk.hex('#4ECDC4'),    // 薄荷绿
    warning: chalk.hex('#FFE66D'),    // 金黄色
    // ...
  };
}

OpenAPI 解析

支持多种格式的 OpenAPI 文档：

远程 URL（JSON/YAML）
本地文件（自动识别格式）
动态重载（文件监控）

协议适配

不同的传输协议有不同的特点，需要做相应的适配：

STDIO: 适合 AI 客户端，简单直接
HTTP: 适合 Web 集成，RESTful 风格
SSE: 适合实时应用，单向流式传输
Streamable: 适合复杂应用，双向流式传输

使用场景

内部 API 集成

css 复制代码

# 让 AI 助手直接调用内部 API（推荐使用 streamable）
mcp-swagger-server --transport streamable --port 3322 --openapi https://internal-api.company.com/openapi.json

API 开发调试

css 复制代码

# 开发环境，文件变化自动重启
mcp-swagger-server --transport streamable --port 3322 --openapi ./dev-api.yaml --watch

微服务集成

bash 复制代码

# 多个服务同时运行
mcp-swagger-server --transport streamable --port 3001 --openapi https://service-a.com/openapi.json &
mcp-swagger-server --transport streamable --port 3002 --openapi https://service-b.com/openapi.json &

一些有趣的发现

在开发过程中发现了几个有趣的点：

OpenAPI 质量参差不齐：很多公开 API 的 OpenAPI 文档都有问题，需要做容错处理
AI 助手偏好：不同的 AI 助手对工具描述的格式有不同的偏好
性能考虑：大型 API 文档（如 GitHub API）转换后可能有数百个工具，需要做优化

社区反馈

项目在公司使用后，收到了一些有趣的反馈：

有人用它来测试自己的 API 文档质量
有团队用它来做 API Mock 服务
还有人建议支持 GraphQL（这个想法不错！）

下一步计划

即将推出的功能

HTTPS/TLS 支持 🔒

- 添加 SSL/TLS 加密支持，确保数据传输安全
- 支持自定义证书和 Let's Encrypt 自动证书
- 为企业级应用提供更好的安全保障

身份认证与授权 🔐

- 支持 JWT、OAuth 2.0、API Key 等多种认证方式
- 基于角色的访问控制（RBAC）
- 与现有身份认证系统集成

性能优化与缓存 ⚡

- 智能缓存机制，减少重复请求
- 连接池管理，提升高并发性能
- 支持集群部署和负载均衡

未来规划

GraphQL 支持：正在研究如何将 GraphQL Schema 转换为 MCP 格式
插件系统：支持自定义转换规则和中间件
Web UI 管理界面：提供可视化的服务器管理和监控（已经实现部分）
云原生支持：Docker 镜像、Kubernetes 部署、Helm Charts
监控与可观测性：集成 Prometheus、Grafana，提供完整的监控方案
多语言 SDK：提供 Python、Go、Java 等语言的客户端库

试用体验

如果你也在用 AI 助手处理 API 相关的工作，不妨试试这个工具：

css 复制代码

npm install -g mcp-swagger-server

# 推荐使用 streamable 协议体验最佳性能
mcp-swagger-server --transport streamable --port 3322 --openapi https://api.github.com/openapi.json

然后在你的 AI 编程工具（如 Cursor 或 Cherry Studio）中配置相应的 MCP 连接，就能看到转换后的 API 工具了。

项目开源地址：GitHub - mcp-swagger-server

欢迎大家试用并提供反馈！如果觉得有用，给个 Star 就是对我最大的鼓励 ⭐

写在最后

开发这个工具的初衷很简单：让已有的 API 文档能够更好地为 AI 时代服务。现在看来，这个方向是对的。

随着 AI 助手越来越普及，我相信会有更多类似的需求。希望这个小工具能为大家节省一些时间，让大家有更多精力去做真正有价值的事情。

如果你在使用过程中遇到任何问题，欢迎在 GitHub Issues 中反馈。让我们一起让 API 文档在 AI 时代发挥更大的价值！