Codex Antigravity MCP (codex-antigravity-mcp)

Plugin y servidor MCP para Codex (Desktop & CLI) que permite delegar tareas de ingeniería de software, refactorización, auditoría, creación de ramas git y ejecución de tests a Google Antigravity CLI (agy) como un subagente autónomo persistente potenciado por Gemini.

Versión 1.1.1

• Corrige la estructura del marketplace para Codex Desktop: .agents/plugins/marketplace.json.

• Corrige la resolución del plugin local desde la raíz del marketplace.

• Simplifica el launcher MCP para que Codex Desktop lo ejecute desde el paquete instalado.

• Evita que el instalador local modifique configuraciones globales de Codex.

Related MCP server: codex-agy-bridge

🚀 Guía de Instalación y Puesta en Marcha (Paso a Paso)

Sigue estos pasos en orden para dejar el plugin 100% operativo en tu equipo:

Paso 1: Instalar Node.js en tu equipo

Si aún no tienes Node.js instalado:

• macOS (Homebrew):

  brew install node

• O descarga el instalador oficial desde nodejs.org (versión 18 o superior).

Paso 2: Instalar y Autenticar Google Antigravity CLI (agy)

El plugin utiliza la CLI oficial de Antigravity (agy) para comunicarse con los modelos de Gemini.

1. Instala agy siguiendo la documentación oficial de Antigravity o mediante el instalador de Google Gemini.

2. Abre tu terminal y ejecuta agy para iniciar sesión con tu cuenta de Google:

   # 1. Verifica la versión
   agy --version
   
   # 2. Inicia sesión interactivamente (solo se hace una vez)
   agy
   
   # 3. Comprueba que los modelos respondan
   agy models

💡 Nota: Si tienes agy instalado en una ruta personalizada fuera del estándar, puedes definir export ANTIGRAVITY_AGY_PATH="/ruta/a/tu/agy".

Paso 3: Clonar el Repositorio y Compilar con Node

Antes de activar el plugin en Codex Desktop, descarga el proyecto e instálalo localmente por consola para que se generen los ejecutables y se registre la configuración:

# 1. Clonar el repositorio
git clone https://github.com/Lucemz/codex-antigravity-mcp.git
cd codex-antigravity-mcp

# 2. Instalar dependencias y compilar
npm install
npm run build

# 3. Registrar el plugin localmente en Codex
npm run install:plugin

Paso 4: Activar en Codex Desktop

1. Abre Codex Desktop.

2. Ve a la sección Plugins / Marketplace.

3. Haz clic en Add Marketplace / Add Repository (Añadir Marketplace o repositorio).

4. Pega la URL del repositorio:

   https://github.com/Lucemz/codex-antigravity-mcp

5. Haz clic en Instalar / Install.

6. Reinicia Codex Desktop (Cmd + Q) o abre un Nuevo Chat para que las herramientas MCP se carguen en la sesión.

🛠️ Herramientas MCP Disponibles (MCP Tools)

Parámetros Principales:

• mode:

  • "plan": Inspección y análisis en solo lectura (sin modificar archivos).

  • "accept-edits": Autorización completa para escribir archivos, crear ramas git y correr comandos.

• skipPermissions: true (por defecto) para ejecución autónoma sin bloqueos interactivos.

• subagents: "auto" (por defecto), "required", o "off".

• model: ID opcional del modelo Gemini (ej. gemini-3.7-flash-medium, gemini-3.8-flash-high, gemini-3.1-pro-high).

💡 Ejemplos de Uso desde Codex

En cualquier conversación de Codex, puedes invocar al plugin escribiendo:

1. Verificar Estado y Conexión

@Codex Antigravity ejecuta antigravity_status y dime qué modelos de Gemini están disponibles.

2. Desarrollo Completo, Ramas y Tests (accept-edits)

@Codex Antigravity en /Users/usuario/proyectos/mi-app:
Crea una sesión persistente en mode "accept-edits".
1. Crea una rama git 'feature/nueva-funcionalidad'.
2. Implementa los cambios solicitados en el código.
3. Ejecuta los tests del proyecto.
4. Si los tests pasan, haz commit y reporta el diff final.

3. Auditoría Arquitectónica y Revisión (plan)

@Codex Antigravity en /Users/usuario/proyectos/mi-app:
Crea una sesión en mode "plan".
Analiza la arquitectura del proyecto, detecta posibles mejoras y genera un plan estructurado sin modificar archivos.

❓ Preguntas Frecuentes (FAQ / Troubleshooting)

1. ¿Por qué me sale antigravity_... undefined o no veo las herramientas?

• Solución: En Codex Desktop, las herramientas MCP se cargan al iniciar una nueva conversación. Cierra la conversación actual y abre un Nuevo Chat, o reinicia la aplicación completamente con Cmd + Q.

2. ¿Qué hacer si sale agy was not found o error de autenticación?

• Solución: Abre tu terminal y corre agy. Si no has iniciado sesión en Google, el comando te guiará interactivamente para autenticar tu cuenta.

🧪 Pruebas Automatizadas (Tests)

El repositorio incluye pruebas unitarias para validar timeouts, heartbeats de inactividad y recuperación de respuestas:

npm test

📄 Licencia

Este proyecto es código abierto bajo la licencia MIT.

Recuperar herramientas MCP en Codex

Si el skill aparece pero no aparecen antigravity_session_*, elimina la instalación y el marketplace antiguos, actualiza la caché y reinstala una sola copia:

CODEX=/Applications/ChatGPT.app/Contents/Resources/codex
REPO=/Users/fitzgeraldbendezu/projects/mcp-antigravity/codex-antigravity-mcp

"$CODEX" plugin remove codex-antigravity@codex-antigravity-marketplace
"$CODEX" plugin marketplace remove codex-antigravity-marketplace
git -C "$REPO" fetch --tags origin
git -C "$REPO" checkout main
git -C "$REPO" pull --ff-only origin main
"$CODEX" plugin marketplace add https://github.com/Lucemz/codex-antigravity-mcp --ref main
"$CODEX" plugin add codex-antigravity@codex-antigravity-marketplace

Luego cierra completamente Codex (no solo la ventana), vuelve a abrirlo y crea una tarea nueva. Comprueba con codex plugin list --json que el plugin esté enabled: true. No ejecutes simultáneamente un .mcp.json manual y el plugin.