Swagger Mcp

TypeScript

MIT License

readingdancer

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: 运行环境（development, production, test）
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：

打开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提示

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

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

使用提示时，客户端可发起prompts/get请求：

json 复制代码

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

主要改进

完整模式信息：生成器现在直接在inputSchema中包含所有模型的完整模式信息，包括嵌套对象
更好的参数命名：参数名现在更具语义且避免使用点号等有问题的字符（如使用taskRequest而非task.Request）
语义化工具名称：工具名称现在更具描述性，并基于HTTP方法和资源路径遵循一致的命名约定
支持YAML格式：生成器现在支持JSON和YAML两种Swagger定义文件
改进的文档：生成的工具定义包含所有参数和属性的全面描述
无外部依赖：生成的代码不需要导入外部模型文件，更自包含且易于使用
AI专用指令：工具描述现在包含帮助AI代理有效使用工具的特殊指令

使用示例

为端点生成MCP工具定义：

typescript 复制代码

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助手向项目添加新端点时，您可以引用"添加新端点"提示，确保助手按正确顺序遵循标准流程