MCP工具

同时安装 MCP server 和 Jupyter kernel 的额外依赖

pip install "stata-code[mcp,kernel]"

安装

要求：Python 3.10+，外加以下任一种 Stata —— Stata 17+（用其自带的 pystata， 支持内存内会话），或 Stata 13+（走 console 后端，不需要 pystata，无状态）。

```bash

从 PyPI 安装

pip install stata-code

或者从源码安装（开发用 editable install）

git clone https://github.com/brycewang-stanford/stata-code.git cd stata-code pip install -e ".[mcp,kernel]"

> **命名说明。** PyPI 上的发行包名是 `stata-code`（带连字符），
> 但 Python 导入名是 `stata_code`（下划线 —— Python 标识符不能包含连字符）。
> 和 `scikit-learn` → `import sklearn` 是同样的约定。
> 所以：`pip install stata-code`，`from stata_code import run`。

注意：`pystata` **不在 PyPI 上**，它随 Stata 一起安装。`stata-code` 会自动在 macOS 的 `/Applications/Stata/utilities/pystata` 以及 Linux / Windows 的对应位置寻找它。如果你的 Stata 安装在其他位置，请在导入前把 `pystata` 加到 `PYTHONPATH`。

安装后可以用只读 doctor 检查本机环境：

doctor 会报告 package/Python 版本、MCP 和 Jupyter extras、pystata 发现结果、 PATH 上的 console scripts、常见项目级/用户级 MCP client 配置文件、 client/VS Code 配置提示，以及 best-effort 的 Stata 版本/edition 探测。它不会 改 shell、Stata、Claude、Cursor 或 VS Code 配置。

---

快速开始

完整 cookbook 在 examples/：基础回归、DiD、图形、多 session、大矩阵。

user scope —— 一次安装，本机所有 Claude Code workspace 全局可用

claude mcp add stata-code --scope user -- stata-code-mcp

1. 安装带 kernel extra 的 stata-code（会同时装上 ipykernel）

pip install "stata-code[kernel]"

python -m stata_code.kernel install --user

检查 kernel 是否注册成功：

从命令行使用（Bash）

任何能 shell out 的 agent 或脚本都能用上同一套结构化引擎 —— 不需要 MCP。 stata-code run 可以执行 .do 文件、一个或多个 -e 片段，或从 stdin 读入的代码， 并打印 RunResult：

stata-code run analysis.do                  # 跑 do 文件，输出文本摘要
stata-code run -e "sysuse auto" -e "regress mpg weight"
stata-code run analysis.do --json           # 完整 RunResult JSON（给 agent 用）
echo "summarize price" | stata-code run -    # 从 stdin 读代码
stata-code run model.do --graphs out/        # 同时把图形导出到 out/
stata-code run job.do --session modelA --timeout-ms 120000

成功退出码是 0，Stata / adapter 出错时是 1，因此可以直接接进 CI 和"改了再跑"的 脚本循环。stata-code lint analysis.do 则在完全不启动 Stata 的前提下做静态检查 （大括号不配对、缺 end、悬空的 ///）。

后端 —— Stata 13+ 且没有 pystata。 --backend 决定代码怎么跑：pystata （Stata 17+，内存内会话）、console（Stata 13+ 批处理，不需要 pystata，无状态）， 或 auto（默认：有 pystata 就用，否则退到 console）。console 后端驱动 Stata 的命令行 可执行文件，并把日志解析成同样的带类型 RunResult —— 带类型的 r()/e()、估计表、 以及错误分类 —— 所以老版本 Stata 和无 pystata 的环境同样是一等公民：

stata-code run analysis.do --backend console
export STATA_CODE_STATA_CLI=/usr/local/stata18/stata-mp   # 自动找不到时手动指定

零 Python 二进制。 独立的 stata-code 可执行文件（由 scripts/build_standalone.py 构建，现成的 CI workflow 模板见 packaging/standalone.github-workflow.yml） 把运行时一起打包，不需要安装 Python。配合 --backend console，这就是一条完全不依赖 Python、又能拿到带类型 Stata 结果的路径。

一条命令配置客户端

stata-code setup 把 MCP server 条目写进客户端配置 —— 它是只读的 doctor 那个 「会改文件」的对应物。它会保留配置里其他的 server，并在覆盖任何文件之前先做备份：

stata-code setup --all                 # Claude Code、Cursor、VS Code（project scope）
stata-code setup --claude --dry-run    # 只预览，不写入
stata-code setup --vscode --python .venv/bin/python   # 指定解释器
stata-code setup --codex               # 打印可复制粘贴的 TOML 片段

local scope —— 仅当前 workspace（本地 Claude 配置，不会提交到仓库）

claude mcp add stata-code --scope local -- stata-code-mcp

作为 VS Code 扩展

配套扩展已发布到 Marketplace：brycewang-stanford.stata-code-vscode。它会以子进程方式启动 stata-code-mcp，并提供语法高亮、**# section 和 program define 的 Outline、.do 文件的 code-lens "Run cell" / "Run section"、七视图侧边栏（sessions / last result / data 变量浏览器 / run history / logs / graphs / outputs）——其中包含一个 agent-native 版的 Stata 变量窗口，以及一个把每次运行写到磁盘的 esttab 表格和 export 文件呈现出来的 Outputs 面板——状态栏指示器、补全、帮助跳转、保守变量重命名，以及来自 v1.0 typed errors 的内联诊断。

```bash

从 VS Code 命令行

code --install-extension brycewang-stanford.stata-code-vscode ```

或者打开 VS Code 的 Extensions 侧栏，搜索 stata-code。扩展同时发布在 Open VSX，因此 Cursor、Windsurf 等 VS Code 兼容编辑器不必经过微软 Marketplace 也能安装。

首次激活时，扩展会在 PATH（以及 workspace 下的 .venv / venv）里探测 stata-code-mcp。如果找不到，会弹出一次性的安装提示，附上准确的 pip install "stata-code[mcp]" 命令——选择 Don't show again 可对当前扩展版本永久静默。

扩展仍然依赖系统 Python 上安装了 MCP extra（pip install "stata-code[mcp]"），从而保证 stata-code-mcp 在 PATH 上可用，并且能导入 MCP SDK。和其它前端一样，需要 Stata 17+ 和有效的 Stata 许可证。

Cell 与 section 约定

扩展识别 .do 文件里两类互补的结构标记。二者可以混用在同一个文件里，互不冲突：

program define … end 代码块也会出现在 Outline 里，嵌套在所属 section 之下。

如果扩展或 MCP client 找不到 server，请在同一个 Python 环境里运行 stata-code doctor --no-stata-probe。它会报告 stata-code-mcp 是否在 PATH 上，并提示 GUI client 常见的绝对路径或 python -m stata_code.mcp 兜底配置。它也会读取当前 workspace 和用户目录里常见的 MCP 配置文件，告诉你 client 是否已经指向 stata-code。

---

对比

stata-code 是这个问题空间里更年轻的、MIT 许可证的、agent-native 的替代方案。AGPL 方案里，SepineTam 的 stata-mcp 目前更成熟；stata-code 的目标是服务那些不能接受 copyleft 传染、又需要结构化智能体接口的场景。