PsychoPy MCP

让 Claude Code / Codex 直接操作并接管 PsychoPy 的 MCP 服务器 —— 用自然语言设计、运行、读取心理学实验，且自动遵循前人文献的范式参数。

Claude/Codex 用自己的文件工具读写实验脚本（.py）；本服务器提供这些工具做不到的 PsychoPy 专属能力：内省、静态校验、运行实验、编译 Builder 文件、驱动常驻交互窗口，以及一套文献校准的经典范式库。

快速上手见 QUICK_START.md，工具清单见 TOOLS_REFERENCE.md。

演示 Demo

一句话「用 Stroop 范式跑个实验再分析」即可走完：生成（文献校准）→ 运行（真实开窗）→ 自动分析出图。

Related MCP server: arXiv Research Assistant MCP Server

架构

Claude Code / Codex
      │  (MCP / stdio JSON-RPC)
      ▼
  psychopy_mcp/server.py  ──FastMCP──┐
      │                              │ subprocess (psychopy venv)
      │   paradigms/  (引擎+14范式)   ├── run_experiment   → 运行 *.py 实验
      │   frontend/   (GUI 启动器)    ├── scaffold_paradigm → 生成文献校准实验
      │   runner/     (常驻窗口)      └── validate / compile / live
      ▼
 .venv (Python 3.10 + PsychoPy 2026.1.3)

• psychopy_mcp/server.py —— MCP 服务器（FastMCP），暴露全部 19 个工具。

• psychopy_mcp/paradigms/ —— 文献校准范式库：共享 engine.py（phase 引擎）+ 每范式一个模块（SPEC + build_trials）+ custom.py（自定义范式）。

• psychopy_mcp/frontend/launcher.py —— Tkinter 桌面启动器：选范式 / 设参数 / 生成并运行 / 新建自定义范式。

• psychopy_mcp/runner/live_session.py —— 常驻子进程，持有 PsychoPy Window，按行收发 JSON，实现"实时接管"。

• workspace/ —— 脚手架/运行/数据的默认工作目录（相对路径解析到这里）。

工具一览

安装

一键（Windows）：

install.bat

创建 .venv、安装 PsychoPy + 本包、并自动注册到 Claude Code。

手动：

python -m venv .venv
.venv\Scripts\python -m pip install -e .
.venv\Scripts\python -m psychopy_mcp.cli configure-claude

项目自带 .mcp.json（用 python -m psychopy_mcp.server 启动），在本目录打开 Claude Code 即自动加载。Codex 用同样的 command/args 即可。CLI 还提供 psychopy-mcp serve|gui|list|configure-claude。

典型工作流

批处理实验（最常用）

env_info()                              # 1. 确认环境
scaffold_experiment("stroop")           # 2. 生成 workspace/stroop.py
   …用文件工具编辑 stroop.py…
validate_script("stroop.py")            # 3. 静态校验
run_experiment("stroop.py")             # 4. 运行（开窗）并收数据
list_data() / read_data("data/xxx.csv") # 5. 看结果

实时接管窗口（边做边看）

live_start(size=[1024,768])
live_cmd("present_text", {"text":"Hello", "wait_keys":["space"]})
live_cmd("present_shape", {"shape":"circle", "size":0.3, "fillColor":"red"})
live_cmd("screenshot", {"filename":"shot.png"})
live_stop()

Builder 文件

read_psyexp("templates/experiment.psyexp")   # 看结构
compile_psyexp("templates/experiment.psyexp") # 编译成 .py 再 run_experiment

文献校准（关键设计）

自然语言搭建实验最大的隐患：模型每次会自己瞎编字号、刺激位置、时序、配色，导致和已发表范式不可比。paradigms/ 把经典范式的规范参数固化下来（含引用），所有条件共享同一套字号与居中位置——拥挤/不一致这类错误从根上不可能出现。

list_paradigms()                    # 看 14 个校准范式
get_paradigm("stroop")              # 看完整规范 + 引用(Stroop 1935; MacLeod 1991)
scaffold_paradigm("stroop", "exp1") # 生成 144 试次平衡版(con=incon=neutral=48)
scaffold_paradigm("nback", "wm1", {"n": 3})   # 可传参数覆盖默认

所有范式都跑在共享的 phase 引擎（paradigms/engine.py）上：每个范式 = 一串 trial，每个 trial = 一串 phase（注视/线索/刺激/反应）。字号、位置、配色统一来自该范式的 SPEC，结构上保证各条件一致。

词汇判断/点探测内置的是小词表，正式研究请替换为 SUBTLEX/ELP 等规范词库；心理旋转默认用 2D 字符变体，需要原版 3D 立方体图请放入图片素材并把刺激改为 kind="image"。

线上实验（Pavlovia / PsychoJS）

只有 Builder .psyexp 能自动转成 JavaScript 在浏览器跑（纯 Coder 脚本不行）。export_web 帮你把范式导出成 .psyexp + .js + 条件文件：

export_web("stroop")   # → workspace/web_stroop/{*.psyexp, *.js, *_conditions.csv}

把该文件夹上传到 Pavlovia（或在 PsychoPy Builder 里 Sync）即可招募线上被试。

目前支持「单文字刺激 + 按键」类范式（Stroop / Flanker / 词汇判断 / 文字类自定义）；含图形/多阶段的范式（Posner/ANT/Simon 等）暂为桌面端。

与 SPSS-MCP 联动（设计→运行→统计 一条龙）

本服务器负责采数据，SPSS-MCP 负责做统计，靠 CSV 衔接。在同一个 Claude 会话里同时配置两个 MCP：

run_experiment("stroop_exp.py")          # 1. 采数据
export_for_spss("data/xxx.csv", aggregate=True)  # 2. 导出 SPSS 可读 CSV
   → 让 SPSS-MCP 导入该 CSV，对 rt_ms 按 condition 跑重复测量 ANOVA   # 3. 出统计

说明 / 限制

• 不是 headless：PsychoPy 基于 GUI，Windows 上运行实验会真实开窗。在带屏幕（或虚拟显示）的机器上跑。

• venv 隔离：服务器与实验都用 .venv\Scripts\python.exe（Python 3.10 + PsychoPy 2026.1.3），不污染系统环境。

• live_cmd exec 是逃生舱：可在窗口进程内执行任意 PsychoPy 代码（作用域含 win, visual, core, event），灵活但需自负其责。

• 一次只允许一个 live 会话；再开需先 live_stop。