opalus12138/spss-mac-mcp/spss-analyst

SPSS Analyst

Workflow

1. Check capabilities — Call spss_check_status first to confirm SPSS batch is available.
2. Explore the data — For any .sav file, call spss_file_summary or spss_read_metadata to know variable names, types, and labels before writing syntax.
3. Run a smoke test before heavy or uncommon analysis — If the target procedure is cold-path, high-cost, or unfamiliar, first run a minimal baseline such as DESCRIPTIVES, FREQUENCIES, or DISPLAY DICTIONARY.
4. Write syntax — Follow conventions below. See references/spss-syntax.md for full command reference.
5. Execute defensively — Use the appropriate MCP tool when one exists; otherwise use spss_run_syntax and add optional subcommands only after the minimal command works.
6. Read warnings, not just success flags — A run may return output and still contain critical warning text. Treat SPSS warning blocks as syntax guidance.
7. Interpret — Explain key results in plain language after output arrives.
8. Archive output — After every analysis tool call that produces a Viewer file:, immediately archive results to spss_result/. See Output Archiving below.

Reliability Rules

• Never guess variable names or data shape.
• Never jump directly to a complex procedure on the first try.
• For uncommon methods, start with the smallest valid syntax and then add print/save options.
• If SPSS says a keyword is unrecognized, rewrite the syntax to match the reported valid keywords.
• If timeout behavior looks stale, verify that repo-local .env is actually being loaded and restart the MCP session if needed.

Core Syntax Rules

Standard File Header

Always begin a syntax block with:

* ============================================================
* 分析目的: [简述目的]
* 数据文件: [文件路径]
* 日期: [YYYY-MM-DD]
* ============================================================
 
GET FILE='C:/Data/myfile.sav'.

Common Procedure Patterns

* 频率表 + 描述统计
FREQUENCIES VARIABLES=var1 var2
  /STATISTICS=MEAN MEDIAN MODE STDDEV
  /ORDER=ANALYSIS.
 
* 描述统计（仅连续变量）
DESCRIPTIVES VARIABLES=score age income
  /STATISTICS=MEAN STDDEV MIN MAX VARIANCE.
 
* 独立样本 t 检验
T-TEST GROUPS=gender(1 2)
  /VARIABLES=score.
 
* 单因素方差分析
ONEWAY score BY group
  /STATISTICS DESCRIPTIVES
  /POSTHOC=TUKEY ALPHA(.05).
 
* 线性回归
REGRESSION
  /DEPENDENT score
  /METHOD=ENTER age edu income.
 
* 交叉表 + 卡方
CROSSTABS
  /TABLES=gender BY jobcat
  /STATISTICS=CHISQ
  /CELLS=COUNT ROW COLUMN.
 
* 计算新变量
COMPUTE bmi = weight / (height * height).
VARIABLE LABELS bmi '体质指数'.
EXECUTE.
 
* 变量重新编码
RECODE age (18 THRU 35=1)(36 THRU 55=2)(56 THRU HI=3) INTO age_group.
VALUE LABELS age_group 1'青年' 2'中年' 3'老年'.
EXECUTE.

Advanced Procedure Guardrails

• For PROXSCAL / MDS, do not assume keywords like SYMMETRIC, EUCLID, or CONFIGURATION are valid in the installed syntax variant without testing.
• Start with a smoke test, then a minimal valid target procedure, then add richer output requests.
• For timeout vs syntax ambiguity, prove the environment with a baseline command first.

Output Archiving

After every mcp__spss__* tool call that produces output (i.e., result contains Viewer file:), immediately:

1. Ensure directory exists

mkdir -p <cwd>/spss_result

2. Determine next sequence number — Glob spss_result/[0-9][0-9]_*, take max prefix + 1 (start at 01).

3. Map tool → type label

4. Copy .spv — Extract path after Viewer file: from tool result, copy to spss_result/NN_<label>.spv. Skip if path missing.

5. Write .sps — Create spss_result/NN_<label>.sps with header block + full syntax:

************************************************************
* 文件名：NN_<label>.sps
* 分析类型：<中文全称>
* 数据文件：<.sav 路径>
* 因变量 / 预测变量 / 分组变量：<变量名>（若适用）
* 关键参数：<聚类数、事后检验、CI水平等>
* 缺失值处理：<LISTWISE / PAIRWISE>
* 执行日期：<YYYY-MM-DD>
************************************************************
<完整 SPSS 语法>

Constraints: sequence number is global (not per-type); parallel tool calls each get their own number; read-only tools (spss_list_files, spss_file_summary, spss_import_csv, spss_check_status, etc.) do not trigger archiving.

Reference Files

• [references/spss-syntax.md](references/spss-syntax.md) — Full command reference: all procedures, data management, variable operations, SELECT IF, SORT, MERGE, OMS. Load when writing unfamiliar or complex commands.
• [references/spss-mcp-tools.md](references/spss-mcp-tools.md) — All MCP tools with parameters and when to use each. Load when choosing which tool to call.
• [references/failure-patterns.md](references/failure-patterns.md) — Read when diagnosing timeouts, invalid keywords, stale .env behavior, success=True with warnings, or advanced procedure incompatibilities.