stata-mcp

<!-- mcp-name: io.github.aliveranme/stata-mcp -->
<p align="center">
  <img src="./assets/readme/hero.svg" width="100%"
       alt="Stata MCP Server — 让 Claude Agent 直接驱动 Stata：一个持久会话跑完加载、建模、诊断、导出。示例展示真实回归输出 regress price weight mpg，weight 系数 1.7466，R²=0.293，N=74。">
</p>

<p align="center">
  <a href="https://www.stata.com"><img src="https://img.shields.io/badge/Stata-Now%2019.5%20MP-1a476f" alt="Stata"></a>
  <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10+-4a90d9" alt="Python"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-stdio-f4a259" alt="MCP"></a>
  <img src="https://img.shields.io/badge/tools-75-6fcf97" alt="75 tools">
  <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT">
</p>

在 Claude Code 里用自然语言做 Stata 分析。你描述要什么，Agent 自己写命令、执行、
读结果、继续下一步 —— 加载数据、清洗、建模、诊断、导出，全在**一个持久的 Stata
会话**里完成，数据不用反复载入。

## 一句话，跑完整个分析

> **你：** 加载 auto.dta，用 weight 和 mpg 回归 price，并检查异方差

**Agent 自动完成（无需你写任何 Stata 命令）：**

```text
stata_use_dataset("auto.dta")          →  74 obs, 12 vars 已载入
stata_regress("price", "weight mpg")   →  R² = 0.293 ; weight 1.75 (p=0.008)
stata_run("estat hettest")             →  Breusch–Pagan χ² 检验异方差
stata_graph("rvfplot", export="…png")  →  残差图导出为文件
```

数据从第一步起就留在内存里，后面每一步都接着用 —— 这正是 `stata_run("regress …")`
之外还值得有一个 MCP Server 的原因。

## 这是什么

两部分组成，一起装进 Claude Code：

- **执行层（MCP Server）** —— 经 `pystata` 直接调用 Stata 的运行时，把 75 个工具
  暴露给 Agent。`stata_run` 执行任意命令、`stata_help` 查任意命令的官方语法，二者
  合起来即「全量内置命令支持」；其余专用工具（回归 / 面板 / IV / 生成变量 / 数据
  清洗 / 后估计 / 文件资源 / 后台任务 …）是给高频命令加结构化参数与校验的便利层。
- **知识层（Skill）** —— 一份 Stata 编程指南：语法要点、分析模板、常见陷阱、命令
  地图与常用外置包。Agent 据此知道**该用什么命令**，而不是靠猜。

## 为什么是 pystata，而不是 subprocess

`pystata` 通过 ctypes 在**进程内**加载 Stata 运行时，而非每条命令起一个子进程：

- **真会话持久** —— Stata 在 MCP Server 启动时初始化一次，数据集、估计结果、局部
  宏在所有工具调用之间保持。多步分析（加载 → 清洗 → 回归 → 诊断）就是自然的对话。
- **低延迟** —— 无进程启动开销，单条命令约 12ms。
- **输出可控** —— 直接读 Stata 输出缓冲；大输出自动分页（`stata_more` 翻页），
  硬上限 120K 字符防止撑爆 MCP 通道；长命令有 60s 超时看门狗（可显式调大）。

## 架构

<p align="center">
  <img src="./assets/readme/workflow.svg" width="100%"
       alt="架构图：Claude Agent 同时使用 stata Skill（知识层）与 MCP Server（执行层）；MCP 经 pystata 的 ctypes 直连调用 Stata DLL；所有工具共享一个持久会话，数据在 use → regress → predict → export 之间保持不变。">
</p>

## 快速开始

### 前置条件

- **Stata**：StataNow 19 或 Stata 18+（MP / SE / BE 均可）——需含 `utilities/pystata`
- **Python** 3.10+（推荐 3.12+）
- **Claude Code** 最新版
- **操作系统**：Windows 或 macOS（见下方「兼容性」）

### 一键安装

```bash
git clone https://gitea.aliveranme.space/aliveranme/stata-mcp.git
cd stata-mcp
python setup.py
```

> 装在非标准位置（如外置卷 `/Volumes/xxx/Applications/StataNow`）时自动检测会失败 ——
> 先 `export STATA_HOME=/你的/Stata路径` 再跑 `setup.py` 即可。

`setup.py` 会：检测 Stata 安装（常见路径 + `STATA_HOME` 环境变量，跨平台）→
创建虚拟环境并安装 `fastmcp` → 生成 `.mcp.json`（保留你已有的其他 MCP Server 配置）
→ 验证 Server 可启动。

<details>
<summary><b>手动安装（自动检测失败时）</b></summary>

```bash
# 1. 指定 Stata 路径（替换为你本机实际路径）
export STATA_HOME="C:/Program Files/StataNow/StataNow19"   # Windows
# export STATA_HOME="/Applications/Stata"                  # macOS
export STATA_EDITION=mp                                     # mp / se / be

# 2. 建虚拟环境并装依赖
cd mcp-stata-server
uv venv
source .venv/Scripts/activate      # Windows Git Bash
# source .venv/bin/activate        # macOS / Linux
uv pip install "fastmcp>=3.2.0"

# 3. 生成配置
cd ..
cp .mcp.json.example .mcp.json     # 编辑其中的 <repo-path>
```
</details>

### 通过 npm 安装（无需 clone 仓库）

若你已有 Node.js ≥ 18 与 `uv`（无 uv 时需 Python 3.10+ 且已装 `fastmcp>=3.2.0`），可直接使用已发布的
npm 包 `@aliveranme/stata-mcp`：

```bash
export STATA_HOME="/你的/Stata路径"     # 含 utilities/pystata
export STATA_EDITION=mp

# 直接跑通（首次启动经 uv 拉取 fastmcp，请给客户端 90s 超时）
npx -y @aliveranme/stata-mcp
```

Claude Code `.mcp.json` 配置：

```json
{
  "mcpServers": {
    "stata": {
      "command": "npx",
      "args": ["-y", "@aliveranme/stata-mcp"],
      "env": { "STATA_HOME": "/Applications/StataNow", "STATA_EDITION": "mp" }
    }
  }
}
```

> `npx @aliveranme/stata-mcp` 与 `npx stata-mcp-server`（bin 名）等价，二者都触发同一个启动器。

### 连接并验证

重启 Claude Code（或 `/reload-plugins`），`.mcp.json` 里的 `stata` Server 会自动连接。
然后在对话里直接说：

> 帮我加载 auto.dta 并做描述统计

Agent 会自动走 `stata_use_dataset` → `stata_describe` → `stata_summarize`。

### 各 Agent 安装教程

除 Claude Code 外，本 MCP 可接入所有支持 MCP 的客户端/Agent。逐平台教程见
[`docs/agent-setup/`](docs/agent-setup/README.md)：

| Agent / 客户端 | 配置位置 | 教程 |
|------|----------|------|
| Claude Code | `.mcp.json` / `claude mcp add` | [claude-code.md](docs/agent-setup/claude-code.md) |
| Claude Desktop | `claude_desktop_config.json` | [claude-desktop.md](docs/agent-setup/claude-desktop.md) |
| Cursor | `.cursor/mcp.json` | [cursor.md](docs/agent-setup/cursor.md) |
| Cline / Roo Code / Continue / Zed / Windsurf | 通用 `mcpServers` schema（Zed 用 `context_servers`） | [other-clients.md](docs/agent-setup/other-clients.md) |

> 插件 / 扩展市场分发（Claude Code 插件、Cursor 扩展、Claude Desktop `.mcpb`）的可行性
> 评估见 [plugin-distribution.md](docs/agent-setup/plugin-distribution.md)。

## MCP 工具（75 个）

> 能力边界不在工具数量上：`stata_run` + `stata_help` 已覆盖全部内置命令。下面的
> 专用工具是给高频命令加结构化参数与校验的便利层。

| 类别 | 工具 |
|------|------|
| **核心执行** | `stata_run`（任意命令，含危险前缀拦截；`save_output=` 完整输出落盘并登记为资源）· `stata_run_do_file`（执行前自动拆出 `ssc install` 单独安装，已装跳过） |
| **数据管理** | `stata_use_dataset` · `stata_import`（excel/csv/sas/spss/dbase/parquet）· `stata_use_example`（sysuse/webuse）· `stata_save_dataset` · `stata_set_cwd` · `stata_generate` · `stata_egen` · `stata_xtset`（面板/时序声明） |
| **数据重构 / 校验** | `stata_merge` · `stata_append` · `stata_reshape` · `stata_collapse` · `stata_frame`（多数据集）· `stata_verify`（count/assert/duplicates/isid/missing）· `stata_replace` · `stata_drop` · `stata_keep` · `stata_rename` · `stata_recode` · `stata_destring` |
| **数据探索** | `stata_describe` · `stata_codebook` · `stata_summarize` · `stata_list` · `stata_tabulate` · `stata_correlate` · `stata_display` |
| **估计** | `stata_regress` · `stata_logistic` · `stata_probit` · `stata_poisson` · `stata_ttest` · `stata_xtreg` · `stata_ivregress` · `stata_logit` · `stata_mlogit` · `stata_nbreg` · `stata_qreg` · `stata_mixed` |
| **后估计** | `stata_margins` · `stata_test` · `stata_predict` · `stata_estat`（vif/hettest/ovtest/ic）· `stata_estimates`（存取与并排比较）· `stata_lincom` · `stata_nlcom` · `stata_hausman` · `stata_return_list` |
| **图形 / 导出** | `stata_graph`（导出即验证文件写入）· `stata_scheme`（主题）· `stata_export_excel` · `stata_export_delimited` · `stata_etable`（回归表直出 Word/Excel） |
| **文件资源回传** | `stata_list_resources` · `stata_read_file`（info/base64）· `stata_register_file` —— 导出产物经资源协议（`resources/read` 读 `stata-file:///`）取回二进制 |
| **包管理与帮助** | `stata_help`（查任意命令帮助）· `stata_install_package` · `stata_uninstall_package` · `stata_describe_package` · `stata_find_package` · `stata_list_packages` |
| **会话生命周期** | `stata_clear`（scope 重置）· `stata_snapshot`（save/list/restore/erase）· `stata_more`（翻页）· `stata_status` · `stata_ping` |
| **长任务控制** | `stata_background`（后台执行，单块上限 3600s）· `stata_task_status` · `stata_task_cancel` · `stata_task_result` · `stata_task_list` |
| **服务器日志** | `stata_read_log`（tail/path） |

<details>
<summary><b>各工具的参数与说明</b></summary>

**数据管理** — `stata_use_dataset` 加载 .dta（可只载入子集）；`stata_import` 覆盖官方
import 命令族，按扩展名推断格式；`stata_save_dataset` 保存；`stata_set_cwd` 改工作目录；
`stata_generate` / `stata_egen` 创建变量（支持官方 `[type]` 存储类型与 `[if] [in]`）；
`stata_xtset` 声明面板 / 时序结构 —— 它是 `stata_xtreg` 的前提。

**数据探索** — `stata_summarize` / `stata_codebook` / `stata_list` / `stata_tabulate`
均支持 `condition`；`stata_correlate` 可选 `pairwise` 走 `pwcorr`；`stata_display`
算表达式 / 看返回值。

**估计** — `stata_regress`（OLS）、`stata_logistic`、`stata_probit`（可选
`marginal_effects`）、`stata_poisson`（可选 `irr`）、`stata_ttest`（可按组）、
`stata_xtreg`（`effects` = fe/re/be/mle/pa，需先 `xtset`）、`stata_ivregress`
（2sls/liml/gmm）。扩展族：`stata_logit`（报告原始系数，OR 用 `logistic`）、
`stata_mlogit`（多分类，`baseoutcome` 定基准）、`stata_nbreg`（负二项）、
`stata_qreg`（分位，`quantile` 默认 0.5）、`stata_mixed`（多水平，`random="|| id:"`）。

**数据清洗** — `stata_replace` 覆盖变量值、`stata_drop`/`stata_keep` 删/留变量或观测
（两种形态二选一）、`stata_rename` 重命名（单个或批量）、`stata_recode` 重编码
（`values="(1=0) (2/4=1)"` 官方规则组）、`stata_destring` 字符串转数值（必须
`replace=True` 或 `generate()`）。

**后估计**（须先跑估计命令）— `stata_margins`（`dydx` / `at`）、`stata_test`
（Wald 检验）、`stata_predict`（预测值 / 残差，会创建变量）、`stata_lincom` /
`stata_nlcom`（线性 / 非线性组合检验）、`stata_hausman`（模型比较，需先
`stata_estimates action="store"` 存两个模型）。

**图形 / 导出** — `stata_graph` 把 graph 与 export 原子执行，以文件是否真被写入判定
成败。导出选项按格式自动适配官方边界：尺寸单位（位图与 svg 用像素、pdf 用英寸、
eps/ps/emf 不支持）、`quality`（仅 jpg）、`mag`（仅 pdf/eps/ps）、`fontface`
（仅矢量格式）—— 不适用的选项被丢弃并在返回信息中说明，而非让 Stata 静默失败。
`stata_scheme` 列出 / 查询 / 设置主题（不传 `scheme` 时**不会**改动你当前的主题）。
`stata_export_excel` 导数据为 .xlsx（支持 `sheet_mode` / `cell` / `firstrow` /
`if`-`in` 筛选）；`stata_export_delimited` 导 CSV / TSV / 自定义分隔符。
**回归表**用 `stata_etable`（官方 `etable`，Stata 17+，无第三方依赖）：
`estimates="m1 m2 m3"` 并排多模型，直出 .docx / .xlsx / .pdf / .tex / .html / .md，
并以文件是否真被写入判定成败 —— `etable` 会先把表打印出来再报导出错误，只看输出
很容易把失败当成功。

**包管理与帮助** — `stata_help("命令")` 查任意内置 / 已装外置命令的官方语法；
`stata_find_package` 走 `net search` 联网找包；`stata_install_package` 装（ssc 或 URL）；
`stata_uninstall_package` 卸载（`ado uninstall`，纯本地）；`stata_describe_package`
查包详情（默认本地 `ado describe`，`source="ssc"` 走联网 `ssc describe` 供装前了解）；
`stata_list_packages` 列已装。

**会话** — `stata_more` 翻上一条命令的完整输出；`stata_status` 一次给出数据集、工作目录、
**frame**、**面板/时序设定**、**已存与活跃的估计结果**、内存 —— 即 Agent 调 `xtreg` /
`margins` / `predict` 前需要确认的全部前提；`stata_ping` 心跳。`stata_clear` 按 scope
重置会话（data/estimates/graphs/panels/all）；`stata_snapshot` 用 Stata 原生快照在数据
阶段间快速回退（save/list/restore/erase）。

**文件资源回传** — 导出工具（`stata_graph` / `stata_export_*` / `stata_etable` /
`stata_save_dataset` / `stata_run save_output=`）成功后把文件登记为 MCP 资源。远程
客户端经 `resources/read` 读 `stata-file:///<路径>` 取回图表 / Excel / CSV / dta 的
二进制，或 `stata_read_file` 取 base64 / 元信息；`stata_list_resources` 列出全部登记
文件，`stata_register_file` 登记已有的磁盘文件。安全边界：**只读登记过的文件**。

**长任务控制** — `stata_background` 把耗时长命令放到后台（立即返回任务号，单块超时
上限 3600s，运行期间其他调用会等待共享的 `_stata_lock`）；`stata_task_