Interview Bank

MCP in 7 Days: Wire Tools Into Any Agent

D2 Writing Your First MCP Server: stdio Transport, the Official SDK, Parameter Schemas, Tool Annotations, and Debugging With Inspector

• What is the most common way a stdio MCP server breaks, and how do you prevent it in code and in process?一个 stdio 的 MCP 服务端最常见的翻车原因是什么？你会在代码和流程上分别怎么堵住它？

  Common in ChinaCommon overseasDeep dive#stdio-transport#debugging

  How to reason about it · think before answering

  1. This checks whether you have actually run one. People who have not will say 'the process did not start' or 'wrong path'; anyone who has been bitten leads with stdout contamination.
  2. Restate the hard rules first: messages are newline-delimited JSON, one per line, with no embedded newlines, and the server must not write anything to stdout that is not an MCP message. Logging goes to stderr. Once the rules are stated the failure mode is obvious.
  3. Call out the symptom, because that is the discriminator: the client only reports a JSON parse failure and cannot point at your console.log, and the polluter is often a third-party library printing a banner or deprecation warning at import time rather than your own code.
  4. Conclusion in two layers. In code: wrap a stderr-only logger, ban direct printing, vet third-party libraries for stdout writes, and ensure serialized JSON carries no raw newlines. In process: add a self-test entry point that links a client and server over an in-memory transport in one process, asserts, and exits with a real status code, then run it in CI so contamination is caught before merge.
  5. Add the adjacent one: graceful shutdown. The spec makes closing stdin and exiting on EOF the primary and only portable shutdown signal; ignoring it leaves orphan processes that show up locally as mysteriously held ports and file locks.
  6. Likely follow-up: if it is this fragile, why use stdio? Zero configuration, zero network attack surface, and process isolation for free — the tradeoff is clearly worth it locally. You switch transports when you need team sharing or multiple replicas.

  分析过程 · 先想清楚再作答

  1. 这题在验有没有真跑过。没实际接过的人会答「进程没起来」「路径不对」这类泛泛的，真踩过的人第一句就会说标准输出被污染。
  2. 拆法：先复述 stdio 的硬规矩——消息是一行一条换行分隔的 JSON、内部不许有裸换行，服务端不得往标准输出写任何不是 MCP 消息的东西，日志一律走标准错误。规矩一说完，翻车原因就自明了。
  3. 现场特征值得单独说，因为它是这题的区分点：客户端只会报一句 JSON 解析失败，指不到你哪一行 console.log；而且污染源常常不是你自己的代码，而是某个第三方库在启动时打的横幅或弃用警告。
  4. 结论分两层。代码上：封一个只写标准错误的日志函数并全局禁用直接打印，接第三方库之前先确认它不往标准输出写东西，把 JSON 序列化后确保不含裸换行。流程上：加一个自测入口，用内存传输在同一个进程里把客户端和服务端接起来跑断言，有明确退出码，进持续集成——这样污染一出现就会在合并前被拦下。
  5. 再补一条相关的：优雅停机。规范说客户端关掉输入流、服务端读到文件结束就应尽快退出，这是主要且唯一可移植的停机信号；不处理它就会留下孤儿进程，本机开发时表现为端口和文件锁莫名被占。
  6. 可预期的追问：既然这么脆，为什么还用 stdio？因为它零配置、零网络攻击面、进程隔离天生就有，本机场景收益远大于代价；要给团队共享或多副本才需要换成远程传输。

  Key points

  • Stdout contamination: stdio reserves stdout for MCP messages, so a single console.log breaks the client's parser
  • The symptom is only a JSON parse failure with no line number, and the culprit is often a third-party library's startup banner
  • In code, use a stderr-only logger, ban direct printing, and vet dependencies for stdout writes
  • In process, add an in-memory-transport self-test with a real exit code in CI, and exit promptly on stdin EOF to avoid orphan processes

  答题要点

  • 最常见的是标准输出被污染：stdio 规定 stdout 只能有 MCP 消息，一行 console.log 就让客户端解析失败
  • 现场只报 JSON 解析失败，指不到具体行，污染源常常是第三方库启动时打的横幅或警告
  • 代码上封一个只写标准错误的日志函数并禁用直接打印，接库之前先验它不写 stdout
  • 流程上加一个用内存传输的自测入口，有明确退出码并进持续集成；同时处理 stdin 关闭时的优雅退出