sepinetam/mcp-for-stata/diagnostic-dofile

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.