notebook-mcp 0.1.0__tar.gz

notebook_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

notebook_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: notebook-mcp
+Version: 0.1.0
+Summary: MCP server that provides notebook-aware context and analysis for .ipynb files
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/your-org/notebook-mcp
+Project-URL: Repository, https://github.com/your-org/notebook-mcp
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: nbformat>=5.10.4
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: networkx>=3.3
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: build>=1.2.1; extra == "dev"
+Requires-Dist: twine>=5.1.0; extra == "dev"
+Dynamic: license-file
+
+# notebook-mcp
+
+MCP server that provides notebook-aware context and analysis for `.ipynb` files.
+
+## Features
+
+- Offline notebook analysis (no kernel required)
+  - Strip outputs (optional)
+  - Stable cell indexing
+  - AST-based `defines` / `uses`
+  - Best-effort dependency graph
+  - Focused context slicing for a target cell
+  - Export notebook to a deterministic Python script (best-effort)
+
+- Optional Jupyter Server adapter (HTTP)
+  - List active sessions
+  - Inspect kernel metadata
+
+## Install (dev)
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Distribution
+
+### Publish Python package (PyPI)
+
+1. Build:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m build
+```
+
+2. Upload:
+
+```bash
+python -m twine upload dist/*
+```
+
+### Publish NPM wrapper
+
+The Node wrapper lives in `npm/` and publishes as a scoped package.
+
+```bash
+cd npm
+npm publish --access public
+```
+
+## Run (stdio transport; best for IDE agents)
+
+```bash
+notebook-mcp
+```
+
+## Run (streamable HTTP transport)
+
+```bash
+set MCP_TRANSPORT=streamable-http
+set MCP_HOST=127.0.0.1
+set MCP_PORT=8000
+notebook-mcp
+```
+
+## Jupyter Server adapter
+
+Set env vars:
+
+- `JUPYTER_BASE_URL` e.g. `http://127.0.0.1:8888`
+- `JUPYTER_TOKEN` (if required)
+
+## Notes
+
+- Dependency graph and stale detection are best-effort offline. Truthful execution/runtime state requires kernel messaging.

notebook_mcp-0.1.0/README.md

@@ -0,0 +1,75 @@
+# notebook-mcp
+
+MCP server that provides notebook-aware context and analysis for `.ipynb` files.
+
+## Features
+
+- Offline notebook analysis (no kernel required)
+  - Strip outputs (optional)
+  - Stable cell indexing
+  - AST-based `defines` / `uses`
+  - Best-effort dependency graph
+  - Focused context slicing for a target cell
+  - Export notebook to a deterministic Python script (best-effort)
+
+- Optional Jupyter Server adapter (HTTP)
+  - List active sessions
+  - Inspect kernel metadata
+
+## Install (dev)
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Distribution
+
+### Publish Python package (PyPI)
+
+1. Build:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m build
+```
+
+2. Upload:
+
+```bash
+python -m twine upload dist/*
+```
+
+### Publish NPM wrapper
+
+The Node wrapper lives in `npm/` and publishes as a scoped package.
+
+```bash
+cd npm
+npm publish --access public
+```
+
+## Run (stdio transport; best for IDE agents)
+
+```bash
+notebook-mcp
+```
+
+## Run (streamable HTTP transport)
+
+```bash
+set MCP_TRANSPORT=streamable-http
+set MCP_HOST=127.0.0.1
+set MCP_PORT=8000
+notebook-mcp
+```
+
+## Jupyter Server adapter
+
+Set env vars:
+
+- `JUPYTER_BASE_URL` e.g. `http://127.0.0.1:8888`
+- `JUPYTER_TOKEN` (if required)
+
+## Notes
+
+- Dependency graph and stale detection are best-effort offline. Truthful execution/runtime state requires kernel messaging.

notebook_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "notebook-mcp"
+version = "0.1.0"
+description = "MCP server that provides notebook-aware context and analysis for .ipynb files"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+  "mcp>=1.0.0",
+  "nbformat>=5.10.4",
+  "pydantic>=2.7.0",
+  "httpx>=0.27.0",
+  "networkx>=3.3",
+  "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.2.0",
+  "ruff>=0.5.0",
+  "build>=1.2.1",
+  "twine>=5.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/your-org/notebook-mcp"
+Repository = "https://github.com/your-org/notebook-mcp"
+
+[project.scripts]
+notebook-mcp = "notebook_mcp.server:main"
+
+[build-system]
+requires = ["setuptools>=69.0.0", "wheel>=0.42.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+pythonpath = ["src"]

notebook_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

notebook_mcp-0.1.0/src/notebook_mcp/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

notebook_mcp-0.1.0/src/notebook_mcp/analyzer.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal
+
+from .ast_analysis import summarize_python_source
+from .context_builder import format_cells_as_context
+from .dependency_graph import build_dependency_edges, topo_sort_cells, upstream_slice
+from .errors import CellNotFoundError
+from .models import FocusedContext, NotebookAnalysis, NotebookCell
+from .notebook_io import load_notebook, strip_outputs_inplace
+from .utils import normalize_newlines, sha256_text
+
+
+def _cell_id(cell: dict, index: int) -> str:
+    # Jupyter notebooks may include a stable 'id' field (nbformat 4.5+).
+    cid = cell.get("id")
+    if isinstance(cid, str) and cid.strip():
+        return cid
+    return f"cell_{index}"  # stable fallback
+
+
+def analyze_notebook(
+    path: str,
+    *,
+    include_markdown: bool = True,
+    strip_outputs: bool = True,
+    cell_types: tuple[str, ...] = ("code", "markdown"),
+) -> NotebookAnalysis:
+    mtime = os.path.getmtime(path)
+    return _analyze_notebook_cached(
+        path,
+        mtime,
+        include_markdown=include_markdown,
+        strip_outputs=strip_outputs,
+        cell_types=cell_types,
+    )
+
+
+@lru_cache(maxsize=32)
+def _analyze_notebook_cached(
+    path: str,
+    mtime: float,
+    *,
+    include_markdown: bool,
+    strip_outputs: bool,
+    cell_types: tuple[str, ...],
+) -> NotebookAnalysis:
+    nb = load_notebook(path)
+    if strip_outputs:
+        strip_outputs_inplace(nb)
+
+    out_cells: list[NotebookCell] = []
+
+    for i, cell in enumerate(nb.get("cells", [])):
+        ctype = cell.get("cell_type")
+        if ctype not in cell_types:
+            continue
+        if ctype == "markdown" and not include_markdown:
+            continue
+
+        source = normalize_newlines(cell.get("source") or "")
+        h = sha256_text(source)
+
+        defines: list[str] = []
+        uses: list[str] = []
+        imports: list[str] = []
+
+        if ctype == "code":
+            s = summarize_python_source(source)
+            defines = sorted(s.defines)
+            uses = sorted(s.uses)
+            imports = sorted(s.imports)
+
+        out_cells.append(
+            NotebookCell(
+                cell_id=_cell_id(cell, i),
+                index=i,
+                cell_type=ctype,
+                source=source,
+                execution_count=cell.get("execution_count"),
+                source_hash=h,
+                defines=defines,
+                uses=uses,
+                imports=imports,
+            )
+        )
+
+    edges = build_dependency_edges(out_cells)
+
+    return NotebookAnalysis(
+        path=str(Path(path)),
+        nbformat=int(nb.get("nbformat", 4)),
+        nbformat_minor=int(nb.get("nbformat_minor", 0)),
+        cells=out_cells,
+        dependency_edges=edges,
+    )
+
+
+def get_focused_context(
+    path: str,
+    *,
+    focus_cell_id: str,
+    max_cells: int = 25,
+    include_markdown: bool = True,
+) -> FocusedContext:
+    analysis = analyze_notebook(path, include_markdown=include_markdown)
+    if focus_cell_id not in {c.cell_id for c in analysis.cells}:
+        raise CellNotFoundError(f"Cell not found: {focus_cell_id}")
+
+    selected_ids = upstream_slice(focus_cell_id, analysis.dependency_edges, max_cells=max_cells)
+
+    cell_by_id = {c.cell_id: c for c in analysis.cells}
+    selected_cells = [cell_by_id[cid] for cid in selected_ids if cid in cell_by_id]
+
+    # Make output readable: topo order within selected cells when possible.
+    selected_edges = [(a, b) for (a, b) in analysis.dependency_edges if a in selected_ids and b in selected_ids]
+    selected_cells = topo_sort_cells(selected_cells, selected_edges)
+
+    context_text = format_cells_as_context(selected_cells)
+
+    return FocusedContext(
+        path=analysis.path,
+        focus_cell_id=focus_cell_id,
+        selected_cell_ids=[c.cell_id for c in selected_cells],
+        context_text=context_text,
+    )
+
+
+def export_notebook_to_script(
+    path: str,
+    *,
+    include_markdown_as_comments: bool = False,
+) -> str:
+    analysis = analyze_notebook(path, include_markdown=True, strip_outputs=True)
+
+    code_cells: list[NotebookCell] = []
+    for c in analysis.cells:
+        if c.cell_type == "code":
+            code_cells.append(c)
+        elif c.cell_type == "markdown" and include_markdown_as_comments:
+            # Keep markdown as a docstring-ish block to preserve narrative.
+            code_cells.append(
+                c.model_copy(update={"cell_type": "code", "source": f"\n\"\"\"\n{c.source}\n\"\"\"\n"})
+            )
+
+    ordered = topo_sort_cells(code_cells, analysis.dependency_edges)
+
+    parts: list[str] = []
+    parts.append(f"# Generated from notebook: {analysis.path}\n")
+
+    for c in ordered:
+        parts.append(f"# --- cell: {c.cell_id} (index={c.index}) ---")
+        parts.append(c.source.rstrip())
+        parts.append("")
+
+    return "\n".join(parts).strip() + "\n"

notebook_mcp-0.1.0/src/notebook_mcp/ast_analysis.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AstSummary:
+    defines: set[str]
+    uses: set[str]
+    imports: set[str]
+
+
+class _Analyzer(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.defines: set[str] = set()
+        self.uses: set[str] = set()
+        self.imports: set[str] = set()
+
+    def visit_Import(self, node: ast.Import) -> None:  # noqa: N802
+        for alias in node.names:
+            name = alias.asname or alias.name.split(".")[0]
+            self.defines.add(name)
+            self.imports.add(alias.name)
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:  # noqa: N802
+        mod = node.module or ""
+        for alias in node.names:
+            if alias.name == "*":
+                continue
+            name = alias.asname or alias.name
+            self.defines.add(name)
+            self.imports.add(f"{mod}:{alias.name}" if mod else alias.name)
+        self.generic_visit(node)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:  # noqa: N802
+        self.defines.add(node.name)
+        self.generic_visit(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:  # noqa: N802
+        self.defines.add(node.name)
+        self.generic_visit(node)
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:  # noqa: N802
+        self.defines.add(node.name)
+        self.generic_visit(node)
+
+    def visit_Name(self, node: ast.Name) -> None:  # noqa: N802
+        if isinstance(node.ctx, ast.Store):
+            self.defines.add(node.id)
+        elif isinstance(node.ctx, ast.Load):
+            self.uses.add(node.id)
+        self.generic_visit(node)
+
+    def visit_arg(self, node: ast.arg) -> None:  # noqa: N802
+        # Treat function args as local defines.
+        self.defines.add(node.arg)
+        self.generic_visit(node)
+
+
+def summarize_python_source(source: str) -> AstSummary:
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return AstSummary(defines=set(), uses=set(), imports=set())
+
+    a = _Analyzer()
+    a.visit(tree)
+
+    # If a name is defined, don't treat it as a dependency use.
+    uses = a.uses - a.defines
+
+    return AstSummary(defines=a.defines, uses=uses, imports=a.imports)

notebook_mcp-0.1.0/src/notebook_mcp/context_builder.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from .models import NotebookCell
+
+
+def format_cells_as_context(cells: list[NotebookCell]) -> str:
+    parts: list[str] = []
+    for c in cells:
+        header = f"# --- cell: {c.cell_id} (index={c.index}, type={c.cell_type}, exec={c.execution_count}) ---"
+        parts.append(header)
+        if c.cell_type == "markdown":
+            parts.append(c.source)
+        else:
+            parts.append(f"```python\n{c.source}\n```")
+        parts.append("")
+
+    return "\n".join(parts).strip() + "\n"

notebook_mcp-0.1.0/src/notebook_mcp/dependency_graph.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from collections import defaultdict
+
+import networkx as nx
+
+from .models import NotebookCell
+
+
+def build_dependency_edges(cells: list[NotebookCell]) -> list[tuple[str, str]]:
+    last_def: dict[str, str] = {}
+    edges: set[tuple[str, str]] = set()
+
+    for cell in cells:
+        for sym in cell.uses:
+            src = last_def.get(sym)
+            if src and src != cell.cell_id:
+                edges.add((src, cell.cell_id))
+
+        for sym in cell.defines:
+            last_def[sym] = cell.cell_id
+
+    return sorted(edges)
+
+
+def topo_sort_cells(cells: list[NotebookCell], edges: list[tuple[str, str]]) -> list[NotebookCell]:
+    g = nx.DiGraph()
+    for c in cells:
+        g.add_node(c.cell_id)
+    g.add_edges_from(edges)
+
+    try:
+        order = list(nx.topological_sort(g))
+    except nx.NetworkXUnfeasible:
+        # Cycles are common; fall back to file order.
+        return cells
+
+    index = {c.cell_id: i for i, c in enumerate(cells)}
+    order = sorted(order, key=lambda cid: index.get(cid, 10**9))
+
+    cell_by_id = {c.cell_id: c for c in cells}
+    return [cell_by_id[cid] for cid in order if cid in cell_by_id]
+
+
+def upstream_slice(
+    focus_cell_id: str,
+    edges: list[tuple[str, str]],
+    max_cells: int,
+) -> list[str]:
+    preds: dict[str, set[str]] = defaultdict(set)
+    for a, b in edges:
+        preds[b].add(a)
+
+    selected: list[str] = []
+    seen: set[str] = set()
+    stack: list[str] = [focus_cell_id]
+
+    while stack and len(selected) < max_cells:
+        cid = stack.pop()
+        if cid in seen:
+            continue
+        seen.add(cid)
+        selected.append(cid)
+
+        for p in sorted(preds.get(cid, set())):
+            if p not in seen:
+                stack.append(p)
+
+    # Put focus cell last to read naturally.
+    if focus_cell_id in selected:
+        selected.remove(focus_cell_id)
+        selected.append(focus_cell_id)
+
+    return selected

notebook_mcp-0.1.0/src/notebook_mcp/errors.py

@@ -0,0 +1,18 @@
+class NotebookMcpError(Exception):
+    pass
+
+
+class NotebookNotFoundError(NotebookMcpError):
+    pass
+
+
+class NotebookParseError(NotebookMcpError):
+    pass
+
+
+class CellNotFoundError(NotebookMcpError):
+    pass
+
+
+class JupyterServerError(NotebookMcpError):
+    pass

notebook_mcp-0.1.0/src/notebook_mcp/jupyter_server.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .errors import JupyterServerError
+from .models import JupyterKernel, JupyterSession
+
+
+class JupyterServerClient:
+    def __init__(self, base_url: str, token: str | None = None, timeout_s: float = 10.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self._client = httpx.Client(timeout=timeout_s)
+
+    def _headers(self) -> dict[str, str]:
+        if not self.token:
+            return {}
+        return {"Authorization": f"token {self.token}"}
+
+    def _get(self, path: str) -> Any:
+        url = f"{self.base_url}{path}"
+        try:
+            r = self._client.get(url, headers=self._headers())
+            r.raise_for_status()
+            return r.json()
+        except Exception as e:  # noqa: BLE001
+            raise JupyterServerError(f"Jupyter request failed: GET {url}") from e
+
+    def list_sessions(self) -> list[JupyterSession]:
+        data = self._get("/api/sessions")
+        out: list[JupyterSession] = []
+        for s in data:
+            kernel = s.get("kernel") or {}
+            out.append(
+                JupyterSession(
+                    id=str(s.get("id") or ""),
+                    path=s.get("path"),
+                    name=s.get("name"),
+                    type=s.get("type"),
+                    kernel_id=kernel.get("id"),
+                    raw=s,
+                )
+            )
+        return out
+
+    def get_kernel(self, kernel_id: str) -> JupyterKernel:
+        k = self._get(f"/api/kernels/{kernel_id}")
+        return JupyterKernel(
+            id=str(k.get("id") or kernel_id),
+            name=k.get("name"),
+            last_activity=k.get("last_activity"),
+            execution_state=k.get("execution_state"),
+            connections=k.get("connections"),
+            raw=k,
+        )
+
+    def close(self) -> None:
+        self._client.close()