Skip to content

SepineTam/mcp-for-stata / plugins/stata-toolbox/skills/diagnostic-dofile

diagnostic-dofile

Verified

Use this skill when the user needs to inspect, audit, or diagnose the safety of a Stata do-file. Typical scenarios include: uncertainty about whether a .do file is safe; receiving a complete do-file from an unofficial source (not the Stata website, not a well-known academic institution or professor's official site); asking to check a batch of do-files; or requesting a read-only security/risk/portability diagnostic report. The skill does not modify the original file; it only emits a JSON report. Note that this is not a mandatory step for every do-file; run it only when a security review is warranted.

Diagnostic do-file

This skill inspects a Stata do-file without changing the original file and outputs a JSON diagnostic report. The underlying script reuses stata_mcp.utils.parse_dofile and stata_mcp.guard.blacklist, so it handles Stata command abbreviations, prefixes (capture / quietly), macro expansion, block comments, #delimit ;, and other common constructs.

When to use

Recommended situations:

  • You receive a complete do-file from an unknown or unofficial source, especially one downloaded from outside the Stata website or well-known academic/professor sites.
  • The code arrives as an email attachment, cloud-drive link, forum post, or chat message, and you want to verify that it contains no dangerous commands or data-overwrite risks.
  • Before taking over or reproducing someone else's project, you want to audit the key do-files.
  • You explicitly want a read-only diagnostic report covering security, portability, encoding, and other dimensions.

This skill is not required every time you write a do-file. For analysis code you wrote yourself, understand, and trust, you can run it directly without generating a diagnostic report each time.

How to run

uv run plugins/stata-toolbox/skills/diagnostic-dofile/diagnose_dofile.py path/to/file.do

Save the report to a file:

uv run plugins/stata-toolbox/skills/diagnostic-dofile/diagnose_dofile.py path/to/file.do -o report.json

Current checks

1. File metadata

  • File path, size, and modification time.
  • UTC timestamp when the report was generated.
  • SHA-256 hash of the file.

2. Encoding and format

  • UTF-8 or UTF-8 with BOM.
  • Non-UTF-8 encodings such as GBK/GB2312.
  • Line ending: LF, CRLF, or mixed.
  • Empty file or comment-only file.

3. Dangerous commands

Based on src/stata_mcp/guard/blacklist.py:

  • Shell / system commands: !, !!, shell, xshell, winexec, unixcmd.
  • File deletion: erase, rm, rmdir.
  • External code execution: do, run, include.
  • Embedded runtimes: python, mata, java, plugin.
  • Package-management commands: ssc, net, github, adoupdate, update.
  • Working-directory changes: cd, chdir.

4. Data-overwrite risks

  • use xxx.dta followed by save xxx.dta, replace pointing to the same file.
  • Memory-clearing operations such as clear all / drop _all.

5. Output-file overwrite

  • graph export xxx, replace.
  • export xxx, replace.
  • Commands with replace such as outreg2, esttab, estout, putexcel, putdocx, putpdf, logout, texdoc.
  • log using xxx.log, replace.
  • saveold xxx, replace.

6. External commands / user-written packages

  • Recognizes common external commands such as reghdfe, estout, outreg2, esttab, coefplot, ivreg2, rdrobust.
  • Reports them so the caller can run Stata help <command> to verify installation.

7. Paths and portability

  • Absolute paths such as /Users/... or C:\....
  • webuse or network URLs for loading data.
  • cd / chdir working-directory changes.

8. Macro and parsing risks

  • Unresolved macro variables (global macros, local macro expressions, etc.).
  • Unclosed block comments, quotes, or program blocks that may affect parsing reliability.

Report format

The report is a JSON object with the following structure:

{
  "schema_version": "0.1.0",
  "generated_at": "2026-09-22T12:34:56.789012Z",
  "file": {
    "path": "/project/analysis.do",
    "size_bytes": 1234,
    "sha256": "abc123...",
    "encoding": "utf-8",
    "has_bom": false,
    "line_ending": "lf"
  },
  "summary": {
    "total_lines": 100,
    "code_lines": 60,
    "comment_lines": 30,
    "blank_lines": 10,
    "error_count": 2,
    "warning_count": 5,
    "info_count": 3
  },
  "findings": [
    {
      "level": "error",
      "line": 12,
      "category": "dangerous_command",
      "message": "Detected dangerous command 'shell'"
    }
  ]
}

Notes

  • The script only reads the original file and never modifies the do-file content.
  • Findings are for reference only; the final execution decision is yours.
  • For Stata-MCP, dangerous commands are automatically blocked by the security guard during stata_do. To disable the guard, configure ~/.statamcp/config.toml, but this is not recommended.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall