haoyu-haoyu/stata-ai-fusion

---

Why Stata AI Fusion?

Stata is one of the most widely used statistical packages in economics, political science, epidemiology, and biostatistics. Yet while R and Python users have enjoyed deep AI integration for years, Stata has remained isolated from the AI-assisted coding revolution.

stata-ai-fusion bridges that gap. It gives AI assistants (Claude, Cursor, GitHub Copilot, and others) the ability to start a real Stata session, run commands, inspect data, extract estimation results, and capture graphs – all through the open Model Context Protocol (MCP).

The project ships as three complementary components so every workflow is covered:

---

Architecture

The data flow is straightforward:

1. AI Assistant sends a tool call (e.g. stata_run_command) via MCP.
2. MCP Server dispatches the request to the Session Manager, which maintains one or more persistent, interactive Stata processes.
3. Stata executes the command; the server captures output, strips SMCL markup, detects errors, and auto-exports any new graphs.
4. The cleaned result (text + optional base64 image) flows back to the AI, which interprets it and responds to the user.

---

Quick Start

Claude Code (recommended)

# Register the MCP server in one command
claude mcp add stata-ai-fusion -- uvx --from stata-ai-fusion stata-ai-fusion

# Verify
claude mcp list

Then try:

> Load the auto dataset in Stata and regress price on mpg and weight with robust SE

Claude Desktop

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "stata": {
      "command": "uvx",
      "args": ["--from", "stata-ai-fusion", "stata-ai-fusion"]
    }
  }
}

Restart Claude Desktop. The Stata tools will appear in the tool list.

Cursor / VS Code (MCP)

Create .cursor/mcp.json or .vscode/mcp.json in your project root:

{
  "servers": {
    "stata": {
      "command": "uvx",
      "args": ["--from", "stata-ai-fusion", "stata-ai-fusion"]
    }
  }
}

Claude.ai (Skill Only)

This mode provides code-generation guidance only (no live Stata execution).

1. Download stata-ai-fusion-skill.zip from the Releases page.
2. Go to Claude.ai > Project > Project Knowledge > Upload.
3. Upload the zip file.

The AI will now reference the 5,653-line knowledge base when writing Stata code for you.

VS Code Extension

# Option 1: VS Code Marketplace
# Search "Stata AI Fusion" in the Extensions panel

# Option 2: From GitHub Release
code --install-extension stata-ai-fusion-0.3.0.vsix

# Option 3: Cursor
cursor --install-extension stata-ai-fusion-0.3.0.vsix

---

Features

MCP Server – 11 tools for AI-driven analysis

The server exposes 11 MCP tools. Each tool can be called by any MCP-compatible AI assistant.

Conversation Example

User: "Analyze the determinants of car prices in the auto dataset."

AI calls: stata_run_command("sysuse auto, clear")
AI calls: stata_inspect_data()                    -> 74 obs, 12 variables
AI calls: stata_run_command("regress price mpg weight foreign, robust")
AI calls: stata_get_results("e", "N,r2,F")        -> N=74, R²=0.52, F=29.1
AI calls: stata_run_command("scatter price mpg || lfit price mpg")
AI calls: stata_export_graph(format="png")        -> [base64 image]

AI: "The regression shows that each additional mile per gallon is associated
     with a $49.50 decrease in price, controlling for weight and origin..."

Skill Knowledge Base – 5,653 lines of Stata expertise

The knowledge base uses a Progressive Disclosure architecture:

• SKILL.md (486 lines) serves as the entry-point router.
• 14 reference files cover specific domains; the AI loads them on demand.
• The AI never reads all 5,653 lines at once – it fetches only what the current task requires.

VS Code Extension – complete Stata IDE

---

MCP Tools Reference

---

Skill Knowledge Base

---

Configuration

---

Stata Auto-Discovery

The server automatically detects your Stata installation using a three-tier strategy:

1. Environment variable – STATA_PATH takes highest priority.
2. Standard paths –
   • macOS: /Applications/Stata*/, /Applications/StataNow/
   • Linux: /usr/local/stata*/, /usr/local/bin/
   • Windows: C:\Program Files\Stata*\
3. System PATH – which stata-mp, which stata-se, which stata

Supported editions: MP, SE, IC, BE (Stata 17, 18, 19 and StataNow).

If auto-detection fails, set the environment variable explicitly:

export STATA_PATH="/Applications/Stata/StataMP.app/Contents/MacOS/stata-mp"

---

Multi-Session Support

The server supports multiple concurrent Stata sessions with complete data isolation:

• Each session maintains its own dataset, variables, and estimation results.
• Sessions persist between tool calls – no need to reload data after every command.
• A default session is created automatically; create named sessions for parallel workflows.
• Idle sessions are automatically cleaned up after 1 hour (configurable).
• All sessions are cleaned up gracefully on server shutdown.

AI calls: stata_run_command(code="sysuse auto, clear", session_id="session_A")
AI calls: stata_run_command(code="sysuse nlsw88, clear", session_id="session_B")
# session_A has 74 obs (auto), session_B has 2,246 obs (nlsw88)

---

Troubleshooting

---

Development

# Clone and set up
git clone https://github.com/haoyu-haoyu/stata-ai-fusion.git
cd stata-ai-fusion
uv sync

# Run unit tests (no Stata required)
uv run pytest tests/test_discovery.py -v

# Run integration tests (requires Stata)
uv run pytest tests/test_integration.py -v

# Build Python package
uv build

# Build VS Code extension
cd vscode-extension && npm install && npm run build

---

Testing

The 118 unit tests run without Stata; all 170 pass on Stata MP 19 (macOS arm64).

---

Project Structure

stata-ai-fusion/
├── src/stata_ai_fusion/
│   ├── __main__.py          # CLI entry point
│   ├── server.py            # MCP server + resource registration
│   ├── stata_discovery.py   # Auto-detect Stata installation
│   ├── stata_session.py     # Interactive & batch session manager
│   ├── graph_cache.py       # Graph capture and base64 encoding
│   ├── result_extractor.py  # r()/e()/c() result extraction
│   └── tools/               # 11 MCP tool implementations
├── skill/
│   ├── SKILL.md             # Main skill routing document (486 lines)
│   └── references/          # 14 reference documents (5,167 lines)
├── vscode-extension/
│   ├── src/                 # TypeScript extension source (5 files)
│   ├── syntaxes/            # TextMate grammar
│   └── snippets/            # 30 code snippets
├── tests/                   # 170 tests (118 unit + 52 integration)
├── assets/                  # Icon, architecture diagrams
└── pyproject.toml

---

Contributing

Contributions are welcome! Here are some ways to help:

• Bug reports: Open an issue describing the problem, your Stata version, and OS.
• New Skill references: Add a .md file to skill/references/ covering a Stata topic.
• New MCP tools: Implement a tool in src/stata_ai_fusion/tools/ and register it.
• VS Code improvements: Expand syntax grammar or add snippets.

Please run uv run pytest tests/ -v before submitting a PR.

---

License

MIT – see LICENSE for details.

Acknowledgments

• Stata by StataCorp
• Model Context Protocol by Anthropic

---

PyPI • VS Code Marketplace • Releases • 中文文档