Skip to content

Unify Cell Insertion Functions into a Single insert_cell Tool #70

@ChengJiale150

Description

@ChengJiale150

Summary

Currently, jupyter_mcp_server/server.py has multiple scattered cell insertion functions: append_markdown_cell, insert_markdown_cell, append_execute_code_cell, and insert_execute_code_cell. It is proposed to unify the insertion functionality into a single insert_cell implementation, merging these functions into a more powerful and flexible tool.

Core Objectives

  1. Simplify Tool API: Reduce the number of tools and lower the cognitive load for the Agent.
  2. Enhance Functional Consistency: Provide uniform insertion behavior and parameter patterns.
  3. Increase Flexibility: Support combinations of multiple cell types and insertion positions.
  4. Improve Maintainability: Reduce code duplication and unify error handling logic.

Analysis of Current Problems

Existing Functions are Scattered and Overlapping

  • append_markdown_cell(cell_source) - Only supports appending markdown at the end.
  • insert_markdown_cell(cell_index, cell_source) - Only supports inserting markdown at a specified position.
  • append_execute_code_cell(cell_source) - Only supports appending and executing code at the end.
  • insert_execute_code_cell(cell_index, cell_source) - Only supports inserting and executing code at a specified position.

Proposed Solution

Implement a unified insert_cell function:

@mcp.tool()
async def insert_cell(
    cell_index: int,
    cell_type: Literal["code", "markdown"],
    cell_source: str,
) -> str:
    """
    Insert a cell to specified position.

    Args:
        cell_index: target index for insertion (0-based). Use -1 to append at end.
        cell_type: Type of cell to insert ("code" or "markdown")
        cell_source: Source content for the cell

    Returns:
        str: Success message and the structure of its surrounding cells (up to 5 cells above and 5 cells below)
    """

Output Example

Cell inserted successfully at index 2 (markdown)!

Current Surrounding Cells:

Index Type Count First Line
0 markdown N/A # Introduction
1 code 1 import pandas as pd
2 markdown N/A # New Section ← newly inserted
3 code 2 df.head()

⚠️ Important Warning: Breaking API Changes

This change will introduce incompatible API changes:

  1. Function Removal: The following existing functions will be removed:
  • append_markdown_cell
  • insert_markdown_cell
  1. Parameter Changes: The new unified parameter model may require adjustments to existing Agent prompts and workflows.

  2. Return Value Changes: The unified return format may affect downstream processing that relies on specific output formats.

Additional Notes

This improvement proposal is inspired by Anthropic's article on writing effective tools for AI Agents. The article emphasizes:

Choosing the right tools to implement (and not to implement)

By selectively implementing tools whose names reflect natural subdivisions of tasks, you simultaneously reduce the number of tools and tool descriptions loaded into the agent's context and offload agentic computation from the agent's context back into the tool calls themselves. This reduces an agent's overall risk of making mistakes.

The unified insert_cell tool aligns with this principle:

  • Reduces the number of tools: From 2 functions to 1.
  • Lowers cognitive load: The Agent only needs to learn how to use one tool.
  • Increases flexibility: Supports more use cases through parameter combinations.
  • Improves consistency: Unified error handling and output format.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions