MCP 服务器

Swagger MCP

一个 MCP 服务器，它可以连接到 Swagger 规范，并帮助 AI 构建所有必需的模型，从而为该服务生成一个 MCP 服务器。

README

Swagger MCP

一个 MCP 服务器，连接到 Swagger 规范，并帮助 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: 环境（开发、生产、测试）
LOG_LEVEL: 日志级别（info、error、debug）

用法

构建应用程序

构建应用程序：

npm run build

这将编译 TypeScript 代码，使其可以作为 MCP 服务器使用

作为 MCP 服务器运行

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

node build/index.js

使用 MCP Inspector

要运行 MCP inspector 进行调试：

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

服务器还提供 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 = TheFilenameOfTheLocallyStoredSwaggerFile

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

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

改进的 MCP 工具代码生成器

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

主要改进

完整的模式信息：生成器现在包括所有模型的完整模式信息，包括嵌套对象，直接包含在 inputSchema 中。
更好的参数命名：参数名称现在更具语义，并避免使用点等有问题的字符（例如，taskRequest 而不是 task.Request）。
语义工具名称：工具名称现在更具描述性，并遵循基于 HTTP 方法和资源路径的一致命名约定。
支持 YAML Swagger 文件：生成器现在支持 JSON 和 YAML Swagger 定义文件。
改进的文档：生成的工具定义包括所有参数和属性的全面描述。
没有外部依赖项：生成的代码不需要导入外部模型文件，使其更独立且更易于使用。
特定于 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);