Antigravity MCP Bridge (Antigravity 2.0 ↔ Gemini Spark)

Streamable HTTP 및 stdio 전송을 기반으로 Gemini Spark 및 원격/로컬 MCP 클라이언트를 통해 Windows의 Google Antigravity 2.0 에이전트를 프로그래밍 방식으로 제어합니다.

아키텍처 개요

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

Related MCP server: tailscale-mcp

빠른 시작 (Windows 원클릭 작업)

• START.bat: 환경을 초기화하고, 보안 인증 토큰이 포함된 .env를 생성하며, 127.0.0.1:8000에서 백그라운드 HTTP 서버를 시작하고, Tailscale Funnel을 활성화한 후 연결 배너를 표시합니다.

• STATUS.bat: 실시간 서버 상태, PID 상태, 인증 토큰 상태, Tailscale 로그인 및 Funnel 상태, Antigravity 런타임 사용 가능 여부를 확인합니다.

• STOP.bat: HTTP MCP 서버 프로세스를 정상적으로 종료하고 Tailscale Funnel 매핑을 비활성화합니다.

주요 기능

1. 이중 전송 지원:

   • 로컬 MCP 클라이언트용 Stdio 전송 (python src/server.py).

   • Gemini Spark 및 원격 클라이언트용 Streamable HTTP 전송 (START.bat / python -m src.http_server).

2. 인증 및 토큰 보호:

   • /mcp에서 토큰 검증을 강제하는 AuthMiddleware.

   • Authorization: Bearer <token>, x-api-key: <token> 또는 ?token=<token> 방식을 지원합니다.

   • .env에 없으면 32자리 16진수 토큰을 자동 생성합니다.

3. Tailscale Funnel 통합:

   • 도메인 구매 없이 안전한 공개 HTTPS 엔드포인트를 제공합니다.

   • Tailscale이 없거나 비활성화된 경우 강력한 감지, 상태 보고 및 해결 안내를 제공합니다.

4. Antigravity 2.0 로컬 엔진:

   • agentapi.bat을 통한 로컬 Antigravity Language Server와의 무설정 통합.

5. 안전 및 워크스페이스 격리:

   • 경로 탐색 공격을 방지하는 워크스페이스 경계 검증.

   • 출력 스트림에서 비밀 키와 토큰을 자동으로 삭제합니다.

   • 다중 에이전트 충돌을 방지하기 위한 동시 워크스페이스 실행 잠금.

제공되는 MCP 도구

• launch_antigravity_agent: 로컬 워크스페이스를 대상으로 Antigravity 에이전트 작업을 실행합니다.

• get_session_status: 세션 상태, 타임스탬프 및 실시간 메타데이터를 확인합니다.

• list_workspace_artifacts: 워크스페이스의 파일, 크기, 타임스탬프 및 SHA256 해시를 인덱싱합니다.

• run_antigravity_cli_command: 지원되는 agentapi 하위 명령어(get-conversation-metadata, send-message, new-conversation)를 실행합니다.

검증 및 테스트 스위트

전체 자동화 단위 및 통합 테스트 실행:

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

실제 엔드투엔드 HTTP MCP 통합 테스트 실행:

.venv\Scripts\python.exe remote_smoke_test.py

로컬 stdio 스모크 테스트 실행:

.venv\Scripts\python.exe smoke_test.py

문서

자세한 문서는 docs/에서 확인할 수 있습니다:

• docs/remote-access.md: 원격 액세스, Tailscale Funnel 및 Gemini Spark 연결에 대한 완전한 가이드.

• docs/mcp-setup.md: Gemini Spark 및 Antigravity IDE용 클라이언트 구성 스니펫.

• docs/security.md: 보안 모델, 경로 검증 및 비밀 정보 삭제 규칙.

• docs/troubleshooting.md: 문제 해결 매트릭스 및 진단 복구 단계.

• FINAL-REPORT.md: 완전한 통합 상태 보고서 및 실증 검증 매트릭스.