@zero-ai-bits/api-mcp

MCP Swagger Enhanced Service (TypeScript).

提供将现有的 Swagger / OpenAPI 接口文档无缝接入 AI 上下文的能力，使大模型可以直接搜索、读取和理解您的项目 API。

特性

• 🚀 全面支持 Swagger/OpenAPI：自动解析和解构 $ref 嵌套引用
• 🔍 多维度接口检索：支持精确查找、模糊搜索、按 Tag 筛选
• ⚡ 高性能缓存：内置请求缓存策略，降低接口拉取延迟
• 🛡️ 多种鉴权支持：支持 Cookie、Basic Auth、Bearer Token 鉴权
• 📦 开箱即用：基于 Model Context Protocol (MCP) 规范标准开发，即插即用

环境配置 (环境变量)

在启动本服务前，可以通过配置环境变量来定制服务行为：

• SWAGGER_URL (必填): Swagger / OpenAPI JSON 数据源的完整 URL
• SWAGGER_AUTH_MODE: 接口鉴权模式，支持 cookie, basic, bearer
• SWAGGER_COOKIE: 选用 cookie 鉴权时配置
• SWAGGER_USERNAME / SWAGGER_PASSWORD: 选用 basic 鉴权时配置
• SWAGGER_BEARER_TOKEN: 选用 bearer 鉴权时配置
• SWAGGER_CACHE_TTL_MS: 接口缓存有效时间，默认 60000 毫秒（1分钟）
• SWAGGER_TIMEOUT_MS: 请求超时时间，默认 20000 毫秒（20秒）
• SWAGGER_LOG_LEVEL: 日志打印级别，默认 info（支持 debug, info, warn, error）

构建与运行

# 安装依赖
pnpm install

# 编译 TypeScript 源码并进行混淆加密
pnpm run build

# 启动服务
pnpm start

提供的 MCP Tools

该服务向 AI 暴露了以下标准工具接口：

1. swagger_find: 精确查找指定路径和方法的接口（返回基本信息）
2. swagger_search: 模糊搜索接口（支持按路径、摘要、operationId 搜索）
3. swagger_get_detail: 获取接口的详细信息（包含参数、请求体、响应结构，自动解析了 $ref）
4. swagger_list_all: 列出所有接口（支持按方法和 tag 过滤）
5. swagger_list_by_tag: 按 tag 列出接口
6. swagger_get_tags: 获取所有可用的 tags 列表
7. swagger_refresh: 强制刷新 Swagger 文档缓存
8. swagger_stats: 获取缓存统计信息

IDE 配置示例 (Cursor / Cline / Windsurf / Claude Desktop 等)

要在 AI 辅助编程工具中使用本服务，请在对应 IDE 的 MCP 配置文件中添加如下配置（以 mcp_config.json 或 cline_mcp_settings.json 为例）：

{
  "mcpServers": {
    "api-mcp": {
      "command": "node",
      "args": [
        "/绝对路径/至/您的/api-mcp/build/index.js"
      ],
      "env": {
        "SWAGGER_URL": "http://127.0.0.1:8080/v2/api-docs",
        "SWAGGER_AUTH_MODE": "bearer",
        "SWAGGER_BEARER_TOKEN": "your-auth-token-here"
      }
    }
  }
}

注意：请将 args 中的路径替换为 api-mcp 构建后的 build/index.js 实际所在绝对路径。