MCP Walkthrough

An MCP server for interactive code walkthroughs with voice narration. Opens files, highlights code, shows inline explanations with a teleprompter-style bubble, and reads each step aloud using neural text-to-speech.

Works with any MCP client: Claude Code, Cursor, VS Code Copilot, Gemini CLI, Codex CLI, Windsurf.

Install

All clients at once

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

Auto-detects which AI coding tools you have and configures all of them.

Manual (any client)

Add to your MCP config (mcpServers key):

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

Skill (Claude Code)

npx skills add stefan-nitu/mcp-walkthrough

Installs the walkthrough skill so Claude auto-loads the tools when you ask it to explain code.

Note: Requires VS Code, VS Code Insiders, or Cursor. A companion VS Code extension is automatically installed on npm install.

What It Does

Text in a terminal isn't enough when an AI explains a solution. MCP Walkthrough opens files in VS Code, highlights specific lines, shows rich markdown explanations, and narrates each step with a natural-sounding voice.

Teleprompter pattern: The explanation bubble builds up as the agent narrates — each highlight's text appends in bold, then unbolds when done. Selection moves through the code in sync with the voice.

Tools

walkthrough

The single entry point for code presentation — dispatches by arguments.

Multi-step narrated tour (N steps):

{
  "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." }
      ]
    }
  ]
}

With highlights (teleprompter):

• Bubble shows explanation — TTS narrates it
• Each highlight appends narration in bold — selection moves to the highlight's lines
• After the last highlight, all text unbolds and navigation controls appear

Without highlights: Simple bubble + full narration of the explanation.

Single-step explain (1 step with explanation): same shape, one entry in steps. Renders one bubble, no tour state.

Highlight only (1 step without explanation): { "steps": [{ "file": "…", "line": 10, "endLine": 15 }] }. Equivalent to show_code.

Navigation: { "action": "next" | "prev" | "goto" | "stop" | "pause" | "resume" }. For goto, pass step (0-based index).

Clear bubbles: { "action": "clear" }.

Status: call with no arguments — returns { active, currentStep, totalSteps, … }.

show_code

Ergonomic single-shot highlight — same as a walkthrough with one step that has no explanation.

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

settings

View or update global config. Changes persist across sessions.

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

• voice — Toggle voice narration on/off
• showBubbles — Toggle explanation bubbles on/off
• autoplay — Auto-advance to next step after narration finishes
• autoplayDelay — Extra delay in ms after narration (additive)

Keyboard Shortcuts

Shown in the explanation bubble after the last highlight:

How It Works

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

1. Agent calls walkthrough tools via MCP
2. MCP server sends steps to VS Code extension via workspace-specific Unix socket
3. Extension shows bubbles, moves selection, narrates with TTS (Edge TTS + native fallback)
4. Each VS Code window gets its own socket — multiple windows work independently
5. Focus stays in your terminal — code appears in the editor beside it

TTS runs in the VS Code extension, not the MCP server. Keyboard shortcuts trigger the same narration path as MCP tool calls.

Development

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

Local Testing

MCP server (npm global):

npm run build && npm install -g .

VS Code extension:

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

Then restart VS Code (not just reload — extension code is cached).

License

MIT

Related Projects

• Model Context Protocol — MCP specification
• MCP TypeScript SDK — SDK used by this server
• add-mcp — Install MCP servers across all clients