Swagger MCP 实战：把 OpenAPI 变成可控的 MCP 工具（Spring Boot + Spring AI）

模块路径：langchain4j-spring-ai-swagger-mcp

目标：将任意 OpenAPI/Swagger (3.x) 文档映射为 MCP 的 tools/resources/prompts，让大模型能安全、可控地调用后端接口。
Git 仓库： langchain4j-spring-agent/langchain4j-spring-ai/langchain4j-spring-ai-swagger-mcp

1. 背景与价值

在大模型接入业务系统时，最头疼的是"如何稳定地调用接口"。Swagger MCP 的价值是：

把接口能力规范化为 MCP tools，避免模型在对话里硬拼 curl。
接口调用链可治理：鉴权、超时、限流、审计集中到 MCP 层。
支持前端自动化生成：模型先读 tool schema，再生成页面与调用链。

对应模块规划见：langchain4j-spring-ai-swagger-mcp/swagger-mcp-skills-plan.md。

2. 模块结构与启动入口

核心入口：langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/SwaggerMcpServerApplication.java

作为独立 Spring Boot 服务启动。
对外暴露 MCP server（SSE/stdio），默认 SSE。

配置示例（来自 application.yml）：

yaml 复制代码

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

3. 核心组件解读

3.1 OpenApiLoader：加载与缓存

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

支持 URL / 本地文件加载 OpenAPI。
缓存 OpenAPI 实例与原始 JSON Map。
支持文档拉取鉴权 headers。

3.2 OpenApiNormalizer：规整接口结构

文件：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）：

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 会话

cmd 复制代码

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

拿到 sessionId 后拼接 message endpoint。

5.2 列出工具

cmd 复制代码

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 列表

cmd 复制代码

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 通用调用

cmd 复制代码

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 工具，再谈提示词与前端自动化。