debug-mcp-stdio

用途

本技能用于在 VS Code 中对以 stdio 方式运行的 Node.js MCP Server 进行断点调试。典型场景是 MCP Server 通过 npx @modelcontextprotocol/inspector 启动，并以 stdio 与客户端通信，用户希望在 VS Code 中命中断点、单步执行、查看变量和调用栈。

主要能力

技能围绕三个关键环节展开：

Node 调试口：使用 node --inspect 或 --inspect-brk 在本地开放调试端口（默认 9229），供 VS Code 连接。
MCP Inspector：作为临时 MCP 客户端与 UI，负责启动 server 并通过 stdio 与其对话。
sourcemap：把构建后的 JS 映射回 TypeScript 源码，使 TS 断点能够准确命中。

技能还提供了排障路径，覆盖端口占用、断点灰色、server 一闪即退、入口路径拼写错误等常见问题。

使用方式

资料给出的总体流程如下：

确认入口与输出目录，例如 build/ 或 dist/ 内的 index.js；常见入口有 build/internal/index.js、build/index.js、dist/index.js。
确认已生成 sourcemap，可通过查找 *.map 文件自检。
在项目根目录的 .vscode/launch.json 中追加 attach 配置，对齐 port 和 outFiles。
在 VS Code 中先启动 Attach，处于等待连接状态。
运行 Inspector 命令启动 server，建议首次使用 --inspect-brk。

VS Code attach 配置示例（来自资料）：

{ "version": "0.2.0", "configurations": [ { "name": "Attach: MCP stdio (Node Inspector)", "type": "node", "request": "attach", "port": 9229, "protocol": "inspector", "restart": true, "timeout": 30000, "sourceMaps": true, "smartStep": true, "skipFiles": ["<node_internals>/", "/node_modules/"], "cwd": "${workspaceFolder}", "outFiles": [ "${workspaceFolder}/build//.js", "${workspaceFolder}/dist/**/.js" ] } ] }

启动命令示例（来自资料）：

默认版：

npx -y @modelcontextprotocol/inspector node --inspect=9229 build/internal/index.js

稳定版（首行暂停）：

npx -y @modelcontextprotocol/inspector node --inspect-brk=9229 build/internal/index.js

换端口版：

npx -y @modelcontextprotocol/inspector node --inspect-brk=9230 build/internal/index.js

使用 pnpm / yarn：

pnpm dlx @modelcontextprotocol/inspector node --inspect=9229 build/internal/index.js

yarn dlx @modelcontextprotocol/inspector node --inspect=9229 build/internal/index.js

启用 sourcemap 的 TypeScript 配置示例：

{ "compilerOptions": { "sourceMap": true, "inlineSources": true } }

打包器方面，tsup 配置 sourcemap: true；esbuild 加 sourcemap: true 或 --sourcemap；rollup 设置 output.sourcemap: true；webpack 设置合适的 devtool，例如 source-map。

排查 sourcemap 是否存在：

find build dist -maxdepth 4 -name "*.map" -print 2>/dev/null | head

检查端口占用（macOS / Linux）：

lsof -nP -iTCP:9229 -sTCP:LISTEN

确认入口文件是否存在：

node -p "require('fs').existsSync('build/internal/index.js')"

兜底方式（不走 inspector，直接跑源码，例如使用 tsx）：

npx -y tsx --inspect-brk=9229 src/index.ts

适用场景

需要调试以 stdio 方式运行的 MCP Server。
已经在 VS Code 中连接 Node Inspector，但断点不命中或变灰。
遇到 9229 端口占用、sourcemap 缺失、入口路径写错等调试链路问题。
需要在调试构建产物和直接调试源码之间做取舍。

限制与约束

端口必须一致：launch.json 的 port 要等于 --inspect=PORT 中的 PORT。
建议先启动 Attach，再启动进程；首次调试推荐使用 --inspect-brk，避免启动过快错过断点。
调试构建产物必须有 sourcemap，否则只能在编译后的 JS 中调试，TS 断点大概率不准。
兜底方式使用 tsx 直接跑源码时不走 inspector，前提是项目允许以这种方式启动。
收费、价格、平台支持范围等资料未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与约束