Skip to content

Commit 30a22fa

Browse files
delphos-mikeclaude
delphos-mike
and
claude
committed
Fix: Add RTC mode to reading tools (read_cell, read_cells, list_cells)
This PR completes the RTC (Real-Time Collaboration) mode fix started in datalayer#135 by extending it to the 3 reading tools that were missed. PR datalayer#135 fixed 5 editing tools to use RTC mode via extension_points, but 3 reading tools still used file operations, causing them to return stale data when notebooks were open in JupyterLab. **Affected tools:** - read_cell_tool.py - read stale file data instead of live YDoc - read_cells_tool.py - read stale file data instead of live YDoc - list_cells_tool.py - read stale file data instead of live YDoc jupyter-mcp-server couldn't find yroom_manager because it was never added to web_app.settings by jupyter-collaboration. The reading tools fell back to file mode, missing unsaved edits. Applied the same fix from datalayer#135 to all 3 reading tools: 1. Access ywebsocket_server via extension_manager.extension_points 2. Get document via room._document (not get_jupyter_ydoc()) 3. Check YDoc first (RTC mode), fall back to file if notebook not open Now all 8 tools (5 editing + 3 reading) consistently use RTC mode. - validate_fixes.py: Static validation (all 8 tools have RTC pattern) - test_rtc_mode.py: Integration tests for RTC functionality - TESTING_RTC_FIX.md: Complete testing guide Found by @delphos-mike using Claude Code during notebook analysis work. The reading tools were returning stale data, making it impossible to see live edits made through MCP tools. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent ca50b5f commit 30a22fa

File tree

3 files changed

+586
-0
lines changed

3 files changed

+586
-0
lines changed

‎TESTING_RTC_FIX.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Testing the RTC Mode Fix
2+
3+
This document explains how to test that the WebSocket disconnect bug has been fixed.
4+
5+
## The Bug
6+
7+
**Original Issue:** MCP cell editing tools (execute_cell, overwrite_cell_source, insert_cell, delete_cell, insert_execute_code_cell) were using file mode instead of RTC mode, causing "Out-of-band changes" that broke the WebSocket connection in JupyterLab, requiring browser refresh.
8+
9+
**Root Cause:** jupyter-mcp-server couldn't find `yroom_manager` because it wasn't added to `web_app.settings` by jupyter-collaboration. The code fell back to file mode.
10+
11+
**Fix:** Access `ywebsocket_server` via `extension_manager.extension_points['jupyter_server_ydoc'].app.ywebsocket_server` and document via `room._document`.
12+
13+
**Additional Fix:** Reading tools (read_cell, read_cells, list_cells) also needed RTC mode to see live unsaved changes instead of stale file data.
14+
15+
## Test Coverage
16+
17+
### Automated Tests
18+
19+
Run the RTC mode tests:
20+
21+
```bash
22+
# Install test dependencies
23+
uv pip install pytest pytest-asyncio
24+
25+
# Run RTC-specific tests
26+
pytest tests/test_rtc_mode.py -v
27+
28+
# Run with JUPYTER_SERVER mode only (the one with jupyter-collaboration)
29+
TEST_MCP_SERVER=false pytest tests/test_rtc_mode.py -v -m jupyter_server
30+
```
31+
32+
### What the Tests Verify
33+
34+
#### 1. `test_rtc_mode_for_cell_operations`
35+
- **Purpose**: Verifies all cell operations complete without causing WebSocket disconnects
36+
- **Tests**: insert_cell, overwrite_cell_source, execute_cell, read_cell, list_cells, delete_cell
37+
- **Pass Criteria**: All operations complete successfully, indicating RTC mode is used
38+
- **Failure Mode**: If file mode is used, operations would cause "Out-of-band changes"
39+
40+
#### 2. `test_reading_tools_see_unsaved_changes`
41+
- **Purpose**: Verifies reading tools see live YDoc data, not stale file data
42+
- **Tests**: read_cell, read_cells, list_cells after making unsaved edits
43+
- **Pass Criteria**: Reading tools see modified content (modified_value=999), NOT initial content (initial_value=1)
44+
- **Failure Mode**: If reading from disk, would see stale initial_value
45+
46+
**This is the KEY test for the new fix** - before our changes, reading tools would fail this test because they read from disk.
47+
48+
#### 3. `test_jupyter_collaboration_extension_loaded`
49+
- **Purpose**: Confirms jupyter-collaboration infrastructure is available
50+
- **Pass Criteria**: Can perform basic operations that require the extension
51+
52+
## Manual Testing
53+
54+
To manually reproduce and verify the fix:
55+
56+
### Prerequisites
57+
```bash
58+
# Start JupyterLab with jupyter-collaboration
59+
cd ~/workspace/tools_and_scripts/main/notebooks/jupyter
60+
./scripts/jupyter-server start
61+
62+
# Or in this repo, start test server
63+
uv run jupyter lab --no-browser --port 8888 --NotebookApp.token=MY_TOKEN
64+
```
65+
66+
### Test Scenario 1: No WebSocket Disconnect
67+
68+
1. **Open notebook in JupyterLab browser UI**
69+
- Navigate to http://localhost:8888
70+
- Create or open a notebook
71+
- Add a cell with: `x = 1`
72+
73+
2. **Use MCP tools to edit the same notebook**
74+
```python
75+
# Via MCP client or Claude Code
76+
use_notebook("test.ipynb", kernel_id="<existing-kernel-id>")
77+
overwrite_cell_source(0, "x = 2")
78+
```
79+
80+
3. **Verify in JupyterLab UI**
81+
- ✅ **Expected (FIXED)**: Cell updates to `x = 2`, no error, no need to refresh
82+
- ❌ **Broken (ORIGINAL BUG)**: "Out-of-band changes" error, WebSocket disconnect, requires browser refresh
83+
84+
### Test Scenario 2: Reading Tools See Live Changes
85+
86+
1. **Create cell via MCP**
87+
```python
88+
use_notebook("test.ipynb", kernel_id="<existing-kernel-id>")
89+
insert_cell(0, "code", "initial_value = 1")
90+
```
91+
92+
2. **Edit cell via MCP (unsaved change)**
93+
```python
94+
overwrite_cell_source(0, "modified_value = 999")
95+
```
96+
97+
3. **Read cell back immediately (before any save)**
98+
```python
99+
cell = read_cell(0)
100+
print(cell["source"])
101+
```
102+
103+
4. **Verify**
104+
- ✅ **Expected (FIXED)**: Shows `modified_value = 999` (live YDoc data)
105+
- ❌ **Broken (BEFORE FIX)**: Shows `initial_value = 1` (stale file data)
106+
107+
## Validation Script
108+
109+
The `validate_fixes.py` script verifies code patterns without running tests:
110+
111+
```bash
112+
python3 validate_fixes.py
113+
```
114+
115+
This checks:
116+
- ✅ All 8 tools have `_get_jupyter_ydoc()` with RTC logic
117+
- ✅ All tools use `extension_manager.extension_points['jupyter_server_ydoc']`
118+
- ✅ All tools access document via `room._document`
119+
- ✅ No old broken `yroom_manager` patterns
120+
121+
## What Makes a Test Pass vs Fail?
122+
123+
### Indicators RTC Mode is Working (Test PASSES):
124+
1. No "Out-of-band changes" errors in logs
125+
2. Cell operations complete without WebSocket disconnect
126+
3. Reading tools see latest edits immediately (not stale file data)
127+
4. JupyterLab UI updates automatically without refresh
128+
129+
### Indicators File Mode Fallback (Test FAILS):
130+
1. "Out-of-band changes" errors in logs
131+
2. WebSocket disconnects requiring browser refresh
132+
3. Reading tools see old content from disk
133+
4. JupyterLab UI requires refresh to see changes
134+
135+
## Files Modified
136+
137+
### Editing Tools (Fixed in PR #135)
138+
- `execute_cell_tool.py`
139+
- `overwrite_cell_source_tool.py`
140+
- `insert_cell_tool.py`
141+
- `insert_execute_code_cell_tool.py`
142+
- `delete_cell_tool.py`
143+
144+
### Reading Tools (Fixed in follow-up)
145+
- `read_cell_tool.py`
146+
- `read_cells_tool.py`
147+
- `list_cells_tool.py`
148+
149+
## Expected Test Results
150+
151+
```bash
152+
$ pytest tests/test_rtc_mode.py -v
153+
154+
tests/test_rtc_mode.py::test_rtc_mode_for_cell_operations PASSED
155+
tests/test_rtc_mode.py::test_reading_tools_see_unsaved_changes PASSED
156+
tests/test_rtc_mode.py::test_jupyter_collaboration_extension_loaded PASSED
157+
158+
============================================================
159+
✅ All cell operations completed without WebSocket disconnect!
160+
161+
This confirms:
162+
- RTC mode is being used (via extension_points)
163+
- No file-mode fallback occurred
164+
- No 'Out-of-band changes' would occur
165+
- WebSocket would remain stable in JupyterLab UI
166+
============================================================
167+
```
168+
169+
## Troubleshooting
170+
171+
### Test fails with "extension_points not found"
172+
- Ensure jupyter-collaboration is installed: `uv pip install jupyter-collaboration`
173+
- Check JupyterLab version compatibility (requires JupyterLab 4.x)
174+
175+
### Test fails with "reading tools see stale data"
176+
- Verify the reading tools have been patched with RTC mode
177+
- Check that `_get_jupyter_ydoc()` method exists in read_cell_tool.py
178+
179+
### WebSocket still disconnects
180+
- Check server logs for "Out-of-band changes" errors
181+
- Verify file_id_manager is accessible
182+
- Confirm ywebsocket_server is being found (should see RTC mode logs)
183+
184+
## References
185+
186+
- Original PR: https://github.com/datalayer/jupyter-mcp-server/pull/135
187+
- jupyter-collaboration docs: https://jupyterlab-realtime-collaboration.readthedocs.io/
188+
- Issue: WebSocket disconnects with "Out-of-band changes"

0 commit comments

Comments
 (0)