AI导哈

Swagger MCP服务生成器

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

  • by Vizioz
  • TypeScript
  • 本地部署
  • 168 星标
  • 更新于
在 GitHub 查看 vizioz/swagger-mcp

使用说明

Swagger MCP

一个连接到Swagger规范的MCP服务器，帮助人工智能构建所有必需的模型，为该服务生成MCP服务器。

特性

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

先决条件

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

安装

  1. 克隆存储库：
git clone https://github.com/readingdancer/swagger-mcp.git
cd swagger-mcp
  1. 安装依赖项：
npm install
  1. 创建一个 .env 文件基于 .env.example 文件：
cp .env.example .env
  1. 更新 .env 文件。

配置

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

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

用法

构建应用程序

构建应用程序：

npm run build

这将编译TypeScript代码，准备用作MCP服务器

作为MCP服务器运行

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

node build/index.js

您还可以通过CLI参数提供Swagger URL：

node build/index.js --swagger-url="https://petstore.swagger.io/v2/swagger.json"

或者使用替代格式：

node build/index.js --swaggerUrl="https://petstore.swagger.io/v2/swagger.json"

备注：CLI --swagger-url 论点优先于 swaggerFilePath 工具调用中的参数。如果两者都提供，则将使用CLI参数。

使用MCP检查器

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

npm run inspector

添加到光标

要将此MCP服务器添加到游标，请执行以下操作：

  1. 打开光标设置>功能>MCP
  2. 点击“+添加新MCP服务器”
  3. 输入服务器的名称（例如“Swagger MCP”）
  4. 选择“stdio”作为传输类型
  5. 输入运行服务器的命令：
    • 基础： node path/to/swagger-mcp/build/index.js
    • 使用Swagger URL： node path/to/swagger-mcp/build/index.js --swagger-url="https://your-api-url/swagger.json"
  6. 点击“添加”

Swagger MCP工具现在将可用于Composer中的光标代理。

小贴士：如果您提供 --swagger-url 配置服务器时不需要提供CLI参数 swaggerFilePath 在工具调用中，使工具更易于使用。

可用的Swagger MCP工具

MCP服务器提供以下工具：

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

Swagger定义优先级：这些工具根据此优先级确定使用哪个Swagger定义：

  1. 命令行界面 --swagger-url 参数（如果在启动服务器时提供）
  2. swaggerFilePath 参数（如果在工具调用中提供）
  3. 如果两者都不可用，则出错

如果您以以下方式启动服务器 --swagger-url，您可以省略 swaggerFilePath 工具中的参数调用方便。

可用的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定义：

方法1：使用CLI参数（推荐）

使用启动MCP服务器 --swagger-url 论点：

node build/index.js --swagger-url="https://your-api-url/swagger.json"

这将自动下载并缓存Swagger定义。所有工具都将使用此定义，您不需要提供 swaggerFilePath 在工具调用中。

方法2：使用getSwaggerDefinition工具

或者，您可以要求代理使用以下命令获取Swagger文件 getSwaggerDefinition 工具。请确保您提供了swagger文件的URL，或者至少提供了一种查找它的方法。这将下载该文件并使用哈希文件名将其保存在本地。文件名将自动添加到 .swagger-mcp 当前解决方案根目录中的设置文件。

自动生成.swagg-mcp配置文件

使用时 getSwaggerDefinition 工具（上述方法2），a .swagger-mcp 文件会自动创建：

SWAGGER_FILEPATH = TheFullPathToTheLocallyStoredSwaggerFile

此配置文件将当前项目与特定的Swagger API关联起来。我们将来可能会用它来存储更多细节。

配置后，您可以在调用工具时从此配置文件中引用Swagger文件路径。但是，如果使用CLI --swagger-url 参数（方法1），此配置文件是可选的，因为Swagger定义是自动加载的。

改进的MCP工具代码生成器

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

关键改进

  1. 完整的架构信息：生成器现在直接在inputSchema中包含所有模型的完整模式信息，包括嵌套对象。

  2. 更好的参数命名：参数名称现在更具语义，避免了点等有问题的字符（例如。， taskRequest 而不是 task.Request).

  3. 语义工具名称：工具名称现在更具描述性，并遵循基于HTTP方法和资源路径的一致命名约定。

  4. 支持YAML Swagger文件：生成器现在支持JSON和YAML Swagger定义文件。

  5. 改进的文档：生成的工具定义包括对所有参数和属性的全面描述。

  6. 无外部依赖关系：生成的代码不需要导入外部模型文件，使其更加自包含且易于使用。

  7. AI特定说明工具描述现在包括针对AI代理的特殊说明，帮助他们了解如何有效地使用工具。

示例用法

要为端点生成MCP工具定义，请执行以下操作：

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

// If server was started with --swagger-url, swaggerFilePath is optional
const toolCode = await generateEndpointToolCode({
  path: '/pets',
  method: 'POST',
  swaggerFilePath: './petstore.json', // Optional if --swagger-url was provided
  singularizeResourceNames: true
});

console.log(toolCode);

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

备注：如果您使用启动服务器 --swagger-url，您可以省略 swaggerFilePath 参数：

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

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

MCP提示AI助手

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

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

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

相关 MCP