Cell ID matching fails in edit_cell when using full source code as identifier

[tofunori]

Bug Report: Cell ID matching fails in edit_cell operation

Problem Description

When attempting to edit Jupyter notebook cells using the edit_cell function, the cell ID matching consistently fails even when using the exact cell source code as returned by read_notebook_source_only.

Steps to Reproduce

1. Read a notebook using read_notebook_source_only
2. Copy the exact cell source code from the output (including the first comment line)
3. Attempt to edit that cell using edit_cell with the copied source as cell_id
4. The operation fails with "No cell found with ID [exact_source_code]"

Expected Behavior

The cell should be found and edited successfully when using the exact source code as returned by the read operation, or at least provide clear guidance on what constitutes a valid cell ID.

Actual Behavior

No cell found with ID # August-only spatial visualization with UltraPlot (FIXED)
import ultraplot as uplt
[... rest of source code ...]

Example Case

• Notebook: netcdf_reader.ipynb
• Cell to edit: Last cell with comment # August-only spatial visualization with UltraPlot (FIXED)
• Read output shows: Cell exists with that exact source code
• Edit attempt: Fails to find the cell using various ID approaches

Attempted Cell ID Formats

1. ❌ Full source code: Complete cell content as returned by read operation
2. ❌ First line only: # August-only spatial visualization with UltraPlot (FIXED)
3. ❌ Truncated comment: Various shortened versions
4. ❌ Position-based: Attempted numeric indexing

Current Workaround

Direct JSON manipulation of the notebook file:

import json
with open('notebook.ipynb', 'r') as f:
    nb = json.load(f)
nb['cells'][-1]['source'] = new_source.split('\n')
with open('notebook.ipynb', 'w') as f:
    json.dump(nb, f, indent=2)

Questions/Issues

1. What constitutes a valid cell ID? The documentation is unclear about the expected format
2. Should cell IDs be UUIDs? Some Jupyter notebooks use UUID-based cell IDs
3. Source code matching: If source-based matching is intended, the algorithm appears broken
4. Error messages: Could be more helpful by listing available cell IDs

Impact

• Breaks the expected workflow: read → identify → edit
• Forces users to bypass the MCP server entirely
• Makes programmatic notebook editing very difficult
• Inconsistent behavior between read and edit operations

Environment

• MCP Server: jupyter-mcp-server
• Client: Claude Code CLI
• Notebook format: Standard Jupyter .ipynb files
• Python version: 3.x

Suggested Improvements

1. Clear documentation on cell ID format and matching rules
2. Better error messages showing available cell IDs when match fails
3. Multiple matching strategies:
   • Exact source matching
   • Comment/header matching
   • Position-based indexing (0, 1, 2, -1, etc.)
   • UUID matching for notebooks that have them
4. Fallback mechanisms when primary matching fails

Additional Context

This issue significantly impacts the usability of the MCP server for automated notebook manipulation workflows. The read-edit cycle should be seamless and intuitive for users.

Would appreciate guidance on the intended cell ID format or if this represents a bug in the matching logic.

[echarles]

@tofunori you mention read_notebook_source_only method. Where is it coming from? Could you summarize the flow that produces the issue?

About the cell id format, that is document in https://jupyter.org/enhancement-proposals/62-cell-id/cell-id.html

From the top of my head, the id of a cell can have any format, should be stable (does not change, even if you move the cell up or down) and should be unique in a notebook. Of course, UUID are great format to assign ids to cells.