Swagger MCP

🚀 基於Swagger的MCP服務器

這是一個通過Model Context Protocol（MCP）處理 Swagger/OpenAPI 規範的服務器，能加載規範、支持多種認證方式，還可自動生成MCP工具，為即時通信提供支持，同時具備 TypeScript 支持。

✨ 主要特性

• 規範加載：可加載 Swagger/OpenAPI 規範。
• 多認證支持：支持基本認證、Bearer Token、API Key（頭或查詢）、OAuth2 等多種身份驗證方法。
• 工具自動生成：能從 API 端點自動生成 MCP 工具。
• 即時通信支持：對即時通信支持 Server-Sent Events (SSE)。
• TypeScript 支持：具備 TypeScript 支持。

⚠️ 安全性提示

⚠️ 重要提示

這是一個個人服務器，請勿將其暴露到公共互聯網。若底層 API 需要身份驗證，同樣不應將 MCP 服務器暴露到公共互聯網。

📋 待辦事項

• 秘密 - MCP 服務器應能夠使用用戶的秘密來對請求進行身份驗證。
• 全面測試套件。

📦 安裝指南

先決條件

• Node.js（v18 或更高）
• Yarn 包管理器
• TypeScript

安裝步驟

1. 克隆倉庫：

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

2. 安裝依賴項：

yarn install

3. 基於示例創建.env文件：

cp .env.example .env

4. 配置你的 Swagger/OpenAPI 規範：
   • 將你的 Swagger 文件放在項目中（例如swagger.json）。
   • 或者提供到你的 Swagger 規範的 URL。
5. 在config.json中更新服務器設置：

{
  "server": {
    "host": "localhost",
    "port": 3000
  },
  "swagger": {
    "url": "url-or-path/to/your/swagger.json",
    "apiBaseUrl": "https://api.example.com",  // 如果Swagger中未指定，則作為備用URL
    "defaultAuth": {  // 如果Swagger中未指定身份驗證方案，則作為備用設置
      "type": "apiKey",
      "apiKey": "your-api-key",
      "name": "Authorization",
      "value": "Bearer ${ apiKey }"
    }
  }
}

💻 使用示例

啟動開發服務器

yarn dev

構建生產環境

yarn build

📚 詳細文檔

API 端點

獲取所有文檔

GET /api-docs

根據名稱獲取文檔

GET /api-docs/{name}

發佈文檔

POST /api-docs

刪除文檔

DELETE /api-docs/{name}

認證方法

基本認證

配置示例：

{
  "defaultAuth": {
    "type": "basic",
    "username": "your-username",
    "password": "your-password"
  }
}

Bearer Token

配置示例：

{
  "defaultAuth": {
    "type": "bearer",
    "token": "your-bearer-token"
  }
}

API Key

配置示例：

{
  "defaultAuth": {
    "type": "apiKey",
    "key": "your-api-key",
    "name": "X-API-Key",
    "value": "${ key }"
  }
}

OAuth2

配置示例：

{
  "defaultAuth": {
    "type": "oauth2",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "accessTokenUrl": "https://example.com/oauth/token",
    "authorizationUrl": "https://example.com/oauth/authorize"
  }
}

環境變量

🧪 測試

運行測試

yarn test

按照環境運行測試

yarn test:dev

按照覆蓋運行測試

yarn test:cov