Antigravity MCP Bridge (Antigravity 2.0 ↔ Gemini Spark)

通过 Gemini Spark 以及基于 Streamable HTTP 和 stdio 传输的远程/本地 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. 认证与令牌保护：

   • AuthMiddleware 在 /mcp 上强制执行令牌验证。

   • 支持 Authorization: Bearer <token>、x-api-key: <token> 或 ?token=<token>。

   • 如果 .env 中缺少令牌，则自动生成 32 位十六进制令牌。

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：完整的集成状态报告和经验验证矩阵。