JupyterLLM - Jupyter LLM Cell Tracker

A VS Code / Cursor extension that adds a "track" toggle to Jupyter notebooks. When enabled, the extension automatically scrolls the notebook to keep the cell being edited by an LLM (along with its generated output) visible on screen.

Features

Core Features

• Track Toggle Button: A status bar item that allows you to quickly toggle tracking on/off
• Auto-Scroll: Automatically scrolls to cells when:
  • Cell content is being edited (including by LLM assistants)
  • New cells are added to the notebook
  • Cell execution completes and output is generated
• Configurable Position: Choose where on screen the tracked cell should appear (bottom, center, or top)
• Debounced Updates: Smooth scrolling with configurable debounce to avoid jitter

MCP Integration (Optional)

The extension includes an MCP (Model Context Protocol) server that allows LLM agents to:

• Execute notebook cells programmatically
• Retrieve cell outputs (text, images, errors)
• List all cells and their contents
• Get notebook metadata

This enables agents to write code, run it, check the results, and iterate based on errors or outputs.

Installation

From Source

1. Clone this repository
2. Run npm install to install dependencies
3. Run npm run compile to build the extension
4. Press F5 in VS Code to launch the Extension Development Host
5. Open a Jupyter notebook to see the extension in action

From VSIX

1. Download the .vsix file from the releases
2. In VS Code, go to Extensions view
3. Click the ... menu and select "Install from VSIX..."
4. Select the downloaded file

Basic Usage

1. Open a Jupyter notebook in VS Code or Cursor
2. Look for the "LLM Track: OFF" button in the status bar (bottom right)
3. Click to toggle tracking on/off, or use the command palette:
   • Cmd/Ctrl + Shift + P → "Toggle LLM Cell Tracking"
4. When tracking is ON, the notebook will automatically scroll to show cells that are being modified

MCP Setup (For LLM Cell Execution)

If you want LLM agents to execute notebook cells and read outputs, follow these steps:

1. Configure Cursor MCP Settings

The extension starts an HTTP bridge on port 54321 (by default) when it activates. You need to register the MCP server with Cursor.

Option A: Use the template (recommended)

Copy the template file to your Cursor config:

# On Windows
copy .cursor\mcp.json.template %APPDATA%\Cursor\User\mcp.json

# On macOS/Linux
cp .cursor/mcp.json.template ~/.cursor/mcp.json

Then edit the copied file and update the path to point to your installation:

{
  "mcpServers": {
    "jupyter-llm-track": {
      "command": "node",
      "args": [
        "/absolute/path/to/JupyterLLM/mcp-server.js"
      ],
      "env": {
        "MCP_BRIDGE_PORT": "54321"
      }
    }
  }
}

Option B: Manually add to existing mcp.json

If you already have MCP servers configured, add the jupyter-llm-track entry to your existing mcp.json file.

2. Add Cursor Rules (Optional but Recommended)

Copy the rules template to your project:

# On Windows
mkdir .cursor\rules
copy .cursor\rules\jupyter-llm.md.template .cursor\rules\jupyter-llm.md

# On macOS/Linux
mkdir -p .cursor/rules
cp .cursor/rules/jupyter-llm.md.template .cursor/rules/jupyter-llm.md

This tells the agent to automatically execute cells after writing them.

3. Restart Cursor

After updating mcp.json, restart Cursor to load the MCP server.

4. Verify MCP Connection

1. Open a Jupyter notebook
2. Start chatting with the agent in Cursor
3. The agent should now have access to tools like:
   • execute_cell(cellIndex)
   • get_cell_output(cellIndex)
   • list_cells()
   • get_notebook_info()

Check the extension's console output (Help → Toggle Developer Tools → Console) to verify the MCP bridge started successfully.

Configuration

Configure the extension in VS Code settings (Cmd/Ctrl + ,):

How It Works

The extension uses polling as the primary change detection mechanism. Every 300ms, it compares cell contents against a snapshot to detect modifications. This is more reliable than VS Code's text document change events, which don't fire consistently when notebooks are reloaded from disk (the typical LLM editing pattern).

When a change is detected, the extension scrolls to the highest-index changed cell to keep the view focused on the agent's active work area.

MCP Architecture

Cursor Agent ↔ (stdio) ↔ mcp-server.js ↔ (HTTP) ↔ VS Code Extension

The standalone mcp-server.js script implements the MCP stdio protocol and communicates with the extension via a local HTTP bridge.

Troubleshooting

MCP tools not appearing

1. Check that the extension is running (look for "LLM Track" in the status bar)
2. Check the Developer Console for MCP bridge startup messages
3. Verify mcp.json paths are absolute and correct
4. Restart Cursor after editing mcp.json

Tracking not scrolling

1. Make sure tracking is ON (status bar shows "LLM Track: ON")
2. The extension only tracks the active notebook editor
3. Check the log file: <extension-dir>/jupyter-llm-track.log

Cell execution fails

1. Ensure the notebook has a running kernel
2. Check that the cell index is valid (0-based)
3. Review cell output for error messages

Development

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch for changes
npm run watch

# Run linting
npm run lint

# Run tests
npm run test

Future Plans

See FUTURE_PLANS.md for ideas and enhancements under consideration, including a custom live viewer with streaming updates.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT