stata-mcp

# 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>

数据管理 — 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_status 查进度、 stata_task_cancel 显式取消、stata_task_result 取结果、stata_task_list 列全部。 stata_read_log 读本服务器运行日志排查问题。

# 调试模式启动 Server
cd mcp-stata-server
source .venv/bin/activate          # 或 .venv/Scripts/activate (Windows)
python server.py

# 单元测试（无需 Stata）
python -m pytest tests/ -q

# 端到端测试（需真实 Stata；未检测到安装时整目录跳过；网络用例需可访问 Stata 官网）
# 必须与 tests/ 分开跑：tests/conftest.py 会把 pystata 换成 mock，同进程内换不回来
STATA_HOME=/path/to/StataNow python -m pytest tests_e2e/ -q

# lint
python -m ruff check server.py tests/ tests_e2e/
python -m ruff check --config pyproject.toml ../setup.py

# 添加依赖
uv pip install <package>
uv pip freeze > requirements.txt