Antigravity Sub-Agent Bridge (FastMCP)

컨테이너화된 FastMCP 서버로, **Google Antigravity CLI(agy --headless)**를 SSE를 통해 원격 Model Context Protocol(MCP) 도구로 노출합니다.

이 브리지를 통해 대화형 AI 클라이언트(Google Spark, Claude, Cursor, ChatGPT 등)는 샌드박스 처리된 컨테이너 작업 공간에서 전체 코딩 및 자동화 하위 에이전트를 실행할 수 있습니다.

🚀 주요 기능

• 동기식 하위 에이전트 실행(execute_antigravity_sync): 코딩/자동화 작업을 agy --headless에 직접 전달하고 에이전트가 완료되면 출력 로그를 반환합니다(1~3분의 짧은 작업에 적합).

• 비동기 백그라운드 실행(start_antigravity_async): 장기 실행 Antigravity 에이전트를 백그라운드에서 실행하고, 분리된 실행을 위해 task_id를 반환합니다.

• 작업 폴링 및 관리(get_antigravity_task_status, list_antigravity_tasks): 진행 상황을 폴링하고, 로그를 검사하며, 모든 백그라운드 하위 에이전트를 나열합니다.

• 작업 공간 격리 및 샌드박싱: ./workspaces만 마운트하는 Docker 컨테이너 내에서 실행되어 호스트 시스템 파일을 보호하면서 에이전트에게 샌드박스 내에서 완전한 빌드, 테스트, 실행 자율성을 제공합니다.

• mcp-server-oauth-proxy와의 원활한 통합: 포트 8080/sse에서 표준 SSE 엔드포인트를 노출하여 Google Spark의 안전한 액세스를 위해 Home Assistant의 OAuth 프록시에 직접 연결할 수 있습니다.

Related MCP server: agy-mcp

🛠️ 저장소 구조

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

📦 빠른 시작 및 배포

1. 환경 구성

.env.example 템플릿을 복사합니다:

cp .env.example .env

(선택 사항: agy 환경에서 요구하는 경우 GEMINI_API_KEY 또는 ANTIGRAVITY_API_KEY를 추가하세요).

2. Docker Compose로 시작

docker compose up -d --build

FastMCP 서버가 다음 주소에서 수신 대기를 시작합니다: 👉 http://localhost:8080/sse (또는 호스트 LAN IP).

3. 컨테이너 상태 확인

docker compose logs -f

🔗 mcp-server-oauth-proxy에 연결

Home Assistant OAuth 프록시를 통해 이 Antigravity 하위 에이전트 브리지를 Google Spark에 안전하게 노출하려면:

1. Home Assistant에서 설정 > 애드온 > MCP Server OAuth Proxy > 구성을 엽니다.

2. 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. 저장하고 애드온을 다시 시작합니다.

4. Google Spark에서 Client ID spark-antigravity를 사용하여 https://antigravity-oauth.yourdomain.com/sse를 가리키는 사용자 지정 도구를 추가합니다.

🧰 사용 가능한 MCP 도구

1. execute_antigravity_sync

• 설명: agy --headless를 통해 작업을 동기적으로 실행하고 출력을 기다립니다.

• 매개변수:

  • prompt (string, 필수): 목표 또는 코딩 지시사항.

  • sub_path (string, 선택): 실행할 /workspace 내 하위 디렉터리.

  • timeout_seconds (int, 기본값: 300): 중단하기 전에 기다릴 최대 시간(초).

2. start_antigravity_async

• 설명: Antigravity 작업을 백그라운드에서 시작하고 task_id를 반환합니다.

• 매개변수:

  • prompt (string, 필수): 목표 또는 코딩 지시사항.

  • sub_path (string, 선택): 실행할 /workspace 내 하위 디렉터리.

3. get_antigravity_task_status

• 설명: 백그라운드 작업의 진행 상황과 전체 로그를 검사합니다.

• 매개변수:

  • task_id (string, 필수): start_antigravity_async가 반환한 8자리 ID.

4. list_antigravity_tasks

• 설명: 모든 활성 및 완료된 백그라운드 작업을 나열합니다.