add_cell

Instructions

Implementation Reference

• src/jupyter-handler.js:591-598 (handler)

  Handler function for the 'add_cell' tool. Computes insertion position (defaults to end) and delegates to the insertCell helper function.

  async addCell(notebookPath, source = '', cellType = 'code', position = null) {
    const notebook = await this.readNotebook(notebookPath);
    
    // If position not specified, add at the end
    const insertPosition = position !== null ? position : notebook.cells.length;
    
    return await this.insertCell(notebookPath, insertPosition, cellType, source);
  }

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

  Core helper function that performs the cell insertion: validates inputs, formats source code into Jupyter notebook array format, creates the new cell object, inserts it into the notebook cells array at the specified position, saves the notebook, and returns a success response.

  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:259-283 (schema)

  Input schema definition for the 'add_cell' tool, specifying parameters, types, defaults, and required fields.

  inputSchema: {
    type: "object",
    properties: {
      notebook_path: {
        type: "string",
        description: "Absolute path to the Jupyter notebook file"
      },
      source: {
        type: "string",
        default: "",
        description: "Initial source code/content for the cell"
      },
      cell_type: {
        type: "string",
        enum: ["code", "markdown", "raw"],
        default: "code",
        description: "Type of cell to create"
      },
      position: {
        type: "integer",
        description: "Position to insert the cell (defaults to end if not specified)"
      }
    },
    required: ["notebook_path"]
  }

• src/index.js:381-387 (registration)

  Registration in the request handler switch statement: maps 'add_cell' tool invocations to the jupyterHandler.addCell method with parameter extraction.

  case "add_cell":
    return await this.jupyterHandler.addCell(
      args.notebook_path,
      args.source,
      args.cell_type,
      args.position
    );

• src/index.js:256-284 (registration)

  Tool registration in the tools array: defines name 'add_cell', description, and input schema for the MCP server.

  {
    name: "add_cell",
    description: "Add a new cell to the notebook",
    inputSchema: {
      type: "object",
      properties: {
        notebook_path: {
          type: "string",
          description: "Absolute path to the Jupyter notebook file"
        },
        source: {
          type: "string",
          default: "",
          description: "Initial source code/content for the cell"
        },
        cell_type: {
          type: "string",
          enum: ["code", "markdown", "raw"],
          default: "code",
          description: "Type of cell to create"
        },
        position: {
          type: "integer",
          description: "Position to insert the cell (defaults to end if not specified)"
        }
      },
      required: ["notebook_path"]
    }
  },