trae-swagger-mcp

介绍

trae-swagger-mcp 是一款基于 Trae IDE 的 MCP 工具，专为解析和处理接口文档而设计。工具核心功能是将 Swagger 接口文档（Swagger + Knife4j等）的 JSON 结构转换为可在 Trae IDE 中便捷查询的格式，大大提升接口文档的使用效率

适用范围：完美适配 Swagger 与 Knife4j 结合的接口文档；对于其它接口文档，比如yapi、自定义的，虽然不支持，但是本工具的实现思路也许能帮到你

背景

针对 Trae IDE 无法直接解析 JSON 文件，仅 DouBao 模型支持图片理解的限制，本工具提供了一种更高效更兼容的接口文档处理方案

【设计思路】最初规划实现自动化文档获取（自动登录、接口搜索与解析文档）并生成 Ant Design 表格展示。但由于 Swagger + Knife4j 采用 Alert 弹窗登录方式（非 Token 认证），自动化登录存在技术限制

【当前实现】采用手动导入 JSON 文档的方式，确保安全性与稳定性：用户只需登录接口文档平台，导出 JSON 数据并粘贴至指定位置，即可通过 Trae IDE 智能体便捷查询接口信息，大幅提升开发效率

开发

克隆或下载项目后，先安装依赖：

# node v16.18.1
npm install

使用 Trae IDE 进行开发，运行测试命令查看工具的解析效果：

npm run test

其实就是告诉 Trae IDE 这个 json 格式的接口文档应该怎么能看得懂，用文本的方式输出

核心配置

swagger-reader.js

• SWAGGER_FILE_PATH：需设置为 JSON 文档的绝对路径
• parseSwaggerDocument 方法：在 ./common.js 文件中根据接口文档结构进行自定义配置

swagger-server.js

• 预留模块，计划用于扩展自动化文档获取功能

注意事项

修改代码后，需在 Trae IDE 的 MCP 设置中点击「重启」按钮，最好新开一个项目去测试

使用

工具配置

首次使用需在 Trae IDE 中完成以下配置

1. 添加 MCP 服务器

手动配置 MCP 服务器，示例配置：

{
  "mcpServers": {
    "swagger-reader": {
      "command": "node",
      "args": [
        "D:/newer/trae-swagger-mcp/swagger-reader.js"
      ]
    }
  }
}

注意事项：

• swagger-reader 为工具名称
• args 必须填写绝对路径，确保在任何项目中都能正常使用

2. 创建智能体

新建智能体或者编辑智能体，示例配置：

智能体名称：swagger 专家
提示词：当我说"AAASwagger专家"，你用swagger-reader这个MCP工具，直接帮我读取并解析swagger-doc.json这个接口文档
工具：swagger-reader
工具-内置：关闭"预览"、关闭"联网搜索"

简单使用

1. 准备接口文档

登录 Swagger 接口文档平台，导出接口数据为 JSON 格式，粘贴至项目根目录的 swagger-doc.json 文件中。

2. 启动查询

• 打开 Trae IDE，创建或打开任意项目
• 新建对话，选择「swagger 专家」智能体
• 使用指令触发工具，可以参考以下指令：

AAASwagger专家，请阅读文档，当前接口路径是什么，接口中文名称是什么
AAASwagger专家，请阅读文档，当前post请求接口名称是什么，content type是什么，需要什么请求参数
AAASwagger专家，请阅读文档，当前请求接口名称是什么，返回了什么业务数据给前端

3. 文档更新

每次需要查询新接口时，重复步骤 1 更新 swagger-doc.json 文件内容。

高级使用

通过训练智能体和配置项目规则，可以将接口信息解析与页面开发流程深度融合，可参考我的博客《Trae IDE 读取并解析接口文档：trae-swagger-mcp 插件开发分享》