yq-api-doc-mcp 祐全接口文档 MCP 服务

一个用于查询 Swagger/OpenAPI 接口文档的 MCP (Model Context Protocol) 服务。

功能特性

核心功能

• 批量查询：支持一次查询多个接口的文档信息
• 自动匹配：自动匹配接口所属的接口域和服务
• Markdown 格式：返回格式化的 Markdown 文档

数据管理

• 文件缓存：接口域缓存 + 服务文档缓存，持久化存储
• 缓存兜底：请求失败时自动从缓存读取，保证服务可用性
• 缓存提示：标注数据来源和缓存时间
• 并发控制：支持配置最大并发请求数

高级功能

• 字段过滤：支持 Knife4j 扩展字段 x-includeParameters/x-ignoreParameters
  • 白名单模式：只显示指定的字段
  • 黑名单模式：排除指定的字段
• 批量优化：超过 5 个接口时自动简化输出

快速开始

配置

添加服务配置：

{
  "mcpServers": {
    "yq-api-doc": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@linjian612/yq-api-doc-mcp@latest"
      ],
      "env": {
        "API_REGION_URL": "https://api.example.com/api/regions",
        "SWAGGER_AUTH_TOKEN": "Basic your_base64_encoded_token"
      }
    }
  }
}

可选配置项：

| 变量名 | 说明 | 默认值 | |--------|------|--------| | HTTP_TIMEOUT | HTTP 请求超时时间（毫秒） | 30000 | | MAX_CONCURRENT_REQUESTS | 最大并发请求数 | 5 |

使用方法

在对话中直接使用，例如：

请获取以下接口的文档：
https://api.example.com/v1/users

工具说明

名称：get-api-doc

描述：获取 Swagger/OpenAPI 接口文档。

参数：

• apiUrls (string[]): 一个或多个完整接口地址

输出：

• success (boolean): 整体查询是否成功
• results (array): 每个接口的详细结果
  • apiUrl: 接口地址
  • success: 单个接口是否成功
  • markdown: Markdown 格式的文档
  • error: 错误信息
  • fromCache: 是否来自缓存
  • cachedTime: 缓存时间
• summary (object): 汇总信息
  • total: 接口总数
  • success: 成功数量
  • failed: 失败数量
  • fromCache: 来自缓存的数量
• markdown (string): Markdown 格式的完整文档

特性：

• 只读操作
• 幂等操作（多次调用结果一致）

缓存说明

缓存提示

当接口请求失败但缓存有数据时，会显示：

> 📦 请求最新文档数据失败，已从缓存读取历史数据
> 缓存时间：2025-03-06 14:30:00

缓存策略

• 接口域数据：成功时更新缓存，失败时从缓存读取
• 业务接口：总是请求最新数据，失败时从缓存读取并标注为兜底缓存
• 缓存无 TTL：文件存在即有效

常见问题

如何生成 Basic Auth Token？

Token 格式为 Basic <base64_encoded_token>，可以使用以下方式生成：

echo -n "username:password" | base64

为什么显示"使用缓存的数据"？

这表示请求最新文档失败，系统从历史缓存中读取了数据。请检查：

• 网络连接是否正常
• 接口服务是否正常运行
• 鉴权 Token 是否有效

如何升级到最新版本？

重启 MCP 服务后 npx 会自动获取并使用最新版本，注意：MCP 配置时记得使用 @latest 标签。

批量查询超过 5 个接口时为什么输出简化了？

为了减少返回内容的长度，超过 5 个接口时会自动省略以下内容：

• 文档地址
• 请求/响应示例
• 响应状态