MCP踩坑实录

MCP踩坑记录

1 背景

基于 MCP 标准协议实现了知识检索 Server，解决了 stdio 传输下的 GIL 死锁、日志污染协议流、同步阻塞操作三个生产级问题，支持 GitHub Copilot / Claude Desktop 即插即用调用私有文档库。

2 stdio 传输的 GIL 死锁问题

这是 MCP Server 中最容易被忽视的生产问题：

# server.py — _preload_heavy_imports()def _preload_heavy_imports():"""在 anyio 启动前预加载重型模块，避免 stdio 读取线程和 import 锁竞争死锁。原理：MCP SDK 用 anyio 的 stdio 传输，内部有一个后台线程在读 stdin。如果某个工具被执行时才 import chromadb（它又 import onnxruntime），这个 import 可能卡住 2-5 秒。与此同时 stdin-reader 线程也在等——两个线程都在等对方释放 GIL，就死锁了。解决：在主线程、任何 async 线程启动前，先把所有重型模块 import 完。"""import chromadb # 启动慢，但 import 一次就够了import src.libs.splitter# 触发 langchain 导入import src.core.query_engine# 触发所有检索器导入

为什么其他模块没有这个问题？ ——普通 HTTP Server 每个请求是一个新线程/进程，import 阻塞只影响那个请求。但 MCP 的 stdio 传输是单进程 + 后台 reader 线程 + JSON-RPC over stdin/stdout，reader 线程一直在等输入，worker 线程一直在等 import 锁，形成死锁。

3 日志污染协议流

# server.py — _redirect_all_loggers_to_stderr()def _redirect_all_loggers_to_stderr():"""MCP 协议规定 stdout 只能发送 JSON-RPC 消息。如果任何 logger 往 stdout 写日志，会把日志混进 JSON 流里，客户端解析 JSON 失败就会断开连接。解决：把所有 logger 的 StreamHandler 重定向到 stderr。"""root = logging.getLogger()stderr_handler = logging.StreamHandler(sys.stderr)# 移除所有 stdout handlerfor handler in root.handlers[:]:if isinstance(handler, logging.StreamHandler) and not isinstance(handler, logging.FileHandler):root.removeHandler(handler)root.addHandler(stderr_handler)

踩坑经历：我第一次跑 MCP Server 时就遇到了Invalid JSON错误，排查了 2 小时才发现是httpx库的 logger 往 stdout 打了请求日志。

4 异步桥接模式

# query_knowledge_hub.py — execute()async def execute(self, query, top_k=5, collection=None):# 所有阻塞操作都桥接到线程池，不阻塞事件循环await asyncio.to_thread(self._ensure_initialized, collection)results = await asyncio.to_thread(self._perform_search, query, top_k, trace)if self.config.enable_rerank and results:results = await asyncio.to_thread(self._apply_rerank, query, results, top_k, trace)response = self._response_builder.build(results, query, collection)return response

为什么用asyncio.to_thread而不是async def？ ——因为hybrid_search.search()内部调用了 ChromaDB 的同步 API 和httpx的同步请求，这些库没有 async 版本。asyncio.to_thread把它们放到线程池中执行，不阻塞 MCP 的事件循环。

5 即插即用的过程

// Claude Desktop 配置 (claude_desktop_config.json){"mcpServers": {"knowledge-base": {"command": "python","args": ["-m", "src.mcp_server"],"env": {"SETTINGS_PATH": "/path/to/settings.yaml"}}}}

用户在 Claude Desktop 里加这个配置后，Claude 就能直接调用query_knowledge_hub工具搜索私有文档库。工具的描述（TOOL_DESCRIPTION）会自动展示给 Claude 的 system prompt，Claude 就知道什么时候该调用这个工具。