Add move_cell MCP tool on prerelease track (#22)

* chore: bump runtimed to 2.0.1 prerelease

* feat: add move_cell MCP tool

* chore: split stable and prerelease release tracks

* ci: validate release track metadata

Author: rgbkrk

.github/workflows/publish.yml

@@ -16,6 +16,39 @@ jobs:
       - name: Set up Python
         run: uv python install 3.12
 
+      - name: Validate release track
+        env:
+          TARGET_COMMITISH: ${{ github.event.release.target_commitish }}
+          IS_PRERELEASE: ${{ github.event.release.prerelease }}
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          import tomllib
+
+          target = os.environ["TARGET_COMMITISH"]
+          is_prerelease = os.environ["IS_PRERELEASE"].lower() == "true"
+
+          with open("pyproject.toml", "rb") as f:
+            version = tomllib.load(f)["project"]["version"]
+
+          prerelease_match = re.match(r"^(\d+)\.(\d+)\.(\d+)a\d+$", version)
+          stable_match = re.match(r"^(\d+)\.(\d+)\.(\d+)$", version)
+
+          if target == "main":
+            assert is_prerelease, "Releases from main must be GitHub prereleases"
+            assert prerelease_match, "Versions on main must be prereleases like 2.0.1a<timestamp>"
+            assert int(prerelease_match.group(1)) >= 2, "Versions on main must be on the 2.x prerelease line"
+          elif target == "release/1.9.x":
+            assert not is_prerelease, "Releases from release/1.9.x must be stable"
+            assert stable_match, "release/1.9.x must publish stable versions like 1.9.x"
+            assert stable_match.group(1) == "1" and stable_match.group(2) == "9", "release/1.9.x must stay on 1.9.x"
+          else:
+            raise AssertionError(
+              f"Unsupported release target '{target}'. Use main for prereleases or release/1.9.x for stable releases."
+            )
+          PY
+
       - name: Build package
         run: uv build
 

README.md

@@ -23,10 +23,16 @@ We're in the prelimiary stages of hooking up the realtime system from nteract/de
 #### Claude Code
 
 ```bash
-# Add to Claude Code
+# Stable desktop 1.4.x / stable MCP
 claude mcp add nteract -- uvx nteract
 ```
 
+For desktop nightly / the upcoming 2.x transition, use the prerelease MCP package and nightly socket:
+
+```bash
+claude mcp add nteract-nightly -- env RUNTIMED_SOCKET_PATH="$HOME/Library/Caches/runt-nightly/runtimed.sock" uvx --prerelease allow nteract
+```
+
 That's it. Now Claude can execute Python code, create visualizations, and work with your data.
 
 ## What is this?
@@ -54,13 +60,21 @@ You can open the same notebook in the [nteract desktop app](https://github.com/n
 
 ## Installation
 
+Stable line for desktop `1.4.x`:
+
 ```bash
 uvx nteract
 ```
 
+Prerelease line for desktop nightly / 2.x transition:
+
+```bash
+uvx --prerelease allow nteract
+```
+
 ## Claude Code Setup
 
-Add nteract as an MCP server:
+Add stable `nteract` as an MCP server:
 
 ```bash
 claude mcp add nteract -- uvx nteract
@@ -81,12 +95,17 @@ Or manually add to your Claude configuration:
 
 ### Using with Nightly
 
-If you're using nteract desktop nightly builds, point at the nightly socket:
+If you're using nteract desktop nightly builds, point at the nightly socket and allow prereleases:
 
 ```bash
 claude mcp add nteract -- env RUNTIMED_SOCKET_PATH="$HOME/Library/Caches/runt-nightly/runtimed.sock" uvx --prerelease allow nteract
 ```
 
+### Release Tracks
+
+- `main` publishes prerelease `nteract` builds for the 2.x transition and tracks `runtimed 2.x` prereleases.
+- `release/1.9.x` is the stable maintenance line for desktop `1.4.x` and stays on `runtimed 1.9.0`.
+
 ## Available Tools
 
 | Tool | Description |
@@ -102,6 +121,7 @@ claude mcp add nteract -- env RUNTIMED_SOCKET_PATH="$HOME/Library/Caches/runt-ni
 | `get_cell` | Get a cell by ID with outputs |
 | `get_all_cells` | View all cells in the notebook |
 | `set_cell_source` | Update a cell's source code |
+| `move_cell` | Reorder a cell within the notebook |
 | `clear_outputs` | Clear a cell's outputs |
 | `delete_cell` | Remove a cell from the notebook |
 | `start_kernel` | Start a Python kernel |

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nteract"
-version = "1.9.1"
+version = "2.0.1a202603110913"
 description = "Bring AI to Jupyter notebooks. MCP server for Claude, ChatGPT, Gemini, OpenCode and any agent."
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -11,7 +11,7 @@ requires-python = ">=3.10"
 dependencies = [
     "mcp>=1.26.0",
     "httpx>=0.27.0,<1.0",
-    "runtimed>=1.9.0,<2.0",
+    "runtimed>=2.0.1a202603110913,<3.0",
 ]
 
 [project.scripts]

src/nteract/_mcp_server.py

@@ -967,6 +967,29 @@ async def delete_cell(cell_id: str) -> dict[str, Any]:
     return {"cell_id": cell_id, "deleted": True}
 
 
+@mcp.tool(annotations=ToolAnnotations(destructiveHint=True))
+async def move_cell(cell_id: str, after_cell_id: str | None = None) -> dict[str, Any]:
+    """Move a cell to a new position in the notebook.
+
+    Reorders the shared document and syncs the change to all connected clients.
+
+    Args:
+        cell_id: The cell to move.
+        after_cell_id: Move after this cell. Use None to move to the start.
+
+    Returns:
+        Confirmation of the move, including the new internal position token.
+    """
+    session = await _get_session()
+    new_position = await session.move_cell(cell_id=cell_id, after_cell_id=after_cell_id)
+    return {
+        "cell_id": cell_id,
+        "after_cell_id": after_cell_id,
+        "new_position": new_position,
+        "moved": True,
+    }
+
+
 @mcp.tool(annotations=ToolAnnotations(destructiveHint=True))
 async def clear_outputs(cell_id: str) -> dict[str, Any]:
     """Clear a cell's outputs.
@@ -1010,6 +1033,19 @@ async def collect_events() -> None:
     with contextlib.suppress(asyncio.TimeoutError):
         await asyncio.wait_for(collect_events(), timeout=timeout_secs)
 
+    if complete:
+        # Prefer the synced document as the final source of truth once execution
+        # finishes. This is more robust across runtimed output transport changes.
+        session = await _get_session()
+        with contextlib.suppress(Exception):
+            cell = await session.get_cell(cell_id=cell_id)
+            has_error_output = any(output.output_type == "error" for output in cell.outputs)
+            status = "error" if has_error_output else "idle"
+            header = _format_header(cell.id, status=status, execution_count=cell.execution_count)
+            items: list[ContentItem] = [TextContent(type="text", text=header)]
+            items.extend(_outputs_to_content(cell.outputs))
+            return items
+
     return _execution_result_to_content(cell_id, events, complete)
 
 

tests/test_mcp_integration.py

@@ -131,6 +131,7 @@ async def test_list_tools(mcp_client: ClientSession):
     assert "get_cell" in tool_names
     assert "get_all_cells" in tool_names
     assert "delete_cell" in tool_names
+    assert "move_cell" in tool_names
     assert "execute_cell" in tool_names
 
     # run_code should be removed
@@ -349,3 +350,47 @@ async def test_delete_cell(mcp_client: ClientSession):
     text = _get_text(result)
     # The full cell_id shouldn't appear (we only show first 8 chars in header)
     assert cell_id not in text
+
+
+@pytest.mark.asyncio
+async def test_move_cell(mcp_client: ClientSession):
+    """Test cell reordering."""
+    await mcp_client.call_tool("connect_notebook", {})
+
+    result = await mcp_client.call_tool("create_cell", {"source": "first"})
+    first_id = _extract_cell_id(_get_text(result))
+    assert first_id is not None
+
+    result = await mcp_client.call_tool("create_cell", {"source": "second"})
+    second_id = _extract_cell_id(_get_text(result))
+    assert second_id is not None
+
+    result = await mcp_client.call_tool("create_cell", {"source": "third"})
+    third_id = _extract_cell_id(_get_text(result))
+    assert third_id is not None
+
+    result = await mcp_client.call_tool(
+        "move_cell",
+        {"cell_id": third_id, "after_cell_id": first_id},
+    )
+    data = _parse_json(result)
+    assert data["moved"] is True
+    assert data["cell_id"] == third_id
+    assert data["after_cell_id"] == first_id
+
+    result = await mcp_client.call_tool("get_all_cells", {})
+    text = _get_text(result)
+    assert text.index("first") < text.index("third") < text.index("second")
+
+    result = await mcp_client.call_tool(
+        "move_cell",
+        {"cell_id": second_id, "after_cell_id": None},
+    )
+    data = _parse_json(result)
+    assert data["moved"] is True
+    assert data["cell_id"] == second_id
+    assert data["after_cell_id"] is None
+
+    result = await mcp_client.call_tool("get_all_cells", {})
+    text = _get_text(result)
+    assert text.index("second") < text.index("first") < text.index("third")