Fix: Access ywebsocket_server via extension_manager to enable RTC mode (#135)

## Problem

When using jupyter-mcp-server as a Jupyter Server Extension with jupyter-collaboration,
MCP tools fall back to "file mode" instead of using RTC (Real-Time Collaboration) mode.

**Symptoms:**
- User executes cells successfully from JupyterLab UI
- MCP client (Claude Code) modifies/executes cells via MCP tools (works fine)
- After MCP modifications, user's UI becomes unresponsive
- Cells don't execute from UI, execution counter doesn't update
- Browser refresh required to restore UI functionality
- Kernel stays alive but WebSocket connection is broken

**Environment Tested:**
- jupyter-mcp-server 0.17.0 (Jupyter Server Extension mode)
- jupyterlab 4.4.1
- jupyter-collaboration 4.0.2
- Python 3.13.7
- Claude Code as MCP client

**MCP Configuration (.mcp.json):**
```json
{
  "mcpServers": {
    "jupyter": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8888/mcp"]
    }
  }
}
```

**Server logs show:**
```
[INFO] Notebook <id> not open, using file mode
[INFO] Wrote outputs to cell <n> in <path>
[INFO] Out-of-band changes. Overwriting the content in room json:notebook:<id>
```

The "Out-of-band changes" message indicates MCP wrote to the file directly,
bypassing the Y.js collaboration layer, which breaks the UI's WebSocket connection.

## Root Cause

1. MCP tools access collaboration via `serverapp.web_app.settings.get("yroom_manager")`
2. jupyter-collaboration never adds `yroom_manager` to web_app.settings
3. YDocExtension stores it as `self.ywebsocket_server` but doesn't expose it in settings
4. When yroom_manager lookup returns None, tools fall back to direct file writes
5. Direct file writes bypass Y.js CRDT layer → "Out-of-band changes" → WebSocket disconnect

## Solution

Access ywebsocket_server via the extension_manager:
```python
serverapp.extension_manager.extension_points['jupyter_server_ydoc'].app.ywebsocket_server
```

Also fixed DocumentRoom API - access document via `room._document` instead of
calling non-existent `get_jupyter_ydoc()` method.

## Impact

✅ MCP now uses true RTC mode when jupyter-collaboration is available
✅ No more WebSocket disconnections after MCP cell modifications
✅ UI stays responsive - no browser refresh required
✅ Enables true simultaneous editing between MCP clients and human users
✅ Works with Claude Code, VS Code, Cursor, and other MCP clients

## Files Changed

- execute_cell_tool.py
- overwrite_cell_source_tool.py
- insert_cell_tool.py
- insert_execute_code_cell_tool.py
- delete_cell_tool.py

## Testing

Verified with:
- JupyterLab 4.4.1 + jupyter-collaboration 4.0.2 + datalayer-pycrdt 0.12.17
- jupyter-mcp-server 0.17.0 as Jupyter Server Extension
- Claude Code as MCP client (npx mcp-remote transport)
- Confirmed MCP cell modifications no longer break UI WebSocket
- Confirmed execution from both MCP and UI works simultaneously without refresh

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[email protected]>

Author: delphos-mike

jupyter_mcp_server/tools/delete_cell_tool.py

@@ -30,20 +30,37 @@ async def _get_jupyter_ydoc(self, serverapp: Any, file_id: str):
             YNotebook instance or None if not in a collaborative session
         """
         try:
-            yroom_manager = serverapp.web_app.settings.get("yroom_manager")
-            if yroom_manager is None:
+            # Access ywebsocket_server from YDocExtension via extension_manager
+            # jupyter-collaboration doesn't add yroom_manager to web_app.settings
+            ywebsocket_server = None
+
+            if hasattr(serverapp, 'extension_manager'):
+                extension_points = serverapp.extension_manager.extension_points
+                if 'jupyter_server_ydoc' in extension_points:
+                    ydoc_ext_point = extension_points['jupyter_server_ydoc']
+                    if hasattr(ydoc_ext_point, 'app') and ydoc_ext_point.app:
+                        ydoc_app = ydoc_ext_point.app
+                        if hasattr(ydoc_app, 'ywebsocket_server'):
+                            ywebsocket_server = ydoc_app.ywebsocket_server
+
+            if ywebsocket_server is None:
                 return None
-                
+
             room_id = f"json:notebook:{file_id}"
-            
-            if yroom_manager.has_room(room_id):
-                yroom = yroom_manager.get_room(room_id)
-                notebook = await yroom.get_jupyter_ydoc()
-                return notebook
+
+            # Get room and access document via room._document
+            # DocumentRoom stores the YNotebook as room._document, not via get_jupyter_ydoc()
+            try:
+                yroom = await ywebsocket_server.get_room(room_id)
+                if yroom and hasattr(yroom, '_document'):
+                    return yroom._document
+            except Exception:
+                pass
+
         except Exception:
             # YDoc not available, will fall back to file operations
             pass
-        
+
         return None
 
     def _get_cell_index_from_id(self, ydoc, cell_id: str) -> Optional[int]:

jupyter_mcp_server/tools/execute_cell_tool.py

@@ -24,16 +24,33 @@ class ExecuteCellTool(BaseTool):
     async def _get_jupyter_ydoc(self, serverapp, file_id: str):
         """Get the YNotebook document if it's currently open in a collaborative session."""
         try:
-            yroom_manager = serverapp.web_app.settings.get("yroom_manager")
-            if yroom_manager is None:
+            # Access ywebsocket_server from YDocExtension via extension_manager
+            # jupyter-collaboration doesn't add yroom_manager to web_app.settings
+            ywebsocket_server = None
+
+            if hasattr(serverapp, 'extension_manager'):
+                extension_points = serverapp.extension_manager.extension_points
+                if 'jupyter_server_ydoc' in extension_points:
+                    ydoc_ext_point = extension_points['jupyter_server_ydoc']
+                    if hasattr(ydoc_ext_point, 'app') and ydoc_ext_point.app:
+                        ydoc_app = ydoc_ext_point.app
+                        if hasattr(ydoc_app, 'ywebsocket_server'):
+                            ywebsocket_server = ydoc_app.ywebsocket_server
+
+            if ywebsocket_server is None:
                 return None
 
             room_id = f"json:notebook:{file_id}"
 
-            if yroom_manager.has_room(room_id):
-                yroom = yroom_manager.get_room(room_id)
-                notebook = await yroom.get_jupyter_ydoc()
-                return notebook
+            # Get room and access document via room._document
+            # DocumentRoom stores the YNotebook as room._document, not via get_jupyter_ydoc()
+            try:
+                yroom = await ywebsocket_server.get_room(room_id)
+                if yroom and hasattr(yroom, '_document'):
+                    return yroom._document
+            except Exception:
+                pass
+
         except Exception:
             pass
 

jupyter_mcp_server/tools/insert_cell_tool.py

@@ -19,32 +19,49 @@ class InsertCellTool(BaseTool):
 
     async def _get_jupyter_ydoc(self, serverapp: Any, file_id: str):
         """Get the YNotebook document if it's currently open in a collaborative session.
-        
+
         This follows the jupyter_ai_tools pattern of accessing YDoc through the
         yroom_manager when the notebook is actively being edited.
-        
+
         Args:
             serverapp: The Jupyter ServerApp instance
             file_id: The file ID for the document
-            
+
         Returns:
             YNotebook instance or None if not in a collaborative session
         """
         try:
-            yroom_manager = serverapp.web_app.settings.get("yroom_manager")
-            if yroom_manager is None:
+            # Access ywebsocket_server from YDocExtension via extension_manager
+            # jupyter-collaboration doesn't add yroom_manager to web_app.settings
+            ywebsocket_server = None
+
+            if hasattr(serverapp, 'extension_manager'):
+                extension_points = serverapp.extension_manager.extension_points
+                if 'jupyter_server_ydoc' in extension_points:
+                    ydoc_ext_point = extension_points['jupyter_server_ydoc']
+                    if hasattr(ydoc_ext_point, 'app') and ydoc_ext_point.app:
+                        ydoc_app = ydoc_ext_point.app
+                        if hasattr(ydoc_app, 'ywebsocket_server'):
+                            ywebsocket_server = ydoc_app.ywebsocket_server
+
+            if ywebsocket_server is None:
                 return None
-                
+
             room_id = f"json:notebook:{file_id}"
-            
-            if yroom_manager.has_room(room_id):
-                yroom = yroom_manager.get_room(room_id)
-                notebook = await yroom.get_jupyter_ydoc()
-                return notebook
+
+            # Get room and access document via room._document
+            # DocumentRoom stores the YNotebook as room._document, not via get_jupyter_ydoc()
+            try:
+                yroom = await ywebsocket_server.get_room(room_id)
+                if yroom and hasattr(yroom, '_document'):
+                    return yroom._document
+            except Exception:
+                pass
+
         except Exception:
             # YDoc not available, will fall back to file operations
             pass
-        
+
         return None
 
     async def _insert_cell_ydoc(

jupyter_mcp_server/tools/insert_execute_code_cell_tool.py

@@ -23,19 +23,36 @@ class InsertExecuteCodeCellTool(BaseTool):
     async def _get_jupyter_ydoc(self, serverapp: Any, file_id: str):
         """Get the YNotebook document if it's currently open in a collaborative session."""
         try:
-            yroom_manager = serverapp.web_app.settings.get("yroom_manager")
-            if yroom_manager is None:
+            # Access ywebsocket_server from YDocExtension via extension_manager
+            # jupyter-collaboration doesn't add yroom_manager to web_app.settings
+            ywebsocket_server = None
+
+            if hasattr(serverapp, 'extension_manager'):
+                extension_points = serverapp.extension_manager.extension_points
+                if 'jupyter_server_ydoc' in extension_points:
+                    ydoc_ext_point = extension_points['jupyter_server_ydoc']
+                    if hasattr(ydoc_ext_point, 'app') and ydoc_ext_point.app:
+                        ydoc_app = ydoc_ext_point.app
+                        if hasattr(ydoc_app, 'ywebsocket_server'):
+                            ywebsocket_server = ydoc_app.ywebsocket_server
+
+            if ywebsocket_server is None:
                 return None
-                
+
             room_id = f"json:notebook:{file_id}"
-            
-            if yroom_manager.has_room(room_id):
-                yroom = yroom_manager.get_room(room_id)
-                notebook = await yroom.get_jupyter_ydoc()
-                return notebook
+
+            # Get room and access document via room._document
+            # DocumentRoom stores the YNotebook as room._document, not via get_jupyter_ydoc()
+            try:
+                yroom = await ywebsocket_server.get_room(room_id)
+                if yroom and hasattr(yroom, '_document'):
+                    return yroom._document
+            except Exception:
+                pass
+
         except Exception:
             pass
-        
+
         return None
 
     async def _insert_execute_ydoc(

jupyter_mcp_server/tools/overwrite_cell_source_tool.py

@@ -20,19 +20,36 @@ class OverwriteCellSourceTool(BaseTool):
     async def _get_jupyter_ydoc(self, serverapp: Any, file_id: str):
         """Get the YNotebook document if it's currently open in a collaborative session."""
         try:
-            yroom_manager = serverapp.web_app.settings.get("yroom_manager")
-            if yroom_manager is None:
+            # Access ywebsocket_server from YDocExtension via extension_manager
+            # jupyter-collaboration doesn't add yroom_manager to web_app.settings
+            ywebsocket_server = None
+
+            if hasattr(serverapp, 'extension_manager'):
+                extension_points = serverapp.extension_manager.extension_points
+                if 'jupyter_server_ydoc' in extension_points:
+                    ydoc_ext_point = extension_points['jupyter_server_ydoc']
+                    if hasattr(ydoc_ext_point, 'app') and ydoc_ext_point.app:
+                        ydoc_app = ydoc_ext_point.app
+                        if hasattr(ydoc_app, 'ywebsocket_server'):
+                            ywebsocket_server = ydoc_app.ywebsocket_server
+
+            if ywebsocket_server is None:
                 return None
-                
+
             room_id = f"json:notebook:{file_id}"
-            
-            if yroom_manager.has_room(room_id):
-                yroom = yroom_manager.get_room(room_id)
-                notebook = await yroom.get_jupyter_ydoc()
-                return notebook
+
+            # Get room and access document via room._document
+            # DocumentRoom stores the YNotebook as room._document, not via get_jupyter_ydoc()
+            try:
+                yroom = await ywebsocket_server.get_room(room_id)
+                if yroom and hasattr(yroom, '_document'):
+                    return yroom._document
+            except Exception:
+                pass
+
         except Exception:
             pass
-        
+
         return None
 
     def _generate_diff(self, old_source: str, new_source: str) -> str: