vscode-runtime-notebook-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Test Commands

npm run build         # Build extension (esbuild)
npm test              # Run unit tests (vitest)
npm run test:e2e      # Run E2E tests (requires VS Code instance)
npm run watch         # Build in watch mode

Architecture

VS Code extension exposing MCP tools for Jupyter notebook manipulation via HTTP server (port 49777).

src/
├── extension.ts           # Entry point, activates on VS Code startup
├── mcp/
│   ├── server.ts          # HTTP server + MCP StreamableHTTPServerTransport
│   └── tools/
│       ├── index.ts       # Registers all tools with McpServer
│       ├── cells.ts       # 14 cell tools (insert, edit, run, delete, etc.)
│       └── kernel.ts      # Kernel tools (restart, interrupt, info)
├── utils/
│   ├── notebook.ts        # VS Code Notebook API wrappers
│   └── output.ts          # Parse cell outputs (text, images, errors)
└── schemas/               # Zod validation schemas

Key flow: MCP client → HTTP POST /mcp → McpServer.tool() handler → VS Code Notebook API → Response

Core Design Principle

"Agent execution in sync with human/UI" - When an agent executes code, the result must be identical to human execution:

• Cell persists in notebook (never deleted after execution)
• Output visible in UI with execution number [1], [2]
• Agent receives output to iterate

Reference implementation: Claude Code extension (~/.cursor/extensions/anthropic.claude-code-*/extension.js)

Critical Implementation Details

Cell Execution Wait Condition

The waitForCellExecution function in src/utils/notebook.ts must use:

// CORRECT - waits for kernel to finish
if (typeof cell.executionSummary?.success === 'boolean') { ... }

// WRONG - returns immediately (executionSummary exists but success is undefined)
if (cell.executionSummary?.success !== undefined) { ... }