MCP Walkthrough
Provides code walkthroughs for Windsurf (by Codeium), enabling step-by-step code explanations with highlighting and voice narration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Walkthrough Walk me through the main function in src/index.ts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-walkthroughAuto-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 |
|
Cursor |
|
VS Code Copilot |
|
Windsurf |
|
Skill (Claude Code)
npx skills add stefan-nitu/mcp-walkthroughInstalls 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 |
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 itEach highlight appends
narrationin bold — selection moves to the highlight's linesAfter 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 |
| Next step |
| Previous step |
| Pause / resume |
| Stop walkthrough |
How It Works
AI Agent → MCP Server (stdio) → Unix socket → VS Code Extension → Editor API + TTSAgent calls walkthrough tools via MCP
MCP server sends steps to VS Code extension via workspace-specific Unix socket
Extension shows bubbles, moves selection, narrates with TTS (Edge TTS + native fallback)
Each VS Code window gets its own socket — multiple windows work independently
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 lintingLocal 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 --forceThen 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
Available Tools
5 toolsget_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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Make narrated, on-brand product videos of your real app from your coding agent or AI assistant.
Loom for agents: AI agents record narrated product demos, plus transcripts, summaries, and search.
Make narrated demo videos of web apps from your AI assistant.
Ask other AI models and generate images, speech, music and video from your coding agent.
Related MCP Servers
FlicenseNot gradedqualityDmaintenanceTurn 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-- AlicenseAqualityCmaintenanceEnables 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.7MIT
- AlicenseAqualityBmaintenanceEnables 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.3MIT
- AlicenseAqualityCmaintenanceEnables 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.18MIT