MCP Server 运行模式入门（Streamable HTTP / stdio）
目标：把你当前项目里“关键类/方法/字段”与 MCP 协议运行流程对上号，尽量解释“它在做什么、为什么需要它”。
目录
- 一、Streamable HTTP 模式（基于 WebFlux）
- 二、stdio 模式（基于标准输入输出）
- 三、两种模式对比与选型
- 四、项目内关键类逐段解读（对照源码）
- 五、常见疑问与排查思路
一、Streamable HTTP 模式（基于 WebFlux）
1. 适用场景
- 需要把 MCP Server 作为常驻服务部署（本机、服务器、容器）。
- 需要通过HTTP接入（便于反向代理、网关、HTTPS、负载均衡）。
- 多客户端或并发调用场景更合适。
2. 核心概念
- Streamable HTTP：MCP 的一种传输方式，统一通过单一 HTTP 端点传输消息。
- 端点：例如
/mcp/message，客户端在此进行初始化、调用工具与接收服务端推送。 - WebFlux：Spring 的响应式 Web 容器，用于承载 Streamable HTTP 的路由与流式消息。
3. 运行流程（概念图）
4. 关键配置项（你的项目里）
spring.ai.mcp.server.stdio=false- 含义：关闭 stdio，启用 HTTP 传输。
spring.main.web-application-type=reactive- 含义：使用 WebFlux 作为容器。
spring.ai.mcp.server.sse-message-endpoint=/mcp/message- 含义：Streamable HTTP 端点路径。
server.port=8101- 含义：HTTP 服务监听端口。
5. WebFlux 与 MVC 的区别（简要对比）
| 维度 | WebFlux | Spring MVC |
|---|---|---|
| 编程模型 | 响应式（Reactive Streams） | 同步阻塞 |
| 线程模型 | 少量线程处理大量连接 | 一请求一线程 |
| 适合场景 | 高并发、流式传输、SSE | 传统表单/REST、同步调用 |
| 依赖容器 | Netty/响应式容器 | Servlet 容器 |
| MCP 适配 | Streamable HTTP 更自然 | 需要额外适配或走 stdio |
二、stdio 模式（基于标准输入输出）
1. 适用场景
- MCP Server 不需要暴露 HTTP 服务，仅在本机被 MCP Client 调用。
- 更适合开发调试、小工具、单用户场景。
2. 核心概念
- stdio：MCP Client 拉起 MCP Server 进程，通过 stdin/stdout 进行 JSON-RPC 通信。
- 进程生命周期：通常由客户端控制，客户端启动时拉起，结束时退出。
3. 运行流程（概念图）
4. 关键配置项（思路说明）
spring.ai.mcp.server.stdio=true- 含义：启用 stdio 模式。
spring.main.web-application-type=none- 含义：不启动 Web 容器。
三、两种模式对比与选型
| 维度 | Streamable HTTP | stdio |
|---|---|---|
| 通信方式 | HTTP 单端点流式 | stdin/stdout |
| 部署形态 | 常驻服务 | 被客户端拉起 |
| 并发能力 | 好 | 一般 |
| 网络要求 | 需要端口 | 无需端口 |
| 适用场景 | 多用户/生产 | 单机/开发 |
四、项目内关键类逐段解读（对照源码）
下面按你项目里的核心类解释“它的意义”和“它做了什么”。
1.StreamableMcpServerConfiguration
文件：mcp-core/src/main/java/com/xbk/mcp/server/infrastructure/mcp/StreamableMcpServerConfiguration.java
(1) 类级别注解
@Configuration- 标识这是 Spring 配置类，负责创建 Bean。
@EnableConfigurationProperties(McpServerProperties.class)- 绑定
spring.ai.mcp.server.*配置。
- 绑定
@ConditionalOnClass(...)- 只有当 MCP + WebFlux 相关类存在时才启用（避免缺依赖启动失败）。
@ConditionalOnExpression("${spring.ai.mcp.server.enabled:true} && !${spring.ai.mcp.server.stdio:true}")- 配置启用 MCP 且 stdio 关闭时，才启用 Streamable HTTP。
(2)streamableServerTransportProvider(...)
- 作用：提供 Streamable HTTP 传输实现。
- 关键点：读取
sseMessageEndpoint（默认/mcp/message），并构建 WebFlux 传输提供器。
(3)mcpStreamableRouterFunction(...)
- 作用：把 MCP 的 HTTP 路由注册到 WebFlux 中。
- 结果：WebFlux 会把
/mcp/message交给 MCP 处理。
(4)mcpServerCapabilitiesBuilder()
- 作用：创建 MCP ServerCapabilities 的 Builder。
- 结果：后续会把“工具/资源/提示”能力声明进去。
(5)mcpStreamableSyncServer(...)
- 作用：创建 MCP Server 实例并注册能力。
- 具体流程：
- 组装
serverInfo（名称、版本）。 - 创建
McpServer.sync(transportProvider)。 - 从 Spring 容器里收集 Tool/Resource/Prompt。
- 注册到
serverBuilder。 - 设置
capabilitiesBuilder。 build()生成 MCP Server。
- 组装
(6) 关键字段含义
McpStreamableServerTransportProvider transportProvider- HTTP 传输层（Streamable HTTP），负责消息通道。
McpSchema.ServerCapabilities.Builder capabilitiesBuilder- MCP 服务端能力声明。
ObjectProvider<List<ToolCallback>> toolCallbacksProvider- Spring 容器里所有 @McpTool 形成的回调。
2.McpServerProperties
文件：mcp-core/src/main/java/com/xbk/mcp/server/infrastructure/mcp/McpServerProperties.java
enabled：是否启用 MCP Server。name/version：用于 initialize 返回的服务端标识。stdio：是否走 stdio 传输。sseMessageEndpoint：Streamable HTTP 端点。toolChangeNotification/resourceChangeNotification/promptChangeNotification：能力变更通知开关。
3.HttpClientLogInterceptor
文件：mcp-core/src/main/java/com/xbk/mcp/server/infrastructure/logging/HttpClientLogInterceptor.java
- 作用：统一记录外部 HTTP 请求的请求头、请求体、响应体、耗时。
- 关键点：
requestBody：读取并压成单行日志。response.peekBody(...)：读取响应，不消费原始响应流。toSingleLine：把换行替换成\\n以保证日志单行。
4.CsdnToolApplication
文件：mcp-tool-csdn/src/main/java/com/xbk/mcp/server/CsdnToolApplication.java
- 作用：启动 MCP Server（CSDN 模块）并输出启动日志。
- 说明：它不直接管 MCP 逻辑，真正的 MCP Server 在
mcp-core里装配。
五、常见疑问与排查思路
1. Claude Code 显示not authenticated
- 通常是 MCP 配置 schema 不匹配（
type写错、url未指向/mcp/message）。
2. 日志出现协议版本警告
- 客户端与服务端支持版本不一致，一般会降级继续运行。
3. 工具调用不上
- 检查：
@McpTool是否被扫描到- 服务端是否启用了 MCP
- Tool 是否在容器里生成 Bean
备注：如果你希望“对照源码逐行讲解”
你可以告诉我你最不理解的类或方法，我可以进一步拆成“每一段在做什么”。
