-
-
Notifications
You must be signed in to change notification settings - Fork 117
Description
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
- Simplify Tool API: Reduce the number of tools and lower the cognitive load for the Agent.
- Enhance Functional Consistency: Provide uniform insertion behavior and parameter patterns.
- Increase Flexibility: Support combinations of multiple cell types and insertion positions.
- 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:
- Function Removal: The following existing functions will be removed:
append_markdown_cell
insert_markdown_cell
-
Parameter Changes: The new unified parameter model may require adjustments to existing Agent prompts and workflows.
-
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.