vscode-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.

What this is

A VS Code extension (extensionDependencies: ms-toolsai.jupyter) that runs an embedded HTTP MCP server inside the VS Code extension host. It exposes the Jupyter notebooks already open in the user's editor — and their kernels — to MCP-compatible AI agents (Claude Code, Cursor, etc.). All notebook reads/writes/executions go through the live VS Code Notebook API, so they share state with the editor (undo/redo, the same kernel, the same outputs).

Commands

npm install
npm run build       # esbuild bundle → dist/extension.js
npm run watch       # rebuild on change
npm run typecheck   # tsc --noEmit
npm test            # @vscode/test-electron + Mocha integration suite

To run the extension: open this folder in VS Code and press F5 to launch an Extension Development Host. The dev host runs the launch config in .vscode/launch.json (which has npm: build as a preLaunchTask).

npm test requires uv on PATH — pretest runs scripts/setup-test-python.sh which uv syncs two venvs (pinned to Python 3.13 via .python-version): the main kernel env at test/fixtures/python/.venv, and test/fixtures/python-unregistered/.venv — an ipykernel-only env that no test registers with the Python extension itself, used by the step-2 kernel test to prove notebook_select_kernel can make a never-before-seen interpreter usable on its own. Tests live in test/integration/suite/ and are compiled by tsc -p tsconfig.test.json to out/. The runner downloads a fresh stable VS Code into .vscode-test/, installs ms-toolsai.jupyter into it, opens the workspace at test/fixtures/workspace/, and drives the MCP tools through an in-memory transport (no HTTP). Manual testing still uses end-to-end-test/test.ipynb opened in the dev host.

Kernel selection in tests

The Jupyter extension exposes no public API to assign a kernel to a notebook. The controller-id format Jupyter uses internally (.jvsc74a57bd0<sha256(normalizedInterpreterPath)>.<normPath>.<normPath>.-m#ipykernel_launcher) now lives in production code — controllerIdForInterpreter / normalizeInterpreterPath in src/utils/kernel.ts, mirroring getKernelId / getInterpreterKernelSpecName in microsoft/vscode-jupyter; if Jupyter changes that scheme these break. The helper selectVenvKernel in test/integration/suite/helpers.ts imports those and dispatches notebook.selectKernel, and notebook_select_kernel's python_path parameter exposes the same logic to agents so they can attach a kernel by interpreter path without hashing or popping the picker (the former roadmap item, now shipped).