penpot/.devenv

.devenv/ — Per-Workspace AI-Client MCP Configs

This directory carries the pieces needed to point an AI coding agent (currently Claude Code, opencode, VS Code Copilot, and the OpenAI Codex CLI) at the MCP servers running inside the parallel devenv instance the developer is currently working in. Every parallel workspace (ws0, ws1, …) has its own copy because the Penpot MCP and Serena MCP host ports are workspace-specific.

Layout

.devenv/
  README.md
  scripts/
    merge-mcp-config.py    # generator helper invoked by manage.sh
  shared/                  # committed; workspace-independent entries
    claude-code.json       # Playwright — same for every workspace
    opencode.json
    vscode.json
    codex.toml
  templates/               # committed; entries with ${...} port placeholders
    claude-code.json       # Penpot MCP, Serena MCP — port is the only diff
    opencode.json
    vscode.json
    codex.toml
  mcp/                     # gitignored; written by manage.sh per workspace
    claude-code.json       # loaded via Claude Code's --mcp-config flag
    opencode.json          # loaded via OPENCODE_CONFIG env var

One more file is generated outside .devenv/, in the directory VS Code itself auto-discovers (gitignored):

.vscode/mcp.json           # auto-loaded by GitHub Copilot in VS Code

Codex is the exception: it has no way to load an MCP config from an arbitrary path, and its only project-level config file (.codex/config.toml) is one a developer may already own. So we do not write a file for Codex at all — start-coding-agent codex injects our servers as -c command-line overrides built fresh from shared/codex.toml + templates/codex.toml at launch.

• shared/ holds MCP entries that don't depend on the workspace — the browser-driving Playwright server today, plus any other workspace-independent servers we add later. Same content in every workspace, so it's a static checked-in file.
• templates/ holds the workspace-specific entries (Penpot MCP, Serena MCP) with ${PENPOT_MCP_PORT} and ${SERENA_MCP_PORT} placeholders. The placeholders are resolved per-workspace from the port-base constants in manage.sh.
• mcp/ (Claude Code, opencode) is the result of merging shared/ with the port-substituted templates/. manage.sh writes these on every run-devenv --agentic pass. Gitignored, dedicated paths with no developer content — never edit by hand, your edits will be overwritten on the next reconcile.
• .vscode/mcp.json is the same merge, but written to the path VS Code auto-discovers. Because on ws0 that path is the live repo's own file, the reconcile deep-merges into it: any servers you added yourself are kept, and only the entries we manage (penpot, serena-devenv, playwright) are (re)written to the current ports. On ws1+ the file doesn't exist yet, so it is created from scratch.
• scripts/merge-mcp-config.py is the generator. Its json mode does the JSON deep-merge (with --merge-into-existing for the VS Code path); its codex-args mode prints the -c assignments for Codex. manage.sh's _merge-mcp-config-json helper is a thin shim over the former, and start-coding-agent calls the latter directly. Run python3 .devenv/scripts/merge-mcp-config.py --help for the CLI.

Launching a coding agent

The easiest path is the wrapper command, which knows the right flags per client, cd's into the target workspace, and refuses to launch unless the target instance is running and its MCP config has been generated:

# Default target is ws0 (the live repo).
./manage.sh start-coding-agent claude               [...args to forward]
./manage.sh start-coding-agent opencode             [...args to forward]
./manage.sh start-coding-agent vscode               [...args to forward to 'code']
./manage.sh start-coding-agent codex                [...args to forward]

# Target a parallel workspace with --ws N. N is an integer (non-negative);
# 'main', 'ws1' and similar spellings are rejected.
./manage.sh start-coding-agent claude --ws 1
./manage.sh start-coding-agent opencode --ws 2

Equivalents by hand (run from inside the workspace directory):

claude --mcp-config .devenv/mcp/claude-code.json
OPENCODE_CONFIG=.devenv/mcp/opencode.json opencode
code "$PWD"                  # VS Code auto-discovers .vscode/mcp.json
# Codex: pass our servers as -c overrides (no config file is written).
codex $(python3 .devenv/scripts/merge-mcp-config.py --format codex-args \
          .devenv/shared/codex.toml .devenv/templates/codex.toml \
          | sed 's/^/-c /')

start-coding-agent codex does the -c wiring for you (and resolves the workspace's ports first). Because our servers arrive as command-line overrides, no "trusted project" prompt is involved for them — that prompt only gates Codex's own .codex/config.toml, which we never write.

Overriding our entries

Both the auto-discovered configs and the launcher-loaded configs sit on top of the developer's global config (with varying precedence rules). All four clients offer escape hatches for shadowing entries we ship:

• Claude Code — claude mcp add --scope local … installs a private entry that overrides the one in mcp/claude-code.json. Local scope wins.
• opencode — drop an opencode.json at the repo root with the override entries you need. opencode's precedence chain is global → OPENCODE_CONFIG → project, so the project file always wins. The root opencode.json is gitignored on purpose, since these overrides are personal.
• VS Code Copilot — the reconcile deep-merges into .vscode/mcp.json, so any servers you add there yourself are preserved (only penpot, serena-devenv and playwright are rewritten). To shadow one of ours, put an entry under the same name in your VS Code user-profile MCP config — it is loaded alongside the workspace file and wins.
• Codex CLI — our servers arrive as -c overrides, which are Codex's highest-precedence layer, so they win over a same-named [mcp_servers.<name>] in your ~/.codex/config.toml or a project .codex/config.toml. To override one of ours, append your own -c after the client name — extra args are forwarded after ours and the later -c wins, e.g. ./manage.sh start-coding-agent codex -- -c 'mcp_servers.penpot.url="…"'.

See docs/technical-guide/developer/agentic-devenv.md for the broader client-configuration story (browser remote debugging, AI-client config schemas, manual setup for unsupported clients).