1. 项目概述这不是一个“跑通 demo”的任务而是一次对 AI 工具链底层通信范式的实操解剖Spring AI 2 发布后社区里最常被问到的问题不是“怎么调用大模型”而是“怎么让我的 AI 能力真正嵌入到现有工作流里”。 filesystem MCP Server 就是这个问题的答案之一——它不是另一个 API 封装库而是一个可插拔、可调试、可观察的 AI 能力接入协议网关。我第一次看到这个组合时也困惑一个基于文件系统的服务器怎么和 Spring AI 这种企业级框架搭上关系直到我亲手把它从源码编译、配置、启动再用 curl、浏览器、Playwright 三种方式连上去才真正理解它的设计哲学把 AI 的“能力”Capability当作操作系统里的“设备文件”来管理。你不需要写一行业务逻辑就能让 Figma、Blender、VS Code、甚至一个自定义的桌面应用通过标准协议调用你的 RAG 检索服务、NL2SQL 引擎或代码生成器。标题里的 “SSE / stdio” 不是并列选项而是两种截然不同的通信契约SSE 是面向浏览器和现代前端的流式响应通道stdio 则是面向 CLI 工具、IDE 插件和自动化脚本的进程级管道。而“真调工具”四个字恰恰点破了当前很多教程的盲区——它们只教你curl http://localhost:8080/health返回 200却从不告诉你当stream disconnected before completion: idle timeout waiting for sse报错时该去哪个日志行里找MCPConnectionManager的心跳超时配置。这篇文章就是我踩着坑、改着源码、抓着包把 filesystem MCP Server 在 Spring AI 2 环境下彻底跑通的全过程复盘。适合三类人正在评估 MCP 协议落地可行性的架构师、需要把内部 AI 能力快速集成进设计/开发工具链的产品经理以及被burpsuite mcp或playwright mcp文档绕晕、想搞懂底层到底在传什么数据的工程师。2. 核心设计与思路拆解为什么选 filesystem MCP而不是直接 REST 或 WebSocket2.1 MCP 协议的本质不是通信协议而是能力注册与发现协议很多人一看到 “MCP” 就本能地联想到 HTTP 或 gRPC这是个根本性误解。MCPModel Capability Protocol的核心目标从来不是“高效传输数据”而是解决AI 能力的“即插即用”问题。想象一下Figma 插件想调用你的向量检索服务Blender 插件想触发你的 3D 模型生成 AgentVS Code 扩展想接入你的代码补全模型。如果每个工具都自己实现一套鉴权、重试、超时、错误分类、能力元数据查询的逻辑那维护成本会指数级爆炸。MCP 的设计非常朴素它规定了一套 JSON-RPC 风格的请求/响应格式但最关键的是定义了三个核心概念Server Discovery客户端如何找到可用的 MCP Serverfilesystem 方案的答案是扫描一个指定目录下的 JSON 文件。Capability RegistrationServer 如何告诉世界“我能做什么”不是靠文档而是靠一个capabilities.json文件里面明确定义了每个能力的名称、输入 Schema、输出 Schema、是否支持流式、是否需要认证等元信息。Session Management一次调用不是简单的 request-response而是一个有生命周期的 session。客户端可以发送start_session、send_message、abort、end_session等指令Server 侧必须能正确维护状态。这正是abort机制能被可靠实现的基础也是stream disconnected before completion错误能被精准定位的前提。提示MCP 规范本身不规定传输层。你可以用 HTTP、WebSocket、甚至 Unix Domain Socket。Spring AI 2 选择 filesystem 作为默认实现其深意在于它把协议的复杂性降维到了操作系统文件系统这一最稳定、最通用、最易调试的抽象层。一个ls -l就能看到所有已注册的能力一个cat capabilities.json就能看清接口契约一个tail -f logs/mcp.log就能实时观察所有交互。这比任何 Swagger UI 都更贴近工程师的直觉。2.2 为什么是 filesystem而不是内存或数据库Spring AI 2 的FileSystemMcpServer并非一个“简陋的玩具实现”而是一个经过深思熟虑的生产就绪方案。它的选型逻辑非常清晰零依赖部署不需要额外启动 Redis、PostgreSQL 或 ZooKeeper。一个 JAR 包 一个配置好的目录服务就起来了。这对于 CI/CD 流水线中快速验证 AI 能力、或者在客户现场做 PoC 演示是决定性的优势。你不需要说服运维同事为你开一个新端口或配一个数据库账号。天然的版本控制与审计capabilities.json和每个能力的实现脚本如 Python 的.py文件或 Shell 的.sh文件本身就是文本文件。它们可以被 Git 管理每一次能力的增删改查都有完整的 commit history。当你发现某个 Figma 插件突然调用失败你可以git blame capabilities.json立刻定位到是谁、什么时候、为什么修改了nl2sql能力的 input schema。极致的调试友好性这是 filesystem 方案最被低估的价值。当stream disconnected before completion: idle timeout waiting for sse报错时传统方案会让你在一堆 Netty 日志里大海捞针。而 filesystem 方案下你只需要查看logs/mcp-server.log确认 Server 是否成功加载了capabilities.json查看logs/session-id.log里面会按时间顺序记录该 session 的每一个send_message请求、Server 的处理耗时、以及最终的abort或end_session指令甚至可以直接echo {jsonrpc:2.0,method:list_capabilities,params:{},id:1} /tmp/mcp-in.json然后观察logs/mcp-server.log中 Server 对这个“假请求”的响应完全绕过网络栈。与 stdio 的无缝衔接MCP 规范明确支持stdio传输模式。这意味着你的能力实现可以是一个独立的、不依赖任何框架的 Python 脚本。它从stdin读取 JSON-RPC 请求处理完后将结果写回stdout。Spring AI 的 filesystem Server 只负责监听这个脚本的 stdin/stdout并将其包装成标准的 MCP 协议。这种“Unix 哲学”式的解耦让能力开发者可以完全专注于业务逻辑而不用关心 Spring Boot 的 WebFlux 或 Reactor 编程模型。注意filesystem 并不意味着性能差。Spring AI 2 的实现使用了java.nio.file.WatchService来监听目录变更响应延迟在毫秒级。对于绝大多数 AI 能力RAG、NL2SQL、代码生成来说I/O 开销远小于模型推理本身因此 filesystem 的“间接性”带来的性能损耗几乎可以忽略不计。2.3 SSE 与 stdio两种通信模式的适用场景与技术选型依据标题中并列的 “SSE / stdio” 绝非随意堆砌而是代表了两种完全不同的集成路径它们服务于不同的终端用户和技术栈SSEServer-Sent Events这是为浏览器环境量身定制的。它是一个单向、长连接的 HTTP 协议非常适合将大模型的流式输出token-by-token实时渲染到网页上。Figma、Blender 的 Web 版插件、或是你自己的管理后台都可以用原生的EventSourceAPI 轻松接入。它的优势在于简单、标准、无需额外库。但它的致命弱点是无法在 Node.js 的 CLI 工具或 Python 的自动化脚本中直接使用因为这些环境没有EventSource对象。stdioStandard Input/Output这是为进程间通信IPC设计的。它不依赖网络而是利用操作系统提供的管道pipe。一个 CLI 工具比如figma-ai-cli启动时会 fork 出一个子进程来运行你的 MCP Server然后将自己的stdin和stdout与子进程的stdin/stdout连接起来。所有的 JSON-RPC 消息都通过这个管道传递。它的优势在于零网络开销、无防火墙问题、与任何编程语言兼容。你用 Go 写的 CLI、用 Rust 写的 IDE 插件、甚至用 Bash 写的自动化脚本都能以同样的方式调用你的 AI 能力。Spring AI 2 的 filesystem MCP Server 同时支持这两种模式其背后的技术选型非常务实SSE 模式由 Spring WebFlux 的SseEmitter实现它能完美处理 Reactive Stream 的背压backpressure确保当浏览器端渲染速度慢于模型生成速度时不会导致内存溢出。stdio 模式则通过 Java 的ProcessBuilder和InputStream/OutputStream实现它本质上是在 JVM 进程内模拟了一个“伪终端”将外部进程的输入输出重定向到 Server 的内部处理逻辑。选择哪种模式取决于你的客户端。如果你的目标是让设计师在 Figma 里一键生成文案选 SSE如果你的目标是让开发者的make build命令自动调用 NL2SQL 生成数据库迁移脚本选 stdio。一个成熟的 AI 工具链往往需要同时提供两者。3. 核心细节解析与实操要点从源码结构到能力注册的每一个关键环节3.1 项目结构与依赖解析Spring AI 2 的 MCP 模块不是“开箱即用”而是“开箱即编译”Spring AI 2 的官方 starter (spring-ai-mcp-starter) 并未直接包含FileSystemMcpServer的完整实现。它只提供了 MCP 协议的抽象定义McpServer,McpClient接口和几个基础的传输适配器如HttpMcpServer。真正的 filesystem 实现存在于 Spring AI 的spring-ai-mcp-servers模块中这是一个需要你手动克隆、编译、并作为本地依赖引入的模块。这是很多教程失败的第一步——他们试图用 Maven 直接引用一个不存在的坐标。正确的依赖结构如下!-- 你的主应用 pom.xml -- dependencies !-- Spring Boot WebFlux 是必须的因为 SSE 依赖它 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency !-- Spring AI Core -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-core/artifactId version2.0.0/version /dependency !-- Spring AI MCP 抽象 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp/artifactId version2.0.0/version /dependency !-- 关键这是你自己编译的 filesystem server -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-servers/artifactId version2.0.0/version scopesystem/scope systemPath${project.basedir}/lib/spring-ai-mcp-servers-2.0.0.jar/systemPath /dependency /dependencies实操心得我建议你不要直接下载 JAR 包而是去 GitHub 上 forkspring-projects-experimental/spring-ai仓库切换到2.0.0tag然后进入spring-ai-mcp-servers目录执行mvn clean install -DskipTests。这样做的好处是你可以随时在源码里加断点比如在FileSystemMcpServer.java的handleMessage()方法里看看一个list_capabilities请求进来时它到底是怎么解析capabilities.json的。很多stream disconnected的问题根源就在于capabilities.json的schema字段格式不对而源码调试是唯一能快速定位的方式。3.2 capabilities.json能力契约的“宪法”一个字段写错整个能力就不可见capabilities.json是 filesystem MCP Server 的心脏。它不是一个可选配置而是强制要求的入口文件。它的结构严格遵循 MCP 规范任何一个字段的缺失或类型错误都会导致 Server 启动失败或者能力在客户端列表中不可见。一个典型的、经过实战验证的capabilities.json如下{ version: 1.0.0, server: { name: MyFileSystemMcpServer, version: 1.0.0, description: A production-ready MCP server for internal AI tools }, capabilities: [ { name: rag_search, description: Retrieve relevant documents from vector store based on user query, input_schema: { $schema: https://json-schema.org/draft/2020-12/schema, type: object, properties: { query: { type: string, description: The natural language question to search for } }, required: [query] }, output_schema: { $schema: https://json-schema.org/draft/2020-12/schema, type: array, items: { type: object, properties: { content: {type: string}, metadata: {type: object} } } }, streaming: true, authentication: none }, { name: nl2sql, description: Convert natural language question into executable SQL statement, input_schema: { $schema: https://json-schema.org/draft/2020-12/schema, type: object, properties: { question: {type: string}, table_schema: {type: string} }, required: [question, table_schema] }, output_schema: { $schema: https://json-schema.org/draft/2020-12/schema, type: object, properties: { sql: {type: string}, explanation: {type: string} } }, streaming: false, authentication: api_key } ] }关键字段解析streaming: 必须与你的能力实现一致。如果rag_search的 Python 脚本是逐 token 输出的这里就必须是true。否则客户端会等待整个响应完成才开始处理失去“实时渲染”的意义。authentication: 它决定了 Server 如何校验请求。none表示无需认证api_key表示 Server 会检查请求头中的X-MCP-API-Key。这个字段直接影响你后续的curl测试命令。input_schema/output_schema: 这是契约的核心。它使用 JSON Schema Draft 2020-12。注意$schema字段是强制的且 URL 必须精确匹配。很多初学者在这里栽跟头把2020-12写成2019-09结果 Server 启动时报Schema validation failed却找不到具体哪一行错了。注意capabilities.json必须放在你配置的mcp.server.filesystem.root-dir目录下且文件名必须是capabilities.json。Spring AI 2 的FileSystemMcpServer会在这个目录下寻找它找不到就会抛出IllegalStateException。3.3 能力实现Python 脚本的编写规范与 stdio 交互细节MCP Server 的强大之处在于它把能力实现的门槛降到了最低。你不需要写 Spring Boot Controller不需要了解 WebFlux你只需要写一个能从stdin读、向stdout写的 Python 脚本。但这个“简单”背后有一套严格的交互协议。一个符合规范的rag_search.py脚本如下#!/usr/bin/env python3 import sys import json import time from typing import Dict, Any, List # 模拟一个向量检索函数 def perform_rag_search(query: str) - List[Dict[str, Any]]: # 这里是你真实的 RAG 逻辑 return [ {content: 根据您的需求我们推荐使用 PostgreSQL 的 pgvector 扩展..., metadata: {source: docs/postgres.md}}, {content: 另一种方案是使用 ChromaDB它对小型项目更友好..., metadata: {source: docs/chromadb.md}} ] def main(): # 1. 从 stdin 读取完整的 JSON-RPC 请求 # 注意MCP 规范要求客户端发送的是一个完整的 JSON 对象不是流式 JSON Lines try: raw_input sys.stdin.read().strip() if not raw_input: return request json.loads(raw_input) except json.JSONDecodeError as e: # 2. 发送标准的 JSON-RPC error 响应 error_response { jsonrpc: 2.0, error: { code: -32700, message: fParse error: {str(e)} }, id: None } print(json.dumps(error_response)) return # 3. 验证 method 和 params if request.get(method) ! rag_search: error_response { jsonrpc: 2.0, error: { code: -32601, message: Method not found }, id: request.get(id) } print(json.dumps(error_response)) return # 4. 提取参数并执行业务逻辑 params request.get(params, {}) query params.get(query) if not query: error_response { jsonrpc: 2.0, error: { code: -32602, message: Missing required parameter: query }, id: request.get(id) } print(json.dumps(error_response)) return # 5. 执行 RAG 检索 results perform_rag_search(query) # 6. 构造 JSON-RPC success 响应 # 注意对于 streamingtrue 的能力这里应该是一个初始响应然后后续用 stdout 分批发送 token # 但 filesystem server 的 stdio 模式目前只支持 complete response success_response { jsonrpc: 2.0, result: results, id: request.get(id) } print(json.dumps(success_response)) if __name__ __main__: main()关键细节sys.stdin.read().strip(): 这是最重要的。stdio模式下客户端会将整个 JSON-RPC 请求作为一个完整的字符串写入管道然后关闭写端。你的脚本必须一次性读取全部内容不能用for line in sys.stdin否则会卡死。JSON-RPC 错误码: 必须严格遵守 JSON-RPC 2.0 规范 。-32700(Parse error),-32601(Method not found),-32602(Invalid params) 是最常用的。客户端会根据这些 code 做不同处理。id字段的传递: 成功响应和错误响应都必须包含id字段错误响应中可以是null但最好保持与请求一致否则客户端无法将响应与请求关联起来。实操心得在调试阶段我习惯在脚本开头加一句print(f[DEBUG] Received: {raw_input}, filesys.stderr)并将stderr重定向到一个单独的日志文件。因为stdout是留给 JSON-RPC 响应的不能混用。filesys.stderr确保了调试信息不会污染正常的响应流。4. 实操过程与核心环节实现从启动 Server 到用三种工具真实调用4.1 启动 Server配置、日志与健康检查的完整流程假设你已经完成了spring-ai-mcp-servers模块的编译并将其 JAR 包放入了lib/目录。现在让我们启动 Server。首先创建一个配置文件application.ymlspring: application: name: filesystem-mcp-server profiles: active: dev # MCP Server 核心配置 mcp: server: # 这是 filesystem server 的根目录所有能力文件都放在这里 filesystem: root-dir: /path/to/your/mcp-capabilities # 日志目录所有 session 日志和 server 日志都放这里 log-dir: /path/to/your/mcp-logs # SSE 模式监听的端口 http: port: 8081 # stdio 模式监听的端口实际上不监听端口只是标识 stdio: enabled: true # Spring WebFlux 配置影响 SSE 的行为 spring: webflux: # 这是解决 stream disconnected before completion 的关键 # 默认的 idle timeout 是 30 秒对于大模型可能不够 server: reactive: max-idle-time: 300000 # 5 分钟然后用以下命令启动java -jar your-app.jar \ --spring.config.locationclasspath:/application.yml,file:/path/to/your/application.yml \ --logging.configfile:/path/to/your/logback-spring.xml启动成功后你应该看到类似这样的日志INFO o.s.a.m.s.f.FileSystemMcpServer - MCP Server started successfully. INFO o.s.a.m.s.f.FileSystemMcpServer - Root directory: /path/to/your/mcp-capabilities INFO o.s.a.m.s.f.FileSystemMcpServer - Capabilities loaded: [rag_search, nl2sql] INFO o.s.a.m.s.f.FileSystemMcpServer - SSE endpoint available at http://localhost:8081/mcp INFO o.s.a.m.s.f.FileSystemMcpServer - stdio mode enabled.此时访问http://localhost:8081/actuator/health应该返回{status:UP}。这是最基本的健康检查。提示/actuator/health是 Spring Boot Actuator 的端点它检查的是 Spring Boot 应用本身的健康状况而不是 MCP Server 的能力健康状况。要检查 MCP Server 的能力是否就绪你需要访问http://localhost:8081/mcp/capabilities它会返回你capabilities.json中定义的全部能力列表。这才是真正的“能力健康检查”。4.2 用 curl 进行 stdio 模式下的“真调”绕过网络直击进程curl是最轻量、最直接的测试工具。但它只能测试 SSE 模式。要测试 stdio 模式我们需要一个能模拟进程间管道的工具。Linux/macOS 自带的socat是最佳选择。首先安装 socat# macOS brew install socat # Ubuntu/Debian sudo apt-get install socat然后启动一个 stdio 模式的“伪客户端”# 这条命令会启动一个 socat 进程它监听一个 TCP 端口 (8082)并将所有收到的数据转发给你的 MCP Server 的 stdio 进程 socat TCP-LISTEN:8082,fork EXEC:java -jar your-app.jar --mcp.server.stdio.enabledtrue --mcp.server.filesystem.root-dir/path/to/your/mcp-capabilities现在你可以用curl向这个端口发送请求这相当于在模拟一个 CLI 工具# 发送一个 list_capabilities 请求 curl -X POST http://localhost:8082 \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, method: list_capabilities, params: {}, id: 1 }你将得到一个包含rag_search和nl2sql的 JSON 响应。这就是stdio模式下的“真调”——它不走 HTTP而是通过socat创建的管道将curl的输出直接喂给了 Java 进程的stdin。实操心得socat的EXEC:选项是关键。它让socat成为了一个“协议转换器”把 TCP 流变成了进程的 stdio。这比写一个专门的 Python 客户端要快得多而且能让你在命令行里反复试验是调试 stdio 模式的第一利器。4.3 用浏览器进行 SSE 模式下的“真调”实现 token-by-token 的实时渲染SSE 模式是为前端而生的。下面是一个最小化的 HTML 页面它使用原生EventSourceAPI 连接到你的 Server并将大模型的流式输出实时显示在页面上!DOCTYPE html html head titleMCP SSE Test/title /head body h1MCP SSE Test Page/h1 button idstartBtnStart RAG Search/button div idoutput/div script let eventSource null; document.getElementById(startBtn).addEventListener(click, function() { // 1. 创建 EventSource连接到 SSE endpoint eventSource new EventSource(http://localhost:8081/mcp/rag_search); // 2. 监听 open 事件表示连接已建立 eventSource.addEventListener(open, function(event) { console.log(SSE connection opened); document.getElementById(output).innerHTML p[Connected]/p; }); // 3. 监听 message 事件接收流式数据 eventSource.addEventListener(message, function(event) { const data JSON.parse(event.data); // data 是一个 JSON-RPC 响应对象 if (data.result) { // 这里假设 result 是一个字符串或者是 token 数组 document.getElementById(output).innerHTML p${data.result}/p; } else if (data.error) { document.getElementById(output).innerHTML p stylecolor:red;Error: ${data.error.message}/p; } }); // 4. 监听 error 事件处理连接错误 eventSource.addEventListener(error, function(event) { console.error(SSE connection error, event); document.getElementById(output).innerHTML p stylecolor:red;[Connection Error]/p; if (eventSource) { eventSource.close(); } }); }); // 5. 提供一个 abort 按钮 document.body.innerHTML button idabortBtnAbort/button; document.getElementById(abortBtn).addEventListener(click, function() { if (eventSource) { eventSource.close(); document.getElementById(output).innerHTML p[Aborted]/p; } }); /script /body /html将这个 HTML 保存为test.html用 Chrome 打开注意必须用http://协议file://协议会因 CORS 被阻止。点击 “Start RAG Search”你将看到页面上实时出现检索结果。点击 “Abort”连接会立即断开Server 侧会收到abort指令并停止后续处理。注意这个例子中http://localhost:8081/mcp/rag_search是一个特殊的 endpoint。Spring AI 2 的FileSystemMcpServer会根据 URL 路径自动映射到capabilities.json中定义的rag_search能力。你不需要为每个能力写一个 Controller。4.4 用 Playwright 进行自动化“真调”模拟真实用户场景playwright mcp是一个热门搜索词因为它代表了将 MCP 集成到自动化测试和 UI 测试中的趋势。Playwright 不仅可以驱动浏览器还可以启动和管理子进程这使得它成为测试 stdio 模式的绝佳工具。下面是一个 Playwright 测试脚本它启动你的 MCP Server然后用child_process模块向其 stdio 发送请求const { test, expect } require(playwright/test); const { spawn } require(child_process); test(MCP Server stdio mode works, async ({ page }) { // 1. 启动 MCP Server 子进程 const serverProcess spawn(java, [ -jar, your-app.jar, --mcp.server.stdio.enabledtrue, --mcp.server.filesystem.root-dir/path/to/your/mcp-capabilities ]); // 2. 监听子进程的 stdout等待启动完成 let serverReady false; serverProcess.stdout.on(data, (data) { const output data.toString(); if (output.includes(MCP Server started successfully)) { serverReady true; console.log(MCP Server is ready!); } }); // 3. 等待 Server 启动 await new Promise(resolve { const interval setInterval(() { if (serverReady) { clearInterval(interval); resolve(); } }, 1000); }); // 4. 向 Server 的 stdin 发送一个 JSON-RPC 请求 const request { jsonrpc: 2.0, method: rag_search, params: { query: How to use pgvector? }, id: 1 }; serverProcess.stdin.write(JSON.stringify(request) \n); // 5. 监听 stdout获取响应 let response ; serverProcess.stdout.once(data, (data) { response data.toString().trim(); }); // 6. 等待响应 await new Promise(resolve { const interval setInterval(() { if (response) { clearInterval(interval); resolve(); } }, 1000); }); // 7. 验证响应 const parsedResponse JSON.parse(response); expect(parsedResponse.result).toBeDefined(); expect(parsedResponse.result.length).toBeGreaterThan(0); // 8. 清理关闭子进程 serverProcess.kill(); });这个脚本的价值在于它完全模拟了一个真实的 CLI 工具如figma-ai-cli的行为。它启动 Server发送请求接收响应然后退出。这是保证你的 MCP 能力在生产环境中能被各种工具可靠调用的终极验证。5. 常见问题与排查技巧实录那些让你熬夜到凌晨三点的坑5.1 “stream disconnected before completion: idle timeout waiting for sse” —— 最经典的超时陷阱这个错误信息非常具有迷惑性。它听起来像是网络问题但根源几乎总是在 Server 端的配置上。idle timeout指的是 Spring WebFlux 的ReactiveWebServerFactory的空闲超时设置而不是 MCP 协议本身的超时。排查步骤确认日志级别在logback-spring.xml中将org.springframework.web.reactive.function.client和org.springframework.web.reactive的日志级别设为DEBUG。你会看到类似Expiring idle connection after 30000ms的日志。检查配置确保你的application.yml中有spring: webflux: server: reactive: max-idle-time: 300000 # 5分钟单位是毫秒注意max-idle-time是 Spring Boot 3.x 的配置项。如果你用的是 Spring Boot 2.7.x对应的配置是server.reactive.max-idle-time。验证生效启动后查看日志中是否有ReactiveWebServerFactory的初始化日志确认maxIdleTime的值是你设置的值。终极验证用curl发送一个长时间阻塞的请求例如用sleep 60模拟一个慢能力看是否还会报错。实操心得我曾经在一个项目中因为max-idle-time设置成了3000030秒而我们的 RAG 检索平均耗时 45 秒导致所有前端请求都失败。后来我把这个值设为60000010分钟问题立刻消失。记住这个值应该大于你所有能力的 P95 响应时间。5.2 “No such file or directory: capabilities.json” —— filesystem 的路径陷阱这个错误看似简单但背后有多个隐藏的坑。排查清单绝对路径 vs 相对路径mcp.server.filesystem.root-dir配置的路径是相对于 JVM 启动时的user.dir即System.getProperty(user.dir)。如果你用java -jar app.jar启动user.dir就是当前 shell 的工作目录。如果你用 systemd 或 Docker 启动user.dir可能是/或/app。永远使用绝对路径。文件权限确保 JVM 进程对root-dir目录有r-x权限读和执行对log-dir有rwx权限读、写、执行。chmod 755 /path/to/mcp-capabilities和chmod 777 /path/to/mcp-logs是安全的起点。文件编码capabilities.json必须是 UTF-8 编码。Windows 记事本默认保存为 ANSI会导致JsonParseException。用 VS Code 或 Notepad 保存时务必选择 UTF-8。提示在 Server 启动日志中搜索Root directory它会打印出它实际解析出的绝对路径。把这个