trae-swagger-mcp 插件开发分享
- 背景
- 介绍
- 实现
- 效果
- 进阶
- 总结
背景
针对 Trae IDE 无法直接解析 JSON 文件、且仅 DouBao 模型支持图片理解的限制，所以开发了本工具
其实上传接口文档的截图，让 AI 解析图片上的内容也十分方便，但是我想要解析完成的内容能直接帮我用Ant Design 表格组件完成页面开发，需要满足0个错别字的要求，截图有点难以实现。而且公司项目的某些接口，后端返回的业务字段经常都20、30个，长截图起来也很麻烦
其实市面上也有相应的工具：vite-plugin-swagger-mcp，但是公司部分项目还是用的webpack，这个也就不适用了
介绍
最初的设计思路，是想实现自动化文档获取（自动登录、接口搜索与解析文档）并用 Ant Design 表格展示返回的字段。但由于 Swagger + Knife4j 采用 Alert 弹窗登录方式（非 Token 认证），自动化登录难以实现
目前的实现是采用手动导入 JSON 文档的方式，确保安全性与稳定性：用户只需登录接口文档平台，导出 JSON 数据并粘贴至指定位置，即可通过 Trae IDE 智能体便捷查询接口信息，大大提升开发效率，也是这个实现恰巧兼容了 Yapi、Apifox 还有其它接口文档的解析，因为实现思路都是大差不差的
实现
其实10月份的时候就已经做的七七八八了，但是不是特别“智能”，get请求、post请求参数都解析不明白。更别说post请求有分好多种 Content Type，智能体也不是很理解文档的结构
分享一下实现思路，还有踩坑的地方
Github源码：https://github.com/QianYin-Zhou/trae-swagger-mcp
一、生成简单的MCP Server
直接跟 Trae AI 说创建一个 MCP Server 项目，想让它读取根目录的swagger-doc.json文件，简单解析这个文件的大致内容和文件大小
开发 MCP 工具主要是这个依赖：@modelcontextprotocol/sdk
{"name":"trae-swagger-mcp","version":"1.0.0","description":"trae-swagger-mcp 是一款基于 Trae IDE 的 MCP 工具，专为解析和处理接口文档而设计","type":"module","main":"swagger-reader.js","scripts":{"test":"node swagger-reader-test.js","start:reader":"node swagger-reader.js","start:server":"node swagger-server.js"},"keywords":[],"author":"cissy <2405071403@qq.com>","license":"ISC","dependencies":{"@modelcontextprotocol/sdk":"^1.20.0","express-basic-auth":"^1.2.1","node-fetch":"^3.3.2","zod":"^3.25.76"}}二、跑通流程
Trae IDE再新建一个项目或者直接用公司项目，先打开设置
选择 “手动添加” 自己开发的 MCP Server，可参考以下配置：
{"mcpServers":{"swagger-reader":{"command":"node","args":["D:/newer/trae-swagger-mcp/swagger-reader.js"]}}}这里swagger-reader为工具名称，args必须填写绝对路径才能确保在任何项目中都能正常使用。
配置效果：
添加完工具之后，还要去添加智能体
输入对话
AAASwagger专家，请阅读文档，给输出文档的大致内容、文档的大小没问题的话就是完全跑通了
三、不断调整
确认流程能跑通之后，专注工具的开发。工具开发的核心思路就是：让 Trae 能够“理解”你的 API 接口数据结构
再建一个swagger-reader-test.js文件，用控制台测试输出的文本，这样就不需要老是切项目
这个“翻译”过程可以让 AI 反复修改，一直到能让它：无论复制哪个接口，什么请求，请求参数含有对象嵌套对象、响应体含有对象嵌套对象再嵌套对象，也能列出前端开发所需要的数据
效果
示例：请求参数是一个对象，这个对象嵌套了对象
接口文档，不论 yapi 还是 swagger，还是apifox ，一般都能将文档导出为 json 格式
输入对话
AAASwagger专家，请阅读文档，当前请求接口名称是什么，需要什么请求参数，是什么contenttype对话效果
这里完全是一一对应的，没有错别字，再多训练训练，让它把字段处理一下，开发也能更高效。甚至也能让它可视化输出
让上面返回的接口信息，搭配组件一起使用。比如 xxx列表接口信息转成Ant Design Vue 表格组件所需的列配置
其它的 Descriptions 描述列表组件也行！
进阶
如果还想提高效率，可以配置单个项目的规则。不清楚别的IDE有没有这个功能，反正在Trae IDE中，项目规则的意思是：
在项目中创建 .trae/rules/project_rules.md 文件定义 TRAE 在当前项目中对话时需要遵循的规则。
就是一个 Markdown 文件
比如让它把接口加在src\api\urls.js文件上，输入对话：
AAASwagger专家，你已经把文档解析的特别棒了。我第一次用Trae IDE我想知道`project_rules.md`这个rules我该怎么写？ 需求：现在读取解析文档做得特别好，但是我得把解析完的东西放在我的项目代码上，比如当前的接口：“/ut/lock/add” 接口，判断有没有存在`src\api\urls.js`的 rfidUrl 上，没有的话，要帮我加上去，顺便要加一条中文注释在上方 我想把上面的需求固定成一句话，我怎么去写`project_rules.md`这个文件？继续训练，让它判断重复的同时，告诉我哪里重复，对话
继续优化规则文档，有些场景，比如：“AAASwagger专家，给我返回请求参数，并且把接口信息添加到 projectUrl 上”, 但是 lockUrl 已存在了这个接口，这时候你要跟我说“不允许添加在projectUrl ，在 lockUrl 存在接口。请不要重复添加，请引用 lockUrl ”最终的Trae Rules 规则示例：
总结
AI 就是一张白纸，需要很细致地教它怎么读懂文档。简单它能懂，但是复杂的还是要疯狂写注释，让它读懂；输出过程中，如果它犯错，要纠正，然后优化项目规则让它永远记住！很好，今天周五，祝大家训“狗”愉快！
