Swagger MCP Server With Docker

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

使用MCP检查器

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

npm run inspector

添加到光标

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

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

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

可用的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 当前解决方案根目录中的设置文件。

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

SWAGGER_FILENAME = TheFilenameOfTheLocallyStoredSwaggerFile

这个简单的配置文件将您当前的项目与特定的Swagger API相关联，我们可能会在将来使用它来存储更多详细信息。

配置后，MCP将能够找到您的Swagger定义，并将其与您当前的解决方案相关联，从而减少获取与您正在处理的解决方案相关的项目和任务所需的API调用次数。

改进的MCP工具代码生成器

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

关键改进

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

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

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

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

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

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

1. 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);

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

许可证

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

MCP提示AI助手

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

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

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