# 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:
```cmd
.venv\Scripts\python.exe -m pytest tests/
```

Run real end-to-end HTTP MCP integration test:
```cmd
.venv\Scripts\python.exe remote_smoke_test.py
```

Run local stdio smoke test:
```cmd
.venv\Scripts\python.exe smoke_test.py
```

---

## Documentation

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