Jupyter VS Code MCP

Расширение VS Code, которое предоставляет операции с блокнотами Jupyter как инструменты MCP через обычный HTTP — один переносимый URL для любого ИИ-агента программирования. Никаких абсолютных путей, никакой команды node, никакой обвязки stdio.

Подключите любой MCP-клиент к этому URL — и агент сможет просматривать, редактировать, запускать и отлаживать блокноты в вашей текущей сессии редактора: он видит те же ячейки, что и вы, общается с тем же ядром, которое использует ваш блокнот (локальным или удалённым — включая Colab), и каждое действие попадает в настоящий интерфейс VS Code.

Возможности

Редактирование блокнота со стабильными идентификаторами ячеек

• Каждая ячейка идентифицируется единой схемой: #NB-xxxxxxxx, сохраняемой в стандартном поле cell id формата nbformat 4.5. Она переживает правки, вставку/удаление других ячеек, сдвиги индексов, сохранение/повторное открытие, перезагрузку расширения — даже копирование файла на другую машину.

• Идентификаторы никогда не переиспользуются после удаления: новые ячейки всегда получают свежие случайные ID. jupyter_get_summary назначает ID любой ячейке, у которой его нет (например, созданной вручную в интерфейсе), поэтому каждый полученный идентификатор можно сразу использовать.

• Индексы всюду отсчитываются от нуля (сводка, исходники, диапазоны запуска, выводы) — никакой путаницы в соглашениях.

Неблокирующее управление выполнением

• jupyter_run_cells запускает выполнение и сразу возвращает управление; опрашивайте состояние через jupyter_wait_until_idle или снимайте снимок через jupyter_get_status. Никаких слепых пауз и таймаутов MCP на длинных ячейках.

• Защита от неготового ядра: запуск на неработающем или отсутствующем ядре возвращает полезные подсказки, а не зависает.

• jupyter_interrupt_kernel прерывает текущий запуск, сохраняя все переменные.

Интеллект ядра (уровня Copilot)

• jupyter_get_variables — отчёты о переменных с учётом типов: DataFrame/Series как {shape, columns[:8], head(2)}, ndarray как {shape, dtype}, контейнеры с length, скаляры — короткими repr-представлениями. Использует официальный API представления переменных Jupyter, если он доступен, в противном случае — незаметный опрос ядра, который никогда не затрагивает счётчик выполнений. Опциональная фильтрация по символам документа скрывает внутренний шум только тогда, когда символы действительно доступны.

• jupyter_get_pip_packages — инвентаризация окружения (имя + версия) из активного окружения ядра.

• jupyter_install_packages — pip выполняется внутри собственного интерпретатора ядра, поэтому пакеты попадают в среду выполнения, которую реально использует блокнот, — включая удалённые ВМ вроде Colab, но никогда на локальный хост. Поддерживает спецификации версий и --upgrade, проверяет затем, что каждая спецификация разрешается, и честно сообщает об ошибках (с реальным хвостом вывода pip), а не делает вид, что всё успешно.

• jupyter_get_status опрашивает живое ядро на предмет реальной версии Python и платформы, а не доверяет устаревшим метаданным.

• jupyter_select_kernel открывает встроенный выбор ядра VS Code, когда ядро не активно.

Транспорт MCP только по сети

• Streamable HTTP (спецификация MCP 2025-11-25) с ответами в виде простого JSON — минимальному клиенту достаточно одного curl.

• Эндпоинты: /mcp (плюс устаревший /sse), GET /health для проверки живости и определения версии.

• Поддерживаются несколько одновременных сессий агентов; сессии переживают смену порта на лету.

Честная отчётность

Ошибки содержат контекст и подсказки для следующего шага: отсутствующее ядро → инструкция по запуску, устаревший ID → обновление через сводку, неудачная установка pip → реальный хвост ошибки pip, занятое ядро → явное уведомление об отсрочке вместо молча пустых результатов.

Related MCP server: Jupyter MCP Server

Инструменты

Стабильные идентификаторы ячеек

Каждая ячейка получает случайный постоянный ID (#NB-xxxxxxxx), записываемый в стандартное поле cell id формата nbformat 4.5 — тот же слот, который платформа сама читает и который без потерь проходит через сохранение/загрузку. ID не зависит от изменения позиции, правок содержимого, вставки/удаления соседних ячеек и циклов повторного открытия. Предпочитайте ID индексам; вызывайте jupyter_get_summary, чтобы их узнать (он также добавляет недостающие ID ячейкам, созданным вне инструментов).

Ввод без префикса из 8 шестнадцатеричных символов (abcd1234) принимается как сокращение для #NB-abcd1234.

Совместимые агенты

Работает любой MCP-клиент, говорящий по HTTP. Часто используемые конфигурации:

Claude Code, Cursor, Windsurf, Cline, Copilot:

{
  "mcpServers": {
    "jupyter-vscode-mcp": {
      "url": "http://localhost:9123/mcp"
    }
  }
}

OpenCode, Kilo Code:

{
  "mcp": {
    "jupyter-vscode-mcp": {
      "type": "remote",
      "url": "http://localhost:9123/mcp",
      "enabled": true
    }
  }
}

Выполните "Jupyter VS Code MCP: Show MCP Configuration" из палитры команд → выберите своего агента → фрагмент скопирован в буфер обмена.

Установка и запуск

Скачайте последний .vsix из Releases, затем:

code --install-extension jupyter-vscode-mcp-<version>.vsix

1. Откройте любой .ipynb — сервер автоматически запускается на 127.0.0.1:9123 (строка состояния показывает состояние; нажмите, чтобы переключить).

2. Добавьте указанную выше URL-конфигурацию своему агенту.

3. Проверяйте живость в любой момент: curl http://localhost:9123/health.

Настройки: jupyter-vscode-mcp.mcpPort (по умолчанию 9123, применяется на лету), jupyter-vscode-mcp.autoStart (по умолчанию true).

Рекомендуемый рабочий процесс

jupyter_list_open_notebooks   → pick notebook
jupyter_get_summary           → stable #NB-* IDs, exec state        (0-based)
jupyter_get_cell_source       → read only what you need
jupyter_edit_cell             → IDs stay valid after edits
jupyter_run_cells             → starts async, returns immediately
jupyter_wait_until_idle       → blocks until done (or poll get_status)
jupyter_get_outputs           → inline short text, artifact files for big/binary
jupyter_get_variables         → inspect kernel state after runs

Архитектура

AI agent ──HTTP/JSON-RPC──▶ VS Code extension (in-process http server :9123)
                                 │ vscode.* APIs + ms-toolsai.jupyter public API
                                 ▼
                     notebook cells, outputs, kernel status

Взаимодействие с ядром использует документированный публичный API ms-toolsai.jupyter (kernel.executeCode, команды прерывания/перезапуска, команды перечисления переменных и пакетов pip) с запасными вариантами в виде команд; отслеживание выполнения опирается на workspace.onDidChangeNotebookDocument.

Разработка

npm install
npm run compile      # typecheck
npm run lint
npm run build        # esbuild bundle
npm run smoke        # local protocol smoke test (vscode stubbed)
npx @vscode/vsce package

Ссылки

• Model Context Protocol — транспорт Streamable HTTP, спецификация 2025-11-25

• microsoft/vscode-copilot-chat (MIT) — паттерны суммаризации переменных, бюджеты усечения и фильтрации по символам

• SMARK OpenCode IDE Bridge — предварительные проверки ядра через публичный API Jupyter, запасные команды прерывания/перезапуска, отслеживание завершения на основе событий

• kriss-spy/opencode-jupyter — исходная концепция HTTP-моста

Лицензия

MIT