Swagger MCP 实战：基于 Spring Boot 与 Spring AI 将 OpenAPI 转为工具

文件：langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/openapi/OpenApiNormalizer.java

• 生成规范化 operation 结构。
• 自动补齐缺失 operationId。
• 提取参数、requestBody、response schema。

3.3 ToolSpecFactory：生成工具规范

文件：langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/openapi/ToolSpecFactory.java

• 生成工具名：svc.{serviceKey}.{operationId}。
• 把参数与 body 映射为 tool input schema。

3.4 OpenApiInvoker：执行调用

文件：langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/openapi/OpenApiInvoker.java

• 按 operationId + args 拼出真实 HTTP 请求。
• 支持 body / header 参数。
• 具备超时、最大响应体限制。

3.5 SwaggerCallTool：MCP 工具入口

文件：langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/tools/SwaggerCallTool.java

暴露的 MCP tools 包括：

• listApis：列出已加载 OpenAPI 服务。
• listOperations：分页返回 operationId 列表。
• call：通用调用入口（serviceKey + operationId + args）。
• getComponents / getInfo / getServers / getPaths：自省工具。

4. MCP 服务配置与启动

Spring 配置入口：SwaggerMcpServerConfig

• 支持 SSE 或 stdio。
• 自动注册工具到 MCP server。
• 提供请求日志过滤。

典型启动命令（Windows CMD）：

cd /d D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai
mvn -pl langchain4j-spring-ai-swagger-mcp -am spring-boot:run

5. 调用闭环（SSE 示例）

完整流程详见：langchain4j-spring-ai-swagger-mcp/doc/swagger-mcp-call.md

5.1 建立 SSE 会话

curl.exe -N "http://127.0.0.1:3000/sse"

拿到 sessionId 后拼接 message endpoint。

5.2 列出工具

curl.exe -X POST "http://127.0.0.1:3000/mcp/message?sessionId=你的 sessionId" ^
-H "Content-Type: application/json" ^
-d "{\"jsonrpc\":\"2.0\",\"id\":\"1\",\"method\":\"tools/list\",\"params\":{}}"

5.3 获取 operationId 列表

curl.exe -X POST "http://127.0.0.1:3000/mcp/message?sessionId=你的 sessionId" ^
-H "Content-Type: application/json" ^
-d "{\"jsonrpc\":\"2.0\",\"id\":\"2\",\"method\":\"tools/call\",\"params\":{\"name\":\"listOperations\",\"arguments\":{\"serviceKey\":\"local\"}}}"

5.4 通用调用

curl.exe -X POST "http://127.0.0.1:3000/mcp/message?sessionId=你的 sessionId" ^
-H "Content-Type: application/json" ^
-d "{\"jsonrpc\":\"2.0\",\"id\":\"3\",\"method\":\"tools/call\",\"params\":{\"name\":\"call\",\"arguments\":{\"serviceKey\":\"local\",\"operationId\":\"getUserById\",\"args\":{\"id\":\"123\"}}}}"

6. 设计要点与可扩展点

• 工具模式切换：perOperation（默认）或 callOnly。
• 鉴权集中化：bearer/apiKey/basic 统一在 MCP 层注入。
• 安全边界：可对 OpenAPI 拉取 + 下游调用进行限制。
• 缓存与热更新：reload 可强制刷新 OpenAPI。

7. 常见问题（排障思路）

• tools/list 为空：服务未启动或端口不对。
• listOperations 为空：OpenAPI 解析失败或地址不可达。
• call 报 operation not found：operationId 不存在或未加载。

更多排错点：langchain4j-spring-ai-swagger-mcp/doc/swagger-mcp-call.md。

8. 小结

Swagger MCP 的核心思路是：把 OpenAPI 翻译成 LLM 能稳定执行的 MCP 工具。它解决了'模型无法稳定调用接口'的痛点，并将鉴权、限流、日志等治理能力集中在中间层，适合用于 AI Agent 的生产环境接入。

如果你正在做'模型 + 业务系统'的落地，建议优先把接口能力变成 MCP 工具，再谈提示词与前端自动化。