企业官网建设流程全解析

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 或 WebSocket？

2.1 MCP 协议的本质：不是通信协议，而是能力注册与发现协议

很多人一看到 “MCP” 就本能地联想到 HTTP 或 gRPC，这是个根本性误解。MCP（Model Capability Protocol）的核心目标，从来不是“高效传输数据”，而是解决AI 能力的“即插即用”问题。想象一下：Figma 插件想调用你的向量检索服务，Blender 插件想触发你的 3D 模型生成 Agent，VS Code 扩展想接入你的代码补全模型。如果每个工具都自己实现一套鉴权、重试、超时、错误分类、能力元数据查询的逻辑，那维护成本会指数级爆炸。MCP 的设计非常朴素：它规定了一套 JSON-RPC 风格的请求/响应格式，但最关键的是定义了三个核心概念：

• Server Discovery：客户端如何找到可用的 MCP Server？filesystem 方案的答案是：扫描一个指定目录下的 JSON 文件。
• Capability Registration：Server 如何告诉世界“我能做什么”？不是靠文档，而是靠一个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并非一个“简陋的玩具实现”，而是一个经过深思熟虑的生产就绪方案。它的选型逻辑非常清晰：

1. 零依赖部署：不需要额外启动 Redis、PostgreSQL 或 ZooKeeper。一个 JAR 包 + 一个配置好的目录，服务就起来了。这对于 CI/CD 流水线中快速验证 AI 能力、或者在客户现场做 PoC 演示，是决定性的优势。你不需要说服运维同事为你开一个新端口或配一个数据库账号。

2. 天然的版本控制与审计：capabilities.json和每个能力的实现脚本（如 Python 的.py文件或 Shell 的.sh文件）本身就是文本文件。它们可以被 Git 管理，每一次能力的增删改查，都有完整的 commit history。当你发现某个 Figma 插件突然调用失败，你可以git blame capabilities.json，立刻定位到是谁、什么时候、为什么修改了nl2sql能力的 input schema。

3. 极致的调试友好性：这是 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 对这个“假请求”的响应，完全绕过网络栈。

4. 与 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” 绝非随意堆砌，而是代表了两种完全不同的集成路径，它们服务于不同的终端用户和技术栈：

• SSE（Server-Sent Events）：这是为浏览器环境量身定制的。它是一个单向、长连接的 HTTP 协议，非常适合将大模型的流式输出（token-by-token）实时渲染到网页上。Figma、Blender 的 Web 版插件、或是你自己的管理后台，都可以用原生的EventSourceAPI 轻松接入。它的优势在于简单、标准、无需额外库。但它的致命弱点是：无法在 Node.js 的 CLI 工具或 Python 的自动化脚本中直接使用，因为这些环境没有EventSource对象。

• stdio（Standard 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> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> </dependency> <!-- Spring AI Core --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-core</artifactId> <version>2.0.0</version> </dependency> <!-- Spring AI MCP 抽象 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-mcp</artifactId> <version>2.0.0</version> </dependency> <!-- 关键！这是你自己编译的 filesystem server --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-mcp-servers</artifactId> <version>2.0.0</version> <scope>system</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": f"Parse 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 响应 # 注意：对于 streaming=true 的能力，这里应该是一个初始响应，然后后续用 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}", file=sys.stderr)，并将stderr重定向到一个单独的日志文件。因为stdout是留给 JSON-RPC 响应的，不能混用。file=sys.stderr确保了调试信息不会污染正常的响应流。

4. 实操过程与核心环节实现：从启动 Server 到用三种工具真实调用

4.1 启动 Server：配置、日志与健康检查的完整流程

假设你已经完成了spring-ai-mcp-servers模块的编译，并将其 JAR 包放入了lib/目录。现在，让我们启动 Server。

首先，创建一个配置文件application.yml：

spring: 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.location=classpath:/application.yml,file:/path/to/your/application.yml \ --logging.config=file:/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.enabled=true --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> <title>MCP SSE Test</title> </head> <body> <h1>MCP SSE Test Page</h1> <button id="startBtn">Start RAG Search</button> <div id="output"></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 style="color:red;">Error: ${data.error.message}</p>`; } }); // 4. 监听 error 事件，处理连接错误 eventSource.addEventListener('error', function(event) { console.error('SSE connection error', event); document.getElementById('output').innerHTML += '<p style="color:red;">[Connection Error]</p>'; if (eventSource) { eventSource.close(); } }); }); // 5. 提供一个 abort 按钮 document.body.innerHTML += '<button id="abortBtn">Abort</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.enabled=true', '--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 协议本身的超时。

排查步骤：

1. 确认日志级别：在logback-spring.xml中，将org.springframework.web.reactive.function.client和org.springframework.web.reactive的日志级别设为DEBUG。你会看到类似Expiring idle connection after 30000ms的日志。
2. 检查配置：确保你的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。
3. 验证生效：启动后，查看日志中是否有ReactiveWebServerFactory的初始化日志，确认maxIdleTime的值是你设置的值。
4. 终极验证：用curl发送一个长时间阻塞的请求（例如，用sleep 60模拟一个慢能力），看是否还会报错。

实操心得：我曾经在一个项目中，因为max-idle-time设置成了30000（30秒），而我们的 RAG 检索平均耗时 45 秒，导致所有前端请求都失败。后来我把这个值设为600000（10分钟），问题立刻消失。记住，这个值应该大于你所有能力的 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，它会打印出它实际解析出的绝对路径。把这个