MCP client ──stdio──▶ python3 -m scratch_unified
                        ├── social_*   website + social graph (scratchattach)
                        ├── project_*  goboscript text-authoring loop
                        ├── spy_*      blocks ↔ real Python (ScratchPy)
                        └── sb3_*      block surgery + headless VM test loop (Node sidecar)

git clone <this-repo> && cd scratch-unified-mcp
pip install -e .
# runtime deps (gitignored reference clones — re-clone to update):
git clone https://github.com/uukelele/scratch-mcp upstream-scratch-mcp
git clone https://github.com/playforge-coding/scratch4js upstream-scratch4js
git clone https://github.com/ZDStudios/scratchpy-studio upstream-scratchpy-studio
# optional, unlocks sb3_* proxy tools:
cd upstream-scratch4js && pnpm install && pnpm build

// MCP client config
{ "mcpServers": { "scratch-unified": {
  "command": "python3",
  "args": ["-m", "scratch_unified"],
  "cwd": "/path/to/scratch-unified-mcp",
  "env": {
    "PYTHONPATH": "/path/to/scratch-unified-mcp",
    "SCRATCH_MCP_DATA_DIR": "/path/to/scratch-unified-mcp/.sessions"
    // "SCRATCH_MCP_BRIDGE_PORT": "9060"  // only if something else holds 9060
  },
  "timeout": 600000
} } }

python3 tests/test_offline.py   # 34 checks, no network, no credentials
python3 tests/test_runtime.py   # 41 checks, headless VM playtest (see below)
python3 build_tower_game.py     # 42-check static gate, regenerates the demo .sb3

34 passed, 0 failed   (offline: tool surface, sessions, spy round-trip, git diff)
41 passed, 0 failed   (runtime: live VM playtest + debug + media tools)
42 passed, 0 failed   (static gate on the generator)

scratch_unified/          the server (this is what runs)
  server.py               FastMCP app + main()
  vendor_uu/              uukelele/scratch-mcp, vendored (social + projects)
  spy_loader.py           headless ScratchPy import (tkinter stubbed if absent)
  spy_tools.py            14 spy_* wrappers, one shared .spy server
  node_bridge.py          lazy Node sidecar transport (newline-delimited JSON-RPC, TIMEOUT-guarded)
  typed_proxy.py          typed sb3_* proxies (FastMCP rejects **kwargs)
  sb3_extra.py            git unpack/pack/diff, studio/remix/favorites, cloud vars
upstream-scratch-mcp/     reference clone (read-only)
upstream-scratch4js/      reference clone + Node sidecar source (runtime dep for sb3_*)
upstream-scratchpy-studio/  reference clone (runtime dep, loaded headless)
tests/                    test_offline.py (34) + test_runtime.py (41) + test_stress.py (47)
build_tower_game.py       demo game generator + 42-check static gate
tower-castle-defense.sb3  generated demo (84 KB)
docs/                     PRD, ARCHITECTURE, IDENTIFIERS, HANDOFF, RESEARCH-HEADLESS-RUNTIME