Swagger MCP Toolkit

swagg-mcp工具包

用于Swagger/OpenAPI定义的MCP服务器：连接到Swagger规范，帮助AI/客户端快速探索端点/模型并生成MCP工具定义代码。

本项目改编自上游项目：https://github.com/Vizioz/Swagger-MCP

此叉子的变化

• 增强的Swagger 2.0定义支持（同时保留了原有的Swagger mcp功能）
• 添加了Knife4j/KnifeHeader处理：支持自定义 headers，加 gatewayHeader / gatewayCode 直通
• 添加 swagger-resources 支持：新 listSwaggerResources 和 saveSwaggerResources 工具

特性

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

先决条件

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

安装

1. 克隆存储库：

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

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参数。

通过npm（npx）运行

如果您将此项目发布为名为的npm包 swagger-mcp-toolkit，您可以在不克隆的情况下运行它：

npx -y swagger-mcp-toolkit@latest --swagger-url="https://petstore.swagger.io/v2/swagger.json"

使用MCP检查器

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

npm run inspector

添加到光标

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

1. 打开光标设置>功能>MCP
2. 点击“+添加新MCP服务器”
3. 输入服务器的名称（例如，“Swagger MCP Toolkit”）
4. 选择“stdio”作为传输类型
5. 输入运行服务器的命令：

- 基础： node path/to/swagger-mcp-toolkit/build/index.js - 使用Swagger URL： node path/to/swagger-mcp-toolkit/build/index.js --swagger-url="https://your-api-url/swagger.json"

1. 点击“添加”

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

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

自定义MCP配置示例

本地构建使用情况：

{
  "mcpServers": {
    "get-swagger": {
      "command": "node",
      "args": [
        "C:/projects/swagger-mcp-toolkit/build/index.js",
        "--swagger-url=http://xxx.xx.xx.xx:xxxxxx"
      ],
      "env": {}
    }
  }
}

npm（npx）用法：

{
  "mcpServers": {
    "get-swagger": {
      "command": "npx",
      "args": [
        "-y",
        "swagger-mcp-toolkit@latest",
        "--swagger-url=http://xxx.xx.xx.xx:xxxxxx"
      ],
      "env": {}
    }
  }
}

可用的Swagger MCP工具

MCP服务器提供以下工具：

• getSwaggerDefinition：从URL下载Swagger定义
• listSwaggerResources：取刀4j swagger-resources 用于模块选择
• saveSwaggerResources：取刀4j swagger-resources 并将其保存为JSON文件
• listEndpoints：列出Swagger定义中的所有端点（可选 swaggerFilePath)
• listEndpointModels：列出特定端点使用的所有模型（可选 swaggerFilePath)
• generateModelCode：为模型生成TypeScript代码（可选 swaggerFilePath)
• generateEndpointToolCode：为MCP工具定义生成TypeScript代码（可选 swaggerFilePath)

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

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

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

许可证

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

MCP提示AI助手

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

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

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