Swagger MCP

连接到 Swagger 规范的 MCP 服务器并帮助 AI 构建所有必需的模型以生成该服务的 MCP 服务器。

特征

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

先决条件

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

安装

克隆存储库：

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

安装依赖项：

npm install

基于.env.example文件创建.env文件：

cp .env.example .env

更新.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

添加到光标

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

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

Swagger MCP 工具现在可供 Composer 中的 Cursor Agent 使用。

可用的 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 工具代码生成器已得到增强，可以提供更完整、更可用的工具定义：

关键改进

完整的模式信息：生成器现在直接在 inputSchema 中包含所有模型（包括嵌套对象）的完整模式信息。
更好的参数命名：参数名称现在更加语义化，避免使用点之类的有问题的字符（例如，使用taskRequest而不是task.Request ）。
语义工具名称：工具名称现在更具描述性，并遵循基于 HTTP 方法和资源路径的一致命名约定。
支持 YAML Swagger 文件：生成器现在支持 JSON 和 YAML Swagger 定义文件。
改进的文档：生成的工具定义包括所有参数和属性的全面描述。
无外部依赖：生成的代码不需要导入外部模型文件，使其更加独立且更易于使用。
人工智能特定说明：工具描述现在包括针对人工智能代理的特殊说明，帮助他们了解如何有效地使用这些工具。

示例用法

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

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

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

console.log(toolCode);

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

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

MCP 提示 AI 助手

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

查看PROMPTS.md文件以获取完整的提示集合。

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

Integrations