MCP.Resources

Stata-MCP 提供用于访问 Stata 文档和帮助内容的 MCP 资源。

---

help

平台支持：仅限 macOS 和 Linux（不支持 Windows）

@stata_mcp.resource(
    uri="help://stata/{cmd}",
    name="help",
    description="Get help for a Stata command"
)
def help(cmd: str) -> str:
    ...

资源 URI：help://stata/{cmd}

输入参数： - cmd：Stata 命令名（必填，如 "regress"、"describe"、"xtset"、"merge"）

返回结构： 包含 Stata 帮助文本输出的字符串。可能包含缓存状态前缀： - "Cached result for {cmd}\n{help_text}" - 从缓存检索 - "Saved result for {cmd}\n{help_text}" - 从项目缓存检索 - "{help_text}" - 来自 Stata 的新结果 - "No help found for the command in Stata ado locally: {cmd}" - 命令未找到

操作示例：

# 回归命令
help("regress")
help("logit")
help("probit")

# 面板数据命令
help("xtset")
help("xtreg")
help("xtmixed")

# 数据管理
help("merge")
help("reshape")
help("collapse")

# 时间序列
help("tsset")
help("arima")
help("varsoc")

实现架构：

帮助资源在 MCP 框架中实现双重注册模式，既作为资源（可通过 help://stata/{cmd} 以 URI 寻址）又作为可执行工具。这种双重注册启用灵活的访问模式：客户端可以将其作为标准工具调用，或通过资源协议访问。

StataHelp 类通过三层缓存策略管理帮助文本检索：

1. 项目级缓存（STATA_MCP_SAVE_HELP，默认：true）：
2. 将帮助文本存储在 stata-mcp-tmp/help__{cmd}.txt
3. 在项目目录内跨会话持久化

4. 检索优先级最高

5. 全局缓存（STATA_MCP_CACHE_HELP，默认：false）：

6. 将帮助文本存储在 ~/.statamcp/help/help__{cmd}.txt
7. 在所有项目间共享

8. 项目缓存未命中时的次要优先级

9. 实时 Stata 执行：

10. 以 help {cmd} 命令调用 Stata CLI
11. 捕获 stdout 作为返回值
12. 当两层缓存都未命中时回退到此层

缓存失效： 不存在自动的基于 TTL 的过期。缓存失效需要： - 手动删除缓存文件（rm ~/.statamcp/help/help__{cmd}.txt） - 设置环境变量 STATA_MCP_CACHE_HELP=false 以禁用缓存 - 设置环境变量 STATA_MCP_SAVE_HELP=false 以禁用项目级缓存

错误检测： 帮助系统通过将 Stata 输出与标准错误消息模板比较来检测命令是否存在：

help {cmd}
help for {cmd} not found
try help contents or search {cmd}

如果输出匹配此模式，系统抛出异常，指示命令在本地安装的 ado 文件中未找到。此行为在缓存未命中后、缓存新结果之前发生。

平台考虑： - macOS/Linux：完全支持缓存和实时 Stata 执行 - Windows：由于 Windows 平台上 Stata CLI 的限制而不支持

性能优化： 对于频繁访问的命令（如 regress、xtreg），启用 STATA_MCP_CACHE_HELP=true 以避免重复的 Stata 调用。首次执行查询 Stata（约 50-200ms，取决于 Stata 启动时间），后续查询从缓存返回（约 1-5ms 文件读取）。

使用说明： - 帮助文本语言取决于 Stata 安装区域设置 - 多语言支持需要单独的 Stata 安装或区域设置重新配置 - 缓存文件是纯文本 UTF-8 编码，允许手动检查或编辑 - 资源 URI 模式 help://stata/{cmd} 通过 MCP 资源协议启用程序化访问

环境变量：

变量	默认值	描述
STATA_MCP_CACHE_HELP	false	在 ~/.statamcp/help/ 启用全局缓存
STATA_MCP_SAVE_HELP	true	在 stata-mcp-tmp/ 启用项目级缓存

与工具的集成： 帮助资源在多种工作流程中与 Stata-MCP 工具集成： - 执行前验证：在生成 do 文件前检查命令语法 - 错误诊断：理解 Stata 执行中的错误消息 - 学习辅助：在分析会话期间提供上下文帮助 - 代码补全：建议有效的命令选项和语法

示例工作流程：

# 1. 检查命令是否存在
help_result = help("ivregress2")
if "not found" not in help_result:
    # 2. 使用该命令生成 do 文件
    write_dofile("ivregress2 y x1 x2, robust")

    # 3. 执行 do 文件
    stata_do("/path/to/do/file")

---