.mcp.json — operator notes

This file documents the MCP servers PRISM uses for TUI testing. The authoritative config lives in .mcp.json; this doc explains the why and lists the additional MCPs that don't live in .mcp.json because they need a manual install step.

Why notes aren't in .mcp.json itself

Forge's MCP config parser is strict on top-level fields — it only accepts mcpServers. An earlier version of this file inlined a _notes_for_installer array, and forge's TUI failed to boot with:

ERROR: An error occurred while reading config at: ./.mcp.json
Caused by:
    unknown field `_notes_for_installer`, expected `mcpServers` at line 19 column 24

Hence: this sidecar .md. Don't put metadata back inside the JSON.

Already wired in .mcp.json (auto-pull on first use)

| MCP | When to reach for it | |-----|----------------------| | pty-debug | First. Fast, local, text snapshots. Already installed (with the spawn-helper +x fix shipped 2026-05-08). | | terminalcp (@mariozechner/terminalcp) | Full PTY emulation — preserves ANSI colors, cursor, special keys with higher fidelity than pty-debug. Auto-pulls via npx -y on first start. | | iterm-tmux (mcpretentious) | Drives a REAL iTerm2/tmux window the user can watch. Use when the human should see the agent typing in their actual terminal. Has mcpretentious-screenshot for visual layered snapshots (text + cursor + colors + styles). |

Manual install via scripts/install-tui-mcps.sh

These need cargo install or git clone + uv pip install and aren't distributed via npm — Claude Code's permission gate blocks agent-initiated installs from non-registry sources, so the install script runs them under explicit user authorization.

| MCP | What it adds | Install path | |-----|--------------|--------------| | mcp-tui-driver | tui_screenshot returns a real PNG of the screen — visual verification of color, kerning, alignment that text dumps can't show. | cargo install --git https://github.com/michaellee8/mcp-tui-driver --locked | | mcp-tui-test | Playwright-style buffer-mode TUI testing — position assertions, wait_for_text, snapshot diffing for regression coverage. | Cloned to ~/.prism/mcps/mcp-tui-test/ with its own venv. | | @microsoft/tui-test | NOT an MCP — a CI dev dependency. End-to-end TUI test framework for PRISM's CI matrix. | npm i -D @microsoft/tui-test |

Bringup checklist

After cloning the repo or pulling on a fresh machine:

cd ~/Downloads/PRISM
bash scripts/install-tui-mcps.sh   # adds the 3 manual MCPs/dev-deps
# then restart Claude Code so the new MCP entries are picked up

The script is idempotent and updates .mcp.json itself once the binaries / venvs install successfully.

Known gotchas

1. Don't add comments / sidebands to .mcp.json. Forge fails the whole TUI boot if there's any unknown top-level key. The boot error surfaces in the chat panel as An error occurred while reading config at: ./.mcp.json — easy to misread as a server problem.

2. pty-mcp-server's spawn-helper needs +x. If a Node upgrade or homebrew reinstall clears the bit, every spawn fails with posix_spawnp failed. Re-run:

   chmod +x /opt/homebrew/lib/node_modules/@so2liu/pty-mcp-server/node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper
   

3. Auto-install via npx -y requires network on first start. If you're offline at first launch, the terminalcp and iterm-tmux MCPs will fail to come up. Pre-warm them once with internet, then they're cached.

4. terminalcp needs an explicit --mcp flag. Without it, the binary prints a usage banner to stdout and exits. rmcp tries to parse the banner as JSON and the failure shows up as a chat-panel error:

   ERROR rmcp::transport::async_rw: Error reading from stream:
   serde error expected ident at line 1 column 2
   

   Args must include "--mcp". Caught 2026-05-09 by driving the live TUI under pty-debug. (mcpretentious and pty-mcp-server correctly start in MCP mode by default — only terminalcp is sensitive to this.)