Antigravity MCP Bridge (Antigravity 2.0 ↔ Gemini Spark)

Programmatically control Google Antigravity 2.0 agents on Windows via Gemini Spark and remote/local MCP clients over Streamable HTTP and stdio transport.

---

Architecture Overview

Gemini Spark (or Remote MCP Client)
      │
      │ HTTPS Request (Authorization: Bearer <MCP_AUTH_TOKEN>)
      ▼
Tailscale Funnel (Public HTTPS: https://<node>.<tailnet>.ts.net/mcp)
      │
      │ Encrypted Local Tunnel
      ▼
Streamable HTTP MCP Server (src/http_server.py on 127.0.0.1:8000)
      │
      ├── AuthMiddleware (Validates MCP_AUTH_TOKEN -> 401 Unauthorized if invalid)
      ├── /health & /healthz Diagnostic Endpoints
      │
      ▼
FastMCP Core Server (src/server.py - Streamable HTTP & stdio)
      │
      ├── launch_antigravity_agent
      ├── get_session_status
      ├── list_workspace_artifacts
      └── run_antigravity_cli_command
      │
      ▼
Antigravity Bridge Adapter -> agentapi.bat -> Antigravity 2.0 Runtime -> Local Workspace

---

Quick Start (Windows One-Click Operations)

• START.bat: Initializes environment, creates .env with secure auth token, starts background HTTP server on 127.0.0.1:8000, enables Tailscale Funnel, and displays connection banner.
• STATUS.bat: Inspects live server health, PID status, auth token state, Tailscale login & Funnel status, and Antigravity runtime availability.
• STOP.bat: Gracefully terminates the HTTP MCP server process and disables Tailscale Funnel mapping.

---

Key Features

1. Dual Transport Support:
   • Stdio transport for local MCP clients (python src/server.py).
   • Streamable HTTP transport for Gemini Spark and remote clients (START.bat / python -m src.http_server).
2. Authentication & Token Protection:
   • AuthMiddleware enforcing token validation on /mcp.
   • Supports Authorization: Bearer <token>, x-api-key: <token>, or ?token=<token>.
   • Auto-generates 32-character hex token if missing in .env.
3. Tailscale Funnel Integration:
   • Secure public HTTPS endpoint without purchasing a domain.
   • Robust detection, status reporting, and resolution guidance when Tailscale is absent or disabled.
4. Antigravity 2.0 Local Engine:
   • Zero-config integration with local Antigravity Language Server via agentapi.bat.
5. Safety & Workspace Isolation:
   • Workspace boundary validation preventing path traversal attacks.
   • Automatic secret key and token redaction from output streams.
   • Concurrent workspace execution locking preventing multi-agent conflicts.

---

Exposed MCP Tools

• launch_antigravity_agent: Launches an Antigravity agent task targeting a local workspace.
• get_session_status: Inspects session status, timestamps, and live metadata.
• list_workspace_artifacts: Indexes files, sizes, timestamps, and SHA256 hashes in workspace.
• run_antigravity_cli_command: Executes supported agentapi subcommands (get-conversation-metadata, send-message, new-conversation).

---

Verification & Test Suite

Run full automated unit and integration tests:

.venv\Scripts\python.exe -m pytest tests/

Run real end-to-end HTTP MCP integration test:

.venv\Scripts\python.exe remote_smoke_test.py

Run local stdio smoke test:

.venv\Scripts\python.exe smoke_test.py

---

Documentation

Detailed documentation is available in docs/:

• docs/remote-access.md: Complete guide for remote access, Tailscale Funnel, and Gemini Spark connection.
• docs/mcp-setup.md: Client configuration snippets for Gemini Spark and Antigravity IDE.
• docs/security.md: Security model, path validation, and secret redaction rules.
• docs/troubleshooting.md: Troubleshooting matrix and diagnostic recovery steps.
• FINAL-REPORT.md: Complete integration status report and empirical verification matrix.