STATA-MCP Repro
# STATA-MCP
Project-local, reproducible Stata execution for humans and AI agents. Every managed analysis stays beside its source project and produces immutable, readable do-files, logs, results, graphs, and provenance.
## Why this exists
Existing Stata MCP servers prove that agents can call Stata. STATA-MCP Repro adds the controls required for real research: explicit project ownership, deterministic planning gates, immutable run identity, process-tree cancellation, typed results, graph provenance, safe migration, and one shared human/agent ledger.
Core guarantees:
- startup never creates a workspace;
- no forced `stata-mcp-folder` and no copied central archive;
- one `.stata-mcp.toml` selects a human-readable project-relative artifact directory;
- run names are descriptive and collision-safe;
- completed runs are immutable and every artifact is SHA-256 bound to its run;
- medical and other material analyses require a reviewed, approved plan;
- dashboard listens only on `127.0.0.1` with an expiring bearer token;
- humans and agents create the same canonical run records.
## Start
Prerequisites: Python 3.11–3.13, a separately licensed Stata installation, and [uv](https://docs.astral.sh/uv/).
```console
git clone https://github.com/taewat07/STATA-MCP-AGENT.git
cd STATA-MCP-AGENT
uv tool install .
stata-mcp install --all
cd "/path/to/research-project"
stata-mcp project init --artifact-dir "analysis/stata" --name "Readable study name"
stata-mcp doctor
```
Restart the AI client after installation. Use `stata-planner` to inspect and approve a material analysis, then `stata-analyst` to execute it. Humans can inspect the same ledger with:
```console
stata-mcp dashboard --project .
```
The command prints the loopback URL and a short-lived token. The VS Code client connects to this service; it never starts or stops the MCP server.
## Documentation
Read the [installation guide](docs/installation.md), [architecture](docs/architecture.md), [human and agent workflows](docs/workflows.md), [provenance contract](docs/provenance.md), and [security model](docs/security.md). Legacy users should follow the [copy-first migration guide](docs/migration.md).
Contributions follow [CONTRIBUTING.md](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md), and the public [security policy](SECURITY.md).
## Status and attribution
Pre-release `0.1.x`; APIs may change under the documented two-release deprecation policy. Derived from SepineTam's MCP-for-Stata 1.21.3; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Not affiliated with or endorsed by StataCorp LLC. Licensed AGPL-3.0-or-later.
TDQS
Scored across 22 tools
Active tools have distinct purposes across planning, project management, run lifecycle, data inspection, and output retrieval. Deprecated tools are clearly labeled with redirecting messages, so misselection is unlikely despite some overlap in names.
All tools use snake_case, but there is a clear split: active tools favor object_verb naming (e.g., run_prepare, data_inspect) while deprecated tools use verb_object naming (e.g., write_dofile, read_file). This mixed pattern reduces readability, though deprecated markers mitigate confusion.
The total of 22 tools is heavy, and 9 of them are deprecated, artificially inflating the surface. The active 13 tools form a well-scoped set, but the obsolete entries should be removed to bring the count into an ideal range.
The active tool chain covers the full reproducibility lifecycle: plan preparation and approval, project initialization, run preparation/execution/monitoring, and artifact retrieval. Minor gaps like lack of list operations for runs or projects are workable.