模块路径:langchain4j-spring-ai-swagger-mcp
目标:将任意 OpenAPI/Swagger (3.x) 文档映射为 MCP 的 tools/resources/prompts,让大模型能安全、可控地调用后端接口。
1. 背景与价值
在大模型接入业务系统时,最头疼的是'如何稳定地调用接口'。Swagger MCP 的价值是:
介绍 Swagger MCP 模块,旨在将 OpenAPI/Swagger 文档映射为 MCP 的 tools/resources/prompts,使大模型能安全调用后端接口。核心功能包括接口规范化、鉴权治理及前端自动化生成。通过 Spring Boot 启动 MCP Server,支持 SSE/stdio 传输。文章详解了 OpenApiLoader、Normalizer、ToolSpecFactory 等组件,提供了配置示例、SSE 调用闭环流程及常见问题排查思路。该方案解决了模型稳定调用接口的痛点,适合 AI Agent 生产环境接入。
模块路径:langchain4j-spring-ai-swagger-mcp
目标:将任意 OpenAPI/Swagger (3.x) 文档映射为 MCP 的 tools/resources/prompts,让大模型能安全、可控地调用后端接口。
在大模型接入业务系统时,最头疼的是'如何稳定地调用接口'。Swagger MCP 的价值是:
对应模块规划见:langchain4j-spring-ai-swagger-mcp/swagger-mcp-skills-plan.md。
核心入口:langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/SwaggerMcpServerApplication.java
配置示例(来自 application.yml):
server:
port: 3000
transport:
mode: sse
swagger:
mcp:
services:
- serviceKey: local
openapiUrl: http://127.0.0.1:9010/v3/api-docs/default
baseUrl: http://127.0.0.1:9010
toolMode: perOperation
timeoutMs: 8000
maxBodyBytes: 1048576
auth:
type: none
文件:langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/openapi/OpenApiLoader.java
文件:langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/openapi/OpenApiNormalizer.java
operationId。文件:langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/openapi/ToolSpecFactory.java
svc.{serviceKey}.{operationId}。文件:langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/openapi/OpenApiInvoker.java
文件: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:自省工具。Spring 配置入口:SwaggerMcpServerConfig
典型启动命令(Windows CMD):
cd /d D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai
mvn -pl langchain4j-spring-ai-swagger-mcp -am spring-boot:run
完整流程详见:langchain4j-spring-ai-swagger-mcp/doc/swagger-mcp-call.md
curl.exe -N "http://127.0.0.1:3000/sse"
拿到 sessionId 后拼接 message endpoint。
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\":{}}"
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\"}}}"
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\"}}}}"
perOperation(默认)或 callOnly。reload 可强制刷新 OpenAPI。tools/list 为空:服务未启动或端口不对。listOperations 为空:OpenAPI 解析失败或地址不可达。call 报 operation not found:operationId 不存在或未加载。更多排错点:langchain4j-spring-ai-swagger-mcp/doc/swagger-mcp-call.md。
Swagger MCP 的核心思路是:把 OpenAPI 翻译成 LLM 能稳定执行的 MCP 工具。它解决了'模型无法稳定调用接口'的痛点,并将鉴权、限流、日志等治理能力集中在中间层,适合用于 AI Agent 的生产环境接入。
如果你正在做'模型 + 业务系统'的落地,建议优先把接口能力变成 MCP 工具,再谈提示词与前端自动化。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online