Antigravity Sub-Agent Bridge (FastMCP)

Un servidor FastMCP contenedorizado que expone la CLI de Google Antigravity (agy --headless) como herramientas remotas del Model Context Protocol (MCP) a través de SSE.

Este puente permite que clientes de IA conversacionales (como Google Spark, Claude, Cursor o ChatGPT) envíen sub-agentes completos de codificación y automatización en un espacio de trabajo contenedorizado y aislado.

🚀 Características principales

• Ejecución síncrona de sub-agentes (execute_antigravity_sync): Envía una tarea de codificación/automatización directamente a agy --headless y devuelve el registro de salida cuando el agente termina (ideal para tareas cortas de 1 a 3 minutos).

• Ejecución asíncrona en segundo plano (start_antigravity_async): Lanza un agente Antigravity de larga duración en segundo plano, devolviendo un task_id para ejecución desacoplada.

• Consulta y gestión de tareas (get_antigravity_task_status, list_antigravity_tasks): Consulta el progreso, inspecciona los registros y lista todos los sub-agentes en segundo plano.

• Aislamiento del espacio de trabajo y sandboxing: Se ejecuta dentro de un contenedor Docker que monta solo ./workspaces, protegiendo los archivos del sistema anfitrión mientras le da al agente plena autonomía de compilación, prueba y ejecución dentro de su sandbox.

• Integración perfecta con mcp-server-oauth-proxy: Expone endpoints SSE estándar en el puerto 8080/sse, conectable directamente al proxy OAuth de Home Assistant para acceso seguro desde Google Spark.

Related MCP server: agy-mcp

🛠️ Estructura del repositorio

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

📦 Inicio rápido e implementación

1. Configurar el entorno

Copia la plantilla .env.example:

cp .env.example .env

(Opcional: Añade tu GEMINI_API_KEY o ANTIGRAVITY_API_KEY si tu entorno agy lo requiere).

2. Iniciar con Docker Compose

docker compose up -d --build

El servidor FastMCP comenzará a escuchar en: 👉 http://localhost:8080/sse (o la IP LAN de tu host).

3. Verificar el estado del contenedor

docker compose logs -f

🔗 Conexión con mcp-server-oauth-proxy

Para exponer este puente de sub-agentes Antigravity de forma segura a Google Spark a través de tu proxy OAuth de Home Assistant:

1. En Home Assistant, abre Configuración > Complementos > MCP Server OAuth Proxy > Configuración.

2. Añade una nueva entrada de servidor en servers:

    - 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. Guarda y reinicia el complemento.

4. En Google Spark, añade la herramienta personalizada apuntando a https://antigravity-oauth.yourdomain.com/sse con el ID de cliente spark-antigravity.

🧰 Herramientas MCP disponibles

1. execute_antigravity_sync

• Descripción: Ejecuta una tarea de forma síncrona mediante agy --headless y espera la salida.

• Parámetros:

  • prompt (string, obligatorio): El objetivo o la instrucción de codificación.

  • sub_path (string, opcional): Subdirectorio dentro de /workspace en el que ejecutar.

  • timeout_seconds (int, predeterminado: 300): Máximo de segundos a esperar antes de abortar.

2. start_antigravity_async

• Descripción: Inicia una tarea de Antigravity en segundo plano y devuelve un task_id.

• Parámetros:

  • prompt (string, obligatorio): El objetivo o la instrucción de codificación.

  • sub_path (string, opcional): Subdirectorio dentro de /workspace en el que ejecutar.

3. get_antigravity_task_status

• Descripción: Inspecciona el progreso y los registros completos de una tarea en segundo plano.

• Parámetros:

  • task_id (string, obligatorio): El ID de 8 caracteres devuelto por start_antigravity_async.

4. list_antigravity_tasks

• Descripción: Lista todas las tareas en segundo plano activas y completadas.