Skip to main content
Glama
MCP Walkthrough

MCP Walkthrough

by Stefan-Nitu

NPM Version NPM Downloads CI Status MIT Licensed

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

Client

Config file

Claude Code

.mcp.json (project) or ~/.claude.json (global)

Cursor

.cursor/mcp.json

VS Code Copilot

.vscode/mcp.json

Windsurf

~/.codeium/windsurf/mcp_config.json

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.

Related MCP server: CodeTour

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

Tool

Description

walkthrough

One tool for all code presentation — 1 step with explanation shows an inline bubble; 1 step without explanation highlights only; N steps start a narrated tour; action: "clear" clears bubbles; action in next/prev/goto/stop/pause/resume navigates; empty args returns status

show_code

Open a file and highlight specific lines — ergonomic shortcut for the no-commentary case

settings

Global config: voice, bubbles, autoplay, autoplayDelay

walkthrough_voice_selection

Change narrator voice, audition voices, list available

get_selection

Read the currently highlighted code in VS Code

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); it jumps to the start of that step. pause silences the tour where it is, and resume replays the current narration from its start. Next, previous and goto also resume a paused tour. Each returns the tour's status, or { ok: false, error } when no tour is running or the step is out of range.

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

Status: call with no arguments — returns { ok, active, paused, currentStep, totalSteps, highlight, title }. currentStep is 0-based and null when no tour is running; highlight is { index, total } (0-based) while a highlight is narrating, otherwise null; title is the step's title or null.

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 at the bottom of every tour bubble. They work only while a tour is running, so outside a tour Cmd+Shift+arrow keeps its usual text-selection behavior. Use Ctrl instead of Cmd on Windows and Linux.

Shortcut

Action

Cmd+Shift+→

Next step

Cmd+Shift+←

Previous step

Cmd+Shift+↑

Pause / resume

Cmd+Shift+↓

Stop walkthrough

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

Available Tools

5 tools
get_selectionA

Get the code the user has selected or highlighted in VS Code — returns file path, line range, and selected text. Use when the user refers to 'this code', 'what I've selected', 'the highlighted block', or before calling walkthrough/show_code when the user has already selected the code they want to discuss. Returns an empty selection object when nothing is highlighted.

Inputs: no named parameters.

settingsA

View or update global walkthrough settings — voice narration on/off, explanation bubbles on/off, autoplay on/off, and autoplay delay. Use when the user asks to enable, disable, or configure any of those, mute/unmute narration, toggle bubbles, or check current settings. Do NOT use to change the narration voice name — use walkthrough_voice_selection for that. Call with no arguments to read current settings. Changes persist across sessions.

Inputs: voice, autoplay, showBubbles, autoplayDelay.

show_codeA

Open a file in VS Code and highlight specific lines without any explanation bubble. Use when the user asks to show, open, jump to, or point at specific code with no commentary needed. Do NOT use when you need to explain what the code does — use the walkthrough tool with a step that includes an explanation. Do NOT use for multi-step tours — use walkthrough with multiple steps. Line numbers are 1-based; character offsets are 0-based.

Inputs: file (required), line (required), endChar, endLine, +1 more.

walkthroughA

Show, explain, and tour code in VS Code — the one tool for all code presentation with commentary, from single inline explanations to multi-step narrated tours. Use when the user asks to explain code, walk through code, tour a codebase, ask 'how does this work', navigate an active tour, clear bubbles, or check walkthrough state. Do NOT use for jumping to code without commentary — use show_code instead. Dispatches by arguments: one step with explanation shows an inline markdown bubble (single-step explain); one step WITHOUT explanation highlights only (same as show_code); multiple steps start a narrated tour; action: 'clear' removes all bubbles; action in {'next','prev','goto','stop','pause','resume'} navigates an active tour (pass step index for goto); no arguments returns current status. Proper usage for multi-point steps: keep explanation to 1–2 intro sentences and put each point in its own highlights[] entry with its own line range and narration — the teleprompter UX (selection moving with the voice, bubble text building up) depends on this pattern. Cramming multiple points into one long explanation breaks both the audio flow and the visual sync. Never use numbered lists (1. 2.) in explanations or narrations — TTS reads them as 'one dot… two dot' and it's painful. Markdown: real newlines for paragraphs, NOT literal backslash-n; avoid ## headers — use bold instead. Uses global voice/bubble/autoplay settings from the settings tool.

Inputs: step, steps, action.

walkthrough_voice_selectionA

Change the narration voice, preview how it sounds, list available voices, or audition voices back-to-back. Use when the user asks to change the voice, try a different voice, hear voice options, compare voices, or asks 'what voices are available'. Do NOT use to toggle voice on/off — use the settings tool for that. Pass voice to switch to a specific voice and hear a sample. Pass list: true to list voices without playing audio. Pass audition: true to play voices back-to-back for comparison. Filter with locale (e.g. 'en-US', 'en', 'de') and gender. Voice selection persists across sessions.

Inputs: list, voice, gender, locale, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation4/5

    Most tools have clearly separated roles: get_selection feeds input, show_code handles no-commentary jumps, settings manages toggles, and walkthrough_voice_selection handles voices. The only real overlap is between show_code and walkthrough's one-step no-explanation mode, but the descriptions give explicit do-not-use rules that resolve it.

    Naming Consistency2/5

    show_code and get_selection follow verb_noun style, while walkthrough and settings are bare nouns, and walkthrough_voice_selection is an awkward noun phrase rather than a verb action. The mixed conventions make it harder to predict tool names.

    Tool Count5/5

    Five tools is a well-scoped count for this focused VS Code walkthrough server. Each tool covers a distinct functional area without unnecessary bulk or missing core capabilities.

    Completeness5/5

    The set covers the full workflow: get user selection, show code, explain/walk through code, run multi-step tours, navigate/clear tours, configure settings, and change voices. There are no obvious dead ends or missing operations for the apparent domain.

    Maintenance

    ActivitySlowing
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Turn your AI coding agent into a producer of interactive, narrated walkthroughs — code, whiteboard, and 3D casts, each a single self-contained HTML file that opens in any browser. Runs locally over npx.
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables LLMs to create animated, narrated tours of GitHub pull requests, with a local browser viewer showing diffs and code highlights while speaking the narration aloud.
      7
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables an AI assistant to have its recent code actions summarized aloud through system speakers, using offline native voices or cloud neural voices. It supports asynchronous playback and voice listing so users can hear what the agent did without reading the full response.
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to turn codebase changes into animated, narrated presentations that open in a browser and update live as the agent builds them, including stepped diffs, sequence diagrams, and review feedback loops.
      18
      MIT