金大哥 - openapi-analyzer-mcp MCP 详情

article

README

🚀 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：API注册表 (OPENAPI_DISCOVERY_URL)
🥈 优先级2：单个URL (OPENAPI_SPEC_URLS)
🥉 优先级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_DISCOVERY_URL | API注册表的URL（apis.json 格式），例如 https://docs.company.com/apis.json，优先级为1（最高） | | OPENAPI_SPEC_URLS | 以逗号分隔的OpenAPI规范URL列表，例如 https://api1.com/spec.yaml,https://api2.com/spec.json，优先级为2（中等） | | OPENAPI_SPECS_FOLDER | 本地OpenAPI文件文件夹的绝对路径，例如 /absolute/path/to/specs，优先级为3（回退） |

⚠️ 重要提示

必须至少设置一个环境变量

系统按优先级顺序尝试源，并在首次成功时停止

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服务器提供了以下工具供编程访问： | 工具 | 描述 | 参数 | |------|------|------| | load_specs | 智能加载：使用优先级系统自动加载规范（注册表 → URL → 文件夹） | 无 | | list_apis | 列出所有已加载的API及其基本信息（标题、版本、端点数量） | 无 | | get_api_spec | 获取特定文件的完整OpenAPI规范 | filename | | search_endpoints | 通过关键字在所有API中搜索端点 | query | | get_api_stats | 生成所有已加载API的全面统计信息 | 无 | | find_inconsistencies | 检测认证方案中的不一致性 | 无 | | compare_schemas | 比较不同API中同名的模式 | schema1，schema2（可选） | | get_load_sources | 新增！ 展示规范的加载来源（注册表、URL或文件夹） | 无 |

🔍 示例输出

🎯 智能发现结果

加载来源信息

[
  {
    "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中显示

验证环境变量是否设置 - 必须至少配置一个源
检查URL是否可访问 - 手动测试发现URL和规范URL
配置更改后完全重启Claude Desktop
检查远程API注册表的网络连接
验证文件格式 - 支持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上给它点个 ⭐！