agy-frontend-mcp (TypeScript / Node)

A TypeScript/Node port of agy-frontend-mcp — an MCP server that delegates frontend coding to agy (the Antigravity / Gemini CLI) inside an isolated git worktree, so an MCP client (e.g. Claude Code) can hand a whole frontend task to Gemini, review the diff, and decide whether to merge.

Same behavior and design as the Python version (the design docs in ../docs/superpowers/specs/ apply); this is the "more universal language" build with npx distribution.

Requirements

• agy on PATH and logged in
• Node ≥ 18, git

Tools

• frontend_delegate(task, model?, base_repo?, session_id?, add_dirs?, timeout_seconds?, sandbox?) — run one agy agentic loop in a fresh worktree (or continue via session_id). Returns {session_id, branch, worktree_path, status, summary, changed_files, diffstat, stderr_tail, elapsed_s}. Success is judged by the git diff, not agy's exit code (status ∈ success / needs_attention / timeout).
• frontend_diff(session_id) — the worktree's git diff (truncated past MAX_DIFF_BYTES).
• frontend_finish(session_id, action) — merge into base, or discard; the per-task agy state dir is reclaimed either way.

Build & run

npm install
npm run build          # → dist/
npm test               # vitest (fakes agy)
AGY_SMOKE=1 npm test -- tests/smoke.test.ts   # real agy, end-to-end

Register in Claude Code (.mcp.json)

{
  "mcpServers": {
    "agy-frontend": {
      "command": "node",
      "args": ["/abs/path/to/agy-frontend-mcp/ts/dist/server.js"],
      "timeout": 1800000
    }
  }
}

Once published to npm, npx agy-frontend-mcp works as the command/args.

How it works (the agy quirks this encapsulates)

• Isolation — agy --gemini_dir=<empty per-task dir> relocates all agy state so it can't read other projects' transcripts; OAuth is unaffected (system keyring).
• Writes into the worktree — the prompt is scoped to the absolute worktree path, because agy writes loose filenames into its own scratch sandbox.
• No hangs — every agy subprocess gets stdin = ignore (agy blocks on inherited stdin) and is killed by process group on timeout.
• Permissions — --dangerously-skip-permissions (no TTY); safety is the worktree boundary. sandbox=false by default (frontend tasks often need the network).

Notes

• Dev-only npm audit findings come from the vitest/vite/esbuild toolchain and are not shipped (the published package contains only dist/ + @modelcontextprotocol/sdk + zod).

License

MIT — see ../LICENSE.