jcollab 0.1.0__py3-none-any.whl

jcollab/__init__.py

@@ -0,0 +1,2 @@
+"""jcollab: MCP server for live co-editing of JupyterLab notebooks."""
+__version__ = "0.1.0"

jcollab/discovery.py

@@ -0,0 +1,133 @@
+"""Find running Jupyter servers of the current user via Jupyter's own runtime files.
+
+Jupyter Server writes ``jpserver-<pid>.json`` (url, port, root_dir, pid, token; mode 600) into the
+runtime dir for every server and removes it on clean shutdown. Crashed servers leave stale files, so
+every candidate is checked for a live pid and probed on ``/api/status``.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+from jupyter_core.paths import jupyter_runtime_dir
+
+
+@dataclass(frozen=True)
+class Instance:
+    url: str            # always ends with "/" (includes base_url)
+    token: str
+    root_dir: str
+    pid: int
+    port: int
+
+    @property
+    def name(self) -> str:
+        return f"{Path(self.root_dir).name or self.root_dir}:{self.port}"
+
+    def public(self) -> dict:
+        return {"name": self.name, "url": self.url, "root_dir": self.root_dir, "pid": self.pid, "port": self.port,
+                "token_protected": bool(self.token)}
+
+
+def _pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _candidates() -> list[Instance]:
+    out = []
+    for f in sorted(Path(jupyter_runtime_dir()).glob("jpserver-*.json")):
+        try:
+            d = json.loads(f.read_text())
+            if not _pid_alive(int(d["pid"])):
+                continue
+            url = d["url"] if d["url"].endswith("/") else d["url"] + "/"
+            out.append(Instance(url=url, token=d.get("token") or "", root_dir=d.get("root_dir") or d.get("notebook_dir") or "",
+                                pid=int(d["pid"]), port=int(d["port"])))
+        except (OSError, ValueError, KeyError):
+            continue
+    return out
+
+
+async def _probe(inst: Instance) -> bool:
+    """Reach the server on loopback first: the advertised hostname (e.g. 0.0.0.0 or the host name) may not resolve."""
+    try:
+        async with httpx.AsyncClient(timeout=2) as c:
+            r = await c.get(local_url(inst) + "api/status", headers=auth_headers(inst))
+            return r.status_code == 200
+    except httpx.HTTPError:
+        return False
+
+
+def local_url(inst: Instance) -> str:
+    """URL on 127.0.0.1 with the instance's base_url path (servers bound to 0.0.0.0 or a host name are still reachable here)."""
+    from urllib.parse import urlparse
+    p = urlparse(inst.url)
+    return f"http://127.0.0.1:{inst.port}{p.path}"
+
+
+def auth_headers(inst: Instance) -> dict:
+    return {"Authorization": f"token {inst.token}"} if inst.token else {}
+
+
+async def discover() -> list[Instance]:
+    cands = _candidates()
+    ok = await asyncio.gather(*[_probe(i) for i in cands])
+    live = [i for i, good in zip(cands, ok) if good]
+    # A stale file can share a port with a live server only if the pid is alive but is a different process; keep the
+    # entry that answered, drop duplicates by port.
+    seen, out = set(), []
+    for i in live:
+        if i.port not in seen:
+            seen.add(i.port)
+            out.append(i)
+    return out
+
+
+async def resolve(selector: str | int | None) -> Instance:
+    """Pick an instance by port, name (``Trading:8889``), root_dir basename or substring. Optional if exactly one is running."""
+    live = await discover()
+    if not live:
+        raise RuntimeError("No running Jupyter server found (runtime dir has no live jpserver-*.json).")
+    if selector in (None, ""):
+        if len(live) == 1:
+            return live[0]
+        raise ValueError("Several Jupyter servers are running, pass `instance`: " + ", ".join(i.name for i in live))
+    s = str(selector)
+    exact = [i for i in live if s in (i.name, str(i.port), i.root_dir, Path(i.root_dir).name)]
+    hits = exact or [i for i in live if s.lower() in i.name.lower() or s in i.root_dir]
+    if len(hits) == 1:
+        return hits[0]
+    raise ValueError(f"Instance {s!r} " + ("is ambiguous: " if hits else "not found. Running: ") + ", ".join(i.name for i in (hits or live)))
+
+
+_VERSIONS: dict[int, dict] = {}
+
+
+def server_versions(inst: Instance) -> dict | None:
+    """jupyter-ydoc / pycrdt versions of the Jupyter server process (same machine only), via its own interpreter."""
+    import subprocess
+    if inst.pid in _VERSIONS:
+        return _VERSIONS[inst.pid]
+    try:
+        py = os.readlink(f"/proc/{inst.pid}/exe")
+        out = subprocess.run([py, "-c", "import importlib.metadata as m;print(m.version('jupyter-ydoc'),m.version('pycrdt'))"],
+                             capture_output=True, text=True, timeout=15).stdout.split()
+        _VERSIONS[inst.pid] = {"jupyter-ydoc": out[0], "pycrdt": out[1], "python": py}
+    except (OSError, IndexError, subprocess.SubprocessError):
+        return None
+    return _VERSIONS[inst.pid]
+
+
+def client_versions() -> dict:
+    import importlib.metadata as m
+    return {"jupyter-ydoc": m.version("jupyter-ydoc"), "pycrdt": m.version("pycrdt")}

jcollab/doc.py

@@ -0,0 +1,325 @@
+"""Live notebook document: one Yjs connection per (server, notebook), with health checks and verified writes.
+
+Why the care: a Yjs peer can silently stop being a peer (websocket closed, session expired, document room recreated)
+while its in-memory copy keeps accepting edits that nobody ever sees. ``DocSession.ensure`` therefore re-checks the
+connection before every operation, and ``DocSession.persisted`` confirms that an edit reached the file on the server.
+"""
+from __future__ import annotations
+
+import asyncio
+import copy
+import difflib
+import time
+from typing import Any
+
+from jupyter_nbmodel_client import NbModelClient, get_jupyter_notebook_websocket_url
+from pycrdt import Assoc, YMessageType, read_message
+
+from .discovery import client_versions, server_versions
+from .rest import Rest
+
+CLIENT_NAME = "metis"
+
+
+class DocError(RuntimeError):
+    pass
+
+
+def set_text(ytext, new: str) -> None:
+    """Replace a Yjs text with ``new`` using minimal edits, so open editors keep cursor and scroll position."""
+    old = str(ytext)
+    if old == new:
+        return
+    if len(old) + len(new) > 20000:
+        ytext.clear()
+        ytext += new
+        return
+    ops = difflib.SequenceMatcher(None, old, new, autojunk=False).get_opcodes()
+    for tag, i1, i2, j1, j2 in reversed(ops):
+        if tag == "equal":
+            continue
+        if i2 > i1:
+            del ytext[i1:i2]
+        if j2 > j1:
+            ytext.insert(i1, new[j1:j2])
+
+
+def youtput(o: dict):
+    """One nbformat output as the Yjs value JupyterLab expects (stream text is a shared Text)."""
+    from pycrdt import Map, Text
+    o = copy.deepcopy(o)
+    if o.get("output_type") == "stream":
+        t = o.get("text", "")
+        o["text"] = Text(t if isinstance(t, str) else "".join(t))
+    return Map(o)
+
+
+def set_outputs(yc, outputs: list[dict]) -> None:
+    from pycrdt import Array
+    if not isinstance(yc.get("outputs"), Array):
+        yc["outputs"] = Array()
+    youts = yc["outputs"]
+    youts.clear()
+    youts.extend([youtput(o) for o in outputs])
+
+
+class LiveClient(NbModelClient):
+    """NbModelClient that also applies incoming awareness messages (the stock client drops them), so the
+    cursors/selections JupyterLab tabs publish are visible."""
+
+    async def _on_message(self, websocket, message: bytes) -> None:
+        if message and message[0] == YMessageType.AWARENESS:
+            try:
+                self._doc.awareness.apply_awareness_update(read_message(message[1:]), "remote")
+            except Exception:  # noqa: BLE001 - awareness is advisory, never break syncing over it
+                pass
+            return
+        await super()._on_message(websocket, message)
+
+
+class DocSession:
+    def __init__(self, rest: Rest, path: str):
+        self.rest = rest
+        self.path = path
+        self._nb: NbModelClient | None = None
+        self.lock = asyncio.Lock()
+        self.reconnects = 0
+        self._pointer: asyncio.Task | None = None
+
+    # -- connection ------------------------------------------------------------------------------------------------
+
+    @staticmethod
+    def _running(nb: NbModelClient) -> bool:
+        task = getattr(nb, "_NbModelClient__run", None)
+        return task is not None and not task.done()
+
+    async def ensure(self) -> NbModelClient:
+        nb = self._nb
+        if nb is not None and nb.synced and self._running(nb):
+            return nb
+        await self.close()
+        hdr = await self.rest.xsrf_headers()
+        token = self.rest.inst.token or None
+        url = await asyncio.to_thread(get_jupyter_notebook_websocket_url, self.rest.base.rstrip("/"), self.path, token,
+                                      10.0, None, hdr or None)
+        nb = LiveClient(url, path=self.path, username=CLIENT_NAME, additional_headers=hdr or None)
+        await nb.start()
+        if not nb.synced:
+            await nb.stop()
+            raise DocError(f"Could not sync the shared document for {self.path} (is jupyter-collaboration installed and enabled?)")
+        self._nb = nb
+        self.reconnects += 1
+        return nb
+
+    async def close(self) -> None:
+        nb, self._nb = self._nb, None
+        if nb is not None:
+            try:
+                await nb.stop()
+            except Exception:
+                pass
+
+    async def doc(self):
+        """The ``jupyter_ydoc.YNotebook`` behind the live connection."""
+        return (await self.ensure())._doc
+
+    # -- addressing ------------------------------------------------------------------------------------------------
+
+    async def index(self, ref: int | str) -> int:
+        """Resolve a cell reference: index (negative counts from the end), digit string, or cell id."""
+        doc = await self.doc()
+        n = doc.cell_number
+        if isinstance(ref, str):                      # an exact id wins, also when it looks like a number
+            for i in range(n):
+                if doc.ycells[i].get("id") == ref:
+                    return i
+            if not ref.lstrip("-").isdigit():
+                raise DocError(f"No cell with id {ref!r} in {self.path}")
+        i = int(ref)
+        if i < 0:
+            i += n
+        if not 0 <= i < n:
+            raise DocError(f"Cell index {ref} out of range (notebook has {n} cells)")
+        return i
+
+    async def ycell(self, ref: int | str):
+        return (await self.doc()).ycells[await self.index(ref)]
+
+    # -- reading ---------------------------------------------------------------------------------------------------
+
+    async def cell(self, ref: int | str, outputs: bool = False) -> dict[str, Any]:
+        doc = await self.doc()
+        i = await self.index(ref)
+        return self.describe(doc.ycells[i], i, outputs)
+
+    @staticmethod
+    def describe(yc, i: int, outputs: bool = False) -> dict[str, Any]:
+        d = {"index": i, "id": yc.get("id"), "cell_type": yc.get("cell_type"), "source": str(yc["source"]),
+             "metadata": yc["metadata"].to_py() if yc.get("metadata") is not None else {}}
+        if d["cell_type"] == "code":
+            ec = yc.get("execution_count")
+            d["execution_count"] = int(ec) if ec is not None else None
+            d["execution_state"] = yc.get("execution_state")
+            outs = yc.get("outputs")
+            d["n_outputs"] = len(outs) if outs is not None else 0
+            if outputs:
+                d["outputs"] = outs.to_py() if outs is not None else []
+        return d
+
+    async def cells(self, outputs: bool = False) -> list[dict[str, Any]]:
+        doc = await self.doc()
+        return [self.describe(doc.ycells[i], i, outputs) for i in range(doc.cell_number)]
+
+    # -- verification ----------------------------------------------------------------------------------------------
+
+    async def persisted(self, timeout: float = 4.0) -> tuple[bool, str]:
+        """Wait until the file on the server shows the same cell sources as the live document."""
+        doc = await self.doc()
+        ids = [doc.ycells[i].get("id") for i in range(doc.cell_number)]
+        if len(set(ids)) != len(ids):
+            return False, ("live document has duplicate cell ids: client/server Yjs version skew. "
+                           + self.skew_hint())
+        want = [str(doc.ycells[i]["source"]) for i in range(doc.cell_number)]
+        deadline = asyncio.get_running_loop().time() + timeout
+        have: list[str] = []
+        while True:
+            try:
+                nb = (await self.rest.contents(self.path))["content"]
+                have = ["".join(c["source"]) if isinstance(c["source"], list) else c["source"] for c in nb["cells"]]
+            except Exception as e:  # noqa: BLE001 - report, do not hide
+                return False, f"could not read file back: {e}"
+            if have == want:
+                return True, "ok"
+            if asyncio.get_running_loop().time() > deadline:
+                diff = [i for i in range(max(len(have), len(want)))
+                        if i >= len(have) or i >= len(want) or have[i] != want[i]][:5]
+                ids = [str(doc.ycells[i].get("id")) for i in range(doc.cell_number)]
+                return False, f"file on server differs from the live document (cells {diff}, file has {len(have)} cells, live has {len(want)}: ids {ids})"
+            await asyncio.sleep(0.25)
+
+    async def point_at(self, ref: int | str, seconds: float = 30.0, select: bool = True, scroll: bool = True,
+                       force_scroll: bool = False, label: str | None = None) -> dict[str, Any]:
+        """Show a labelled "Metis" cursor/selection in a cell for a while (visible in every open tab, and reachable via
+        the Collaborators sidebar of JupyterLab)."""
+        nb = await self.ensure()
+        doc = nb._doc
+        i = await self.index(ref)
+        t = doc.ycells[i]["source"]
+        n = len(t)
+        if n == 0:
+            raise DocError(f"Cell {i} is empty, nothing to point at (put some text in it first)")
+        anchor = t.sticky_index(0, Assoc.AFTER).to_json()
+        head = t.sticky_index(n - 1 if select else 0, Assoc.AFTER).to_json()
+        nb.set_local_state_field("user", {"username": "metis", "name": "Metis", "display_name": "Metis", "initials": "M",
+                                          "avatar_url": None, "color": "#d97757"})
+        nb.set_local_state_field("cursors", [{"anchor": anchor, "head": head, "primary": True, "empty": not (select and n > 1)}])
+        if scroll:
+            nb.set_local_state_field("scrollTo", {"cell": doc.ycells[i].get("id"), "nonce": str(time.time_ns()), "force": force_scroll, "label": label})
+        if self._pointer is not None:
+            self._pointer.cancel()
+
+        async def clear():
+            await asyncio.sleep(seconds)
+            try:
+                nb.set_local_state_field("cursors", [])
+                nb.set_local_state_field("scrollTo", None)
+            except Exception:  # noqa: BLE001
+                pass
+        self._pointer = asyncio.create_task(clear())
+        return {"pointing_at": i, "id": doc.ycells[i].get("id"), "seconds": seconds}
+
+    async def user_focus(self) -> list[dict[str, Any]]:
+        """Where other people (browser tabs) have their cursor/selection: cell, line, selected text.
+
+        JupyterLab publishes cursors through Yjs awareness as relative positions naming a character item. The offset
+        is resolved with pycrdt; the cell is the one whose text holds the same item at that offset."""
+        from pycrdt import StickyIndex
+        nb = await self.ensure()
+        doc, aw = nb._doc, nb._doc.awareness
+        out: list[dict[str, Any]] = []
+        for cid, st in list(aw.states.items()):
+            if cid == aw.client_id or not st.get("cursors"):
+                continue
+            user = st.get("user", {})
+            who = user.get("display_name") or user.get("name") or user.get("owner") or str(cid)
+            for cur in st["cursors"]:
+                try:
+                    a = StickyIndex.from_json(cur["anchor"]).get_index()
+                    h = StickyIndex.from_json(cur["head"]).get_index()
+                except Exception:  # noqa: BLE001
+                    continue
+                item = cur["anchor"].get("item")
+                cands = []
+                for i in range(doc.cell_number):
+                    t = doc.ycells[i]["source"]
+                    if a is None or len(t) < a:
+                        continue
+                    if item is None:
+                        cands.append(i)           # cursor at the very end/start: no item to match
+                        continue
+                    if a >= len(t):
+                        continue
+                    try:
+                        if t.sticky_index(a, Assoc(cur["anchor"].get("assoc", 0))).to_json().get("item") == item:
+                            cands.append(i)
+                    except BaseException:  # noqa: BLE001 - pycrdt panics on some positions
+                        continue
+                if not cands:
+                    continue
+                i = cands[0]
+                src = str(doc.ycells[i]["source"])
+                lo, hi = sorted((a, h if h is not None else a))
+                out.append({"user": who, "cell_index": i, "cell_id": doc.ycells[i].get("id"),
+                            "cell_type": doc.ycells[i].get("cell_type"),
+                            "line": src.count("\n", 0, lo), "column": lo - (src.rfind("\n", 0, lo) + 1),
+                            "selection": src[lo:hi] if hi > lo else None,
+                            **({"ambiguous_cells": cands} if len(cands) > 1 else {})})
+        return out
+
+    def skew_hint(self) -> str:
+        srv, cli = server_versions(self.rest.inst), client_versions()
+        if srv is None:
+            return f"Client has {cli}; install the same jupyter-ydoc and pycrdt versions as the Jupyter server."
+        fix = f"{self.rest.inst.name} runs jupyter-ydoc {srv['jupyter-ydoc']}, pycrdt {srv['pycrdt']}; client has {cli}."
+        return fix + f" Fix: pip install jupyter-ydoc=={srv['jupyter-ydoc']} pycrdt=={srv['pycrdt']} in the jcollab venv."
+
+    async def health(self) -> dict[str, Any]:
+        nb = await self.ensure()
+        peers = []
+        try:
+            for cid in nb.get_connected_peers():
+                u = (nb.get_peer_state(cid) or {}).get("user", {})
+                peers.append(u.get("display_name") or u.get("agent") or u.get("owner") or str(cid))
+        except Exception:  # noqa: BLE001
+            pass
+        viewers = None
+        sess = await self.rest.session_for(self.path)
+        if sess:  # awareness peers are not reliably reported; open frontends show up as kernel websocket connections
+            viewers = (await self.rest.request("GET", f"api/kernels/{sess['kernel']['id']}")).json().get("connections")
+        ok, detail = await self.persisted()
+        srv, cli = server_versions(self.rest.inst), client_versions()
+        return {"yjs_versions": {"client": cli, "server": srv and {k: srv[k] for k in ("jupyter-ydoc", "pycrdt")},
+                                 "match": bool(srv) and all(srv[k] == cli[k] for k in cli)},
+                "synced": nb.synced, "connections_made": self.reconnects, "awareness_peers": peers,
+                "frontends_attached_to_kernel": viewers, "persisted": ok, "detail": detail}
+
+
+class Sessions:
+    """Cache of DocSession per (instance, notebook path)."""
+
+    def __init__(self):
+        self._rest: dict[int, Rest] = {}
+        self._docs: dict[tuple[int, str], DocSession] = {}
+
+    def rest(self, inst) -> Rest:
+        r = self._rest.get(inst.port)
+        if r is None or r.inst != inst:
+            r = self._rest[inst.port] = Rest(inst)
+        return r
+
+    def doc(self, inst, path: str) -> DocSession:
+        key = (inst.port, path)
+        d = self._docs.get(key)
+        if d is None or d.rest.inst != inst:
+            d = self._docs[key] = DocSession(self.rest(inst), path)
+        return d

jcollab/kernel.py

@@ -0,0 +1,236 @@
+"""Kernel execution that leaves cells exactly as if the user had run them in JupyterLab.
+
+A cell run by the user shows: ``[*]`` while busy (shared cell field ``execution_state``), outputs streaming in, the
+kernel's own ``execution_count``, and ``metadata.execution`` with the iopub/shell timestamps that
+jupyterlab-execute-time displays. ``run_cell`` writes all of that into the shared document while the kernel runs.
+
+Code that is only inspected (``run_code``) uses ``store_history=False`` so it never consumes an execution count.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+import uuid
+from typing import Any
+
+import websockets
+
+from .doc import DocError, DocSession, set_outputs, youtput
+from .discovery import auth_headers
+from .rest import Rest
+
+
+class KernelError(RuntimeError):
+    pass
+
+
+def _ws_url(rest: Rest, kernel_id: str) -> str:
+    base = rest.base.replace("http://", "ws://", 1)
+    return f"{base}api/kernels/{kernel_id}/channels"
+
+
+def _request(code: str, store_history: bool, session: str) -> tuple[str, dict]:
+    msg_id = uuid.uuid4().hex
+    return msg_id, {
+        "header": {"msg_id": msg_id, "msg_type": "execute_request", "username": "metis", "session": session,
+                   "version": "5.3", "date": time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())},
+        "parent_header": {}, "metadata": {}, "channel": "shell", "buffers": [],
+        "content": {"code": code, "silent": False, "store_history": store_history, "user_expressions": {},
+                    "allow_stdin": False, "stop_on_error": True},
+    }
+
+
+def _nb_output(mt: str, ct: dict) -> dict | None:
+    if mt == "stream":
+        return {"output_type": "stream", "name": ct.get("name", "stdout"), "text": ct.get("text", "")}
+    if mt == "display_data":
+        return {"output_type": "display_data", "data": ct.get("data", {}), "metadata": ct.get("metadata", {})}
+    if mt == "execute_result":
+        return {"output_type": "execute_result", "data": ct.get("data", {}), "metadata": ct.get("metadata", {}),
+                "execution_count": ct.get("execution_count")}
+    if mt == "error":
+        return {"output_type": "error", "ename": ct.get("ename", ""), "evalue": ct.get("evalue", ""),
+                "traceback": ct.get("traceback", [])}
+    return None
+
+
+class _Sink:
+    """Receives kernel messages for one execute_request; optionally mirrors them into a shared-document cell."""
+
+    def __init__(self, doc=None, ycell=None):
+        self.doc, self.yc = doc, ycell
+        self.outputs: list[dict] = []
+        self.timing: dict[str, str] = {}
+        self.count: int | None = None
+        self.status = "unknown"
+        self.display_ids: dict[str, int] = {}
+        self._clear_next = False
+
+    # ydoc helpers -----------------------------------------------------------------------------------------------
+    def _youts(self):
+        return self.yc["outputs"]
+
+    def _push_timing(self):
+        if self.yc is not None:
+            with self.doc._ydoc.transaction():
+                self.yc["metadata"]["execution"] = dict(self.timing)
+
+    def _add(self, out: dict):
+        if self._clear_next:
+            self._clear_next = False
+            self.outputs.clear()
+            if self.yc is not None:
+                with self.doc._ydoc.transaction():
+                    self._youts().clear()
+        last = self.outputs[-1] if self.outputs else None
+        merged = out["output_type"] == "stream" and last and last["output_type"] == "stream" and last["name"] == out["name"]
+        if merged:
+            last["text"] += out["text"]
+        else:
+            self.outputs.append(out)
+        if self.yc is None:
+            return
+        with self.doc._ydoc.transaction():
+            youts = self._youts()
+            if merged:
+                youts[len(youts) - 1]["text"] += out["text"]
+            else:
+                youts.append(youtput(out))
+
+    def _replace(self, idx: int, out: dict):
+        self.outputs[idx] = out
+        if self.yc is not None:
+            with self.doc._ydoc.transaction():
+                self._youts()[idx] = youtput(out)
+
+    def clear(self):
+        self.outputs.clear()
+        if self.yc is not None:
+            with self.doc._ydoc.transaction():
+                self._youts().clear()
+
+    # message handling -------------------------------------------------------------------------------------------
+    def on_iopub(self, msg: dict):
+        mt, ct = msg["msg_type"], msg.get("content", {})
+        date = msg.get("header", {}).get("date")
+        if mt == "execute_input":
+            self.count = ct.get("execution_count")
+            if date:
+                self.timing["iopub.execute_input"] = date
+            self._push_timing()
+        elif mt == "status":
+            state = ct.get("execution_state")
+            if state == "busy" and date and "iopub.status.busy" not in self.timing:
+                self.timing["iopub.status.busy"] = date
+                self._push_timing()
+            elif state == "idle":
+                if date:
+                    self.timing["iopub.status.idle"] = date
+                self.status = "idle"
+        elif mt == "clear_output":
+            if ct.get("wait"):
+                self._clear_next = True
+            else:
+                self.clear()
+        elif mt == "update_display_data":
+            did = ct.get("transient", {}).get("display_id")
+            if did in self.display_ids:
+                self._replace(self.display_ids[did], {"output_type": "display_data", "data": ct.get("data", {}),
+                                                      "metadata": ct.get("metadata", {})})
+        else:
+            out = _nb_output(mt, ct)
+            if out:
+                if mt == "execute_result":
+                    self.count = ct.get("execution_count", self.count)
+                did = ct.get("transient", {}).get("display_id")
+                self._add(out)
+                if did:
+                    self.display_ids[did] = len(self.outputs) - 1
+
+    def on_reply(self, msg: dict):
+        date = msg.get("header", {}).get("date")
+        if date:
+            self.timing["shell.execute_reply"] = date
+        started = msg.get("metadata", {}).get("started")
+        if started:
+            self.timing["shell.execute_reply.started"] = started
+        ct = msg.get("content", {})
+        self.reply_status = ct.get("status")
+        if ct.get("execution_count") is not None:
+            self.count = ct["execution_count"]
+
+
+async def _execute(rest: Rest, kernel_id: str, code: str, sink: _Sink, store_history: bool, timeout: float) -> bool:
+    """Run code, feed messages into ``sink``. Returns False if the timeout hit (the kernel is interrupted then)."""
+    msg_id, req = _request(code, store_history, uuid.uuid4().hex)
+    sink.reply_status = None
+    async with websockets.connect(_ws_url(rest, kernel_id), additional_headers=auth_headers(rest.inst) or None,
+                                  max_size=64 * 1024 * 1024) as ws:
+        await ws.send(json.dumps(req))
+        deadline = time.monotonic() + timeout
+        got_reply = False
+        while not (got_reply and sink.status == "idle"):
+            left = deadline - time.monotonic()
+            if left <= 0:
+                await rest.kernel_action(kernel_id, "interrupt")
+                return False
+            try:
+                msg = json.loads(await asyncio.wait_for(ws.recv(), min(left, 5)))
+            except asyncio.TimeoutError:
+                continue
+            if msg.get("parent_header", {}).get("msg_id") != msg_id:
+                continue
+            if msg.get("channel") == "shell" or msg["msg_type"] == "execute_reply":
+                sink.on_reply(msg)
+                got_reply = True
+            else:
+                sink.on_iopub(msg)
+    return True
+
+
+async def kernel_for(rest: Rest, ds_path: str, doc=None) -> str:
+    name = "python3"
+    if doc is not None:
+        try:
+            name = doc._ymeta["metadata"].to_py().get("kernelspec", {}).get("name") or name
+        except Exception:  # noqa: BLE001
+            pass
+    sess = await rest.ensure_session(ds_path, name)
+    return sess["kernel"]["id"]
+
+
+async def run_cell(ds: DocSession, ref: int | str, timeout: float = 300) -> dict[str, Any]:
+    doc = await ds.doc()
+    i = await ds.index(ref)
+    yc = doc.ycells[i]
+    if yc.get("cell_type") != "code":
+        raise DocError(f"Cell {i} is a {yc.get('cell_type')} cell, only code cells can run")
+    code = str(yc["source"])
+    kid = await kernel_for(ds.rest, ds.path, doc)
+    sink = _Sink(doc, yc)
+    t0 = time.monotonic()
+    with doc._ydoc.transaction():              # same state a user click produces: [*], no outputs, no old timing
+        yc["execution_state"] = "running"
+        yc["execution_count"] = None
+        set_outputs(yc, [])
+        if "execution" in yc["metadata"]:
+            del yc["metadata"]["execution"]
+    finished = False
+    try:
+        finished = await _execute(ds.rest, kid, code, sink, True, timeout)
+    finally:
+        with doc._ydoc.transaction():
+            yc["execution_count"] = sink.count
+            yc["execution_state"] = "idle"
+        sink._push_timing()
+    return {"index": i, "id": yc.get("id"), "execution_count": int(sink.count) if sink.count is not None else None, "status": sink.reply_status,
+            "timed_out": not finished, "seconds": round(time.monotonic() - t0, 2), "outputs": sink.outputs}
+
+
+async def run_code(rest: Rest, path: str, code: str, timeout: float = 60, doc=None) -> dict[str, Any]:
+    """Inspection run: not stored in kernel history, no execution count consumed, nothing written to the notebook."""
+    kid = await kernel_for(rest, path, doc)
+    sink = _Sink()
+    finished = await _execute(rest, kid, code, sink, False, timeout)
+    return {"status": sink.reply_status, "timed_out": not finished, "outputs": sink.outputs}

jcollab/rest.py

@@ -0,0 +1,58 @@
+"""Async REST access to one Jupyter server (contents, sessions, kernels), XSRF-safe for token-less servers."""
+from __future__ import annotations
+
+import httpx
+
+from .discovery import Instance, auth_headers, local_url
+
+
+class Rest:
+    def __init__(self, inst: Instance):
+        self.inst = inst
+        self.base = local_url(inst)
+        self._c = httpx.AsyncClient(timeout=15)
+
+    async def _headers(self, write: bool) -> dict:
+        h = auth_headers(self.inst)
+        if write and not self.inst.token:
+            if not self._c.cookies.get("_xsrf"):
+                await self._c.get(self.base + "login", follow_redirects=True)  # sets the _xsrf cookie even if the page 404s
+            xs = self._c.cookies.get("_xsrf")
+            if xs:
+                h["X-XSRFToken"] = xs
+                h["Cookie"] = f"_xsrf={xs}"
+        return h
+
+    async def request(self, method: str, path: str, *, write: bool = False, **kw) -> httpx.Response:
+        r = await self._c.request(method, self.base + path.lstrip("/"), headers=await self._headers(write), **kw)
+        r.raise_for_status()
+        return r
+
+    async def xsrf_headers(self) -> dict:
+        return await self._headers(True)
+
+    async def contents(self, path: str, content: bool = True) -> dict:
+        return (await self.request("GET", f"api/contents/{path}", params={"content": int(content)})).json()
+
+    async def sessions(self) -> list[dict]:
+        return (await self.request("GET", "api/sessions")).json()
+
+    async def session_for(self, path: str) -> dict | None:
+        for s in await self.sessions():
+            if s.get("path") == path or s.get("notebook", {}).get("path") == path:
+                return s
+        return None
+
+    async def ensure_session(self, path: str, kernel_name: str = "python3") -> dict:
+        s = await self.session_for(path)
+        if s:
+            return s
+        r = await self.request("POST", "api/sessions", write=True, json={
+            "kernel": {"name": kernel_name}, "path": path, "name": path, "type": "notebook"})
+        return r.json()
+
+    async def kernel_action(self, kernel_id: str, action: str) -> None:
+        await self.request("POST", f"api/kernels/{kernel_id}/{action}", write=True)
+
+    async def aclose(self) -> None:
+        await self._c.aclose()

jcollab/server.py

@@ -0,0 +1,463 @@
+"""jcollab MCP server (stdio). Tools address a notebook by ``instance`` (optional if only one server runs) and ``path``."""
+from __future__ import annotations
+
+import base64
+import copy
+import re
+import uuid
+from pathlib import PurePosixPath
+from typing import Any
+
+from mcp.server.mcpserver import Image, MCPServer
+
+from . import kernel
+from .discovery import discover, resolve
+from .doc import DocError, DocSession, Sessions, set_outputs, set_text
+
+INSTRUCTIONS = """Live co-editing of JupyterLab notebooks. Edits go through the shared Yjs document, so an open browser
+tab shows them immediately. Every mutating tool reports `persisted` (the file on the server matches the live document);
+if it is false, tell the user instead of assuming the edit is visible. Cells are addressed by index or cell id.
+Rules: small inspections go through `run_code` (not stored in history, no execution count used). Anything big or
+worth keeping runs as a visible code cell (`insert_cell` + `run_cell`) so the user sees the code. Mentions ("@claude" in a cell): handle only when the user asks (find_mentions, answer via add_comment). Put every markdown
+heading in its own cell. Pass cell_type='markdown' explicitly for prose."""
+
+mcp = MCPServer("jcollab", instructions=INSTRUCTIONS)
+S = Sessions()
+MAX_TEXT = 6000
+
+
+async def _ds(instance: str | None, path: str) -> DocSession:
+    inst = await resolve(instance)
+    path = path.lstrip("/")
+    root = inst.root_dir.rstrip("/") + "/"
+    if path.startswith(root):
+        path = path[len(root):]
+    return S.doc(inst, path)
+
+
+def _clip(s: str) -> str:
+    return s if len(s) <= MAX_TEXT else s[: MAX_TEXT // 2] + f"\n…[{len(s) - MAX_TEXT} chars cut]…\n" + s[-MAX_TEXT // 2:]
+
+
+_ANSI = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+
+
+def render(outputs: list[dict]) -> list[Any]:
+    """Outputs as MCP content: text, and real images for image/png|jpeg."""
+    parts: list[Any] = []
+    for o in outputs:
+        t = o.get("output_type")
+        if t == "stream":
+            parts.append(_clip(o["text"] if isinstance(o["text"], str) else "".join(o["text"])))
+        elif t == "error":
+            tb = _ANSI.sub("", "\n".join(o.get("traceback") or [])[-1500:])
+            parts.append(f"{o['ename']}: {o['evalue']}\n{tb}")
+        elif t in ("execute_result", "display_data"):
+            data = o.get("data", {})
+            for mime, fmt in (("image/png", "png"), ("image/jpeg", "jpeg")):
+                if mime in data:
+                    parts.append(Image(data=base64.b64decode(data[mime]), format=fmt))
+                    break
+            txt = data.get("text/plain")
+            if txt is not None and not any(isinstance(p, Image) for p in parts[-1:]):
+                parts.append(_clip("".join(txt) if isinstance(txt, list) else txt))
+    return parts or ["(no output)"]
+
+
+async def _done(ds: DocSession, **info) -> dict:
+    ok, detail = await ds.persisted()
+    return {**info, "persisted": ok, **({} if ok else {"warning": detail})}
+
+
+def _brief(c: dict, width: int = 160) -> dict:
+    src = c["source"]
+    c = {k: v for k, v in c.items() if k != "source"}
+    c["source"] = src if len(src) <= width else src[:width] + "…"
+    return c
+
+
+# ── instances / files ──────────────────────────────────────────────────────────────────────────────────────────
+
+@mcp.tool()
+async def list_instances() -> list[dict]:
+    """Running Jupyter servers of this user (found via Jupyter's runtime files, no setup needed)."""
+    return [i.public() for i in await discover()]
+
+
+@mcp.tool()
+async def list_notebooks(instance: str | None = None, subdir: str = "") -> list[str]:
+    """All .ipynb paths (relative to the server root) below `subdir`."""
+    inst = await resolve(instance)
+    rest = S.rest(inst)
+    out: list[str] = []
+
+    async def walk(d: str):
+        for e in (await rest.contents(d, content=True))["content"]:
+            if e["type"] == "directory" and not e["name"].startswith("."):
+                await walk(e["path"])
+            elif e["name"].endswith(".ipynb"):
+                out.append(e["path"])
+    await walk(subdir.strip("/"))
+    return sorted(out)
+
+
+# ── reading ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+@mcp.tool()
+async def read_notebook(path: str, instance: str | None = None, start: int = 0, end: int | None = None,
+                        full_source: bool = False) -> dict:
+    """Overview of cells (index, id, type, execution count/state, metadata, source, number of outputs)."""
+    ds = await _ds(instance, path)
+    doc = await ds.doc()
+    cells = (await ds.cells())[start:end]
+    return {"path": ds.path, "n_cells": doc.cell_number, "notebook_metadata": doc._ymeta["metadata"].to_py(),
+            "cells": cells if full_source else [_brief(c) for c in cells]}
+
+
+@mcp.tool()
+async def read_cell(path: str, cell: int | str, instance: str | None = None, include_outputs: bool = True) -> list[Any]:
+    """One cell with full source, metadata and (rendered, incl. images) outputs."""
+    ds = await _ds(instance, path)
+    c = await ds.cell(cell, outputs=include_outputs)
+    outs = c.pop("outputs", [])
+    return [c] + (render(outs) if include_outputs and outs else [])
+
+
+# ── editing ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+def _new_ycell(doc, cell_type: str, source: str, metadata: dict | None):
+    cell = {"cell_type": cell_type, "source": source, "metadata": metadata or {}, "id": uuid.uuid4().hex[:8]}
+    if cell_type == "code":
+        cell.update(outputs=[], execution_count=None)
+    return doc.create_ycell(cell)
+
+
+@mcp.tool()
+async def insert_cell(path: str, source: str, cell_type: str = "code", after: int | str | None = None,
+                      instance: str | None = None, metadata: dict | None = None) -> dict:
+    """Insert a cell after `after` (index or id); appends at the end if `after` is None (use insert_cell_at_start for the top).
+    Always pass cell_type='markdown' for prose; keep each heading in its own cell."""
+    if cell_type not in ("code", "markdown", "raw"):
+        raise DocError("cell_type must be code, markdown or raw")
+    ds = await _ds(instance, path)
+    async with ds.lock:
+        doc = await ds.doc()
+        pos = doc.cell_number if after is None else await ds.index(after) + 1
+        with doc._ydoc.transaction():
+            doc.ycells.insert(pos, _new_ycell(doc, cell_type, source, metadata))
+        return await _done(ds, index=pos, id=doc.ycells[pos].get("id"))
+
+
+RESPONSE_MARKER = "<!-- jcollab-response -->"
+
+
+@mcp.tool()
+async def find_mentions(path: str, instance: str | None = None) -> list[dict]:
+    """List cells containing "@claude" that are not answered yet (no response cell directly below).
+    Only look when the user asks; never answer mentions on your own initiative."""
+    ds = await _ds(instance, path)
+    doc = await ds.doc()
+    out, n = [], doc.cell_number
+    for i in range(n):
+        src = str(doc.ycells[i]["source"])
+        if "@claude" not in src or RESPONSE_MARKER in src:
+            continue
+        nxt = str(doc.ycells[i + 1]["source"]) if i + 1 < n else ""
+        if RESPONSE_MARKER in nxt:
+            continue
+        head = next((str(doc.ycells[j]["source"]).splitlines()[0] for j in range(i, -1, -1)
+                     if doc.ycells[j].get("cell_type") == "markdown" and str(doc.ycells[j]["source"]).startswith("#")), None)
+        out.append({"index": i, "id": doc.ycells[i].get("id"), "cell_type": doc.ycells[i].get("cell_type"),
+                    "heading_above": head, "source": src})
+    return out
+
+
+@mcp.tool()
+async def add_comment(path: str, after: int | str, response: str, instance: str | None = None) -> dict:
+    """Answer a mention: insert a markdown response cell (carrying the jcollab-response marker) below cell `after`."""
+    ds = await _ds(instance, path)
+    async with ds.lock:
+        doc = await ds.doc()
+        pos = await ds.index(after) + 1
+        with doc._ydoc.transaction():
+            doc.ycells.insert(pos, _new_ycell(doc, "markdown", f"{RESPONSE_MARKER}\n{response}", None))
+        return await _done(ds, index=pos, id=doc.ycells[pos].get("id"))
+
+
+@mcp.tool()
+async def insert_cell_at_start(path: str, source: str, cell_type: str = "markdown", instance: str | None = None) -> dict:
+    """Insert a cell as the first cell of the notebook."""
+    ds = await _ds(instance, path)
+    async with ds.lock:
+        doc = await ds.doc()
+        with doc._ydoc.transaction():
+            doc.ycells.insert(0, _new_ycell(doc, cell_type, source, None))
+        return await _done(ds, index=0, id=doc.ycells[0].get("id"))
+
+
+@mcp.tool()
+async def edit_cell(path: str, cell: int | str, source: str, instance: str | None = None) -> dict:
+    """Replace a cell's source with minimal text edits (open editors keep cursor/scroll). Does not change the cell type."""
+    ds = await _ds(instance, path)
+    async with ds.lock:
+        yc = await ds.ycell(cell)
+        with (await ds.doc())._ydoc.transaction():
+            set_text(yc["source"], source)
+        return await _done(ds, index=await ds.index(cell))
+
+
+@mcp.tool()
+async def change_cell_type(path: str, cell: int | str, cell_type: str, instance: str | None = None) -> dict:
+    """Convert a cell to code/markdown/raw (keeps id, source and metadata; drops outputs when leaving code)."""
+    ds = await _ds(instance, path)
+    async with ds.lock:
+        doc = await ds.doc()
+        i = await ds.index(cell)
+        old = doc.ycells[i]
+        new = _new_ycell(doc, cell_type, str(old["source"]), old["metadata"].to_py())
+        new["id"] = old.get("id")
+        with doc._ydoc.transaction():
+            del doc.ycells[i]
+            doc.ycells.insert(i, new)
+        return await _done(ds, index=i)
+
+
+@mcp.tool()
+async def delete_cell(path: str, cell: int | str, instance: str | None = None) -> dict:
+    ds = await _ds(instance, path)
+    async with ds.lock:
+        doc = await ds.doc()
+        i = await ds.index(cell)
+        with doc._ydoc.transaction():
+            del doc.ycells[i]
+        return await _done(ds, deleted=i)
+
+
+@mcp.tool()
+async def move_cell(path: str, cell: int | str, to: int, instance: str | None = None) -> dict:
+    """Move a cell so that it ends up at index `to` (counted after removal)."""
+    ds = await _ds(instance, path)
+    async with ds.lock:
+        doc = await ds.doc()
+        i = await ds.index(cell)
+        data = doc.get_cell(i)
+        with doc._ydoc.transaction():
+            del doc.ycells[i]
+            doc.ycells.insert(max(0, min(to, doc.cell_number)), doc.create_ycell(data))
+        return await _done(ds, moved_from=i, to=to)
+
+
+@mcp.tool()
+async def split_cell(path: str, cell: int | str, at_line: int, instance: str | None = None) -> dict:
+    """Split a cell before line number `at_line` (0-based); the second part becomes a new cell right after."""
+    ds = await _ds(instance, path)
+    async with ds.lock:
+        doc = await ds.doc()
+        i = await ds.index(cell)
+        yc = doc.ycells[i]
+        lines = str(yc["source"]).split("\n")
+        head, tail = "\n".join(lines[:at_line]), "\n".join(lines[at_line:])
+        with doc._ydoc.transaction():
+            set_text(yc["source"], head)
+            doc.ycells.insert(i + 1, _new_ycell(doc, yc["cell_type"], tail, yc["metadata"].to_py()))
+        return await _done(ds, first=i, second=i + 1)
+
+
+@mcp.tool()
+async def merge_cells(path: str, first: int | str, last: int | str, instance: str | None = None) -> dict:
+    """Merge cells first..last (inclusive) into the first one, joined by blank lines."""
+    ds = await _ds(instance, path)
+    async with ds.lock:
+        doc = await ds.doc()
+        a, b = await ds.index(first), await ds.index(last)
+        if b <= a:
+            raise DocError("last must be after first")
+        joined = "\n\n".join(str(doc.ycells[k]["source"]) for k in range(a, b + 1))
+        with doc._ydoc.transaction():
+            set_text(doc.ycells[a]["source"], joined)
+            for k in range(b, a, -1):
+                del doc.ycells[k]
+        return await _done(ds, merged_into=a)
+
+
+# ── metadata ───────────────────────────────────────────────────────────────────────────────────────────────────
+
+@mcp.tool()
+async def get_metadata(path: str, cell: int | str | None = None, key: str | None = None, instance: str | None = None) -> Any:
+    """Metadata of a cell (cell given) or of the notebook (cell=None, e.g. key='scenes_data'). Whole dict if key is None."""
+    ds = await _ds(instance, path)
+    doc = await ds.doc()
+    meta = doc._ymeta["metadata"].to_py() if cell is None else (await ds.cell(cell))["metadata"]
+    return meta if key is None else meta.get(key)
+
+
+@mcp.tool()
+async def set_metadata(path: str, key: str, value: Any = None, cell: int | str | None = None, delete: bool = False,
+                       instance: str | None = None) -> dict:
+    """Set (or delete) one metadata key on a cell (cell given) or the notebook (cell=None). Values are JSON."""
+    ds = await _ds(instance, path)
+    async with ds.lock:
+        doc = await ds.doc()
+        meta = doc._ymeta["metadata"] if cell is None else (await ds.ycell(cell))["metadata"]
+        with doc._ydoc.transaction():
+            if delete:
+                if key in meta:
+                    del meta[key]
+            else:
+                meta[key] = copy.deepcopy(value)
+        return await _done(ds, scope="notebook" if cell is None else f"cell {cell}", key=key, deleted=delete)
+
+
+# ── execution ──────────────────────────────────────────────────────────────────────────────────────────────────
+
+@mcp.tool()
+async def run_cell(path: str, cell: int | str, instance: str | None = None, timeout: float = 300) -> list[Any]:
+    """Run a code cell like the user would: shows [*] while busy, streams outputs, sets the kernel's execution count
+    and the execute-time timing metadata. Returns the outputs (images included)."""
+    ds = await _ds(instance, path)
+    r = await kernel.run_cell(ds, cell, timeout)
+    head = {k: v for k, v in r.items() if k != "outputs"}
+    head.update(await _done(ds))
+    return [head] + render(r["outputs"])
+
+
+@mcp.tool()
+async def run_cells(path: str, start: int | str, end: int | str, instance: str | None = None, timeout: float = 300,
+                    stop_on_error: bool = True) -> list[dict]:
+    """Run code cells start..end (inclusive) one after another. Returns one status line per cell (no outputs)."""
+    ds = await _ds(instance, path)
+    a, b = await ds.index(start), await ds.index(end)
+    res = []
+    for i in range(a, b + 1):
+        if (await ds.cell(i))["cell_type"] != "code":
+            continue
+        r = await kernel.run_cell(ds, i, timeout)
+        res.append({k: v for k, v in r.items() if k != "outputs"} | {"errors": [o["ename"] for o in r["outputs"] if o["output_type"] == "error"]})
+        if stop_on_error and (r["status"] != "ok" or r["timed_out"]):
+            break
+    return res
+
+
+@mcp.tool()
+async def run_code(path: str, code: str, instance: str | None = None, timeout: float = 60) -> list[Any]:
+    """Quick inspection in the notebook's kernel (variables, shapes, small checks). Not recorded in history, uses no
+    execution count, leaves the notebook untouched. Do NOT use for real computations; put those in a visible cell."""
+    ds = await _ds(instance, path)
+    r = await kernel.run_code(ds.rest, ds.path, code, timeout, await ds.doc())
+    return render(r["outputs"]) + (["[timed out, kernel interrupted]"] if r["timed_out"] else [])
+
+
+@mcp.tool()
+async def clear_outputs(path: str, cell: int | str | None = None, instance: str | None = None) -> dict:
+    """Clear outputs and execution count of one cell, or of all cells if `cell` is None."""
+    ds = await _ds(instance, path)
+    async with ds.lock:
+        doc = await ds.doc()
+        idx = range(doc.cell_number) if cell is None else [await ds.index(cell)]
+        with doc._ydoc.transaction():
+            for i in idx:
+                yc = doc.ycells[i]
+                if yc.get("cell_type") == "code":
+                    set_outputs(yc, [])
+                    yc["execution_count"] = None
+                    if "execution" in yc["metadata"]:
+                        del yc["metadata"]["execution"]
+        return await _done(ds, cleared=len(idx))
+
+
+@mcp.tool()
+async def inspect_variables(path: str, instance: str | None = None, pattern: str = "") -> list[Any]:
+    """Names, types and shapes of user variables in the kernel (silent, no history entry)."""
+    code = (
+        "import re as _re\n"
+        "_rows=[]\n"
+        "for _n,_v in list(globals().items()):\n"
+        "    if _n.startswith('_') or _n in ('In','Out','get_ipython','exit','quit'): continue\n"
+        f"    if not _re.search({pattern!r}, _n): continue\n"
+        "    if type(_v).__name__ in ('module','function','builtin_function_or_method','type'): continue\n"
+        "    _s=getattr(_v,'shape',None); _l=len(_v) if hasattr(_v,'__len__') else None\n"
+        "    _rows.append(f'{_n}: {type(_v).__name__}'+(f' shape={_s}' if _s is not None else (f' len={_l}' if _l is not None else f' = {_v!r:.60}')))\n"
+        "print('\\n'.join(_rows) or '(no user variables)')\n"
+        "del _re,_rows")
+    return await run_code(path, code, instance)
+
+
+# ── kernel ─────────────────────────────────────────────────────────────────────────────────────────────────────
+
+async def _kid(ds: DocSession) -> str:
+    s = await ds.rest.session_for(ds.path)
+    if not s:
+        raise kernel.KernelError(f"{ds.path} has no kernel session (run a cell first)")
+    return s["kernel"]["id"]
+
+
+@mcp.tool()
+async def kernel_status(path: str, instance: str | None = None) -> dict:
+    ds = await _ds(instance, path)
+    s = await ds.rest.session_for(ds.path)
+    if not s:
+        return {"kernel": None}
+    k = (await ds.rest.request("GET", f"api/kernels/{s['kernel']['id']}")).json()
+    return {"id": k["id"], "name": k["name"], "execution_state": k["execution_state"], "connections": k["connections"],
+            "last_activity": k["last_activity"]}
+
+
+@mcp.tool()
+async def interrupt_kernel(path: str, instance: str | None = None) -> str:
+    ds = await _ds(instance, path)
+    await ds.rest.kernel_action(await _kid(ds), "interrupt")
+    return "interrupted"
+
+
+@mcp.tool()
+async def restart_kernel(path: str, instance: str | None = None, run_all: bool = False, clear: bool = False,
+                         timeout: float = 300) -> Any:
+    """Restart the notebook's kernel (all in-memory state is lost). Optional: clear outputs first, run all cells after."""
+    ds = await _ds(instance, path)
+    if clear:
+        await clear_outputs(path, None, instance)
+    await ds.rest.kernel_action(await _kid(ds), "restart")
+    doc = await ds.doc()
+    with doc._ydoc.transaction():                      # a restart abandons whatever was running
+        for i in range(doc.cell_number):
+            if doc.ycells[i].get("execution_state") == "running":
+                doc.ycells[i]["execution_state"] = "idle"
+    if run_all:
+        return await run_cells(path, 0, -1, instance, timeout)
+    return "restarted"
+
+
+@mcp.tool()
+async def point_at(path: str, cell: int | str, seconds: float = 30, select: bool = True, instance: str | None = None,
+                   scroll: bool = True, force_scroll: bool = False, label: str | None = None) -> dict:
+    """Show the user which cell you mean: a labelled "Metis" selection appears in that cell in every open tab (and the
+    user can jump to it via JupyterLab's Collaborators sidebar). Still also name the cell in words (heading above it,
+    first line), the user may not have the notebook scrolled there. With the jcollab-scroll lab extension, the user's
+    notebook scrolls to the cell (a toast instead while they type elsewhere, unless force_scroll); label is shown in that toast."""
+    return await (await _ds(instance, path)).point_at(cell, seconds=seconds, select=select, scroll=scroll,
+                                                      force_scroll=force_scroll, label=label)
+
+
+@mcp.tool()
+async def user_focus(path: str, instance: str | None = None) -> list[dict]:
+    """Where the user is: for every open browser tab the cell (index + id) holding the cursor, line/column and the
+    selected text. Use this to resolve "this cell" / "the selected code" / "here". Empty if nobody has a cursor in the
+    notebook (the user must have clicked into a cell; cursors expire after ~30 s without activity)."""
+    return await (await _ds(instance, path)).user_focus()
+
+
+@mcp.tool()
+async def sync_health(path: str, instance: str | None = None) -> dict:
+    """Is the shared document alive? Connection state, peers (e.g. browser tabs), and whether the file matches."""
+    return await (await _ds(instance, path)).health()
+
+
+def main() -> None:
+    import logging
+    for n in ("httpx", "httpcore", "websockets", "jupyter_nbmodel_client"):
+        logging.getLogger(n).setLevel(logging.WARNING)
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

jcollab-0.1.0.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.5
+Name: jcollab
+Version: 0.1.0
+Summary: MCP server for live co-editing and running of JupyterLab notebooks (Yjs, verified writes, multi-instance discovery)
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: jupyter-core
+Requires-Dist: jupyter-nbmodel-client<2,>=1.5.1
+Requires-Dist: jupyter-ydoc<4,>=3.0
+Requires-Dist: mcp<3,>=2
+Requires-Dist: nbformat
+Requires-Dist: pycrdt<0.14,>=0.12.50
+Requires-Dist: websockets>=13

jcollab-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+jcollab/__init__.py,sha256=Jc1fuH5VdKyb1DjytZYAZzWqp2augtJH6xHL6zS6AVw,93
+jcollab/discovery.py,sha256=gDnbAlYOumjtvhpVOUHapoFByNUzslN5t7vp749_Aq0,4996
+jcollab/doc.py,sha256=Bnu7It3EWRQqtgy6YsjSGIWUWrTZrwGNmQbumUELunw,14916
+jcollab/kernel.py,sha256=U00M5pmm1UI5oOBOpP22Il_n5JOHaiHjqi9NrwuAKkA,9897
+jcollab/rest.py,sha256=-XorHuN-8iWo82zSinjsEXNXZ34UKXZTC-NKQAD4mMc,2293
+jcollab/server.py,sha256=giveriIKclwIBuBPqsxDrTZ6X_r4_It6eyFFNvWfX0k,22222
+jcollab-0.1.0.dist-info/METADATA,sha256=2C2jBid80EZxV1WX10MVtV2IavqVGxlT4OvOoeaOZ0o,479
+jcollab-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+jcollab-0.1.0.dist-info/entry_points.txt,sha256=h-5SuMaiVTElQLLUQ9ayftx-hi8iGTYycO1eucSPE2c,48
+jcollab-0.1.0.dist-info/RECORD,,

jcollab-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

jcollab-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jcollab = jcollab.server:main