Swagger MCP

🚀 Swagger MCP

Swagger MCP 是一個 MCP 服務器，它能連接到 Swagger 規範，幫助 AI 構建所需的所有模型，從而為相應服務生成 MCP 服務器。

✨ 主要特性

• 下載 Swagger 規範並將其本地存儲，以便快速參考。
• 返回所有端點及其 HTTP 方法和描述的列表。
• 返回所有模型的列表。
• 返回單個模型。
• 返回連接到端點的服務。
• 返回 MCP 函數定義。
• 生成包含完整架構信息的完整 MCP 工具定義。
• 在工具描述中包含特定於 AI 的說明。

📦 安裝指南

前提條件

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

安裝步驟

1. 克隆倉庫：

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

2. 安裝依賴：

npm install

3. 根據 .env.example 文件創建 .env 文件：

cp .env.example .env

4. 更新 .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

添加到 Cursor

要將此 MCP 服務器添加到 Cursor：

1. 打開 Cursor 設置 > 功能 > MCP。
2. 點擊“+ 添加新的 MCP 服務器”。
3. 為服務器輸入一個名稱（例如，“Swagger MCP”）。
4. 選擇 “stdio” 作為傳輸類型。
5. 輸入運行服務器的命令：node path/to/swagger-mcp/build/index.js，然後根據需要添加上述命令行參數。
6. 點擊“添加”。

現在，Swagger MCP 工具將在 Composer 中對 Cursor 代理可用。

可用的 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 工具代碼生成器已得到增強，可提供更完整和可用的工具定義：

主要改進

1. 完整的架構信息：生成器現在在輸入架構中直接包含所有模型的完整架構信息，包括嵌套對象。
2. 更好的參數命名：參數名稱現在更具語義，避免使用點號等有問題的字符（例如，使用 taskRequest 而不是 task.Request）。
3. 語義化的工具名稱：工具名稱現在更具描述性，並根據 HTTP 方法和資源路徑遵循一致的命名約定。
4. 支持 YAML Swagger 文件：生成器現在支持 JSON 和 YAML 格式的 Swagger 定義文件。
5. 改進的文檔：生成的工具定義包含所有參數和屬性的全面描述。
6. 無外部依賴：生成的代碼不需要導入外部模型文件，使其更獨立且易於使用。
7. 特定於 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);

這將為 POST /pets 端點生成包含完整架構信息的完整 MCP 工具定義。

📄 許可證

本項目根據 MIT 許可證授權 - 有關詳細信息，請參閱 LICENSE 文件。

📚 MCP 為 AI 助手提供的提示

為了幫助 AI 助手有效使用 Swagger MCP 工具，我們創建了一系列提示，引導它們完成常見任務。這些提示為添加新端點、使用生成的模型等過程提供了分步說明。

有關完整的提示集合，請查看 PROMPTS.md 文件。

示例用例：當要求 AI 助手向項目中添加新端點時，您可以參考“添加新端點”提示，以確保助手按正確順序遵循正確的過程。