agy-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file guides Claude Code when working in this repository.

Repository Type

An MCP (Model Context Protocol) server that wraps Google Antigravity's agy CLI, exposing it as tools to Claude Code and other MCP clients. Sister project to codex-mcp-server (same architecture, different upstream CLI).

Development Commands

npm run build          # tsc -> dist/
npm run dev            # run src/index.ts with tsx
npm test               # jest (ESM via ts-jest)
npm run test:coverage  # coverage report
npx jest src/__tests__/agy-handler.test.ts   # single test file
npm run lint           # eslint
npm run format         # prettier

Architecture

MCP Client (Claude Code)
  -> StdioTransport
  -> AgyMcpServer (server.ts)
  -> ToolHandlers (tools/handlers.ts)
  -> executeCommand / executeCommandStreaming (utils/command.ts)
  -> agy CLI (print mode)

File	Purpose
src/index.ts	Entry point; starts AgyMcpServer
src/server.ts	MCP server, list_tools / call_tool, progress notifications
src/tools/definitions.ts	Tool schemas + annotations
src/tools/handlers.ts	Tool logic (agy, models, ping, help, listSessions, changelog)
src/types.ts	Types, Zod schemas, constants
src/session/storage.ts	In-memory session storage
src/utils/command.ts	Process spawning with stdin piping + streaming
src/utils/logger.ts	Markdown conversation transcript logger (env-gated)
src/errors.ts	Error classes

Critical implementation details

• Prompt is the value of -p. agy -p "<prompt>" takes the prompt as the flag value. -p REQUIRES a value — a bare -p errors with "flag needs an argument". agy only falls back to reading stdin when -p is empty. The handler passes the prompt via cmdArgs.push('-p', prompt), and command.ts always closes stdin so agy never blocks waiting for input.
• Answer is on stdout. agy print mode writes the response to stdout (exit 0). Handlers still fall back to stderr for robustness.
• Model selection (agy v1.0.5+). agy --model "<name>" picks the model for a call; agy models lists them. The model param maps to --model (arg > AGY_MCP_DEFAULT_MODEL env > omitted). Names contain spaces/parens and are safe as a single argv value (spawn uses no shell on POSIX). Unknown names are not rejected — agy falls back to its default. (Older agy ≤1.0.3 had no --model.)
• No conversation ID in print mode. Multi-turn continuation uses agy --continue (most-recent conversation). --conversation <id> is only used when the caller supplies an explicit conversationId.
• Conversation logging is env-gated and must never throw. logger.ts appends a Markdown transcript per agy call when AGY_MCP_LOG_DIR or AGY_MCP_LOG_FILE is set (off by default). Failures are caught and logged to stderr only — the tool result is unaffected.