mcp: add view module + sexy global polars HTML render (#777)

## What

A bundled `view` module + a global, gorgeous polars HTML render, so
agents stop hand-rolling `Result(user_html=...)` and stop shelling to
`ls`/`grep`/`cat`.

- **`view.ls/tree/grep/find` return plain `polars.DataFrame`s** → they
compose with the full polars API (`.filter()/.sort()/.join()`) *and*
render as a styled table.
- **`view.cat/read/head/tail/json/diff` return a `Code` view**:
pygments-highlighted HTML for the human, raw text as the agent's value
(no token cost for the HTML).
- **`01-ix-polars.py` installs `view.df_html` as the global
`pl.DataFrame._repr_html_`** so every frame (view's, the agent's, the
human's) gets the same dark, dtype-aware table and stays composable. The
agent's text/plain repr is untouched.
- Built on the bundled `fff`/`polars`/`pygments` (pygments newly added).
No bash.
- Advertised in the MCP server instructions so sessions discover it.

## Look

Flat dark Tokyo-night palette: dtype subheaders, zebra rows, orange
right-aligned tabular-num numerics, green strings, purple bools, muted
italic `null`. (Prototyped + screenshotted before building.)

## Validated

✅ `nix build .#mcp` · ✅ `.#mcp.tests.viewSmoke` (helpers + composability
+ df_html + Code views, cross-platform) · ✅ `nix run .#lint`

Empirically checked the high-risk areas: HTML **escaping** (a
`</td><script>` filename renders as `&lt;script&gt;`, XSS-safe), **empty
frames** (grep no-hits → "0 rows", sort guarded), **fff is sync**
(`grep`/`find`; async are `agrep`/`afind`), **no re-entrancy** (df_html
never re-renders; override lives in startup, not import), and a **safe
`df_html` fallback** (render failure → `<pre>`, never breaks display).

_Authored with Claude (Opus 4.8)._

Author: andrewgazelka

packages/mcp/default.nix

@@ -226,6 +226,26 @@ let
   # ctypes for the Accessibility (TCC) permission check. macOS-only: the module
   # itself raises on a non-Darwin platform, and `Quartz` is not available off
   # Darwin, so the dependency is gated below.
+  # Pretty, composable views of files and search results (view.ls/tree/grep/find
+  # return polars DataFrames; view.cat/json/diff return highlighted Code). Pure
+  # Python over the bundled fff/polars/pygments; cross-platform, so every session
+  # can `import view`.
+  viewPythonSource = builtins.path {
+    name = "ix-mcp-view-python-source";
+    path = ./src/view;
+  };
+  viewModule = pkgs.python3.pkgs.toPythonModule (
+    pkgs.runCommand "ix-mcp-view-python-module"
+      {
+        strictDeps = true;
+        meta.description = "Pretty composable file/search views bundled into the ix-mcp interpreter";
+      }
+      ''
+        site="$out/${pkgs.python3.sitePackages}/view"
+        mkdir -p "$site"
+        cp -r ${viewPythonSource}/view/. "$site/"
+      ''
+  );
   screenPythonSource = builtins.path {
     name = "ix-mcp-screen-python-source";
     path = ./src/screen;
@@ -335,6 +355,8 @@ let
       # capturable out of the box: the worker renders any open figure / object
       # with a `_repr_png_` back as an MCP image block.
       ps.matplotlib
+      # pygments: syntax highlighting for `view`'s Code views (cat/json/diff).
+      ps.pygments
       # playwright for browser automation out of the box. The Nix python package
       # is patched to use `playwright-driver` as its node driver, and the wrapper
       # below points PLAYWRIGHT_BROWSERS_PATH at the matching browser bundle, so
@@ -362,6 +384,7 @@ let
       googleAuthModule
       ixGoogleModule
       ixNotebookMcpModule
+      viewModule
     ]
     ++ darwinExtraPackages ps
   );
@@ -897,6 +920,70 @@ let
         mkdir -p "$out"
       '';
 
+  # The view module: tabular helpers return plain polars DataFrames (so they stay
+  # composable), the file helpers return a Code view whose repr is the raw text,
+  # and df_html renders the styled table the kernel installs globally. Pure local
+  # FS over the bundled fff/polars/pygments, so the sandbox runs it.
+  viewTestPy = pkgs.writeText "ix-mcp-view-test.py" ''
+    import polars as pl
+
+    import view
+
+    base = "${./.}"
+
+    lsdf = view.ls(base)
+    assert isinstance(lsdf, pl.DataFrame) and "kind" in lsdf.columns, lsdf.columns
+    # A DataFrame stays a DataFrame through polars ops (composable).
+    assert isinstance(lsdf.filter(pl.col("kind") == "dir"), pl.DataFrame)
+
+    g = view.grep("viewTestPy", base)
+    assert isinstance(g, pl.DataFrame) and set(g.columns) == {"path", "line", "text"}, g.columns
+    assert g.height > 0, "expected a grep hit for the marker"
+
+    f = view.find("default.nix", base)
+    assert isinstance(f, pl.DataFrame) and "path" in f.columns
+
+    tr = view.tree(base, depth=1)
+    assert isinstance(tr, pl.DataFrame) and "depth" in tr.columns
+
+    out = view.df_html(lsdf)
+    assert "<table" in out and "rows" in out and "tabular-nums" in out, out[:120]
+
+    c = view.cat(base + "/default.nix", lines=(1, 3))
+    assert isinstance(c, view.Code)
+    assert repr(c).count("\n") <= 3
+    assert "span" in c._repr_html_().lower()
+
+    j = view.json({"a": [1, 2], "b": None})
+    assert '"a"' in repr(j) and "span" in j._repr_html_().lower()
+
+    d = view.diff("x\ny\n", "x\nz\n")
+    assert "-y" in repr(d) and "+z" in repr(d)
+
+    print("view-ok")
+  '';
+  viewSmoke =
+    pkgs.runCommand "ix-mcp-view-smoke"
+      {
+        nativeBuildInputs = [ mcpPython ];
+        strictDeps = true;
+      }
+      ''
+        export HOME=$TMPDIR/home
+        mkdir -p "$HOME"
+        ${lib.getExe mcpPython} ${viewTestPy} >stdout 2>stderr || {
+          echo "ix-mcp view smoke failed:" >&2
+          cat stdout stderr >&2
+          exit 1
+        }
+        grep -qx 'view-ok' stdout || {
+          echo "ix-mcp view smoke did not confirm the view module:" >&2
+          cat stdout stderr >&2
+          exit 1
+        }
+        mkdir -p "$out"
+      '';
+
   # macOS-only modules (`screen`, `vmkit`) are only bundled on Darwin; their
   # import tests only exist there.
   screenBundled = importTest "screen" "import screen; print('screen-ok', callable(screen.capture), callable(screen.click), callable(screen.accessibility_trusted))";
@@ -920,6 +1007,7 @@ package.overrideAttrs (old: {
         runtimeSmoke
         richSmoke
         bindDefaultSmoke
+        viewSmoke
         ;
     }
     // lib.optionalAttrs pkgs.stdenv.hostPlatform.isDarwin {

packages/mcp/ix_notebook_mcp/ipython/01-ix-polars.py

@@ -14,3 +14,17 @@
 pl.Config.set_tbl_cols(40)
 pl.Config.set_fmt_str_lengths(80)
 pl.Config.set_tbl_width_chars(160)
+
+# The dashboard renders a DataFrame from its ``text/html`` repr; install the
+# `view` module's styled renderer globally so every DataFrame (a ``view`` result,
+# the agent's own, the human's) shows the same dark, dtype-aware table while
+# staying a plain DataFrame that composes with the polars API. The text/plain
+# repr above is untouched, so this never changes what the agent reads.
+try:
+    import view
+
+    pl.DataFrame._repr_html_ = lambda self: view.df_html(self)
+except Exception:
+    # `view` should always be bundled; if it is not, fall back to polars' default
+    # HTML repr rather than breaking startup.
+    pass

packages/mcp/ix_notebook_mcp/tools.py

@@ -37,8 +37,13 @@
         "once and none blocks the others; for a blocking call (fff, a heavy numpy "
         "op, a subprocess) wrap it in `await asyncio.to_thread(...)` so it stays "
         "off the event loop. Bundled modules import with no install step: `fff` "
-        "(async file search/grep), `tui`, `search`, `exa_py`, `google_auth`, "
-        "numpy, polars, duckdb, httpx, matplotlib, playwright. Use polars (`pl`) "
+        "(async file search/grep), `view`, `tui`, `search`, `exa_py`, "
+        "`google_auth`, numpy, polars, duckdb, httpx, matplotlib, playwright. "
+        "Prefer these over shelling out: `view.ls/tree/grep/find` return "
+        "polars DataFrames (composable + a styled HTML table) and "
+        "`view.cat/read/head/json/diff` return a syntax-highlighted view, so "
+        "you never hand-roll display HTML or run `ls`/`grep`/`cat` in bash. "
+        "Use polars (`pl`) "
         "for dataframes; pandas is not bundled. End a cell with a bare expression "
         "to display its result richly: a polars DataFrame renders as an HTML table "
         "and a matplotlib figure as an image, both in this reply and on the "