mcp-walkthrough 0.1.0

package/README.md

@@ -0,0 +1,221 @@
+[![NPM Version](https://img.shields.io/npm/v/mcp-walkthrough)](https://www.npmjs.com/package/mcp-walkthrough)
+[![NPM Downloads](https://img.shields.io/npm/dm/mcp-walkthrough)](https://www.npmjs.com/package/mcp-walkthrough)
+[![CI Status](https://github.com/Stefan-Nitu/mcp-walkthrough/actions/workflows/ci.yml/badge.svg)](https://github.com/Stefan-Nitu/mcp-walkthrough/actions/workflows/ci.yml)
+[![MIT Licensed](https://img.shields.io/npm/l/mcp-walkthrough)](https://github.com/Stefan-Nitu/mcp-walkthrough/blob/main/LICENSE)
+
+# MCP Walkthrough
+
+An MCP server for interactive code walkthroughs. Claude drives the narrative — opens files, highlights code, shows inline explanations, and navigates step by step.
+
+## Overview
+
+Text in a terminal isn't enough when you want Claude to explain a solution. MCP Walkthrough lets Claude open files in VS Code, highlight specific lines, and show rich markdown explanations right next to the code. Navigate at your own pace — forward, back, or let it autoplay.
+
+**Key Features:**
+- **Inline Explanations** — Markdown comment bubbles appear right next to highlighted code
+- **Multi-Step Walkthroughs** — Claude sends all steps at once, you navigate with keyboard shortcuts
+- **Autoplay** — Optional auto-advance with reading-speed-based timing
+- **Keyboard Navigation** — `Cmd+Shift+Right` / `Cmd+Shift+Left` to navigate steps
+- **Selection Reading** — Claude can see what you've highlighted to discuss it further
+- **Focus Preservation** — Opens files without stealing focus from your terminal
+
+> **Note:** This MCP server requires VS Code. It includes a companion VS Code extension that is automatically installed on first run.
+
+## Installation
+
+### Via npm (Recommended)
+
+```bash
+npm install -g mcp-walkthrough
+```
+
+### From Source
+
+```bash
+git clone https://github.com/Stefan-Nitu/mcp-walkthrough.git
+cd mcp-walkthrough
+bun install
+bun run build
+```
+
+> Requires Bun v1.3.8+ (development) and Node.js v18+ (runtime)
+
+## Quick Start
+
+### With Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-walkthrough": {
+      "command": "npx",
+      "args": ["-y", "mcp-walkthrough"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "mcp-walkthrough": {
+      "command": "mcp-walkthrough"
+    }
+  }
+}
+```
+
+Restart Claude Code to pick up the new server.
+
+### Add a CLAUDE.md hint
+
+MCP tools are deferred (loaded on-demand), so Claude may not use them automatically. Add this to your project's `CLAUDE.md`:
+
+```markdown
+## Walkthrough MCP
+
+You have access to walkthrough tools via MCP. Use them to visually walk the user through code — open files, highlight lines, and show inline explanations in VS Code.
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| **show_code** | Open a file and highlight specific lines |
+| **explain_code** | Highlight lines + show an inline markdown explanation bubble |
+| **clear_explanations** | Remove all explanation bubbles |
+| **walkthrough** | Start a multi-step walkthrough with all steps at once |
+| **walkthrough_navigate** | Navigate an active walkthrough (next/prev/goto) |
+| **walkthrough_status** | Get current walkthrough state |
+| **get_selection** | Read the currently highlighted code in VS Code |
+
+### walkthrough
+
+The main tool. Claude generates all steps and sends them at once. The VS Code extension handles navigation.
+
+```json
+{
+  "steps": [
+    {
+      "file": "/absolute/path/to/file.ts",
+      "line": 10,
+      "endLine": 25,
+      "explanation": "## Auth Middleware\n\nThis validates the JWT token on every request.",
+      "title": "Token Validation"
+    }
+  ],
+  "autoplay": false,
+  "delayMs": 5000
+}
+```
+
+**Parameters:**
+- `steps` — Array of `{ file, line, endLine?, explanation, title? }`
+- `autoplay` — Auto-advance through steps (default: `false`)
+- `delayMs` — Delay between steps in ms when autoplay is on (default: calculated from reading speed)
+
+### walkthrough_navigate
+
+```json
+{ "action": "next" }
+{ "action": "prev" }
+{ "action": "goto", "step": 3 }
+```
+
+### Keyboard Shortcuts
+
+During an active walkthrough:
+- **Cmd+Shift+Right** — Next step
+- **Cmd+Shift+Left** — Previous step
+- **Status bar** — Shows current step, click to stop
+
+## How It Works
+
+```
+Claude Code  →  MCP Server (stdio)  →  HTTP localhost:7890  →  VS Code Extension  →  Editor API
+```
+
+1. Claude calls walkthrough tools via MCP
+2. The MCP server forwards requests to a companion VS Code extension over HTTP
+3. The extension uses the VS Code API to open files, select ranges, and create comment threads
+4. Focus stays in your terminal — code appears in the editor beside it
+
+The VS Code extension is bundled with the npm package and automatically installed on first run.
+
+## Development
+
+### Project Structure
+
+```
+mcp-walkthrough/
+├── src/
+│   ├── index.ts              # MCP server entry point, tool registration
+│   ├── bridge.ts             # HTTP client to VS Code extension
+│   └── utils/
+│       └── logger.ts         # Pino logger (stderr only)
+├── vscode-extension/
+│   ├── src/
+│   │   └── extension.ts      # VS Code extension (HTTP server, Comments API)
+│   └── package.json
+├── tests/
+│   └── bridge.test.ts
+└── docs/
+```
+
+### Testing
+
+```bash
+bun test              # Run all tests
+bun test --watch      # Watch mode
+bun run typecheck     # Type checking
+bun run lint          # Linting
+bun run check         # Full check (typecheck + lint)
+```
+
+### Building
+
+```bash
+bun run build         # Builds MCP server + VS Code extension
+```
+
+The build script syncs the version from root `package.json` into the extension before packaging.
+
+## Troubleshooting
+
+### Tools return "This MCP server only works from VS Code."
+
+The MCP server pings the VS Code extension on startup. If the extension isn't running:
+
+1. Make sure you're running Claude Code inside VS Code (not a standalone terminal)
+2. The extension activates on VS Code startup — try reloading the window (`Cmd+Shift+P` → "Reload Window")
+
+### Extension not installed
+
+The MCP server auto-installs the extension on first run via `code --install-extension`. If this fails:
+
+1. Verify the `code` CLI is available in your terminal
+2. Manually install: `code --install-extension path/to/walkthrough-bridge.vsix`
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. **Write tests first** (TDD approach)
+4. Implement the feature
+5. Ensure all tests pass (`bun test`)
+6. Run linting (`bun run lint`)
+7. Submit a pull request
+
+## License
+
+MIT
+
+## Related Projects
+
+- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification and documentation
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - SDK used by this server
+- [MCP Claude Code Conversation History](https://github.com/Stefan-Nitu/mcp-claude-code-conversation-history) - MCP server for searching Claude Code conversations

package/dist/bridge.d.ts

@@ -0,0 +1,22 @@
+export declare function ensureExtensionInstalled(): void;
+type BridgeResult = Record<string, unknown>;
+export declare let bridgeAvailable: boolean | null;
+export declare function resetBridgeState(): void;
+export declare function checkBridge(): Promise<boolean>;
+export declare function isBridgeAvailable(): boolean;
+export declare function openFile(file: string, line: number, endLine?: number): Promise<BridgeResult>;
+export declare function showExplanation(file: string, line: number, endLine: number | undefined, explanation: string, title?: string): Promise<BridgeResult>;
+export declare function clearExplanations(): Promise<BridgeResult>;
+export interface WalkthroughStep {
+    file: string;
+    line: number;
+    endLine?: number;
+    explanation: string;
+    title?: string;
+}
+export declare function startWalkthrough(steps: WalkthroughStep[], autoplay?: boolean, delayMs?: number): Promise<BridgeResult>;
+export declare function navigateWalkthrough(action: string, step?: number): Promise<BridgeResult>;
+export declare function getWalkthroughStatus(): Promise<BridgeResult>;
+export declare function getSelection(): Promise<BridgeResult>;
+export {};
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAgBA,wBAAgB,wBAAwB,IAAI,IAAI,CAsB/C;AAED,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5C,eAAO,IAAI,eAAe,EAAE,OAAO,GAAG,IAAW,CAAC;AAElD,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAcpD;AAED,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAyBD,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,YAAY,CAAC,CAE/D;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,eAAe,EAAE,EACxB,QAAQ,CAAC,EAAE,OAAO,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,YAAY,CAAC,CAElE;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,CAE1D"}

package/dist/bridge.js

@@ -0,0 +1,96 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "./utils/logger.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const EXTENSION_ID = "undefined_publisher.walkthrough-bridge";
+const VSIX_PATH = join(__dirname, "../vscode-extension/walkthrough-bridge.vsix");
+const BRIDGE_URL = "http://127.0.0.1:7890";
+export function ensureExtensionInstalled() {
+    try {
+        const installed = execSync("code --list-extensions", { encoding: "utf-8" });
+        if (installed.includes(EXTENSION_ID)) {
+            logger.info("Walkthrough bridge extension already installed");
+            return;
+        }
+    }
+    catch {
+        logger.warn("Could not check installed extensions");
+    }
+    if (!existsSync(VSIX_PATH)) {
+        logger.error({ path: VSIX_PATH }, "Extension .vsix not found");
+        return;
+    }
+    try {
+        execSync(`code --install-extension "${VSIX_PATH}"`, { encoding: "utf-8" });
+        logger.info("Installed walkthrough bridge extension");
+    }
+    catch (error) {
+        logger.error({ err: error }, "Failed to install extension");
+    }
+}
+export let bridgeAvailable = null;
+export function resetBridgeState() {
+    bridgeAvailable = null;
+}
+export async function checkBridge() {
+    try {
+        const res = await fetch(`${BRIDGE_URL}/ping`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: "{}",
+        });
+        const data = (await res.json());
+        bridgeAvailable = data.ok === true;
+    }
+    catch {
+        bridgeAvailable = false;
+    }
+    logger.info({ bridgeAvailable }, "Bridge status");
+    return bridgeAvailable;
+}
+export function isBridgeAvailable() {
+    return bridgeAvailable === true;
+}
+const BRIDGE_UNAVAILABLE_ERROR = "This MCP server only works from VS Code.";
+async function bridgeRequest(endpoint, data = {}) {
+    if (bridgeAvailable === false) {
+        return { ok: false, error: BRIDGE_UNAVAILABLE_ERROR };
+    }
+    try {
+        const res = await fetch(`${BRIDGE_URL}${endpoint}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(data),
+        });
+        return (await res.json());
+    }
+    catch {
+        bridgeAvailable = false;
+        return { ok: false, error: BRIDGE_UNAVAILABLE_ERROR };
+    }
+}
+export async function openFile(file, line, endLine) {
+    return bridgeRequest("/open", { file, line, endLine });
+}
+export async function showExplanation(file, line, endLine, explanation, title) {
+    return bridgeRequest("/explain", { file, line, endLine, explanation, title });
+}
+export async function clearExplanations() {
+    return bridgeRequest("/clear");
+}
+export async function startWalkthrough(steps, autoplay, delayMs) {
+    return bridgeRequest("/walkthrough", { steps, autoplay, delayMs });
+}
+export async function navigateWalkthrough(action, step) {
+    return bridgeRequest("/walkthrough/navigate", { action, step });
+}
+export async function getWalkthroughStatus() {
+    return bridgeRequest("/walkthrough/status");
+}
+export async function getSelection() {
+    return bridgeRequest("/selection");
+}
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { checkBridge, clearExplanations, ensureExtensionInstalled, getSelection, getWalkthroughStatus, navigateWalkthrough, openFile, showExplanation, startWalkthrough, } from "./bridge.js";
+import { flushLogs, logger } from "./utils/logger.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
+const server = new McpServer({
+    name: "mcp-walkthrough",
+    version: packageJson.version,
+});
+server.registerTool("show_code", {
+    description: "Open a file in VS Code and highlight specific lines. Use this to walk the user through code.",
+    inputSchema: {
+        file: z.string().describe("Absolute path to the file"),
+        line: z.number().describe("Start line (1-based)"),
+        endLine: z.number().optional().describe("End line (1-based)"),
+    },
+}, async (args) => {
+    const result = await openFile(args.file, args.line, args.endLine);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+    };
+});
+server.registerTool("explain_code", {
+    description: "Open a file in VS Code, highlight lines, and show an inline markdown explanation bubble. Use this to walk the user through code with rich annotations.",
+    inputSchema: {
+        file: z.string().describe("Absolute path to the file"),
+        line: z.number().describe("Start line (1-based)"),
+        endLine: z.number().optional().describe("End line (1-based)"),
+        explanation: z.string().describe("Markdown explanation to display"),
+        title: z.string().optional().describe("Title for the explanation"),
+    },
+}, async (args) => {
+    const result = await showExplanation(args.file, args.line, args.endLine, args.explanation, args.title);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+    };
+});
+server.registerTool("clear_explanations", {
+    description: "Remove all walkthrough explanation bubbles from the editor.",
+}, async () => {
+    const result = await clearExplanations();
+    return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+    };
+});
+const stepSchema = z.object({
+    file: z.string().describe("Absolute path to the file"),
+    line: z.number().describe("Start line (1-based)"),
+    endLine: z.number().optional().describe("End line (1-based)"),
+    explanation: z.string().describe("Markdown explanation"),
+    title: z.string().optional().describe("Step title"),
+});
+server.registerTool("walkthrough", {
+    description: "Start a multi-step code walkthrough. Sends all steps to VS Code at once. The extension handles navigation — user clicks prev/next or uses Cmd+Shift+Left/Right. Optional autoplay with delay between steps. Returns current step state so you can navigate with walkthrough_navigate.",
+    inputSchema: {
+        steps: z.array(stepSchema).describe("Array of walkthrough steps"),
+        autoplay: z
+            .boolean()
+            .optional()
+            .describe("Auto-advance through steps (default: false)"),
+        delayMs: z
+            .number()
+            .optional()
+            .describe("Delay between steps in ms when autoplay is on (default: 5000)"),
+    },
+}, async (args) => {
+    const result = await startWalkthrough(args.steps, args.autoplay, args.delayMs);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+    };
+});
+server.registerTool("walkthrough_navigate", {
+    description: "Navigate an active walkthrough. Use when the user says next, back, or asks to jump to a step. Returns the current step state.",
+    inputSchema: {
+        action: z.enum(["next", "prev", "goto"]).describe("Navigation action"),
+        step: z
+            .number()
+            .optional()
+            .describe("Step index (0-based) for goto action"),
+    },
+}, async (args) => {
+    const result = await navigateWalkthrough(args.action, args.step);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+    };
+});
+server.registerTool("walkthrough_status", {
+    description: "Get the current state of an active walkthrough — which step, total steps, step details.",
+}, async () => {
+    const result = await getWalkthroughStatus();
+    return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+    };
+});
+server.registerTool("get_selection", {
+    description: "Get the currently selected/highlighted code in VS Code. Returns the file path, line range, and selected text. Use when the user wants to discuss specific code they've highlighted.",
+}, async () => {
+    const result = await getSelection();
+    return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+    };
+});
+async function main() {
+    ensureExtensionInstalled();
+    await checkBridge();
+    const transport = new StdioServerTransport();
+    let cleanupStarted = false;
+    const cleanup = async () => {
+        if (cleanupStarted)
+            return;
+        cleanupStarted = true;
+        logger.info("Shutting down...");
+        flushLogs();
+        const timeoutId = setTimeout(() => {
+            logger.error("Cleanup timeout - forcing exit after 5 seconds");
+            flushLogs();
+            process.exit(1);
+        }, 5000);
+        try {
+            await server.close();
+            clearTimeout(timeoutId);
+            logger.info("Cleanup completed");
+            process.exit(0);
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            logger.error({ err: error }, "Error during cleanup");
+            flushLogs();
+            process.exit(1);
+        }
+    };
+    process.once("SIGINT", cleanup);
+    process.once("SIGTERM", cleanup);
+    await server.connect(transport);
+    process.stdin.once("end", cleanup);
+    process.stdin.once("close", cleanup);
+    logger.info("mcp-walkthrough server started");
+}
+main().catch((error) => {
+    logger.error({ err: error }, "Fatal error");
+    flushLogs();
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,4 @@
+import pino from "pino";
+export declare const logger: pino.Logger<never, boolean>;
+export declare function flushLogs(): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAIxB,eAAO,MAAM,MAAM,6BAKlB,CAAC;AAEF,wBAAgB,SAAS,IAAI,IAAI,CAEhC"}

package/dist/utils/logger.js

@@ -0,0 +1,9 @@
+import pino from "pino";
+const destination = pino.destination({ dest: 2, sync: false });
+export const logger = pino({
+    level: process.env.LOG_LEVEL || "info",
+}, destination);
+export function flushLogs() {
+    destination.flushSync();
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAE/D,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CACxB;IACE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM;CACvC,EACD,WAAW,CACZ,CAAC;AAEF,MAAM,UAAU,SAAS;IACvB,WAAW,CAAC,SAAS,EAAE,CAAC;AAC1B,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "mcp-walkthrough",
+  "version": "0.1.0",
+  "description": "MCP server for interactive code walkthroughs - Claude-driven code tours",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-walkthrough": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "vscode-extension/walkthrough-bridge.vsix",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "Stefan Nitu",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "walkthrough",
+    "code-tour",
+    "claude-code"
+  ],
+  "scripts": {
+    "build": "npm run build:extension && tsc -p tsconfig.build.json",
+    "build:extension": "node -e \"const fs=require('fs');const v=require('./package.json').version;const p=JSON.parse(fs.readFileSync('vscode-extension/package.json','utf-8'));p.version=v;fs.writeFileSync('vscode-extension/package.json',JSON.stringify(p,null,2)+'\\n')\" && cd vscode-extension && npm install && npx tsc -p ./ && npx @vscode/vsce package --allow-missing-repository -o walkthrough-bridge.vsix",
+    "postinstall": "node -e \"try{require('child_process').execSync('code --install-extension '+require('path').join(__dirname,'vscode-extension','walkthrough-bridge.vsix')+' --force',{stdio:'ignore'})}catch{}\"",
+    "dev": "bun --watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "check": "bun run typecheck && bun run lint",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.1",
+    "pino": "^10.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.9",
+    "@types/bun": "latest",
+    "husky": "^9.1.7",
+    "typescript": "^6.0.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}