IDE 与编辑器集成：stdio 生命周期、工作区上下文与诊断回写

MCP 的绝大多数使用场景发生在编辑器里：你正在改代码，AI 需要读当前文件、看编译错误、查 Git 历史、跑测试。这些能力天然属于「编辑器知道而模型不知道」的信息——打开的是哪个文件、光标选了什么、Problems 面板里有哪些报错、当前工作区根在哪。

把 MCP 服务器接进编辑器看起来只是往配置文件里加几行 JSON，实际却要处理一堆进程级问题：谁来启动进程、什么时候杀掉、崩溃了怎么办、stdout 被日志污染了怎么办、工具太多把模型选崩了怎么办。本文要回答的就是这些「接进去之后才会遇到」的工程问题。

1. 编辑器为什么是最重要的宿主

1.1 编辑器独有的上下文

模型无法自己获得这些信息，而它们恰恰是「让 AI 干得对」的关键输入。一个不知道用户选中了哪段代码的助手，只能反问或者猜。

1.2 两种集成方向

方向一：编辑器作为宿主（Host）
  编辑器启动 MCP 服务器进程，服务器提供工具给模型用

方向二：编辑器作为能力提供方（Provider）
  编辑器自己跑一个 MCP 服务器，把 IDE 能力暴露给外部 Agent
  例：editor-context 服务器提供 getDiagnostics / getSelection / applyEdit

成熟方案通常两者都有：本地工具服务器（文件、Git、数据库）+ 一个编辑器上下文服务器。

2. 接入形态与配置

2.1 stdio 启动配置

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@acme/docs-mcp@2.4.0"],
      "env": { "DOCS_ROOT": "${workspaceFolder}/docs" },
      "cwd": "${workspaceFolder}"
    },
    "local-tools": {
      "command": "uvx",
      "args": ["acme-tools==1.8.2"],
      "env": { "ACME_TOKEN": "${env:ACME_TOKEN}" }
    }
  }
}

配置里的四个要点：

2.2 变量替换

主流编辑器支持一批内置变量，用于把工作区信息传给服务器：

${workspaceFolder}      当前工作区根（多根时取第一个）
${workspaceFolderBasename}
${env:NAME}             引用环境变量
${userHome}             用户主目录

${workspaceFolder} 在多根工作区下语义模糊。可靠做法是把根通过 MCP 的 Roots 机制动态传递（服务器主动 roots/list），配置里的 cwd 只作为兜底。

2.3 分发方式的取舍

「首次慢」是个体验陷阱：npx -y 首次启动要下载整个依赖树，可能耗时数十秒，而编辑器通常有启动超时（常见 10~30 秒），结果是「服务器启动失败」但日志里看不出原因。生产建议是预安装 + 固定路径。

3. 进程生命周期

3.1 谁启动、何时退出

典型生命周期：
  编辑器启动 / 打开工作区
    → 按配置 spawn 服务器进程（stdio）
    → initialize 握手（能力协商）
    → 会话期内持续服务
  编辑器关闭 / 工作区切换
    → 发送关闭信号，等待进程退出
    → 超时未退则强制 kill

常见错误：编辑器关闭时只杀父进程。如果服务器又 spawn 了子进程（如 npx → node），子进程会变成孤儿继续占用端口与文件句柄。正确做法是把服务器放进进程组并整组终止，或在容器里跑（容器停止即全灭）。

3.2 崩溃与重启

// 服务器侧：崩溃前尽量留下可诊断信息
process.on("uncaughtException", (err) => {
  // 注意：不能写 stdout（那是协议通道），只能写 stderr 或文件
  console.error(JSON.stringify({ level: "fatal", err: String(err), stack: err.stack }));
  process.exit(1);
});

宿主侧的重启策略：
  首次崩溃     → 立即重启
  连续崩溃     → 指数退避（1s, 2s, 4s, 8s，上限 30s）
  N 次内仍失败 → 标记为"不可用"，在 UI 中提示用户查看日志
  重启后       → 重新 initialize、重新拉取 roots 与 tools

要点：重启后必须重新握手，不能复用旧会话的工具列表。旧列表里的工具在新进程里可能已经不存在（版本更新）或语义已变。

3.3 stdout 纪律

这是 stdio 传输最硬的一条约束：stdout 只能承载 JSON-RPC 消息。

// 错误：直接 console.log 会污染协议流
console.log("server started");

// 正确：日志走 stderr
console.error("[docs] server started");

// 或者把 console.log 重定向到 stderr
console.log = (...args: unknown[]) => console.error(...args);

典型故障现象：模型偶尔收到「无法解析的响应」，重启后又好了——多半是某条业务日志走了 stdout，恰好插在两条 JSON-RPC 消息之间，破坏了行分隔解析。防御手段是在服务器入口处主动劫持 console.log，而不是靠开发者自觉。

3.4 日志去哪了

排查集成问题时，第一步永远是打开编辑器的 MCP 输出面板看 stderr。多数「工具不出现」的问题都能在这里找到答案（进程没起来、握手失败、初始化抛异常）。可观测性的完整方法见 https://plumephp.com/mcp-observability-debugging/。

4. 编辑器作为能力提供方

4.1 与 LSP 的分工

编辑器内部已有语言服务器协议（LSP）提供的诊断、补全、跳转能力。MCP 与 LSP 的关系是互补而非替代：

一个常见的错误设计是把 LSP 的原始输出直接塞进 MCP 工具返回值：getDiagnostics 返回 300 条诊断的完整 JSON，模型看完仍然不知道从哪下手。正确做法是做摘要与排序（按严重级别、按文件、按是否与当前改动相关）。LSP 侧的工程细节可参考 语言服务器与工具链 。

4.2 编辑器上下文工具的设计

{
  "name": "get_editor_context",
  "description": "获取编辑器当前状态：打开的文件、活动文件、选中内容、光标位置。用于在用户说「这段代码」时确定指代对象。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "include": {
        "type": "array",
        "items": { "type": "string", "enum": ["activeFile", "selection", "openFiles", "diagnostics"] },
        "default": ["activeFile", "selection"]
      },
      "maxChars": { "type": "integer", "default": 4000 }
    }
  }
}

设计要点：

1. include 让调用方按需取，避免每次返回全部上下文
2. maxChars 限制选区内容长度（用户可能选中一整个文件）
3. description 明确"用于消解指代"，这是模型最容易用错的场景
4. 返回里区分"用户显式选中"与"活动文件"，模型的处理策略不同

4.3 编辑回写：applyEdit

让模型改代码，必须走编辑提案而非直接落盘：

错误：write_file 直接覆盖 src/app.ts
正确：applyEdit 提交一个 diff → 编辑器渲染为可审阅的变更 → 用户接受/拒绝

applyEdit 的输入建议：
  filePath      目标文件
  expectedHash  读取时的内容哈希（防并发修改）
  edits[]       每个 edit 是 {range, newText}
输出：
  applied / rejected / conflict（文件已被用户改动）

expectedHash 是防冲突的关键：如果用户在模型思考期间手改了同一文件，编辑必须失败而不是覆盖。这一模式与文件系统工具的写入语义一致，可参考 https://plumephp.com/mcp-file-system-tools/ 中的并发与幂等章节。

5. 上下文与性能

5.1 工具数量膨胀

工具定义会整体注入模型上下文，且通常位于请求前部（system 区）。因此工具数量直接影响两件事：

1. 固定 token 开销：每个工具约 50~200 token（含 schema 与描述）
2. 选择准确率：候选工具超过约 30 个后，选择错误率明显上升

经验阈值：

5.2 按工作区启停

最有效的降噪手段是按项目类型只启停相关服务器：

{
  "mcpServers": {
    "docs": { "command": "npx", "args": ["-y", "@acme/docs-mcp"] }
  },
  "profiles": {
    "backend": ["docs", "postgres", "git"],
    "frontend": ["docs", "playwright", "git"],
    "ops": ["k8s", "terraform", "git"]
  }
}

多数编辑器已支持按工作区或按 profile 启用不同服务器集合。这比在提示词里叮嘱模型「不要用某个工具」有效得多。

5.3 缓存与刷新

工具列表缓存失效时机：
  会话开始          → 拉取一次
  收到 list_changed → 重新拉取
  配置变更/重启     → 重新拉取
不应缓存过久的理由：
  服务器升级后契约可能变化，旧定义会让模型按旧参数调用

6. 安全与体验

6.1 工作区信任

打开一个陌生仓库就自动启动该仓库 .mcp.json 里定义的服务器，等于让仓库作者在你的机器上执行任意命令。因此编辑器必须实现工作区信任（Workspace Trust）：

未信任工作区 → 不自动启动仓库内定义的服务器
信任后       → 首次启动仍需逐条确认 command 与 args
远程/下载仓库 → 默认不信任

6.2 密钥管理

禁止：把 token 明文写进 .mcp.json（会被提交到仓库）
推荐：.mcp.json 只写 ${env:ACME_TOKEN}，真实值放系统钥匙串或 shell profile
团队共享：提交 .mcp.json.example，真实配置加入 .gitignore

6.3 审批体验

编辑器是唯一能提供高质量审批 UI 的地方：能看到 diff、能看到目标路径、能一键拒绝。因此对写操作、命令执行、网络请求这类高危工具，应把审批点交给编辑器而不是服务器自己判断。审批与权限模型见 https://plumephp.com/mcp-client-integration/ 中的客户端职责部分。

6.4 首次接入的体验设计

服务器启动中  → 显示"正在启动 X 服务器"，而不是静默等待
启动失败      → 直接给出可操作提示："运行 npx -y @acme/docs-mcp 查看错误"
工具为空      → 区分"服务器没起来"与"服务器起来了但没有工具"
权限被拒      → 明确说明被拒的工具名与原因

7. 常见陷阱

8. 小结

把 MCP 接进编辑器，工程重点不在协议而在进程、通道、上下文三件事：

编辑器是 MCP 生态里「离用户最近」的一环。把它当普通客户端来集成，只解决了协议连通；把进程纪律、通道隔离、上下文克制这三件事一并做对，才算真正接入。需要更深入的自定义编辑器插件实现（Neovim、VS Code 扩展等）可参考 Neovim 插件工程 的宿主集成模式。