MCP Jupyter Server

Instructions

Implementation Reference

• src/jupyter-handler.js:174-224 (handler)

  The core handler function that implements the insert_cell tool logic: reads notebook, validates position and cell type, formats source, creates and inserts new cell, writes notebook, returns success message.

  async insertCell(notebookPath, position, cellType = 'code', source = '') {
    const notebook = await this.readNotebook(notebookPath);
    this.validateCellType(cellType);
    
    if (position < 0 || position > notebook.cells.length) {
      throw new Error(`Invalid position ${position}. Must be between 0 and ${notebook.cells.length}`);
    }
    
    // Convert string to array format - each line should end with \n except the last
    let sourceArray;
    if (!source) {
      sourceArray = [''];
    } else {
      const lines = source.split('\n');
      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();
      }
    }
    
    const newCell = {
      cell_type: cellType,
      metadata: {},
      source: sourceArray
    };
    
    if (cellType === 'code') {
      newCell.execution_count = null;
      newCell.outputs = [];
    }
    
    notebook.cells.splice(position, 0, newCell);
    await this.writeNotebook(notebookPath, notebook);
    
    return {
      content: [
        {
          type: "text",
          text: `Successfully inserted ${cellType} cell at position ${position}`
        }
      ]
    };
  }

• src/index.js:93-121 (schema)

  Input schema for the insert_cell tool defining parameters: notebook_path (required), position (required), cell_type (optional, default 'code'), source (optional, default '').

  {
    name: "insert_cell",
    description: "Insert a new cell at a specific position",
    inputSchema: {
      type: "object",
      properties: {
        notebook_path: {
          type: "string",
          description: "Absolute path to the Jupyter notebook file"
        },
        position: {
          type: "integer",
          description: "Position to insert the cell (0-based)"
        },
        cell_type: {
          type: "string",
          enum: ["code", "markdown", "raw"],
          default: "code",
          description: "Type of cell to create"
        },
        source: {
          type: "string",
          default: "",
          description: "Initial source code/content for the cell"
        }
      },
      required: ["notebook_path", "position"]
    }
  },

• src/index.js:344-350 (registration)

  Registration in the CallToolRequestSchema handler switch statement that dispatches 'insert_cell' calls to jupyterHandler.insertCell with argument handling.

  case "insert_cell":
    return await this.jupyterHandler.insertCell(
      args.notebook_path,
      args.position,
      args.cell_type || "code",
      args.source || ""
    );