Swagger MCP

🚀 Swagger MCP

Swagger MCP 是一个 MCP 服务器，它能连接到 Swagger 规范，帮助 AI 构建所需的所有模型，从而为相应服务生成 MCP 服务器。

✨ 主要特性

• 下载 Swagger 规范并将其本地存储，以便快速参考。
• 返回所有端点及其 HTTP 方法和描述的列表。
• 返回所有模型的列表。
• 返回单个模型。
• 返回连接到端点的服务。
• 返回 MCP 函数定义。
• 生成包含完整架构信息的完整 MCP 工具定义。
• 在工具描述中包含特定于 AI 的说明。

📦 安装指南

前提条件

• Node.js（v14 或更高版本）
• npm 或 yarn

安装步骤

1. 克隆仓库：

git clone https://github.com/readingdancer/swagger-mcp.git
cd swagger-mcp

2. 安装依赖：

npm install

3. 根据 .env.example 文件创建 .env 文件：

cp .env.example .env

4. 更新 .env 文件。

📚 详细文档

配置

编辑 .env 文件以配置应用程序：

• PORT：服务器运行的端口（默认值：3000）
• NODE_ENV：环境（开发、生产、测试）
• LOG_LEVEL：日志记录级别（信息、错误、调试）

使用方法

构建应用程序

构建应用程序：

npm run build

这将编译 TypeScript 代码，使其可作为 MCP 服务器使用。

作为 MCP 服务器运行

要作为 MCP 服务器运行，以便与 Cursor 和其他应用程序集成：

node build/index.js

使用 MCP 检查器

要运行 MCP 检查器进行调试：

npm run inspector

添加到 Cursor

要将此 MCP 服务器添加到 Cursor：

1. 打开 Cursor 设置 > 功能 > MCP。
2. 点击“+ 添加新的 MCP 服务器”。
3. 为服务器输入一个名称（例如，“Swagger MCP”）。
4. 选择 “stdio” 作为传输类型。
5. 输入运行服务器的命令：node path/to/swagger-mcp/build/index.js，然后根据需要添加上述命令行参数。
6. 点击“添加”。

现在，Swagger MCP 工具将在 Composer 中对 Cursor 代理可用。

可用的 Swagger MCP 工具

以下工具可通过 MCP 服务器使用：

• getSwaggerDefinition：从 URL 下载 Swagger 定义。
• listEndpoints：列出 Swagger 定义中的所有端点。
• listEndpointModels：列出特定端点使用的所有模型。
• generateModelCode：为模型生成 TypeScript 代码。
• generateEndpointToolCode：为 MCP 工具定义生成 TypeScript 代码。

可用的 Swagger MCP 提示

服务器还提供 MCP 提示，引导 AI 助手完成常见工作流程：

• add-endpoint：使用 Swagger MCP 工具添加新端点的分步指南。

要使用提示，客户端可以使用提示名称和可选参数发出 prompts/get 请求：

{
  "method": "prompts/get",
  "params": {
    "name": "add-endpoint",
    "arguments": {
      "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
      "endpointPath": "/pets/{id}",
      "httpMethod": "GET"
    }
  }
}

该提示将返回一系列消息，引导 AI 助手完成添加新端点所需的精确过程。

设置新项目

首先要求代理获取 Swagger 文件，确保为其提供 Swagger 文件的 URL，或者至少提供一种查找该文件的方法。这将下载文件并以哈希文件名本地保存，该文件名将自动添加到当前解决方案根目录下的 .swagger-mcp 设置文件中。

自动生成的 .swagger-mcp 配置文件

SWAGGER_FILENAME = TheFilenameOfTheLocallyStoredSwaggerFile

这个简单的配置文件将当前项目与特定的 Swagger API 关联起来，将来我们可能会使用它来存储更多详细信息。

配置完成后，MCP 将能够找到您的 Swagger 定义并将其与当前解决方案关联起来，从而减少获取与您正在处理的解决方案相关的项目和任务所需的 API 调用次数。

改进的 MCP 工具代码生成器

MCP 工具代码生成器已得到增强，可提供更完整和可用的工具定义：

主要改进

1. 完整的架构信息：生成器现在在输入架构中直接包含所有模型的完整架构信息，包括嵌套对象。
2. 更好的参数命名：参数名称现在更具语义，避免使用点号等有问题的字符（例如，使用 taskRequest 而不是 task.Request）。
3. 语义化的工具名称：工具名称现在更具描述性，并根据 HTTP 方法和资源路径遵循一致的命名约定。
4. 支持 YAML Swagger 文件：生成器现在支持 JSON 和 YAML 格式的 Swagger 定义文件。
5. 改进的文档：生成的工具定义包含所有参数和属性的全面描述。
6. 无外部依赖：生成的代码不需要导入外部模型文件，使其更独立且易于使用。
7. 特定于 AI 的说明：工具描述现在包含针对 AI 代理的特殊说明，帮助它们有效使用工具。

示例用法

要为端点生成 MCP 工具定义：

import generateEndpointToolCode from './services/generateEndpointToolCode.js';

const toolCode = await generateEndpointToolCode({
  path: '/pets',
  method: 'POST',
  swaggerFilePath: './petstore.json',
  singularizeResourceNames: true
});

console.log(toolCode);

这将为 POST /pets 端点生成包含完整架构信息的完整 MCP 工具定义。

📄 许可证

本项目根据 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。

📚 MCP 为 AI 助手提供的提示

为了帮助 AI 助手有效使用 Swagger MCP 工具，我们创建了一系列提示，引导它们完成常见任务。这些提示为添加新端点、使用生成的模型等过程提供了分步说明。

有关完整的提示集合，请查看 PROMPTS.md 文件。

示例用例：当要求 AI 助手向项目中添加新端点时，您可以参考“添加新端点”提示，以确保助手按正确顺序遵循正确的过程。