Antigravity Orchestrate MCP Server (orchestrate-agy-mcp)

An MCP (Model Context Protocol) server designed to manage, orchestrate, and run Antigravity (agy.exe) coding agent tasks in the background on Windows.

By leveraging pseudo-terminals (node-pty), this server spawns agent jobs asynchronously, monitors their progress, supports failover configurations (e.g. rate limit/quota fallback), and reports status/output updates back to the parent agent. This enables sequential or parallel multi-agent task execution without blockages.

---

Features

• 🚀 Background Execution (run_agy): Spawns agy.exe non-interactively using -p/--print inside a node pseudo-terminal (PTY) environment.
• 🔄 Conversation Resumption (continue_agy): Resumes the most recent or a specific agy conversation session (via -c or --conversation) to supply follow-up feedback.
• ⏱️ Non-blocking Polling & Waiting (wait_for_agy): Optimizes token usage and avoids MCP RPC timeouts by allowing clients to poll execution progress in short intervals (~5s) rather than holding the connection open indefinitely.
• 🛡️ Model Failover & Account Swapping:
  • Automatically detects API quota/rate-limiting errors (e.g., 429, resource_exhausted).
  • Fallbacks from Gemini to Claude (or vice-versa).
  • Can trigger a local PowerShell script (switch-account.ps1) to swap API credentials seamlessly when a secondary failover is needed.
• 📝 Git Summary Reports: Automatically appends a summary of modified/added files and git diff --stat output to the final log once an agent task completes.
• 🧹 ANSI Escape Cleanups: Automatically sanitizes VT100/ANSI terminal color and cursor codes from output buffers to guarantee human-readable plain text logs.

---

Project Structure

mcp-server/
├── .gitignore                   # Excludes node_modules, build outputs, local logs, and state
├── README.md                    # Project documentation
└── agy-mcp-server/              # Source code directory
    ├── package.json             # Dependencies and scripts
    ├── tsconfig.json            # TypeScript configuration
    ├── src/
    │   ├── index.ts             # MCP server initialization & tool handlers
    │   └── JobManager.ts        # Pseudo-terminal management, watchdog timers, failover handling
    ├── test-job-completes.mjs   # Integration check for job completion
    ├── mcp-continue-probe.mjs   # End-to-end check for run -> continue flow
    └── mcp-crash-probe.mjs      # Server stability & stderr error monitoring probe

---

Installation & Build

Prerequisites

• Node.js (v18+ recommended)
• Antigravity CLI (agy.exe) installed on the system path.

Build Steps

1. Navigate into the agy-mcp-server directory:

   cd agy-mcp-server
   

2. Install dependencies:

   npm install
   

3. Compile the TypeScript source code: