# Antigravity MCP

A workspace containing a Python-based Model Context Protocol (MCP) server integrated with the **Google Antigravity SDK** and **Google Cloud Gemini Enterprise Agent Platform (Gemini)**, accompanied by a responsive test client web application.

- [English Documentation](#english-documentation)
- [한국어 문서](#한국어-문서)

---

# English Documentation

> [!WARNING]
> **Prototype Release Notice**
> This repo is a demo and prototype of the Antigravity SDK. Thorough review is required before applying it to a production environment.

## Project Structure

This workspace is divided into two main parts:
1. **`mcp-server/`**: The Core Python MCP Server.
   - Leverages `FastMCP` and the `google.antigravity` SDK.
   - Exposes tools like `agy_task` and `agy_code_review`.
2. **`test-mcp-client/`**: A local test web application.
   - Built on `Starlette` and `Uvicorn`.
   - Provides a web interface to easily test the MCP Server.
   - Connects to the MCP server via SSE on port 8000 automatically, or falls back to STDIO if the persistent server is offline.

---

## System Architecture & Multi-Agent Routing

The interaction model features a collaborative **Multi-Agent Routing** architecture between the parent orchestrator (Claude Code) and the specialized downstream agent (Antigravity Agent). 

```mermaid
graph TD
    CC["Claude Code CLI"] -->|"SSE / STDIO"| MS["AGY MCP Server"]
    TWC["Test Web Client"] -->|"SSE / STDIO"| MS
    
    MS -->|"Invoke SDK / Initialize Agent"| Agent["Antigravity Agent"]
    Agent -->|"Gemini API Call"| Vertex["Gemini Enterprise Agent Platform"]
    
    Agent -.->|"Write telemetry"| Log["Telemetry Log<br>(thinking.log)"]
    TWC -.->|"Tail logs"| Log

    style CC fill:#d4f0ff,stroke:#333,stroke-width:2px
    style TWC fill:#d4f0ff,stroke:#333,stroke-width:2px
    style MS fill:#bbf,stroke:#333,stroke-width:2px
    style Agent fill:#f9f,stroke:#333,stroke-width:2px
    style Vertex fill:#bfb,stroke:#333,stroke-width:2px
    style Log fill:#ffe,stroke:#333,stroke-width:1px
```

### Technical Workflow & Multi-Agent Routing Mechanics

1. **Claude Code as the Parent Orchestrator (Top-Level Router)**
   When the user enters a prompt containing terms like `antigravity`, `agy`, `gemini`, or `제미나이`, Claude Code acts as the orchestrator. Rather than executing general tasks blindly, it matches semantic trigger words dynamically to discover our specialized MCP tools.
2. **Cohesive Semantic Synonym Routing**
   Because the FastMCP tools (`agy_task`, `agy_code_review`) are decorated with rich semantic docstrings, Claude Code delegates the domain-specific tasks to the AGY MCP Server. This avoids spinning up multiple redundant servers, preventing resource overhead and API conflicts.
3. **Delegation to Antigravity Agent (Specialized Downstream Execution)**
   The AGY MCP Server accepts the JSON-RPC request and spawns a highly specialized, autonomous Antigravity Agent. Powered by Gemini, the agent performs localized work (such as code modifications or deep repository reviews) and streams token-by-token reasoning telemetry.
4. **Telemetry Log**
   Inference logs generated during agent execution are stored outside the workspace directory at `~/.gemini/antigravity/thinking.log`.

---

## Installation & Server Setup Guide

Follow these steps to set up the MCP server for the first time on any system (Windows, macOS, or Linux).

### 1. Prerequisites
- **Python 3.10+** installed on your system.
- **Google Cloud SDK (`gcloud` CLI)** installed and configured.
- A **GCP Project** with the **Gemini Enterprise Agent Platform APIs** enabled.

### 2. Google Cloud Authentication
Authenticate your local environment to allow the Antigravity SDK to access Gemini:
```bash
gcloud auth application-default login
```

### 3. Initialize Python Virtual Environment
Set up a clean virtual environment and install dependencies:
```bash
# Create venv
python -m venv agy-mcp-env

# Activate venv
# On macOS/Linux:
source agy-mcp-env/bin/activate
# On Windows (PowerShell):
.\agy-mcp-env\Scripts\Activate.ps1
# On Windows (CMD):
.\agy-mcp-env\Scripts\activate.bat

# Install required packages
pip install -r requirements.txt
```

### 4. Configuration Settings
Create a configuration file named `mcp-server/agy-mcp-config.json` inside your project root to point the server to your GCP resources:
```json
{
  "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
  "GCP_LOCATION": "<YOUR_GCP_LOCATION>",
  "MODEL": "gemini-3.7-flash"
}
```
> [!NOTE]
> Replace `<YOUR_GCP_PROJECT_ID>` with your actual Google Cloud Project ID, and `<YOUR_GCP_LOCATION>` with your desired region (e.g., `us-central1` or `us-east4`).

---

## Integrating with Claude Code

You can integrate this server into **Claude Code** using either of the two transport options below depending on your runtime architecture.

### Option 1: STDIO Transport Mode (Recommended)

In this mode, Claude Code directly spawns the Python MCP server as a background subprocess during execution.

#### A. Windows Setup (PowerShell)
Locate your Claude Code global configuration file (typically `%USERPROFILE%\.claude.json` or `C:\Users\<username>\.claude.json`).
Update or create the file with the following configuration:

```json
{
  "mcpServers": {
    "agy": {
      "command": "<WORKSPACE_ABSOLUTE_PATH>\\agy-mcp-env\\Scripts\\python.exe",
      "args": [
        "<WORKSPACE_ABSOLUTE_PATH>\\mcp-server\\server.py"
      ],
      "env": {
        "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
        "GCP_LOCATION": "<YOUR_GCP_LOCATION>"
      }
    }
  }
}
```
> [!IMPORTANT]
> - Replace `<WORKSPACE_ABSOLUTE_PATH>` with the full absolute path of this workspace directory (e.g. `C:\\Users\\yourname\\projects\\antigravity-mcp-server`).
> - Be sure to use **double backslashes (`\\`)** in paths to escape them correctly in JSON.

#### B. macOS / Linux Setup
Locate your Claude Code global configuration file (typically `~/.claude.json`).
Update or create the file with the following configuration:

```json
{
  "mcpServers": {
    "agy": {
      "command": "<WORKSPACE_ABSOLUTE_PATH>/agy-mcp-env/bin/python",
      "args": [
        "<WORKSPACE_ABSOLUTE_PATH>/mcp-server/server.py"
      ],
      "env": {
        "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
        "GCP_LOCATION": "<YOUR_GCP_LOCATION>"
      }
    }
  }
}
```
> [!IMPORTANT]
> - Replace `<WORKSPACE_ABSOLUTE_PATH>` with the full absolute path of this workspace directory (e.g. `/Users/yourname/projects/antigravity-mcp-server`).

---

### Option 2: Server (SSE) Transport Mode

In this mode, the MCP server runs persistently in a separate terminal process as an HTTP server, and Claude Code communicates with it over Server-Sent Events (SSE).

#### 1. Launch the Standalone Server
Run the following command in a separate terminal window to start the persistent server on port `8000`:

* **On macOS / Linux:**
  ```bash
  agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000
  ```
* **On Windows:**
  ```bash
  .\agy-mcp-env\Scripts\python.exe mcp-server\server.py --transport sse --port 8000
  ```

#### 2. Configure Claude Code Config File
Locate your global Claude Code configuration file (`~/.claude.json` or `%USERPROFILE%\.claude.json`).
Register the persistent server endpoint by updating the file with the following:

```json
{
  "mcpServers": {
    "agy": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}
```

---

## Running the Components

### A. Run the Test Client (Web UI)
To launch the test web app:
```bash
# Using macOS/Linux activated venv or direct path:
agy-mcp-env/bin/python test-mcp-client/app.py

# Using Windows direct path:
.\agy-mcp-env\Scripts\python.exe test-mcp-client\app.py
```
Open [http://127.0.0.1:5001](http://127.0.0.1:5001) in your browser. It will automatically detect your live SSE server on port 8000 or fall back to spawning its own STDIO background subprocess!

### B. Run the MCP Server Directly
If you want to run the server in standalone SSE mode on port 8000:
```bash
agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000
```

## References
- [Google Antigravity Python SDK Repository](https://github.com/google-antigravity/antigravity-sdk-python)

---
---

# 한국어 문서

> [!WARNING]
> **프로토타입 릴리즈 안내**
> 본 repo는 Antigravity SDK의 데모 및 프로토타입입니다. 프로덕션 환경에 적용할 경우 충분한 검토가 필요합니다.

## 프로젝트 구조

본 프로젝트는 Google Antigravity SDK 및 Google Cloud Gemini Enterprise Agent Platform (Gemini) 기반의 파이썬 Model Context Protocol (MCP) 서버와 이를 테스트할 수 있는 반응형 웹 애플리케이션으로 구성되어 있습니다.
1. **`mcp-server/`**: 핵심 파이썬 MCP 서버.
   - `FastMCP` 및 `google.antigravity` SDK 활용.
   - `agy_task` 및 `agy_code_review` 도구 제공.
2. **`test-mcp-client/`**: 로컬 테스트용 웹 애플리케이션.
   - `Starlette` 및 `Uvicorn` 기반 설계.
   - MCP Server를 테스트해볼 수 있는 웹 인터페이스입니다.
   - 활성화된 포트 8000 SSE 서버를 우선 감지하며, 오프라인 시 백그라운드 서브프로세스(STDIO 방식)로 MCP 서버를 유연하게 자동 연동.

---

## 시스템 아키텍처 및 멀티 에이전트 라우팅 (Multi-Agent Routing)

본 작업 공간은 상위 조율자(Claude Code)와 하위 실행자(Antigravity Agent) 간의 유기적인 **멀티 에이전트 라우팅(Multi-Agent Routing)** 구조를 채택하고 있습니다. 전체 상호작용 및 통신 구조는 다음과 같습니다:

```mermaid
graph TD
    CC["Claude Code CLI"] -->|"SSE / STDIO"| MS["AGY MCP 서버"]
    TWC["테스트 웹 앱"] -->|"SSE / STDIO"| MS
    
    MS -->|"SDK 호출 및 초기화"| Agent["Antigravity 에이전트"]
    Agent -->|"Gemini API 호출"| Vertex["Gemini Enterprise Agent Platform"]
    
    Agent -.->|"기록 저장"| Log["Telemetry Log<br>(thinking.log)"]
    TWC -.->|"로그 파싱"| Log

    style CC fill:#d4f0ff,stroke:#333,stroke-width:2px
    style TWC fill:#d4f0ff,stroke:#333,stroke-width:2px
    style MS fill:#bbf,stroke:#333,stroke-width:2px
    style Agent fill:#f9f,stroke:#333,stroke-width:2px
    style Vertex fill:#bfb,stroke:#333,stroke-width:2px
    style Log fill:#ffe,stroke:#333,stroke-width:1px
```

### 기술 워크플로우 및 멀티 에이전트 라우팅 동작 원리

1. **상위 오케스트레이터로서의 Claude Code (최상위 라우터)**
   사용자가 `antigravity`, `agy`, `gemini`, `제미나이` 등의 키워드로 작업을 내리면 Claude Code가 최상위 중재자가 됩니다. 작업을 맹목적으로 자체 수행하는 대신, 의미론적 키워드 매칭을 통해 가장 적합한 전용 MCP 도구를 검색합니다.
2. **통합 의미론적 동의어 라우팅 (Cohesive Semantic Synonym Routing)**
   FastMCP 도구들(`agy_task`, `agy_code_review`)의 docstring에 상세한 의미론적 키워드가 설계되어 있어, Claude Code가 이를 동적으로 감지하여 당사 MCP 서버로 위임(Routing)합니다. 이를 통해 다수의 서버를 개별 실행하지 않고 단일 진입점에서 안정적인 자원 제어가 가능해집니다.
3. **하위 전문 에이전트로의 자율 위임 (Antigravity Agent 실행)**
   AGY MCP 서버는 위임 요청(JSON-RPC)을 수신한 즉시 내부적으로 하위 전문 에이전트(Antigravity Agent)를 동적으로 생성합니다. 이 에이전트는 Google Cloud Gemini Enterprise Agent Platform의 고성능 추론 능력을 직접 활용하여 로컬 파일 편집 및 고도화된 코드 리뷰를 전담 수행합니다.
4. **텔레메트리 로그**
   에이전트 실행 시 발생하는 추론 과정은 프로젝트 디렉터리 바깥 경로(`~/.gemini/antigravity/thinking.log`)에 저장합니다.

---

## 설치 및 서버 설정 가이드

처음 프로젝트를 시작하는 개발자도 쉽게 따라 할 수 있도록 정리된 단계별 가이드입니다 (Windows, macOS, Linux 지원).

### 1. 사전 준비 사항
- **Python 3.10 이상**이 시스템에 설치되어 있어야 합니다.
- **Google Cloud SDK (`gcloud` CLI)** 가 설치 및 로그인 설정되어 있어야 합니다.
- **Gemini Enterprise Agent Platform API** 가 활성화된 **Google Cloud 프로젝트**가 필요합니다.

### 2. Google Cloud 인증 등록
로컬 터미널 환경에 Google Cloud 권한을 이식해 Gemini Enterprise Agent Platform 및 Gemini 모델에 연결할 수 있도록 설정합니다:
```bash
gcloud auth application-default login
```

### 3. 파이썬 가상환경 초기화 및 의존성 설치
새로운 가상환경을 구성하고 프로젝트에 필요한 라이브러리 패키지들을 설치합니다:
```bash
# 가상환경 생성
python -m venv agy-mcp-env

# 가상환경 활성화
# macOS/Linux 환경:
source agy-mcp-env/bin/activate
# On Windows (PowerShell):
.\agy-mcp-env\Scripts\Activate.ps1
# On Windows (CMD):
.\agy-mcp-env\Scripts\activate.bat

# 필수 패키지 설치
pip install -r requirements.txt
```

### 4. GCP 환경 변수 및 설정 파일 작성
`mcp-server/` 디렉터리 하위에 설정 파일 `agy-mcp-config.json`을 새로 작성하여 서버가 접근할 GCP 자원을 선언합니다:
```json
{
  "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
  "GCP_LOCATION": "<YOUR_GCP_LOCATION>",
  "MODEL": "gemini-3.7-flash"
}
```
> [!NOTE]
> `<YOUR_GCP_PROJECT_ID>` 부분에는 실제 Google Cloud Project ID를 적어주시고, `<YOUR_GCP_LOCATION>`에는 리전(예: `us-central1`, `us-east4` 등)을 기입해 주십시오.

---

## Claude Code 연동 방법

이 서버를 **Claude Code**에 연동하는 방법은 런타임 구성 방식에 따라 아래 두 가지 옵션 중 하나를 선택하여 진행할 수 있습니다.

### 옵션 1: STDIO 통신 모드 (추천)

이 모드에서는 Claude Code가 백그라운드 서브프로세스로 파이썬 MCP 서버를 직접 구동하고 필요한 시점에 통신합니다.

#### A. Windows 환경 설정 (PowerShell)
Claude Code의 글로벌 설정 파일(일반적으로 `%USERPROFILE%\.claude.json` 또는 `C:\Users\<사용자명>\.claude.json`)을 찾아 아래와 같이 수정하거나 생성합니다:

```json
{
  "mcpServers": {
    "agy": {
      "command": "<WORKSPACE_ABSOLUTE_PATH>\\agy-mcp-env\\Scripts\\python.exe",
      "args": [
        "<WORKSPACE_ABSOLUTE_PATH>\\mcp-server\\server.py"
      ],
      "env": {
        "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
        "GCP_LOCATION": "<YOUR_GCP_LOCATION>"
      }
    }
  }
}
```
> [!IMPORTANT]
> - `<WORKSPACE_ABSOLUTE_PATH>` 자리에 현재 프로젝트 작업공간 폴더의 **절대 경로**(예: `C:\\Users\\yourname\\projects\\antigravity-mcp-server`)를 입력합니다.
> - JSON 규격에 맞게 경로 내 백슬래시 기호는 **반드시 이중 백슬래시(`\\`)**로 입력하셔야 올바르게 이스케이프 처리됩니다.

#### B. macOS / Linux 환경 설정
Claude Code의 글로벌 설정 파일(일반적으로 `~/.claude.json`)을 찾아 아래와 같이 수정하거나 생성합니다:

```json
{
  "mcpServers": {
    "agy": {
      "command": "<WORKSPACE_ABSOLUTE_PATH>/agy-mcp-env/bin/python",
      "args": [
        "<WORKSPACE_ABSOLUTE_PATH>/mcp-server/server.py"
      ],
      "env": {
        "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
        "GCP_LOCATION": "<YOUR_GCP_LOCATION>"
      }
    }
  }
}
```
> [!IMPORTANT]
> `<WORKSPACE_ABSOLUTE_PATH>` 자리에 현재 프로젝트 작업공간 폴더의 **절대 경로**(예: `/Users/yourname/projects/antigravity-mcp-server`)를 정확히 기입합니다.

---

### 옵션 2: 서버 모드 (SSE 통신 모드)

이 모드에서는 MCP 서버를 별도의 독립된 터미널 런타임에서 백그라운드 HTTP 서버로 상시 대기 구동하며, Claude Code가 Server-Sent Events(SSE) 프로토콜을 통해 연결을 요청합니다.

#### 1. 독립형 서버 실행
별도의 터미널 창을 열고 아래 명령어를 기동하여 포트 `8000`번으로 영속(Persistent) 서버를 시작합니다:

* **macOS / Linux 환경:**
  ```bash
  agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000
  ```
* **Windows 환경:**
  ```bash
  .\agy-mcp-env\Scripts\python.exe mcp-server\server.py --transport sse --port 8000
  ```

#### 2. Claude Code 설정 파일 등록
Claude Code 글로벌 설정 파일(`~/.claude.json` 또는 `%USERPROFILE%\.claude.json`)을 찾아 아래와 같이 수동 실행된 서버의 주소를 명시합니다:

```json
{
  "mcpServers": {
    "agy": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}
```

---

## 구성 요소 실행 방법

### A. 테스트 클라이언트 (Web UI) 구동
테스트용 웹 앱을 실행하려면 다음 명령어를 기동합니다:
```bash
# macOS/Linux에서 가상환경이 켜진 상태 또는 전체 경로로 실행:
agy-mcp-env/bin/python test-mcp-client/app.py

# Windows PowerShell에서 실행:
.\agy-mcp-env\Scripts\python.exe test-mcp-client\app.py
```
Open [http://127.0.0.1:5001](http://127.0.0.1:5001)을 열어줍니다. 실시간으로 8000번 포트의 활성 SSE 서버 상태를 감지하며, 서버가 꺼져 있을 경우 자동으로 백그라운드 STDIO 서브프로세스로 기동해 연동합니다!

### B. MCP 서버 수동 구동 (단독 실행)
독립적인 SSE 수신 포트(8000번)로 서버를 단독 구동하려는 경우:
```bash
agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000
```

## 참고 자료
- [Google Antigravity Python SDK](https://github.com/google-antigravity/antigravity-sdk-python)