Openapi Analyzer MCP

🚀 OpenAPI分析器MCP服務器

一個強大的模型上下文協議（MCP）服務器，用於結合Claude Desktop和其他大語言模型（LLM）客戶端分析OpenAPI規範。該服務器支持通過自然語言查詢API結構、端點和模式，還能幫助識別多個OpenAPI規範間的不一致之處。

🚀 快速開始

本服務器可助力你對API結構、端點、模式等進行自然語言查詢，並識別多個OpenAPI規範間的不一致性。你可以按照以下指南進行安裝、配置和使用。

✨ 主要特性

🎯 智能發現系統

• 📡 API註冊表支持：自動從 apis.json 註冊表中發現API（支持30多種API）
• 🔗 基於URL的加載：從單個URL加載規範，並具備自動回退機制
• 📁 本地文件支持：支持傳統的基於文件夾的規範加載，且支持多種格式
• 🔄 優先級系統：發現URL → 單個URL → 本地文件夾（智能回退）

🔍 高級分析

• 📊 批量分析：可同時加載和分析90多個OpenAPI規範文件
• 🔍 智能搜索：使用自然語言查詢在所有API中查找端點
• 📈 全面統計：生成關於API生態系統的詳細統計信息
• 🔧 不一致性檢測：識別認證方案和命名約定的不匹配之處
• 📋 模式比較：比較不同API中同名的模式
• ⚡ 快速查詢：內存索引實現閃電般的響應速度

🌐 通用兼容性

• 多格式支持：支持JSON、YAML和YML規範
• 版本支持：支持OpenAPI 2.0、3.0和3.1規範
• 遠程與本地：支持URL、API註冊表和本地文件
• 來源跟蹤：明確知曉每個API規範的加載來源

📦 安裝指南

選項1：從npm安裝

npm install openapi-analyzer-mcp

選項2：從源代碼構建

git clone https://github.com/sureshkumars/openapi-analyzer-mcp.git
cd openapi-analyzer-mcp
npm install
npm run build

📚 詳細文檔

⚙️ 配置

🎯 智能發現選項

OpenAPI分析器支持三種發現方法，並具備智能優先級回退機制：

1. 🏆 優先級1：API註冊表 (OPENAPI_DISCOVERY_URL)
2. 🥈 優先級2：單個URL (OPENAPI_SPEC_URLS)
3. 🥉 優先級3：本地文件夾 (OPENAPI_SPECS_FOLDER)

Claude Desktop設置

查找配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\\Claude\\claude_desktop_config.json

配置示例

🌟 選項1：API註冊表發現（推薦）

適用於擁有集中式API註冊表的公司：

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://docs.company.com/apis.json"
      }
    }
  }
}

🔗 選項2：單個API URL

從直接URL加載特定的API：

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx", 
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPEC_URLS": "https://api.example.com/v1/openapi.yaml,https://api.example.com/v2/openapi.yaml,https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

📁 選項3：本地文件夾

適用於本地規範文件的傳統方法：

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPECS_FOLDER": "/absolute/path/to/your/openapi-specs"
      }
    }
  }
}

🔄 選項4：多源回退

提供終極靈活性 - 嘗試所有方法並智能回退：

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://docs.company.com/apis.json",
        "OPENAPI_SPEC_URLS": "https://legacy-api.com/spec.yaml,https://external-api.com/spec.json",
        "OPENAPI_SPECS_FOLDER": "/path/to/local/specs"
      }
    }
  }
}

🏢 實際示例

擁有API註冊表的公司：

{
  "mcpServers": {
    "company-apis": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://api.company.com/registry/apis.json"
      }
    }
  }
}

多個API源：

{
  "mcpServers": {
    "multi-apis": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPEC_URLS": "https://petstore.swagger.io/v2/swagger.json,https://api.example.com/v1/openapi.yaml"
      }
    }
  }
}

🔧 環境變量

⚠️ 重要提示

• 必須至少設置一個環境變量
• 系統按優先級順序嘗試源，並在首次成功時停止
• OPENAPI_SPECS_FOLDER 始終使用絕對路徑
• 所有源均支持JSON、YAML和YML格式

🎯 使用方法

配置完成後，你可以在Claude Desktop中使用自然語言與OpenAPI規範進行交互：

🚀 智能發現查詢

API註冊表發現

"從公司註冊表加載所有API並展示概覽"
"從配置的註冊表發現API並分析其認證模式"
"我們的API註冊表中有哪些可用的API？"
"展示我的規範是從哪裡加載的"

跨API分析

"加載所有我的OpenAPI規範並提供全面總結"
"我有多少個API，總共有多少個端點？"
"比較所有已加載API的認證方案"
"哪些API使用了同一模式的不同版本？"

搜索與發現

"展示所有API中用於創建用戶的POST端點"
"查找所有已加載API中與認證相關的端點"
"哪些API具有分頁參數？"
"搜索處理文件上傳的端點"
"查找所有使用 'User' 模式的API"

分析與比較

"我的API使用了哪些認證方案？"
"哪些API存在不一致的命名約定？"
"比較不同API中的User模式"
"展示仍在使用1.0版本的API"

統計與洞察

"生成關於我的API生態系統的全面統計信息"
"最常用的HTTP方法有哪些？"
"最常見的路徑模式是什麼？"
"展示我的API的版本分佈情況"

🔧 可用工具

MCP服務器提供了以下工具供編程訪問：

🔍 示例輸出

🎯 智能發現結果

加載來源信息

[
  {
    "type": "discovery",
    "url": "https://api.company.com/registry/apis.json",
    "count": 12,
    "metadata": {
      "name": "Company APIs",
      "description": "Collection of company API specifications",
      "total_apis": 12
    }
  }
]

註冊表發現成功

{
  "totalApis": 12,
  "totalEndpoints": 247,
  "loadedFrom": "API Registry",
  "discoveryUrl": "https://api.company.com/registry/apis.json",
  "apis": [
    {
      "filename": "User Management API",
      "title": "User Management API", 
      "version": "2.1.0",
      "endpointCount": 18,
      "source": "https://docs.company.com/user-api.yaml"
    },
    {
      "filename": "Product Catalog API",
      "title": "Product Catalog API",
      "version": "1.5.0", 
      "endpointCount": 32,
      "source": "https://docs.company.com/product-api.yaml"
    }
  ]
}

📊 API統計信息

{
  "totalApis": 12,
  "totalEndpoints": 247,
  "methodCounts": {
    "GET": 98,
    "POST": 67,
    "PUT": 45,
    "DELETE": 37
  },
  "versions": {
    "1.0.0": 8,
    "2.0.0": 3,
    "3.1.0": 1
  },
  "commonPaths": {
    "/api/v1/users/{id}": 8,
    "/api/v1/orders": 6,
    "/health": 12
  }
}

搜索結果

[
  {
    "filename": "user-api.json",
    "api_title": "User Management API",
    "path": "/api/v1/users",
    "method": "POST",
    "summary": "Create a new user",
    "operationId": "createUser"
  },
  {
    "filename": "admin-api.json", 
    "api_title": "Admin API",
    "path": "/admin/users",
    "method": "POST",
    "summary": "Create user account",
    "operationId": "adminCreateUser"
  }
]

🏗️ 創建你自己的API註冊表

如果你想設置自己的 apis.json 註冊表，可以按以下步驟操作：

標準 apis.json 格式

在 https://your-domain.com/apis.json 創建一個文件：

{
  "name": "Your Company APIs",
  "description": "Collection of all our API specifications",
  "url": "https://your-domain.com",
  "apis": [
    {
      "name": "User API",
      "baseURL": "https://api.your-domain.com/users",
      "properties": [
        {
          "type": "Swagger",
          "url": "https://docs.your-domain.com/user-api.yaml"
        }
      ]
    },
    {
      "name": "Orders API", 
      "baseURL": "https://api.your-domain.com/orders",
      "properties": [
        {
          "type": "OpenAPI",
          "url": "https://docs.your-domain.com/orders-api.json"
        }
      ]
    }
  ]
}

自定義註冊表格式

或者使用更簡單的自定義格式：

{
  "name": "Your Company APIs",
  "description": "Our API registry",
  "apis": [
    {
      "name": "User API",
      "version": "v2",
      "spec_url": "https://docs.your-domain.com/user-api.yaml",
      "docs_url": "https://docs.your-domain.com/user-api",
      "status": "stable",
      "tags": ["auth", "users"]
    }
  ]
}

🚨 故障排除

工具未在Claude Desktop中顯示

1. 驗證環境變量是否設置 - 必須至少配置一個源
2. 檢查URL是否可訪問 - 手動測試發現URL和規範URL
3. 配置更改後完全重啟Claude Desktop
4. 檢查遠程API註冊表的網絡連接
5. 驗證文件格式 - 支持JSON、YAML和YML

常見錯誤消息

智能發現錯誤

• "❌ 錯誤：未配置OpenAPI源"：設置 OPENAPI_DISCOVERY_URL、OPENAPI_SPEC_URLS 或 OPENAPI_SPECS_FOLDER 中的至少一個
• "⚠️ 警告：無法從發現URL加載"：檢查註冊表URL是否可訪問，並返回有效的JSON
• "無效的註冊表格式：缺少apis數組"：你的 APIs.json 文件必須包含 apis 數組
• "未找到OpenAPI規範URL"：API條目必須具有 spec_url 或包含OpenAPI/Swagger類型的 properties

傳統錯誤

• "❌ 錯誤：OPENAPI_SPECS_FOLDER不存在"：指定的目錄不存在
• "❌ 錯誤：OPENAPI_SPECS_FOLDER不是一個目錄"：路徑指向的是文件，而不是目錄
• "❌ 錯誤：沒有對OPENAPI_SPECS_FOLDER的讀取權限"：檢查文件夾權限
• "⚠️ 警告：未找到OpenAPI規範文件"：目錄存在，但不包含受支持的文件
• "⚠️ 跳過 [文件]：格式無效"：文件不是有效的JSON/YAML或格式錯誤的OpenAPI規範

調試模式

設置 NODE_ENV=development 以查看詳細日誌：

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "OPENAPI_SPECS_FOLDER": "/path/to/specs",
        "NODE_ENV": "development"
      }
    }
  }
}

🤝 貢獻代碼

歡迎貢獻代碼！請隨時提交拉取請求。對於重大更改，請先打開一個問題討論你想要更改的內容。

開發設置

git clone https://github.com/sureshkumars/openapi-analyzer-mcp.git
cd openapi-analyzer-mcp
npm install
npm run build
npm run dev  # 以開發模式啟動

運行測試

本項目包含一個全面的測試套件，有46個以上的測試覆蓋了所有功能：

# 運行所有測試
npm test

# 以監聽模式運行測試（文件更改時重新運行）
npm run test:watch

# 運行測試並生成覆蓋率報告
npm run test:coverage

測試覆蓋率

測試套件提供了廣泛的覆蓋範圍，測試成功率為100%：

• ✅ 46個測試通過，語句覆蓋率為66.79%，函數覆蓋率為100%
• 單元測試：針對OpenAPIAnalyzer類（30個測試） - 覆蓋所有加載方法和分析功能
• 集成測試：針對MCP服務器配置（8個測試） - 驗證所有工具和導出
• 驗證測試：針對環境設置和錯誤處理（8個測試） - 測試所有發現方法

v1.2.0新增內容：

• ✅ 智能發現測試 - URL加載、API註冊表解析、回退機制
• ✅ 基於構造函數的測試 - 無需環境變量即可靈活配置測試
• ✅ 遠程規範模擬 - 全面覆蓋基於HTTP的規範加載
• ✅ 向後兼容性 - 保留所有現有功能

測試結構

tests/
├── analyzer.test.ts      # 核心OpenAPIAnalyzer功能測試
├── server.test.ts        # MCP服務器配置測試
├── validation.test.ts    # 環境驗證測試
├── setup.ts             # 測試配置
└── fixtures/            # 示例測試數據
    ├── sample-api.json
    ├── another-api.json
    └── invalid-api.json

測試內容

• ✅ OpenAPI規範加載（有效/無效文件、JSON解析）
• ✅ 搜索功能（按路徑、方法、摘要、操作ID）
• ✅ 統計信息生成（方法計數、版本、常見路徑）
• ✅ 模式比較（跨API模式分析）
• ✅ 不一致性檢測（認證方案）
• ✅ 錯誤處理（缺少環境變量、文件權限）
• ✅ 邊緣情況（空目錄、格式錯誤的JSON）

測試技術

• Vitest - 支持TypeScript的快速測試框架
• 全面模擬 - 文件系統操作和控制檯輸出
• 類型安全 - 完全集成TypeScript並使用適當的接口

🆕 更新日誌

版本1.2.0 - 智能發現系統

發佈時間：2025年9月

• 🚀 智能發現系統：具有基於優先級的回退機制的革命性API發現功能

• 📡 API註冊表支持：全面支持 apis.json 格式和自定義註冊表

• 🔗 基於URL的加載：直接從單個URL加載規範

• 🔄 智能回退：發現URL → 單個URL → 本地文件夾優先級系統

• 🏷️ 來源跟蹤：新增 get_load_sources 工具，展示規範的加載來源

• 🏢 生產就緒：已成功與來自各種註冊表的30多個生產API進行測試

• 📊 批量處理：可在數秒內從註冊表加載90多個API

• 🌐 通用格式支持：支持來自任何源（遠程或本地）的JSON、YAML、YML

• ✅ 46個測試通過，成功率為100%

• 📈 覆蓋率提升：語句覆蓋率為66.79%，函數覆蓋率為100%

• 🔧 基於構造函數的測試：靈活的測試配置

• 🔗 遠程規範模擬：全面覆蓋基於HTTP的加載測試

• ⚡ 零破環性更改：保持完全向後兼容性

• 📚 全面文檔：更新了實際示例

• 🏗️ 註冊表設置指南：提供創建自己的 apis.json 註冊表的說明

• 🚨 增強的錯誤處理：更好的錯誤消息和優雅的回退機制

版本1.1.0 - YAML支持與增強分析

• 使用 @apidevtools/swagger-parser 增加了對YAML/YML格式的支持
• 增強了模式比較和不一致性檢測功能
• 改進了錯誤處理和驗證

版本1.0.0 - 初始版本

• 核心OpenAPI分析功能
• 基於本地文件夾的規範加載
• 具有6個核心工具的MCP服務器實現

📄 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。

🙏 致謝

• 基於 Model Context Protocol SDK 構建
• 支持 OpenAPI Initiative 定義的OpenAPI規範
• 與 Claude Desktop 和其他MCP客戶端兼容

為API開發者和文檔團隊用心打造 ❤️

如果你覺得這個工具有用，請在GitHub上給它點個 ⭐！