Swagger MCP

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

特性

• 下载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：日志级别（info、error、debug）

使用

构建应用程序

构建应用程序：

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 = 本地存储的Swagger文件的文件名

这个简单的配置文件将您的当前项目与特定的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文件。

针对AI助手的MCP提示

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

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

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