代码讲解服务器

MCP演练

一个用于交互式代码演练的MCP服务器，带有语音旁白。打开文件，突出显示代码，用提词器风格的气泡显示内联解释，并使用神经文本到语音大声朗读每一步。

适用于 任何MCP客户端：Claude Code、Cursor、VS Code Copilot、Gemini CLI、Codex CLI、Windsurf。

安装

所有客户同时

npx add-mcp walkthrough -- npx -y mcp-walkthrough

自动检测您拥有哪些AI编码工具，并配置所有这些工具。

手册（任何客户）

添加到MCP配置(mcpServers 按键）：

{
  "walkthrough": {
    "command": "npx",
    "args": ["-y", "mcp-walkthrough"]
  }
}

技能（克劳德代码）

npx skills add stefan-nitu/mcp-walkthrough

安装演练技能，以便当您要求Claude解释代码时，它会自动加载工具。

注： 需要VS代码、VS代码内部人员或游标。VS Code扩展会自动安装在 npm install.

它的作用

当人工智能解释解决方案时，终端中的文本是不够的。MCP演练在VS Code中打开文件，突出显示特定行，显示丰富的标记解释，并用自然的声音讲述每一步。

Teleprompter模式： 随着代理的叙述，解释气泡逐渐形成——每个突出显示的文本都以粗体附加，完成后松开。选择与语音同步地在代码中移动。

工具

攻略

代码表示的单一入口点——按参数分派。

多步解说之旅 （N步）：

{
  "steps": [
    {
      "file": "/absolute/path/to/file.ts",
      "line": 33,
      "endLine": 48,
      "title": "Text Preparation",
      "explanation": "Intro context — narrated first, shown in bubble.",
      "highlights": [
        { "line": 35, "endLine": 36, "narration": "First section explained." },
        { "line": 37, "endLine": 40, "narration": "Second section explained." }
      ]
    }
  ]
}

带亮点（提词器）：

• 泡泡秀 explanation --TTS对此进行了叙述
• 每个突出显示都会附加 narration 在 大胆 --选择移动到突出显示的线条
• 在最后一次高亮显示后，将显示所有未绑定的文本和导航控件

无亮点： 简单的泡泡+完整的解释叙述。

单步解释 （1步 explanation)：形状相同，一个条目 steps。渲染一个气泡，没有巡回状态。

仅突出显示 （1步无 explanation): { "steps": [{ "file": "…", "line": 10, "endLine": 15 }] }.相当于 show_code.

导航： { "action": "next" | "prev" | "goto" | "stop" | "pause" | "resume" }.为 goto，通过 step （基于0的指数）。

清除气泡： { "action": "clear" }.

状态： 无参数调用--返回 { active, currentStep, totalSteps, … }.

show_code

符合人体工程学的单镜头亮点——与 walkthrough 有一步没有 explanation.

{ "file": "/absolute/path/to/file.ts", "line": 10, "endLine": 15 }

设置

查看或更新全局配置。更改在会话之间持续存在。

{ "voice": true, "autoplay": false, "autoplayDelay": 2000 }

• 声音 --打开/关闭语音旁白
• showBubbles --打开/关闭解释气泡
• 自动播放 --旁白结束后自动前进到下一步
• 自动播放延迟 --叙述后的额外延迟（毫秒）（加法）

键盘快捷键

在最后一个高亮显示后的解释气泡中显示：

运作原理

AI Agent  →  MCP Server (stdio)  →  Unix socket  →  VS Code Extension  →  Editor API + TTS

1. 代理通过MCP调用演练工具
2. MCP服务器通过特定于工作区的Unix套接字向VS Code扩展发送步骤
3. 扩展显示气泡，移动选择，用TTS叙述（边缘TTS+本地回退）
4. 每个VS Code窗口都有自己的套接字——多个窗口独立工作
5. 焦点停留在终端上——代码出现在它旁边的编辑器中

TTS在VS Code扩展中运行，而不是在MCP服务器中运行。键盘快捷键触发与MCP工具调用相同的叙述路径。

发展

bun install
bun test              # 88 tests
bun run build         # Builds MCP server + VS Code extension
bun run typecheck     # Type checking
bun run lint          # Biome linting

本地测试

MCP服务器 （npm全局）：

npm run build && npm install -g .

VS代码扩展名：

cd vscode-extension && node esbuild.js
npx @vscode/vsce package --allow-missing-repository -o walkthrough-bridge.vsix
code --install-extension walkthrough-bridge.vsix --force

然后重新启动VS Code（不仅仅是重新加载——扩展代码被缓存）。

许可证

麻省理工学院

相关项目

• 模型上下文协议 --MCP规范
• MCP TypeScript SDK --此服务器使用的SDK
• 添加mcp --在所有客户端上安装MCP服务器