Skip to content

References-tools.md

Latest commit

 

History

History
347 lines (264 loc) · 19.6 KB

References-tools.md

File metadata and controls

347 lines (264 loc) · 19.6 KB
Raw

References — Existing Stata Tooling Landscape

A survey of the tools stata_code integrates, learns from, and aims to consolidate.

This document catalogues the current Stata tooling ecosystem across editors, notebooks, and AI agents. For each tool we record what it does, how it communicates with Stata, its maintenance status, and where it leaves gaps that stata_code can fill.

All metrics captured April 2026. Star counts and "last pushed" dates may drift; see linked repos for current state.

Quick Reference Table

Category Tool Stars / Installs Last Active License Stata Comm.
VSCode (syntax) kylebarron.stata-enhanced 62k installs — MIT none
VSCode (MCP + run) hanlulong/stata-mcp 323★ / 11k installs 2026-04 MIT pystata
VSCode (run + cells) kylebutts/vscode-stata 57★ 2025-06 MIT nbstata + AppleScript
VSCode (MCP + run) tmonk/stata-workbench 28★ 2026-02 AGPL-3.0 mcp-stata
VSCode (all-in-one) ZihaoVistonWang.stata-all-in-one ~1k installs — — AppleScript / PowerShell
VSCode (legacy run) amichuda/stataRun 0★ 2019-01 — AppleScript
Jupyter kernel kylebarron/stata_kernel 278★ 2026-04 GPL-3.0 pexpect / console
Jupyter kernel hugetim/nbstata 55★ 2026-01 GPL-3.0 pystata
Jupyter magic TiesdeKok/ipystata 197★ 2023-09 — console
MCP server SepineTam/stata-mcp 153★ 2026-04 AGPL-3.0 pystata
MCP server tmonk/mcp-stata 54★ 2026-03 AGPL-3.0 pystata
Claude Code skill dylantmoore/stata-skill 188★ 2026-04 Other (knowledge only)
Language server euglevi/stata-language-server 4★ 2025-05 MIT none
Atom (run) kylebarron/stata-exec 32★ 2023-03 MIT AppleScript / X11
Atom (syntax) kylebarron/language-stata 48★ 2022-08 MIT none
Sublime mattiasnordin/StataEditor 48★ 2022-02 — AppleScript
Sublime (macOS) zizhongyan/StataImproved 49★ 2026-02 MIT AppleScript
Python library pystata (official) — shipped with Stata proprietary in-process
R bridge lbraglia/RStata 117★ 2025-03 GPL-3.0 subprocess

A. VSCode Extensions

VSCode is now the dominant editor for empirical research. Extensions span three generations: pure syntax → AppleScript-based runners → MCP-powered AI integrations.

A.1 Stata Enhanced (kylebarron.stata-enhanced)

  • Marketplace: 62,401 installs — the de facto baseline syntax highlighter for Stata in VSCode
  • What it does: Syntax highlighting only. Supports .do, .ado, system commands, functions, macros, regex, and dynamic Markdown/LaTeX
  • Communication: None — does not run code
  • Maintenance: Quiet but stable; the grammar is forked into many downstream extensions
  • Pros:
    • Highest install count of any Stata-related VSCode extension
    • Grammar is permissively licensed and widely reused
    • Zero dependencies — pure TextMate grammar
  • Cons:
    • No execution, no language server, no AI integration
    • Hasn't been substantively updated in a while
  • Positioning: The "minimal viable" syntax layer. Most other VSCode extensions either depend on or duplicate its grammar.

A.2 Stata MCP — DeepEcon / hanlulong/stata-mcp

  • GitHub: 323★ · Marketplace: 11,036 installs · License: MIT · Last pushed: 2026-04
  • What it does: Full-featured VSCode/Cursor/Antigravity extension. Runs .do files, exposes results in an editor panel, and simultaneously runs an MCP server on localhost:4000 so AI assistants (Copilot, Claude Code, Cursor AI, Codex, Cline) can drive Stata
  • Communication: pystata for execution; built-in MCP server speaks streamable HTTP + SSE
  • Pros:
    • Most popular Stata-AI integration today; legitimate AI-native UX
    • Multi-session parallel execution
    • Auto-installs uv and Python deps; one-click setup
    • Status bar UX, keyboard shortcuts, graph webview
    • Cross-IDE: VS Code + Cursor + Antigravity from a single codebase
  • Cons:
    • Bundles editor and MCP concerns together — hard to use the MCP server standalone (e.g., from Claude Desktop without VSCode)
    • Stata 17+ only (pystata requirement)
    • Heavy install footprint (auto-installs uv, then a Python venv)
  • Positioning: The clear leader for VSCode + AI users. The reference design for the "editor + MCP in one" pattern.

A.3 kylebutts/vscode-stata

  • GitHub: 57★ · License: MIT · Last pushed: 2025-06
  • What it does: Combines three upstream projects into one extension: Kyle Barron's syntax grammar + poidstotal/stataRun's send-to-Stata commands + an "interactive window" backed by nbstata
  • Communication: nbstata (pystata) for the interactive window; AppleScript / etc. for "send to Stata"
  • Pros:
    • Cell-based workflow (* %% markers) — the closest VSCode equivalent to Jupyter cells
    • Reuses well-tested upstream pieces rather than reinventing
    • Honest credit to upstream authors
  • Cons:
    • Smaller user base than DeepEcon's extension
    • "Send to Stata" still relies on AppleScript-style automation on macOS — fragile
  • Positioning: The "researcher who wants Jupyter-cell ergonomics inside a .do file" choice.

A.4 tmonk/stata-workbench

  • GitHub: 28★ · License: AGPL-3.0 · Last pushed: 2026-02
  • What it does: VSCode/Cursor/Windsurf/Antigravity extension that runs Stata code from the editor and is powered by tmonk/mcp-stata. Designed so AI agents can also drive Stata through the same backend
  • Communication: mcp-stata (pystata-based)
  • Pros:
    • Cleaner separation than hanlulong's — the MCP server (mcp-stata) is a standalone project that the workbench wraps
    • Persistent Stata session; can retrieve r() / e() results and graphs
  • Cons:
    • Smaller user base; less polish than DeepEcon's
    • AGPL-3.0 — copyleft restricts commercial reuse
  • Positioning: The cleanest "MCP-first" architecture among VSCode extensions. Worth studying as an architectural reference.

A.5 Stata All in One (ZihaoVistonWang.stata-all-in-one)

  • Marketplace: ~1,045 installs · License: not stated
  • What it does: Syntax highlighting (built on Stata Enhanced grammar) + smart outline + section/line/selection execution + variable rename + help lookup
  • Communication: AppleScript on macOS, PowerShell on Windows
  • Pros:
    • Multi-level outline support (up to 6 header levels) — strong navigation UX
    • Hierarchical section execution (run from header to next equal/higher header)
  • Cons:
    • No AI / MCP integration
    • Linux unsupported
    • PowerShell automation has timing-sensitive delays
  • Positioning: Productivity-focused for solo Stata users on macOS/Windows — but skips the AI layer.

A.6 stataRun (Yeaoh.stataRun / amichuda/stataRun)

  • Marketplace: small · GitHub (amichuda): 0★ · Last pushed: 2019
  • What it does: Minimal "send code to Stata" via AppleScript
  • Pros: Very small surface; easy to read
  • Cons: Effectively unmaintained; no longer competitive with the MCP-based options
  • Positioning: Historical / educational interest only. Most of its design ideas live on inside kylebutts/vscode-stata.

B. Jupyter Integrations

Two distinct generations: subprocess-based (works with Stata 11+, slower, fragile) and pystata-based (Stata 17+ only, in-process, fast).

B.1 kylebarron/stata_kernel

  • GitHub: 278★ · License: GPL-3.0 · Last pushed: 2026-04
  • What it does: Full Jupyter kernel for Stata. Works with Stata 11+ on Windows/macOS/Linux
  • Communication: pexpect against Stata's console mode; on Windows uses Automation API
  • Pros:
    • Most-used Jupyter Stata kernel by a wide margin
    • Works with older Stata versions (no pystata requirement)
    • Cross-platform with thoughtful per-OS handling
    • Mature feature set: autocomplete, magics, graph display, cache
  • Cons:
    • Console-driven I/O is inherently slower and more fragile than in-process pystata
    • GPL-3.0 viral
    • Newer features (DataGrid widget, Quarto inline code) live in nbstata, not here
  • Positioning: The default choice if you have Stata < 17 or are paranoid about pystata compatibility.

B.2 hugetim/nbstata

  • GitHub: 55★ · License: GPL-3.0 · Last pushed: 2026-01
  • What it does: Modern Jupyter kernel built on top of pystata. Works with Stata 17+ only
  • Communication: pystata (in-process)
  • Pros:
    • Cleaner, faster execution than stata_kernel
    • DataGrid widget with browse-like interactive filtering
    • Variable / data property side panel
    • Quarto inline code support
    • Auto-completion, rich text help, #delimit ; support
    • Compatible with NBClassic, JupyterLab, VS Code, Quarto
  • Cons:
    • Stata 17+ hard requirement
    • Smaller user base than stata_kernel
    • GPL-3.0
  • Positioning: The modern default for Jupyter + Stata. kylebutts/vscode-stata's interactive window is built on it. If you're on Stata 17+, this is what you want.

B.3 TiesdeKok/ipystata

  • GitHub: 197★ · License: not stated · Last pushed: 2023-09
  • What it does: IPython magic (%%stata) for embedding Stata cells inside a Python notebook — not a standalone kernel
  • Communication: subprocess (older approach)
  • Pros:
    • Lets you mix Python and Stata cells in one notebook — useful for hybrid workflows
    • Lower setup overhead than running a full kernel
  • Cons:
    • Not actively maintained (last push 2023-09)
    • Mostly superseded by pystata's own IPython magic, which is bundled with Stata 17+
  • Positioning: Historical — the original "Stata in Python notebooks" idea. Today you'd just use pystata's built-in magic.

B.4 JupyterLab Syntax Extensions

Positioning: Small, single-purpose extensions. The fragmentation (3+ near-identical projects across JupyterLab versions) is itself evidence that this layer needs consolidation.

C. MCP Servers (LLM / Agent Integration)

The newest category. As of April 2026 there are at least four serious projects, plus several tiny experiments. The space is fragmenting fast.

C.1 SepineTam/stata-mcp

  • GitHub: 153★ · License: AGPL-3.0 · Last pushed: 2026-04 · PyPI: stata-mcp
  • What it does: Dedicated MCP server for Stata, plus an "agent mode" CLI and a Claude Code plugin (with companion stata-language-server)
  • Communication: pystata
  • Pros:
    • Cleanest "MCP server only" packaging — installable via uvx stata-mcp
    • Official Claude Code plugin (claude plugin marketplace add sepinetam/stata-mcp)
    • Agent mode for autonomous Stata workflows
    • Active dev, has its own website (statamcp.com), datasets (STOP), and ecosystem (DtaDock, cookbook, SDK)
    • Multilingual (English + Chinese docs)
  • Cons:
    • AGPL-3.0 — viral copyleft restricts who can build on top
    • Requires Stata 17+ (pystata)
    • Has had attribution issues with copycat forks (DMCA takedown noted in README)
  • Positioning: The standalone MCP server of choice. If you want to plug Stata into Claude Desktop or any non-VSCode MCP client, start here.

C.2 hanlulong/stata-mcp

See A.2. Bundles an MCP server inside a VSCode extension. Higher install count than SepineTam but harder to use the MCP component standalone.

C.3 tmonk/mcp-stata

  • GitHub: 54★ · License: AGPL-3.0 · Last pushed: 2026-03
  • What it does: Lightweight MCP server exposing a persistent Stata/MP session. Tools to execute commands, inspect data, retrieve r()/e() stored results, and view graphs
  • Communication: pystata (persistent session)
  • Pros:
    • Smallest, most focused codebase of the three MCP servers
    • Persistent session is useful for stateful empirical workflows
    • Designed to power tmonk/stata-workbench (clean separation of concerns)
  • Cons:
    • Smaller community, fewer integrations
    • AGPL-3.0
  • Positioning: A tight, well-designed MCP server. The architectural model (server + thin VSCode wrapper) is what stata_code should emulate.

C.4 dylantmoore/stata-skill (Claude Code Skill, not MCP)

  • GitHub: 188★ · License: Other · Last pushed: 2026-04
  • What it does: Not a server — a knowledge skill that teaches Claude how to write idiomatic Stata code (37 reference files, 20 community packages, plus a "Stata C plugins" sub-skill)
  • Pros:
    • Complementary to MCP servers — improves the quality of the Stata code an LLM writes, before any execution
    • Covers community packages MCP servers don't know about
  • Cons:
    • Knowledge only; doesn't run code
    • Claude Code-specific (skill format)
  • Positioning: A horizontal addition to any MCP server. Pair this with one of the execution-capable MCPs above for the best agent experience.

C.5 Smaller MCP variants

These are mostly experiments. Listed for completeness.

D. Other Editors

D.1 Atom

Positioning: Atom itself is sunset (2022). These projects survive because their grammar/code is reused downstream.

D.2 Sublime Text

Positioning: A long-tail community for Sublime users. Nothing AI-aware here.

D.3 Vim / Emacs

  • Vim has informal syntax files and vim-stata-style plugins, none with significant adoption
  • Emacs ESS (ess-stata-mode) ships Stata support out of the box for Emacs users — a stable but niche choice

E. Python ↔ Stata Libraries

E.1 pystata (official)

  • Vendor: StataCorp · License: proprietary (ships with Stata) · Stata version: 17+
  • What it does: Official Python ↔ Stata bridge. Two interfaces:
    1. IPython magic (%%stata, %stata) — works in Jupyter, JupyterLab, Spyder, PyCharm
    2. Python API (stata.run(), stata.pdataframe_*, frames, Mata) — works anywhere Python runs
  • Pros:
    • In-process (no subprocess) → fast, no I/O fragility
    • Officially supported by StataCorp
    • Handles graphs, frames, Mata cleanly
    • Foundation for nbstata, SepineTam/stata-mcp, tmonk/mcp-stata, hanlulong/stata-mcp
  • Cons:
    • Requires Stata 17+ and a local install
    • Closed-source (you can read the docs but can't extend the bindings)
  • Positioning: The substrate. Every modern Stata-Python tool is built on this. stata_code will be too.

E.2 TiesdeKok/ipystata

See B.3. Older; superseded by pystata's built-in magic.

F. Other Language Bridges

F.1 lbraglia/RStata

  • GitHub: 117★ · CRAN: yes · License: GPL-3.0 · Last pushed: 2025-03
  • What it does: R package wrapping a Stata subprocess. Lets R users send Stata code, retrieve console output, and pass data frames back and forth
  • Communication: subprocess (Stata batch mode)
  • Pros:
    • The standard R ↔ Stata bridge
    • Handles .dta round-tripping
  • Cons:
    • Subprocess overhead per call
    • R-only; doesn't help Python/JS users
  • Positioning: Out of scope for stata_code directly, but worth knowing as a design reference for "thin language bridge over subprocess."

G. Language Server / Tooling

G.1 euglevi/stata-language-server

  • GitHub: 4★ · License: MIT · Last pushed: 2025-05
  • What it does: LSP server for Stata, built on pygls. Auto-completion, code style checking
  • Pros: Standards-based (LSP); editor-agnostic in principle
  • Cons: Tiny user base; LSP coverage is incomplete
  • Positioning: An early-stage attempt at proper IDE-style intelligence for Stata. SepineTam/stata-mcp's Claude Code plugin already integrates it.

G.2 Honorable mentions

  • stata-syntax (TextMate-style grammars) — reused everywhere
  • DAP (debugger) — no real Stata DAP server exists yet; gap in the ecosystem

H. Where the Gaps Are (Why stata_code Exists)

Reading across this landscape, three structural gaps stand out:

  1. MCP servers and editor extensions are tightly coupled. hanlulong/stata-mcp ships its MCP server inside a VSCode extension; using the MCP standalone is awkward. tmonk separates them but is small. SepineTam separates them but doesn't ship an editor frontend. No project today gives you "one core, multiple equally-supported frontends."

  2. Jupyter and VSCode reinvent the same wheel. nbstata and the VSCode extensions both wrap pystata with their own result schemas, graph handling, and version detection. A user who switches contexts loses everything.

  3. No unified result schema. Every tool returns Stata output in its own shape — some give you the log, some give you r()/e(), some give you graphs as base64, some as files. An agent (or a developer writing tooling on top) has to special-case each one.

stata_code aims to occupy exactly the seat none of these tools occupy: a single Python core with a stable result schema, exposed identically through a Jupyter kernel, a VSCode extension, and an MCP server.

License of this document

This file is part of the stata_code project and is released under the same MIT license as the rest of the repository. All linked projects retain their own licenses; please consult each repo before reusing code.