stata-code 0.4.0__tar.gz → 0.6.0__tar.gz

{stata_code-0.4.0 → stata_code-0.6.0}/.gitignore

@@ -223,3 +223,16 @@ log-files/
 *.smcl
 *.dta
 !tests/fixtures/*.dta
+
+# macOS
+.DS_Store
+**/.DS_Store
+
+# VS Code workspace settings (contain user-machine absolute paths)
+.vscode/
+
+# Claude Code scratch (worktrees, transcripts)
+.claude/
+
+# Demo / scratch notebooks (real tests live under tests/)
+demo-tests/*.ipynb

{stata_code-0.4.0 → stata_code-0.6.0}/CHANGELOG.md

@@ -4,6 +4,152 @@ All notable changes to `stata-code` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project adheres
 to semver-major.minor for the result schema (see `SCHEMA.md` §6).
 
+## Unreleased
+
+## [0.6.0] — 2026-05-08
+
+### Added
+
+- **Notebook navigation tools.** New MCP tools `notebook_outline` and
+  `notebook_get_cell` let agents inspect a `.ipynb` without pulling the whole
+  file into context. `notebook_outline` returns a per-cell index (cell id,
+  type, source preview, line/char counts, execution_count, has-error flag);
+  `notebook_get_cell` returns one cell's full source plus a token-economic
+  outputs summary (head/tail of stream/text outputs, error ename/evalue,
+  truncated traceback, image presence flag). Cell identity follows nbformat
+  4.5+; pre-4.5 cells get a synthesised `synth-<index>-<hash>` id flagged via
+  `id_synthesized`. Read-only.
+- **Notebook search.** `notebook_locate` finds cells by literal `snippet`
+  (whitespace-tolerant fallback), `regex` (Python regex, multiline), or
+  pasted `error_text` (longest code-like line is used as a fingerprint).
+  Returns ranked candidates with `cell_id`, `line_in_cell`, and a small
+  preview. Read-only.
+- **Atomic notebook edits.** New `notebook_edit_cell`,
+  `notebook_insert_cell`, and `notebook_delete_cell` mutate cells via a
+  temp-file + `os.replace` write so the on-disk `.ipynb` is never partially
+  written. Edits preserve `cell.id` and metadata; for code cells they clear
+  outputs and `execution_count`. Optional `expected_source` is an
+  optimistic-concurrency guard that fails with `edit_source_drift` /
+  `delete_source_drift` if the user changed the cell between the agent's
+  read and write. Insertion against a pre-4.5 synth id auto-upgrades the
+  anchor to a real UUID so its id stays valid after the index shift.
+- **Origin echo on `RunResult`.** New optional `origin_cell_id` input
+  joins the existing `origin_path` / `origin_kind` / `origin_label` and
+  is round-tripped on `result.origin` plus the run-bundle manifest. The
+  execution path stays cell-agnostic: the runner does not interpret these
+  fields, only forwards them, so agents can correlate `stata_run` calls
+  with notebook cells without the protocol becoming notebook-aware.
+- **Run-bundle index.** New MCP tool `list_runs` queries the on-disk
+  `manifest.json` files written by `persist_log_files=true` runs. Filters
+  compose: `cell_id`, `origin_path`, `session_id`, `ok`, `since` (ISO 8601
+  UTC, lexicographic compare, inclusive). Returns newest-first compact
+  summaries with `directory`, `manifest_path`, and `log_path` so callers
+  read the full manifest from disk if needed. Read-only.
+- **Notebook MCP prompts.** New `run_notebook_cell_and_report` and
+  `fix_and_rerun_notebook_cell` prompts wire the per-cell repair recipe
+  (read → run with `origin_cell_id` → on failure, edit with
+  `expected_source` guard → rerun → recommend kernel restart after the
+  retry budget is exhausted) so users can `/mcp prompts` it directly.
+- **Capability advertising.** `stata_info.capabilities` now lists
+  `notebook_navigation`, `notebook_search`, `notebook_edit`, `run_index`,
+  and `origin_echo` so clients can feature-detect the Phase 1-3 surface.
+- **Schema-level mutex constraints.** `notebook_locate` and
+  `notebook_insert_cell` inputSchemas now use `oneOf` to express the
+  "exactly one of snippet / regex / error_text" and "exactly one anchor"
+  rules so strict MCP clients catch them before dispatch.
+- **VSCode language layer.** The extension now ships Stata TextMate syntax
+  highlighting and language configuration, plus an Outline provider for
+  `**#` hierarchical sections and `program define` blocks.
+- **VSCode section ergonomics.** `Stata: Run Current Section`,
+  `Cmd/Ctrl+Shift+Enter`, and `▶ Run Section` code lenses run from the
+  current heading to the next equal/higher heading. Existing `Cmd/Ctrl+Enter`
+  also runs a section when the cursor is on a section heading.
+- **VSCode editing aids.** Added Stata command/function/variable completion,
+  configured custom command completions, conservative F2 variable rename
+  (skips line/block comments, string literals, and ``` `macro' ``` references),
+  `Stata: Open Help for Selection`, and `Stata: Insert Line Continuation`
+  for `///` blocks.
+- **Runtime discovery.** `pystata` discovery now honors
+  `STATA_CODE_PYSTATA_PATH`, `PYSTATA_PATH`, `STATA_HOME`, `STATA_PATH`,
+  and `STATA_CLI`, and includes Stata 19 / StataNow default locations.
+- **Capability advertising.** `stata_info` now lists `subprocess_timeout`
+  alongside the existing capability strings so clients can detect that the
+  server isolates Stata in a worker process and enforces hard wall-clock
+  timeouts.
+- **Agent-native MCP surface.** The MCP server now advertises tool
+  `outputSchema` metadata, returns `structuredContent` alongside JSON text for
+  compatibility, exposes RunResult/log/graph/matrix/session resources, and
+  ships workflow prompts for validation, debugging, repair loops, replication
+  audits, and estimation summaries.
+
+### Changed
+
+- **`stata_info` payload is richer.** It now returns a nested `stata`
+  object with version/edition/backend plus the supported capabilities list,
+  while retaining the older flat aliases for compatibility. Operational
+  failures (worker timeout / crash) now report `available: false` together
+  with an `error` field so callers can tell them apart from genuine
+  "Stata not installed".
+- **Jupyter completions inspect live context.** The kernel now completes
+  variables from the last result's dataset and `do_inspect` reports variable
+  type/label metadata when available.
+- **`_summarise_outputs` is now streaming.** A cell with many large stream
+  outputs no longer materialises the full concatenation in memory before
+  truncating to 4 KB; we accumulate `text_chars_total` as we go but stop
+  appending to `text_preview` once the budget is hit.
+
+### Fixed
+
+- **`_pool._utc_iso_ms` race across the second boundary.** The fallback
+  pool helper that builds `started_at` for synthetic timeout / crash
+  results called `datetime.now()` twice; if the two calls straddled a
+  second boundary it could produce timestamps like `T23:59:59.000Z`
+  (correct seconds, wrong milliseconds) and silently break lexicographic
+  compare in `list_runs`'s `since` filter. Captured `now` once.
+- **`limit=True` accepted as `limit=1` in `list_runs`.** Python booleans
+  are a subclass of `int`; the `isinstance(limit, int)` check was passing
+  through `True` / `False`. Both `list_runs` and the MCP dispatcher now
+  reject `bool` explicitly with `limit_invalid`.
+
+## [0.5.0] — 2026-05-08
+
+### Added
+
+- **Bundled Jupyter kernel logos.** `stata-code-kernel install --user`
+  now copies `stata_code/kernel/assets/{logo-32x32.png,logo-64x64.png,
+  logo-svg.svg}` into the kernelspec source dir before
+  `KernelSpecManager().install_kernel_spec` runs. VS Code's Jupyter
+  extension filters out kernelspecs that lack logo files, so prior
+  releases were invisible in its kernel picker; v0.5 fixes that without
+  affecting JupyterLab or classic Jupyter (which both already worked).
+- **TestPyPI publishing step in `release.yml`.** Tag `v*` now publishes
+  to TestPyPI (via OIDC trusted publishing, environment `testpypi`)
+  before publishing to PyPI proper. `continue-on-error: true` keeps
+  PyPI + GitHub Release on the happy path even when TestPyPI is
+  misconfigured. Setup mirrors the PyPI trusted publisher and is
+  documented in [CLAUDE.md](CLAUDE.md).
+
+### Changed
+
+- **`stata_run` tool description and README** clarify the boundary
+  between non-mutating execution and the optional agent "fix and
+  rerun" repair loop. The tool itself never rewrites your `.do` file
+  — but the submitted Stata code can still produce logs, graphs, and
+  output files as usual. Repair loops require explicit user opt-in;
+  failed runs are diagnostics first, not automatic rewrite permission.
+- **VSCode MCP-client handshake version aligned to 0.5.0** (was a
+  stale 0.3.2 since the v0.3.2 release).
+
+### Fixed
+
+- **`install_kernel` no longer `.resolve()`s `sys.executable`.** On
+  macOS Homebrew venvs (and other layouts that use a `python` symlink
+  outside the venv's `bin/` to a Cellar-style real interpreter),
+  resolving the symlink pointed Jupyter at an interpreter that
+  couldn't import `stata_code`. The kernelspec now keeps the
+  unresolved `sys.executable`, so the venv's `python` (with
+  `stata_code` on its `sys.path`) launches the kernel.
+
 ## [0.4.0] — 2026-05-07
 
 ### Added

{stata_code-0.4.0 → stata_code-0.6.0}/LICENSE-POLICY.md

@@ -35,10 +35,11 @@ MIT, BSD, Apache 2.0, ISC. Reading source is allowed; copying must follow the li
 
 - `kylebarron/stata-enhanced` — MIT (TextMate grammar; we do not reuse it).
 - `kylebarron/stata-exec` — MIT (Atom; not reused).
-- `kylebarron/language-stata` — MIT (Atom grammar; not reused).
+- `kylebarron/language-stata` / Stata Enhanced grammar lineage — MIT (bundled in the VS Code extension with notice).
 - `hanlulong/stata-mcp` — MIT (we do not consult its source; see §4).
-- `lbraglia/RStata` — design reference only.
 - `euglevi/stata-language-server` — MIT.
+- `ZihaoVistonWang/stata-outline` — MIT.
+- `ZihaoVistonWang/stata-all-in-one` — MIT; incorporates Stata Enhanced grammar under MIT.
 
 ### 2.3 Copyleft projects (source code forbidden)
 
@@ -49,6 +50,7 @@ MIT, BSD, Apache 2.0, ISC. Reading source is allowed; copying must follow the li
 - `tmonk/stata-workbench` — AGPL-3.0
 - `kylebarron/stata_kernel` — GPL-3.0
 - `hugetim/nbstata` — GPL-3.0
+- `lbraglia/RStata` — GPL-3.0
 
 If new copyleft Stata projects appear, add them here in the same PR that first references them.
 

stata_code-0.6.0/PKG-INFO

@@ -0,0 +1,443 @@
+Metadata-Version: 2.4
+Name: stata-code
+Version: 0.6.0
+Summary: Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)
+Project-URL: Homepage, https://github.com/brycewang-stanford/stata-code
+Project-URL: Repository, https://github.com/brycewang-stanford/stata-code
+Project-URL: Issues, https://github.com/brycewang-stanford/stata-code/issues
+Project-URL: Changelog, https://github.com/brycewang-stanford/stata-code/blob/main/CHANGELOG.md
+Author-email: Bryce Wang <brycewang@stanford.edu>
+License-Expression: MIT
+License-File: LICENSE
+License-File: LICENSE-POLICY.md
+Keywords: causal-inference,jupyter,mcp,pystata,stata,vscode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: ipykernel>=6.0; extra == 'all'
+Requires-Dist: mcp>=1.27; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: kernel
+Requires-Dist: ipykernel>=6.0; extra == 'kernel'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.27; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="branding/logo/horizontal@1024.png" alt="stata-code logo" width="520" />
+</p>
+
+<p align="center">
+  <a href="README.md"><strong>English</strong></a> | <a href="README.zh.md">中文</a>
+</p>
+
+# stata-code
+
+[![PyPI](https://img.shields.io/pypi/v/stata-code.svg)](https://pypi.org/project/stata-code/)
+[![Python](https://img.shields.io/pypi/pyversions/stata-code.svg)](https://pypi.org/project/stata-code/)
+[![License](https://img.shields.io/pypi/l/stata-code.svg)](https://github.com/brycewang-stanford/stata-code/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/brycewang-stanford/stata-code/test.yml?branch=main&label=tests)](https://github.com/brycewang-stanford/stata-code/actions/workflows/test.yml)
+[![Downloads](https://static.pepy.tech/badge/stata-code/month)](https://pepy.tech/project/stata-code)
+[![VS Code](https://img.shields.io/visual-studio-marketplace/v/brycewang-stanford.stata-code-vscode.svg?label=vscode)](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode)
+[![VS Code Installs](https://img.shields.io/visual-studio-marketplace/i/brycewang-stanford.stata-code-vscode.svg)](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode)
+[![VS Code Downloads](https://img.shields.io/visual-studio-marketplace/d/brycewang-stanford.stata-code-vscode.svg?label=vscode%20downloads)](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode)
+[![Rating](https://img.shields.io/visual-studio-marketplace/r/brycewang-stanford.stata-code-vscode.svg)](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode)
+[![GitHub release](https://img.shields.io/github/v/release/brycewang-stanford/stata-code)](https://github.com/brycewang-stanford/stata-code/releases)
+[![GitHub stars](https://img.shields.io/github/stars/brycewang-stanford/stata-code?style=social)](https://github.com/brycewang-stanford/stata-code)
+
+<p align="center">
+  <img src="branding/github-instructions.png" alt="stata-code: agent-native Stata bridge — one Python core, multiple frontends (Jupyter kernel, MCP server, VS Code extension)" width="720" />
+</p>
+
+> Agent-native Stata bridge — **one Python core, multiple frontends**.
+
+`stata-code` lets you drive Stata from modern environments: an LLM agent (Claude Code, Cursor, Claude Desktop), a Jupyter notebook, or a VS Code editor session. All frontends share one Python core and return a stable, structured, **agent-friendly** result schema.
+
+```text
+                    ┌────────────────────────────────────────┐
+                    │     stata-code core (Python)           │
+                    │                                        │
+                    │   • pystata adapter (Stata 17+)        │
+                    │   • v1.0 unified result schema         │
+                    │   • token-economy defaults             │
+                    │   • multi-session via Stata frames     │
+                    │   • typed errors + suggestions         │
+                    └────────────────────────────────────────┘
+                       ↑              ↑              ↑
+              ┌────────┴────┐  ┌──────┴─────┐  ┌────┴────────────┐
+              │  Jupyter    │  │  MCP       │  │  VS Code        │
+              │  kernel     │  │  server    │  │  extension      │
+              └─────────────┘  └────────────┘  └─────────────────┘
+```
+
+**Status: v0.6 (May 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. Current test suite: 310 passing tests across schema, runner, MCP, kernel, notebook, and run-index modules. License: **MIT**.
+
+Two workflows v0.6 explicitly supports for end users:
+
+- **Run Stata code from a Jupyter notebook.** `pip install "stata-code[kernel]"` + `stata-code-kernel install --user` registers a **Stata** kernel that the Jupyter Notebook UI, JupyterLab, and the VS Code Jupyter extension all pick up by name. Cells render Stata logs, graphs, and warnings inline (the kernel logo bundled since v0.5 makes it appear in VS Code's kernel picker too). See [As a Jupyter Kernel](#as-a-jupyter-kernel).
+- **Optional agent "fix and rerun" loop.** `stata_run` returns typed `error.kind/line/context` plus `suggestions` on every failure. By default Claude Code only reports diagnostics — but if you explicitly say "fix this and rerun until it passes", the agent uses the same fields to edit your `.do` file and re-call `stata_run` until the run is green. The repair loop is **opt-in**: failed runs are diagnostics first, not automatic rewrite permission. See [Error Recovery in Agent Workflows](#error-recovery-in-agent-workflows).
+
+---
+
+## Why this exists
+
+The Stata AI / agent tooling landscape is fragmented; see [References-tools.md](References-tools.md):
+
+- Existing MCP servers ([SepineTam/stata-mcp](https://github.com/sepinetam/stata-mcp), [tmonk/mcp-stata](https://github.com/tmonk/mcp-stata)) are **AGPL-3.0**, which is not a fit for closed-source or commercial integration.
+- The popular VS Code AI extension ([hanlulong/stata-mcp](https://github.com/hanlulong/stata-mcp)) is MIT, but it bundles the MCP server inside the extension, making standalone reuse awkward.
+- Each tool wraps `pystata` with its own result shape, so agents have to special-case each integration.
+- Many existing tools were designed for humans first and then bolted onto MCP; they often dump long logs and base64 graph blobs into every reply, burning tokens by default.
+
+`stata-code` is designed to fill that gap:
+
+1. **MIT-licensed**, with no copyleft contagion.
+2. One shared result schema for every frontend: [SCHEMA.md](SCHEMA.md).
+3. Agent-native by default: typed errors, structured `r()` / `e()`, log refs, graph refs, and suggestion seeds.
+4. One core, multiple frontends: Jupyter kernel, MCP server, and VS Code extension.
+
+For the project's clean-room policy around AGPL/GPL Stata projects, see [LICENSE-POLICY.md](LICENSE-POLICY.md).
+
+---
+
+## Install
+
+Requirements: **Stata 17+** (with `pystata` shipped by Stata) and **Python 3.10+**.
+
+```bash
+# from PyPI
+pip install stata-code
+
+# with the MCP server and Jupyter kernel extras
+pip install "stata-code[mcp,kernel]"
+
+# or from source (editable install for development)
+git clone https://github.com/brycewang-stanford/stata-code.git
+cd stata-code
+pip install -e ".[mcp,kernel]"
+```
+
+> **Naming note.** The PyPI distribution is `stata-code` (hyphen), but
+> the Python import is `stata_code` (underscore — Python identifiers
+> can't contain hyphens). Same convention as `scikit-learn` →
+> `import sklearn`. So: `pip install stata-code`,
+> `from stata_code import run`.
+
+Note: `pystata` is **not** on PyPI; it ships with Stata. `stata-code` auto-discovers it on macOS at `/Applications/Stata/utilities/pystata` and at equivalent Linux / Windows paths. If your install is elsewhere, add it to `PYTHONPATH` before importing.
+
+---
+
+## Quick Start
+
+See [`examples/`](examples/) for end-to-end cookbook entries: basic regression, DiD, graphs, multi-session, and large matrices.
+
+### As a Python Library
+
+```python
+from stata_code import run
+
+r = run("sysuse auto, clear")
+r = run("regress mpg weight")
+
+if r.ok:
+    print(r.results.e.scalars["r2"])           # 0.6515 (native float)
+    print(r.results.e.macros["cmd"])           # "regress"
+    b = r.results.e.matrices["b"]
+    print(dict(zip(b.cols, b.values[0])))      # {"weight": -0.006, "_cons": 39.44}
+else:
+    print(r.error.kind, r.error.message)       # ErrorKind.VARNAME_NOT_FOUND, "..."
+    for s in r.error.suggestions:
+        print("hint:", s.action)               # "Did you mean `mpg`?"
+```
+
+### As an MCP Server
+
+After `pip install "stata-code[mcp]"`, the `stata-code-mcp` binary is on your `PATH`. You can wire it into Claude Code, Cursor, Claude Desktop, or any other MCP-compatible client.
+
+#### Claude Code via `claude mcp add` (recommended)
+
+If you have not installed Claude Code yet, see [anthropics/claude-code](https://github.com/anthropics/claude-code).
+
+The fastest way is the `claude mcp add` CLI. Pick a scope based on how widely you want `stata-code` available:
+
+```bash
+# user scope — install once, available in every Claude Code workspace on this machine
+claude mcp add stata-code --scope user -- stata-code-mcp
+
+# local scope — only for the current workspace (your local Claude config, not committed)
+claude mcp add stata-code --scope local -- stata-code-mcp
+
+# project scope — written into ./.mcp.json so collaborators on this repo share it
+claude mcp add stata-code --scope project -- stata-code-mcp
+```
+
+Then launch `claude` and type `/mcp` to confirm `stata-code` shows up with its 15 tools (`stata_run`, `stata_info`, `get_log`, `get_graph`, `get_matrix`, `list_sessions`, `cancel_session`, `reset_session`, `notebook_outline`, `notebook_get_cell`, `notebook_locate`, `notebook_edit_cell`, `notebook_insert_cell`, `notebook_delete_cell`, `list_runs`).
+
+#### Error Recovery in Agent Workflows
+
+`stata_run` does not rewrite the source `.do` file or change code on its own. It executes the submitted Stata code, so that code may still create logs, graphs, tables, or other outputs as usual. When Stata fails, `stata_run` returns typed diagnostics (`error.kind`, `error.message`, `error.line`, `error.context`) plus best-effort `suggestions`. That supports two distinct Claude Code workflows:
+
+- For "run this do-file" or "verify this code", Claude can report the failure and suggested next steps without changing source files.
+- For "fix this and rerun until it passes", Claude can use the same structured error fields to edit the `.do` file, call `stata_run` again, and iterate.
+
+If you want the repair loop, say so explicitly. Otherwise, treat failed runs as diagnostics first, not as automatic permission to rewrite code.
+
+#### `uvx` (no global pip install)
+
+If you prefer not to `pip install stata-code` globally, run it ephemerally through [`uv`](https://github.com/astral-sh/uv):
+
+```bash
+claude mcp add stata-code --scope user -- uvx --from stata-code stata-code-mcp
+```
+
+`uvx` will resolve and cache `stata-code` on first launch. Note: `pystata` is **not** on PyPI, so it still has to be locatable on the host. The runner adds the standard Stata install path (e.g. `/Applications/Stata/utilities/pystata` on macOS) to `sys.path` automatically; if your Stata lives elsewhere, set `PYTHONPATH` in the env block.
+
+#### Manual JSON config (Cursor / Claude Desktop / fallback)
+
+For clients without a `mcp add` CLI, edit the config file directly (`~/.claude/mcp.json`, Cursor settings, Claude Desktop `claude_desktop_config.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "stata-code": {
+      "command": "stata-code-mcp"
+    }
+  }
+}
+```
+
+Or run it as a module if the binary is not on `PATH`:
+
+```bash
+python -m stata_code.mcp
+```
+
+The MCP server registers 15 tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `stata_run` | Execute Stata code and return a v1.0 RunResult JSON |
+| `stata_info` | Report Stata edition, version, and capabilities |
+| `get_log` | Fetch the full log behind a `log://` ref |
+| `get_graph` | Fetch graph bytes behind a `graph://` ref (`ImageContent`) |
+| `get_matrix` | Fetch matrix payloads behind a `matrix://` ref |
+| `list_sessions` | Enumerate live sessions |
+| `cancel_session` | Cooperatively cancel the next `stata_run` for a session |
+| `reset_session` | Drop a session's data |
+| `notebook_outline` | Compact per-cell index of a `.ipynb` (cell_id, type, preview) |
+| `notebook_get_cell` | One cell's full source plus a token-economic outputs summary |
+| `notebook_locate` | Find cells by snippet / regex / pasted error text |
+| `notebook_edit_cell` | Atomically replace one cell's source (preserves id, clears outputs) |
+| `notebook_insert_cell` | Insert a new cell with a fresh nbformat 4.5+ UUID |
+| `notebook_delete_cell` | Remove a cell by id |
+| `list_runs` | Query run-bundle manifests (filter by notebook / cell_id / session / since / ok) |
+
+For modern MCP clients, these tools now return structured results through
+`structuredContent` with `outputSchema` metadata, while still keeping the
+serialized JSON text block for older clients. The server also exposes MCP
+resources:
+
+| Resource | Purpose |
+| --- | --- |
+| `stata://schema/run-result` | JSON Schema for `stata_run` structured output |
+| `stata://server/capabilities` | Server instructions, tools, and resource templates |
+| `stata://sessions` | Current subprocess-backed Stata sessions |
+| `log://...` | Full log text from a truncated `stata_run` result |
+| `graph://...` | Captured graph image bytes |
+| `matrix://...` | Deferred large matrix payloads |
+
+MCP prompts are available for common agent workflows:
+`run_do_file_and_report`, `debug_stata_error`,
+`fix_and_rerun_until_passes`, `replication_audit`, and
+`summarize_estimation_results`.
+
+### As a Jupyter Kernel
+
+`stata-code` ships a Jupyter kernel as part of the Python package — there is no separate "Jupyter plugin" in the JupyterLab extension marketplace. Installation is two steps: `pip install` the package with the `kernel` extra, then register the kernelspec with Jupyter.
+
+**Prerequisites**: Stata 17+ installed locally with a valid license (the kernel calls Stata via `pystata`), and Python 3.10+ with `jupyter`/`jupyterlab` already on the same environment.
+
+```bash
+# 1. Install stata-code with the kernel extra (pulls in ipykernel)
+pip install "stata-code[kernel]"
+
+# 2. Register the kernelspec into Jupyter's user data dir
+stata-code-kernel install --user
+# Or, equivalently:
+# python -m stata_code.kernel install --user
+```
+
+Verify the kernel is registered:
+
+```bash
+jupyter kernelspec list
+# should include an entry named `stata`
+```
+
+Then open Jupyter Notebook / JupyterLab (or a `.ipynb` in VS Code), pick **Stata** in the kernel selector, and run Stata commands in cells. Logs, graphs, and warnings render inline.
+
+> JupyterLab's Extension Manager only installs front-end JS extensions, so it cannot install a kernel — `pip install` plus the `install --user` step above is the only supported path.
+
+### As a VS Code Extension
+
+The companion extension is on the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode). It spawns `stata-code-mcp` as a child process and adds syntax highlighting, an Outline view for `**#` sections and `program define` blocks, code-lens "Run cell" and "Run section" actions on `.do` files, a sidebar (sessions / last result / run history / logs / graphs), status-bar indicators, completions, help lookup, conservative variable rename, and inline diagnostics from the v1.0 typed errors.
+
+```bash
+# from the VS Code CLI
+code --install-extension brycewang-stanford.stata-code-vscode
+```
+
+Or open the **Extensions** sidebar in VS Code and search `stata-code`.
+
+The extension still requires the MCP extra on your system Python (`pip install "stata-code[mcp]"`), so that `stata-code-mcp` resolves on `PATH` and can import the MCP SDK. Stata 17+ and a valid Stata license are required as for any other frontend.
+
+---
+
+## Token-Economy Defaults
+
+A typical `stata_run` response is about **10x smaller** than servers that dump logs and images directly. Three design choices drive this:
+
+1. **Logs return `head` + `tail` + `ref`** by default. Full logs are fetched on demand via `get_log(ref)`. A Stata regression log can be about 6,000 tokens; `stata-code` returns about 600 by default.
+2. **Graphs return refs, not inline base64**. A 30 KB PNG can become about 50,000 base64 tokens; returning a ref avoids that unless the agent actually needs the bytes.
+3. **Errors are typed**. Agents can check `err.kind == "varname_not_found"` instead of regex-parsing English logs.
+
+For example, a misspelled variable returns a structured error:
+
+```json
+{
+  "ok": false,
+  "rc": 111,
+  "error": {
+    "kind": "varname_not_found",
+    "varname": "mpgg",
+    "line": 3,
+    "context": {
+      "before": ["use auto"],
+      "failing": "summarize mpgg",
+      "after": []
+    },
+    "suggestions": [
+      {"action": "Did you mean `mpg`?", "command": "describe"}
+    ]
+  }
+}
+```
+
+The full schema is in [SCHEMA.md](SCHEMA.md).
+
+---
+
+## Architecture
+
+```text
+stata_code/
+├── core/
+│   ├── _runtime.py    # process-singleton pystata wrapper
+│   ├── _refs.py       # LRU ref store for log/graph/matrix payloads
+│   ├── schema.py      # Pydantic v2 models for the v1.0 result schema
+│   ├── errors.py      # rc → ErrorKind mapping + suggestion seeds
+│   └── runner.py      # the one execute(); collects everything via sfi
+├── mcp/
+│   └── server.py      # MCP server (15 tools)
+└── kernel/
+    └── kernel.py      # Jupyter kernel
+```
+
+`runner.py` is the only place that touches Stata. The Jupyter kernel and MCP server both import from it and only translate results into their own transports.
+
+---
+
+## Comparison
+
+| | stata-code | SepineTam/stata-mcp | hanlulong/stata-mcp | nbstata |
+| --- | --- | --- | --- | --- |
+| License | **MIT** | AGPL-3.0 | MIT | GPL-3.0 |
+| Standalone MCP | ✓ | ✓ | bundled with VS Code | — |
+| Jupyter kernel | ✓ | — | — | ✓ |
+| Unified result schema | ✓ ([SCHEMA.md](SCHEMA.md)) | per-tool | per-tool | per-tool |
+| Token-economy defaults | ✓ (log refs, graph refs) | — | — | — |
+| Typed errors + suggestions | ✓ (32 kinds) | — | — | — |
+| Multi-session | ✓ (Stata frames) | partial | — | — |
+| Mature ecosystem | early | ✓ (statamcp.com, cookbook) | ✓ (11k installs) | ✓ |
+
+`stata-code` is the younger, MIT-licensed, agent-native alternative in this problem space. Among the AGPL options, SepineTam's `stata-mcp` is currently more mature; `stata-code` is aimed at cases where copyleft contagion is unacceptable and agents need structured results.
+
+---
+
+## Roadmap
+
+### Done (through v0.6 — May 2026)
+
+- v1.0 result schema ([SCHEMA.md](SCHEMA.md))
+- `pystata`-based runner with native-typed `r()`, `e()`, and matrices
+- Multi-session via Stata frames
+- Per-line error attribution: line number, context, commands_executed
+- Graph capture: `png` / `svg` / `pdf` with ref store
+- Log truncation with ref store
+- Warning extraction: 5 categories + generic notes
+- 32-kind error taxonomy with canonical suggestions
+- MCP server: 15 tools, including notebook navigation / search / atomic edits and the run-bundle index (`list_runs`)
+- Jupyter kernel: rewired to the v1.0 pipeline, kernel logos bundled
+- Matrix size cap + `get_matrix(ref)` for large matrices (>10k cells)
+- Cooperative cancellation: `cancel(session_id)` / MCP `cancel_session`
+- Per-cell repair loop on `.ipynb` via `notebook_outline` / `notebook_get_cell` / `notebook_edit_cell` with optimistic-concurrency `expected_source` guards and `origin_cell_id` echo on `RunResult`
+- Persistent run bundles + `list_runs` query over `manifest.json` files (filter by cell / origin / session / since / ok)
+- JSON Schema artifact auto-generated from `schema.py`: [`schema/run_result.schema.json`](schema/run_result.schema.json)
+- VS Code extension published to the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode): syntax highlighting, section outline/navigation, code-lens cell and section runners, sidebar (sessions / last result / run history / logs / graphs), status bar, completions, conservative variable rename, diagnostics, MCP child-process spawn
+- Clean-room license policy ([LICENSE-POLICY.md](LICENSE-POLICY.md))
+
+### Next Up
+
+- Console fallback for Stata 11–16, re-implemented against the v1.0 schema
+- Hard timeout / mid-Stata interrupt; design and tradeoffs in [`docs/design/hard_timeout.md`](docs/design/hard_timeout.md)
+- Extra VS Code polish (esbuild bundle, lighter VSIX, command palette UX)
+- **v1.0** — Stable schema, broader Stata edition coverage
+
+See [SCHEMA.md §7](SCHEMA.md) for explicitly out-of-scope items.
+
+---
+
+## Testing
+
+```bash
+pip install -e ".[dev,mcp,kernel]"
+pytest                              # full suite (310 tests)
+pytest -m "not stata_required"      # CI subset; no Stata needed
+pytest -m "stata_required" -v       # Stata-only integration tests
+```
+
+The `stata_required` marker tags the real-Stata integration tests. CI uses `pytest -m "not stata_required"` so it does not collect them. Locally without Stata, those tests skip cleanly with the `"pystata / Stata 17+ not available"` message.
+
+---
+
+## Contributing
+
+- Read [LICENSE-POLICY.md](LICENSE-POLICY.md) before opening a PR.
+- Add a one-line acknowledgement to your first PR description; the template is in the policy file.
+- Tests are required for any new schema field or runner behavior.
+
+---
+
+## License
+
+The code is licensed under [MIT](./LICENSE). [LICENSE-POLICY.md](LICENSE-POLICY.md) explains how this project relates to other Stata projects.
+
+## Trademark Notice
+
+Stata is a registered trademark of StataCorp LLC. This project is independent and not affiliated with or endorsed by StataCorp.
+
+## Acknowledgements
+
+The Stata tooling landscape that this project builds on and learns from is surveyed in [References-tools.md](References-tools.md). All listed projects retain their own licenses and authorship; please consult each repository before reuse.