内容
# 反重力MCP
一个包含基于Python的模型上下文协议（MCP）服务器的工作空间，该服务器与 **谷歌反重力SDK** 和 **谷歌云Gemini企业代理平台（Gemini）** 集成，同时附带一个响应式测试客户端Web应用程序。
- [English 文档](#english-文档)
- [한국어 문서](#한국어-文档)
---
# English 文档
> [!WARNING]
> **原型发布通知**
> 本仓库是Antigravity SDK的演示和原型。在将其应用于生产环境之前，需要进行彻底的审查。
## 项目结构
该工作空间分为两个主要部分：
1. **`mcp-server/`**: 核心Python MCP服务器。
- 利用 `FastMCP` 和 `google.antigravity` SDK。
- 暴露 `agy_task` 和 `agy_code_review` 等工具。
2. **`test-mcp-client/`**: 本地测试Web应用程序。
- 基于 `Starlette` 和 `Uvicorn` 构建。
- 提供Web界面以轻松测试MCP服务器。
- 通过SSE在8000端口自动连接到MCP服务器，或在持久服务器离线时回落到STDIO。
---
## 系统架构和多代理路由
交互模型采用父 orchestrator（Claude Code）和专用下游代理（Antigravity Agent）之间的协作 **多代理路由** 架构。
```mermaid
graph TD
CC["Claude Code CLI"] -->|"SSE / STDIO"| MS["AGY MCP 服务器"]
TWC["测试Web客户端"] -->|"SSE / STDIO"| MS
MS -->|"调用SDK / 初始化代理"| Agent["Antigravity 代理"]
Agent -->|"Gemini API 调用"| Vertex["Gemini 企业代理平台"]
Agent -.->|"写入遥测日志"| 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作为父 orchestrator（顶级路由器）**
当用户输入包含 `antigravity`、`agy`、`gemini` 或 `제미나이` 等术语的提示时，Claude Code充当 orchestrator。 而不是盲目执行通用任务，它动态匹配语义触发词以发现我们的专用MCP工具。
2. **语义同义词路由**
由于FastMCP工具（`agy_task`、`agy_code_review`）具有丰富的语义文档字符串，Claude Code将特定领域的任务委托给AGY MCP服务器。 这避免了启动多个冗余服务器，防止资源开销和API冲突。
3. **委托给Antigravity代理（专用下游执行）**
AGY MCP服务器接受JSON-RPC请求并生成一个高度专门化的自治Antigravity代理。 由Gemini提供支持，该代理执行本地工作（例如代码修改或深度存储库审查）并流式传输token-by-token推理遥测。
4. **遥测日志**
代理执行期间生成的推理日志存储在工作空间目录外部的 `~/.gemini/antigravity/thinking.log`。
---
## 安装和服务器设置指南
按照以下步骤在任何系统（Windows、macOS或Linux）上首次设置MCP服务器。
### 1. 先决条件
- **Python 3.10+** 已安装在您的系统上。
- **谷歌云SDK（`gcloud` CLI）** 已安装并配置。
- 一个具有 **Gemini企业代理平台API** 的 **GCP项目**。
### 2. 谷歌云认证
认证您的本地环境以允许Antigravity SDK访问Gemini：
```bash
gcloud auth application-default login
```
### 3. 初始化Python虚拟环境
设置干净的虚拟环境并安装依赖项：
```bash
# 创建虚拟环境
python -m venv agy-mcp-env
# 激活虚拟环境
# 在macOS/Linux上：
source agy-mcp-env/bin/activate
# 在Windows（PowerShell）上：
.\agy-mcp-env\Scripts\Activate.ps1
# 在Windows（CMD）上：
.\agy-mcp-env\Scripts\activate.bat
# 安装所需包
pip install -r requirements.txt
```
### 4. 配置设置
在项目根目录中创建一个名为 `mcp-server/agy-mcp-config.json` 的配置文件，以将服务器指向您的GCP资源：
```json
{
"GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
"GCP_LOCATION": "<YOUR_GCP_LOCATION>",
"MODEL": "gemini-3.5-flash"
}
```
> [!NOTE]
> 将 `<YOUR_GCP_PROJECT_ID>` 替换为您的实际Google Cloud项目ID，将 `<YOUR_GCP_LOCATION>` 替换为您的期望区域（例如 `us-central1` 或 `us-east4`）。
---
## 与Claude Code集成
您可以通过以下两种传输选项之一将此服务器集成到 **Claude Code** 中，具体取决于您的运行时架构。
### 选项1：STDIO传输模式（推荐）
在此模式下，Claude Code直接将Python MCP服务器作为后台子进程启动。
#### A. Windows设置（PowerShell）
找到您的Claude Code全局配置文件（通常为 `%USERPROFILE%\.claude.json` 或 `C:\Users\<username>\.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通过服务器发送事件（SSE）与其通信。
#### 1. 启动独立服务器
在单独的终端窗口中运行以下命令，以在 `8000` 端口启动持久服务器：
* **在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）
启动测试Web应用程序：
```bash
# 使用macOS/Linux激活的虚拟环境或直接路径：
agy-mcp-env/bin/python test-mcp-client/app.py
# 使用Windows直接路径：
.\agy-mcp-env\Scripts\python.exe test-mcp-client\app.py
```
打开 [http://127.0.0.1:5001](http://127.0.0.1:5001)。它将自动检测端口8000上的实时SSE服务器或回落到启动自己的STDIO后台子进程！
### B. 直接运行MCP服务器
如果您想在 `8000` 端口以独立的SSE模式运行服务器：
```bash
agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000
```
## 参考资料
- [谷歌反重力Python SDK仓库](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 권한을 이식해 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.5-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`)를 <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
```
## 참고 자료
- [구글 반중력 Python SDK](https://github.com/google-antigravity/antigravity-sdk-python)
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器