Stata AI Fusion

Stata AI Fusion

MCP Server + Skill Knowledge Base + VS Code Extension for Stata

Let AI directly execute Stata code, generate publication-quality analysis, and provide a complete IDE experience.

   

Quick Start • Features • MCP Tools • Skill Knowledge • VS Code Extension • 中文文档

______________________________________________________________________

为什么选择Stata AI Fusion？

Stata是经济学、政治学、流行病学和生物统计学中使用最广泛的统计软件包之一。然而，尽管R和Python用户多年来一直享受着深度的人工智能集成，但Stata仍然与人工智能辅助编码革命隔绝。

国家融合 弥合这一差距。它使AI助手（Claude、Cursor、GitHub Copilot等）能够启动真正的Stata会话、运行命令、检查数据、提取估计结果和捕获图形——所有这些都是通过开放的 模型上下文协议 （MCP）。

该项目由三个互补的组成部分组成，因此涵盖了每个工作流程：

______________________________________________________________________

建筑

数据流很简单：

1. AI助手 发送工具调用（例如。 run_command)通过MCP。
2. MCP服务器 将请求发送到 会话管理器，其维护一个或多个持久的交互式Stata进程。
3. 国家 执行命令；服务器捕获输出，剥离SMCL标记，检测错误，并自动导出任何新图形。
4. 清理后的结果（文本+可选的base64图像）流回人工智能，人工智能对其进行解释并对用户做出响应。

______________________________________________________________________

快速开始

克劳德代码（推荐）

# 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

然后尝试：

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

克劳德桌面版

编辑您的配置文件：

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

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

重新启动克劳德桌面。Stata工具将出现在工具列表中。

光标/VS代码（MCP）

创建 .cursor/mcp.json 或 .vscode/mcp.json 在项目根目录中：

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

Claude.ai（仅限技能）

此模式仅提供代码生成指导（没有实时Stata执行）。

1. 下载 stata-ai-fusion-skill.zip 从 发布 页面。
2. 首选 Claude.ai>项目>项目知识>上传.
3. 上传zip文件。

现在，AI在为您编写Stata代码时将参考5653行知识库。

VS代码扩展

# 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.2.3.vsix

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

______________________________________________________________________

特性

MCP服务器——11种人工智能驱动分析工具

服务器公开了11个MCP工具。每个工具都可以被任何兼容MCP的AI助手调用。

对话示例

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

AI calls: run_command("sysuse auto, clear")
AI calls: inspect_data()                          -> 74 obs, 12 variables
AI calls: run_command("regress price mpg weight foreign, robust")
AI calls: get_results("e", "N r2 F")              -> N=74, R²=0.52, F=29.1
AI calls: run_command("scatter price mpg || lfit price mpg")
AI calls: 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..."

技能知识库——5653行Stata专业知识

知识库使用 渐进式披露 架构：

• 技能.md （486条线路）用作入口点路由器。
• 14个参考文件 覆盖特定领域；AI按需加载它们。
• AI从不一次读取所有5653行，它只获取当前任务所需的内容。

VS代码扩展——完整的Stata IDE

______________________________________________________________________

MCP工具参考

______________________________________________________________________

技能知识库

______________________________________________________________________

配置

______________________________________________________________________

自动 发现 状态

服务器使用三层策略自动检测您的Stata安装：

1. 环境变量 -- STATA_PATH 具有最高优先级。
2. 标准路径 --

- macOS： /Applications/Stata*/, /Applications/StataNow/ - Linux： /usr/local/stata*/, /usr/local/bin/ - 窗户： C:\Program Files\Stata*\

1. 系统路径 -- which stata-mp, which stata-se, which stata

支持的版本： 国会议员, 东南, 集成电路, 是 （Stata 17、18、19和StataNow）。

如果自动检测失败，请显式设置环境变量：

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

______________________________________________________________________

多会话支持

服务器支持多个并发的Stata会话，并实现完全的数据隔离：

• 每个会话都维护自己的数据集、变量和估计结果。
• 会话在工具调用之间持续存在，无需在每个命令后重新加载数据。
• 默认会话会自动创建；为并行工作流创建命名会话。
• 空闲会话将在1小时后自动清理（可配置）。
• 服务器关闭时，所有会话都会被优雅地清理。

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

______________________________________________________________________

故障排除

Stata not found / auto-discovery fails

服务器在三个地方搜索Stata（参见 自动 发现 状态).如果没有工作，你会看到：

StataNotFoundError: No Stata installation found

修复它：

1. 手动查找您的Stata可执行文件：

   # macOS
   find /Applications -name "stata-mp" -o -name "stata-se" -o -name "stata" 2>/dev/null

   # Linux
   which stata-mp || which stata-se || which stata

   # Windows (PowerShell)
   Get-ChildItem "C:\Program Files\Stata*" -Recurse -Filter "Stata*.exe" | Select-Object FullName

1. 显式设置路径：

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

   # Windows (PowerShell)
   $env:STATA_PATH = "C:\Program Files\Stata18\StataMP-64.exe"

1. 对于Claude Code，将其添加到MCP配置中：

   {
     "env": {
       "STATA_PATH": "/path/to/your/stata"
     }
   }

常见陷阱：

• 在macOS上，指向二进制文件 *里面* 这 .app 捆绑，而不是 .app 自身
• 在Windows上，使用完整路径，包括 -64 64位版本的后缀
• StataNow使用不同的二进制名称--检查 Contents/MacOS/ 确切的名字

pexpect installation or "spawn" errors

pexpect 是驱动Stata交互式控制台的库。问题表现为：

ModuleNotFoundError: No module named 'pexpect'
# or
pexpect.exceptions.ExceptionPexpect: The command was not found ...

修复它：

# If using uv (recommended)
uv pip install pexpect

# If using pip
pip install pexpect

Windows用户： pexpect 对Windows的支持有限。服务器使用 pexpect.popen_spawn 在Windows上，它可以工作，但有一些局限性：

• 没有伪终端（PTY），因此某些Stata输出格式可能不同
• more 必须禁用分页（服务器会自动处理）
• 如果遇到问题，请尝试从WSL2运行

MCP server won't start or connect

症状： Claude Code或Cursor显示“MCP服务器启动失败”或Stata工具未出现。

步骤1——独立测试服务器：

# Should print tool list and wait for input
uv run stata-ai-fusion

如果失败，请检查错误消息：

• StataNotFoundError → see 未找到Stata 上方
• ModuleNotFoundError → 安装缺少的依赖项： uv pip install stata-ai-fusion
• Address already in use → 另一个实例正在运行；先杀了它

步骤2——检查MCP配置：

克劳德代码(~/.claude/settings.json 或项目 .claude/settings.json):

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

对于光标(.cursor/mcp.json):

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

步骤3--启用调试日志记录：

export MCP_STATA_LOGLEVEL=DEBUG
uv run stata-ai-fusion

这显示了每个Stata交互，包括发现、会话创建和命令执行。

Windows-specific issues

路径分隔符： 在中始终使用正斜杠或原始字符串 STATA_PATH:

# PowerShell
$env:STATA_PATH = "C:/Program Files/Stata18/StataMP-64.exe"
# or
$env:STATA_PATH = "C:\Program Files\Stata18\StataMP-64.exe"

Windows上的Stata版本检测： 服务器在以下位置检查Windows注册表 HKEY_LOCAL_MACHINE\SOFTWARE\StataCorpLP 和 HKEY_CURRENT_USER\SOFTWARE\StataCorpLP 对于已安装的版本。如果您的注册表项是非标准的（例如，便携式安装），请设置 STATA_PATH 手动。

长期问题： 如果您的项目路径超过260个字符，请启用长路径支持：

# Run as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

防病毒干扰： 一些防病毒软件块 pexpect 从产卵斯塔塔开始。如果服务器挂起“正在创建会话”，请将您的Stata目录和Python环境添加到排除列表中

Session timeout / "No active session" errors

为什么会发生： 空闲会话将在以下时间自动清理 1小时 释放系统资源。如果你的人工智能对话暂停了很长时间，然后又继续，那么会话可能已经关闭。

修复它：

• 只需运行另一个命令——服务器会自动创建一个新的默认会话
• 如果你需要一个特定的命名会话：让人工智能调用 create_session
• 对于长时间运行的批处理作业，请使用 run_do_file 随着 batch_mode=true （设计用于延长执行时间）

提示： 您可以随时通过要求AI呼叫来检查活动会话 list_sessions.

Output seems truncated

根据设计，服务器会截断非常大的输出，以保持在AI上下文窗口限制范围内：

• 负责人： 前3000个字符
• 尾部： 最后5000个字符
• 内联图： 高达5% run_command，每3个 run_do_file

对于大输出，使用 run_do_file 随着 batch_mode=true --这会将所有输出捕获到日志文件中，并返回摘要而不是全文。

对于图形，请使用 export_graph 以全分辨率将特定图形保存到文件中，而不是依赖内联预览。

______________________________________________________________________

发展

# 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

______________________________________________________________________

测试

所有85项测试都通过了Stata MP 19（macOS arm64）。

______________________________________________________________________

项目结构

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/                   # 85 tests (39 unit + 46 integration)
├── assets/                  # Icon, architecture diagrams
└── pyproject.toml

______________________________________________________________________

贡献

欢迎投稿！以下是一些帮助方法：

• 错误报告：打开一个问题，描述问题、您的Stata版本和操作系统。
• 新技能参考：添加a .md 文件到 skill/references/ 涵盖Stata主题。
• 新的MCP工具：在中实施工具 src/stata_ai_fusion/tools/ 并注册它。
• VS代码改进：展开语法语法或添加代码段。

请快跑 uv run pytest tests/ -v 在提交PR之前。

______________________________________________________________________

许可证

麻省理工学院——见 许可证 了解详情。

致谢

• 国家 StataCorp
• 模型上下文协议 通过Anthropic

______________________________________________________________________

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