MCP Jupyter Server

Instructions

Implementation Reference

• src/jupyter-handler.js:313-399 (handler)

  The main handler function that executes bulk cell operations (edit, delete, convert) on a Jupyter notebook. It reads the notebook, applies operations in sorted order to handle index shifts, writes back changes, and reports success/errors.
  async bulkEditCells(notebookPath, operations) { const notebook = await this.readNotebook(notebookPath); let successCount = 0; const errors = []; // Sort operations by index in descending order for deletions const sortedOps = operations.sort((a, b) => { if (a.type === 'delete' && b.type !== 'delete') return -1; if (a.type !== 'delete' && b.type === 'delete') return 1; return b.cell_index - a.cell_index; }); for (const op of sortedOps) { try { switch (op.type) { case 'edit': if (op.cell_index < 0 || op.cell_index >= notebook.cells.length) { throw new Error(`Invalid cell index ${op.cell_index}`); } // Convert string to array format - each line should end with \n except the last const lines = op.new_source.split('\n'); const sourceArray = lines.map((line, index) => { if (index === lines.length - 1) { return line === '' ? '' : line; } else { return line + '\n'; } }); // Remove empty last element if original ended with \n if (sourceArray.length > 1 && sourceArray[sourceArray.length - 1] === '') { sourceArray.pop(); } notebook.cells[op.cell_index].source = sourceArray; break; case 'delete': if (op.cell_index < 0 || op.cell_index >= notebook.cells.length) { throw new Error(`Invalid cell index ${op.cell_index}`); } notebook.cells.splice(op.cell_index, 1); break; case 'convert': if (op.cell_index < 0 || op.cell_index >= notebook.cells.length) { throw new Error(`Invalid cell index ${op.cell_index}`); } this.validateCellType(op.new_type); const cell = notebook.cells[op.cell_index]; cell.cell_type = op.new_type; if (op.new_type === 'code') { cell.execution_count = null; cell.outputs = []; } else { delete cell.execution_count; delete cell.outputs; } break; default: throw new Error(`Unknown operation type: ${op.type}`); } successCount++; } catch (error) { errors.push(`Operation ${op.type} on cell ${op.cell_index}: ${error.message}`); } } await this.writeNotebook(notebookPath, notebook); const resultText = [ `Bulk operation completed: ${successCount}/${operations.length} operations successful` ]; if (errors.length > 0) { resultText.push(`\nErrors:\n${errors.join('\n')}`); } return { content: [ { type: "text", text: resultText.join('\n') } ] }; }
• src/index.js:187-222 (schema)

  Input schema for the bulk_edit_cells tool, defining parameters: notebook_path (string) and operations (array of objects with type 'edit'/'delete'/'convert', cell_index (required), optional new_source and new_type).
  name: "bulk_edit_cells", description: "Perform bulk operations on multiple cells", inputSchema: { type: "object", properties: { notebook_path: { type: "string", description: "Absolute path to the Jupyter notebook file" }, operations: { type: "array", items: { type: "object", properties: { type: { type: "string", enum: ["edit", "delete", "convert"] }, cell_index: { type: "integer" }, new_source: { type: "string" }, new_type: { type: "string", enum: ["code", "markdown", "raw"] } }, required: ["type", "cell_index"] } } }, required: ["notebook_path", "operations"] } },
• src/index.js:369-373 (registration)

  Registration in the CallToolRequest handler switch statement, dispatching calls to bulk_edit_cells to the JupyterHandler.bulkEditCells method.
  case "bulk_edit_cells": return await this.jupyterHandler.bulkEditCells( args.notebook_path, args.operations );