MCP 模式 stdio 挂起（可选依赖缺失）

你会遇到什么

你用 MCP server 模式（skillspector mcp）时进程挂起无输出，像死机一样，没有报错、没有日志。你以为是工具坏了，其实是 MCP 模式依赖的可选组件没装全（Issue #199 场景）。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

MCP 模式依赖可选组件，默认 pip install skillspector 安装不完整；缺组件时 stdio 会话协议初始化卡住，挂起时无任何报错。而主扫描路径 skillspector scan 不需要 MCP 也能完成扫描。

MCP 的 stdio 模式本质是“子进程 + 标准输入输出”的 JSON-RPC 会话：MCP client 把 skillspector mcp 启动为子进程，双方通过 stdin/stdout 逐行交换 JSON 消息，协议第一步是初始化握手（initialize 请求 → 响应）。

可选依赖缺失时，子进程在 import 阶段就失败了，而失败发生在“协议还没开始”的位置——没有请求存在，自然没有任何报错可输出，client 只能一直等，表现就是挂起无输出。

所以“无报错”恰恰是关键线索：挂起 + 完全无输出 = 大概率是进程根本没起来（依赖缺失 / import 失败），而不是逻辑死循环。排查顺序因此固定：先 --help 验证 CLI 层能正常加载（能输出说明包本体没坏）→ 再判断问题在协议侧 → 补可选依赖；排查期间用 scan 主路径绕开 MCP 继续干活。

一步步来

1. Ctrl+C 退出挂起进程 — 必做

挂起无输出时先退出，别干等。

2. 确认 CLI 层正常 — 必做

skillspector mcp --help

能正常输出 = CLI 层正常，问题在 MCP 会话协议侧（可选依赖缺失）。

3. 安装 MCP 相关可选依赖 — 进阶

按项目文档安装后重启 MCP 模式（包名以文档为准，示例 skillspector[mcp]）。

4. 排查期间用主路径 — 排查

skillspector scan <目标目录>

不需要 MCP 也能完成扫描（本市场实测构造样本检出）。

怎么确认修好了

MCP 模式不再挂起（预期形态）：

skillspector mcp
→ 正常启动，stdout 出现 MCP 协议握手/就绪输出

或确认主路径可用：skillspector scan 正常输出扫描结果。

其它环境的表现

症状

用 MCP server 模式（skillspector mcp）时进程挂起无输出。

原因

MCP 模式依赖可选组件，默认 pip 安装不完整（Issue #199 场景）；stdio 挂起时无报错，像死机。

解法

1. 先 Ctrl+C 退出，确认依赖：按项目文档安装 MCP 相关可选依赖后重启。
2. 排查期间用 skillspector scan 主路径（不需要 MCP 也能完成扫描）。
3. 挂起时检查：skillspector mcp --help 是否正常输出（能输出说明 CLI 层正常，问题在会话协议侧）。