SepineTam/mcp-for-stata / plugins/stata-toolbox/skills/diagnostic-dofile
diagnostic-dofile
VerifiedUse 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.dtafollowed bysave xxx.dta, replacepointing 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
replacesuch asoutreg2,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/...orC:\.... webuseor network URLs for loading data.cd/chdirworking-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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |