Skip to content

MCP.Resources

Stata-MCP provides MCP resources for accessing Stata documentation and help contents.

help

Platform Support: macOS and Linux only (Windows not supported)

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

Resource URI: help://stata/{cmd}

Input Parameters: - cmd: Stata command name (required, e.g., "regress", "describe", "xtset", "merge")

Return Structure: String containing Stata help text output. May include cache status prefix: - "Cached result for {cmd}\n{help_text}" - Retrieved from cache - "Saved result for {cmd}\n{help_text}" - Retrieved from project cache - "{help_text}" - Fresh result from Stata - "No help found for the command in Stata ado locally: {cmd}" - Command not found

Operational Examples:

# Regression commands
help("regress")
help("logit")
help("probit")

# Panel data commands
help("xtset")
help("xtreg")
help("xtmixed")

# Data management
help("merge")
help("reshape")
help("collapse")

# Time series
help("tsset")
help("arima")
help("varsoc")

Implementation Architecture:

The help resource implements a dual-registered pattern in the MCP framework, functioning as both a resource (URI-addressable via help://stata/{cmd}) and an executable tool. This dual registration enables flexible access patterns: clients can either invoke it as a standard tool or access it via the resource protocol.

The StataHelp class manages help text retrieval with a three-tier caching strategy:

  1. Project-level Cache (STATA_MCP_SAVE_HELP, default: true):
  2. Stores help text in stata-mcp-tmp/help__{cmd}.txt
  3. Persists across sessions within the project directory

  4. Highest priority for retrieval

  5. Global Cache (STATA_MCP_CACHE_HELP, default: false):

  6. Stores help text in ~/.statamcp/help/help__{cmd}.txt
  7. Shared across all projects

  8. Secondary priority if project cache miss

  9. Live Stata Execution:

  10. Invokes Stata CLI with help {cmd} command
  11. Captures stdout for return value
  12. Falls back to this tier when both caches miss

Cache Invalidation: No automatic TTL-based expiration exists. Cache invalidation requires: - Manual deletion of cache files (rm ~/.statamcp/help/help__{cmd}.txt) - Setting environment variable STATA_MCP_CACHE_HELP=false to disable caching - Setting environment variable STATA_MCP_SAVE_HELP=false to disable project-level caching

Error Detection: The help system detects command existence by comparing Stata output against a standard error message template:

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

If the output matches this pattern, the system raises an exception indicating the command is not found in locally installed ado-files. This behavior occurs after cache miss and before caching new results.

Platform Considerations: - macOS/Linux: Full support with caching and live Stata execution - Windows: Not supported due to Stata CLI limitations on Windows platforms

Performance Optimization: For frequently accessed commands (e.g., regress, xtreg), enable STATA_MCP_CACHE_HELP=true to avoid repeated Stata invocations. The first execution queries Stata (~50-200ms depending on Stata startup time), subsequent queries return from cache (~1-5ms file read).

Usage Notes: - Help text language depends on the Stata installation locale - Multilingual support requires separate Stata installations or locale reconfiguration - Cache files are plain text UTF-8 encoded, allowing manual inspection or editing - The resource URI pattern help://stata/{cmd} enables programmatic access via MCP resource protocol

Environment Variables:

Variable Default Description
STATA_MCP_CACHE_HELP false Enable global caching at ~/.statamcp/help/
STATA_MCP_SAVE_HELP true Enable project-level caching at stata-mcp-tmp/

Integration with Tools: The help resource integrates with Stata-MCP tools in several workflows: - Pre-execution validation: Check command syntax before generating do-files - Error diagnosis: Understand error messages from Stata execution - Learning assistance: Provide contextual help during analysis sessions - Code completion: Suggest valid command options and syntax

Example Workflow:

# 1. Check if a command exists
help_result = help("ivregress2")
if "not found" not in help_result:
    # 2. Generate do-file using the command
    write_dofile("ivregress2 y x1 x2, robust")

    # 3. Execute the do-file
    stata_do("/path/to/do/file")