Antigravity Sub-Agent Bridge (FastMCP)

Ein containerisierter FastMCP-Server, der die Google Antigravity CLI (agy --headless) als entfernte Model Context Protocol (MCP)-Werkzeuge über SSE bereitstellt.

Diese Brücke ermöglicht es konversationsbasierten KI-Clients (wie Google Spark, Claude, Cursor oder ChatGPT), vollständige Codierungs- und Automatisierungs-Sub-Agenten in einer isolierten, containerisierten Arbeitsumgebung zu starten.

🚀 Hauptfunktionen

• Synchrone Sub-Agent-Ausführung (execute_antigravity_sync): Sendet eine Codierungs-/Automatisierungsaufgabe direkt an agy --headless und gibt das Ausgabeprotokoll zurück, sobald der Agent fertig ist (ideal für kurze Aufgaben von 1–3 Minuten).

• Asynchrone Hintergrundausführung (start_antigravity_async): Startet einen langlebigen Antigravity-Agenten im Hintergrund und gibt eine task_id für die entkoppelte Ausführung zurück.

• Aufgabenabfrage und -verwaltung (get_antigravity_task_status, list_antigravity_tasks): Fragt Fortschritte ab, prüft Protokolle und listet alle Hintergrund-Sub-Agenten auf.

• Arbeitsbereichsisolierung und Sandboxing: Läuft in einem Docker-Container, der nur ./workspaces einbindet, schützt so die Host-Dateien und gibt dem Agenten gleichzeitig volle Build-, Test- und Ausführungsfreiheit in seiner Sandbox.

• Nahtlose Integration mit mcp-server-oauth-proxy: Stellt standardmäßige SSE-Endpunkte auf Port 8080/sse bereit, die direkt in den OAuth-Proxy von Home Assistant eingebunden werden können, um einen sicheren Zugriff von Google Spark zu ermöglichen.

Related MCP server: agy-mcp

🛠️ Repository-Struktur

antigravity-mcp-bridge/
├── Dockerfile              # Container image with Python 3.12, Node.js, git, & agy CLI
├── docker-compose.yml      # Service definitions with volume mounts & port bindings
├── requirements.txt        # fastmcp, mcp[cli], pydantic
├── server.py               # FastMCP Server exposing Antigravity agent tools
├── .env.example            # Environment variable template
├── .gitignore              # Ignored artifacts & workspace directories
└── README.md               # Documentation

📦 Schnellstart & Bereitstellung

1. Umgebung konfigurieren

Kopieren Sie die .env.example-Vorlage:

cp .env.example .env

(Optional: Fügen Sie Ihren GEMINI_API_KEY oder ANTIGRAVITY_API_KEY hinzu, falls Ihre agy-Umgebung dies erfordert).

2. Mit Docker Compose starten

docker compose up -d --build

Der FastMCP-Server lauscht dann auf: 👉 http://localhost:8080/sse (oder Ihrer Host-LAN-IP).

3. Container-Gesundheit überprüfen

docker compose logs -f

🔗 Verbindung zum mcp-server-oauth-proxy herstellen

Um diese Antigravity-Sub-Agent-Brücke sicher über Ihren Home-Assistant-OAuth-Proxy für Google Spark bereitzustellen:

1. Öffnen Sie in Home Assistant Einstellungen > Add-ons > MCP Server OAuth Proxy > Konfiguration.

2. Fügen Sie unter servers einen neuen Servereintrag hinzu:

    - client_name: "Google Spark"
      server_name: "Antigravity Bridge"
      server_url: "http://<YOUR_DOCKER_HOST_IP>:8080/sse"
      bearer_token: ""
      client_id: "spark-antigravity"
      client_secret: "secret-antigravity"
      allowed_redirect_uris: "https://oauth-redirect.googleusercontent.com"
      host: "antigravity-oauth.yourdomain.com"
      path_prefix: ""

3. Speichern und starten Sie das Add-on neu.

4. Fügen Sie in Google Spark das benutzerdefinierte Werkzeug hinzu, das auf https://antigravity-oauth.yourdomain.com/sse mit der Client-ID spark-antigravity verweist.

🧰 Verfügbare MCP-Werkzeuge

1. execute_antigravity_sync

• Beschreibung: Führt eine Aufgabe synchron über agy --headless aus und wartet auf die Ausgabe.

• Parameter:

  • prompt (Zeichenfolge, erforderlich): Das Ziel oder die Codierungsanweisung.

  • sub_path (Zeichenfolge, optional): Unterverzeichnis in /workspace, in dem ausgeführt werden soll.

  • timeout_seconds (Ganzzahl, Standard: 300): Maximale Wartezeit in Sekunden, bevor abgebrochen wird.

2. start_antigravity_async

• Beschreibung: Startet eine Antigravity-Aufgabe im Hintergrund und gibt eine task_id zurück.

• Parameter:

  • prompt (Zeichenfolge, erforderlich): Das Ziel oder die Codierungsanweisung.

  • sub_path (Zeichenfolge, optional): Unterverzeichnis in /workspace, in dem ausgeführt werden soll.

3. get_antigravity_task_status

• Beschreibung: Ruft Fortschritt und vollständige Protokolle einer Hintergrundaufgabe ab.

• Parameter:

  • task_id (Zeichenfolge, erforderlich): Die 8-stellige ID, die von start_antigravity_async zurückgegeben wurde.

4. list_antigravity_tasks

• Beschreibung: Listet alle aktiven und abgeschlossenen Hintergrundaufgaben auf.