# Antigravity IDE x Google Workspace (Docs, Sheets, Drive) MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-green.svg)](https://nodejs.org)
[![Token Savings](https://img.shields.io/badge/Token%20Savings-70%25%20to%2090%25-orange.svg)](recipes/token-optimization-cheatsheet.md)

A standalone, token-optimized **Model Context Protocol (MCP)** server integration connecting **Antigravity IDE** with **Google Docs, Google Sheets, Google Drive, Gmail, and Google Calendar**.

Engineered with token-reduction protocols (`AGENTS.md`) designed to reduce context consumption by **70% to 90%**, accelerating agent latency and preserving the LLM context window.

---

## Table of Contents
1. [Overview & Capabilities](#overview--capabilities)
2. [Prerequisites](#prerequisites)
3. [Step 1: Google Cloud OAuth 2.0 Credentials](#step-1-google-cloud-oauth-20-credentials)
4. [Step 2: Interactive Setup & Management Script](#step-2-interactive-setup--management-script)
5. [Step 3: IDE Activation](#step-3-ide-activation)
6. [Token Optimization Strategy](#token-optimization-strategy)
7. [Turnkey Templates, Recipes & Antigravity Skill](#turnkey-templates-recipes--antigravity-skill)
8. [Project Workspace Starter Kit (Your Own Project)](#project-workspace-starter-kit-use-in-your-own-project)
9. [Credential Management & Revocation](#credential-management--revocation)
10. [Example Prompt Templates](#example-prompt-templates)
11. [Troubleshooting & FAQ](#troubleshooting--faq)
12. [Contributing & Pull Requests](#contributing--pull-requests)
13. [License](#license)

---

## Overview & Capabilities

Once integrated, Antigravity IDE gains direct access to your Google Workspace environment:

- **Google Docs**: Author new documents, read content as token-lean Markdown, insert structured tables, conduct surgical text replacements (`findAndReplace`, `replaceRangeWithMarkdown`), and append revisions.
- **Google Sheets**: Provision spreadsheets, inspect schema metadata, perform 2D batch writes, set cell formatting/borders, and compute formula ranges.
- **Google Drive**: Search folders/files, inspect file metadata, create directory structures, and manage file hierarchies.
- **Gmail & Calendar**: Compose and draft messages, list recent inbox threads, schedule meetings, and modify calendar events.

---

## Prerequisites

- **Node.js**: Version 18.0.0 or higher.
- **npm**: Version 8.0.0 or higher.
- **PowerShell**: Windows PowerShell 5.1 or PowerShell Core 7+.
- **Google Cloud Platform (GCP) Account**: Access to create an OAuth 2.0 Client ID.

---

## Step 1: Google Cloud OAuth 2.0 Credentials

To authorize access to your Google Workspace resources:

1. **Open Google Cloud Console**: Navigate to [console.cloud.google.com](https://console.cloud.google.com/).
2. **Create or Select a Project**: Select the project dropdown in the top navigation bar and click **New Project** (e.g., `Antigravity-Workspace-MCP`).
3. **Enable Workspace APIs**: In the top search bar, locate and enable each of the following:
   - `Google Docs API`
   - `Google Sheets API`
   - `Google Drive API`
   - *(Optional)* `Gmail API`, `Google Calendar API`.
4. **Configure OAuth Consent Screen**:
   - Navigate to **APIs & Services** > **OAuth consent screen** (or **Google Auth Platform**).
   - User Type: Select **External**, then click **Create**.
   - Input App Name (e.g., `Antigravity MCP`), User support email, and Developer contact information.
   - **Scopes**: Click **Add or remove scopes** and select:
     - `.../auth/documents`
     - `.../auth/spreadsheets`
     - `.../auth/drive`
   - **Test Users**: Under the **Audience** / **Test users** section, click **Add Users** and add your personal Google account email address.
5. **Create OAuth Client ID**:
   - Navigate to **APIs & Services** > **Credentials**.
   - Click **+ Create Credentials** > **OAuth client ID**.
   - Application type: Select **Desktop app**.
   - Click **Create**.
   - Note down:
     - **Client ID** (`xxx...apps.googleusercontent.com`)
     - **Client Secret** (`GOCSPX-xxx...`)

---

## Step 2: Interactive Setup & Management Script

This repository includes `setup.ps1`, an interactive management console providing automated setup, credential updating, browser authentication, diagnostics, and complete uninstallation/permission revocation.

### Launching the Management Console:

```powershell
.\setup.ps1
```

The script displays an interactive menu:

```text
======================================================================
    Google Workspace MCP for Antigravity IDE - Management Console
======================================================================
  [1] Complete Setup / Install (Dependencies, OAuth & IDE Config)
  [2] Update OAuth Credentials (Client ID & Client Secret)
  [3] Re-authenticate Account (OAuth Browser Sign-in)
  [4] Revoke Permissions & Uninstall (Revoke Token, Remove Config)
  [5] View Diagnostics & Connection Status
  [0] Exit
======================================================================
```

### Script Execution Modes:

- **Interactive Menu**: Run `.\setup.ps1` with no arguments to navigate the interactive console.
- **Direct Parameter Execution**:
  ```powershell
  # Non-interactive automated install
  .\setup.ps1 -ClientID "your-client-id" -ClientSecret "your-client-secret"
  
  # Or invoke specific actions
  .\setup.ps1 -Action Install
  .\setup.ps1 -Action UpdateCredentials
  .\setup.ps1 -Action Reauth
  .\setup.ps1 -Action Uninstall
  .\setup.ps1 -Action Status
  ```

---

## Step 3: IDE Activation

After completing setup:

1. Launch **Antigravity IDE**.
2. Press **`Ctrl + Shift + P`** (or `Cmd + Shift + P` on macOS) to open the Command Palette.
3. Type and select **`Reload Window`**.
4. Antigravity IDE will automatically detect and load the `google-docs` MCP server. You can verify connection status under **Additional Options (...)** > **MCP Servers**.

---

## Token Optimization Strategy

Large documents and spreadsheets can rapidly exhaust context windows if unoptimized. The rules codified in `AGENTS.md` enforce surgical, token-efficient interactions:

| Operation | Inefficient Approach (Excessive Tokens) | Optimized Strategy (70-90% Reduction) |
| :--- | :--- | :--- |
| **Reading Google Docs** | JSON AST format (~15,000 tokens for 5 pages). | Request Markdown via `format: "markdown"` (~1,500 tokens). |
| **Modifying Docs** | Reading full doc and overwriting entirely. | Use `findElement` with `replaceRangeWithMarkdown` or `modifyText`. |
| **Reading Sheets** | Unbounded range read (e.g. `A:Z` with empty cells). | Query `getSpreadsheetInfo` first; read bounded active bounds (e.g. `A1:F25`). |
| **Writing to Sheets** | Repeated single-cell write calls. | Aggregate into 2D arrays and issue a single `writeSpreadsheet` or `batchWrite`. |
| **Agent Response** | Echoing complete document contents back to chat. | Return success status, resource URL, and a 1-2 bullet diff summary. |

---

## Turnkey Templates, Recipes & Antigravity Skill

This repository provides pre-built templates, styling recipes, and an Antigravity Skill automatically discovered by the IDE to streamline document authoring and minimize token overhead.

### 1. Antigravity Skill & Rule (`.agents/`)
- [`.agents/skills/google-workspace-designer/SKILL.md`](file:///c:/Users/nguye/Material/tools/tool_dev/antigravity-google-suite/.agents/skills/google-workspace-designer/SKILL.md): Complete design skill loaded automatically by Antigravity, including palette definitions, table creation sequences, and image constraints.
- [`.agents/rules/workspace-token-standards.md`](file:///c:/Users/nguye/Material/tools/tool_dev/antigravity-google-suite/.agents/rules/workspace-token-standards.md): Mandatory agent rules enforcing markdown-first reads, bounded spreadsheet queries, and zero-echoing outputs.

### 2. Ready-to-Use Document & Spreadsheet Templates (`templates/`)
- [`templates/docs/project-specification.md`](file:///c:/Users/nguye/Material/tools/tool_dev/antigravity-google-suite/templates/docs/project-specification.md): Architecture spec & PRD layout with KPI tables, RACI matrix, roadmap timeline, and risk register.
- [`templates/docs/executive-brief.md`](file:///c:/Users/nguye/Material/tools/tool_dev/antigravity-google-suite/templates/docs/executive-brief.md): 2-page decision brief with business case comparison and budget breakdown.
- [`templates/sheets/project-tracker.json`](file:///c:/Users/nguye/Material/tools/tool_dev/antigravity-google-suite/templates/sheets/project-tracker.json): Sprint task tracker schema with cell values, formula rows, number formats, and border definitions.
- [`templates/sheets/kpi-dashboard.json`](file:///c:/Users/nguye/Material/tools/tool_dev/antigravity-google-suite/templates/sheets/kpi-dashboard.json): Financial model schema with gross margin formulas, currency formatting, and frozen panes.

### 3. Execution Recipes & Architecture Guides (`recipes/`)
- [`recipes/document-understanding-guide.md`](file:///c:/Users/nguye/Material/tools/tool_dev/antigravity-google-suite/recipes/document-understanding-guide.md): Architecture guide for index-first reading and understanding large docs without context bloat.
- [`recipes/table-styling.md`](file:///c:/Users/nguye/Material/tools/tool_dev/antigravity-google-suite/recipes/table-styling.md): Exact parameters for `updateTableCellStyle`, `updateTableBorders`, `formatCells`, and `setCellBorders`.
- [`recipes/image-formatting.md`](file:///c:/Users/nguye/Material/tools/tool_dev/antigravity-google-suite/recipes/image-formatting.md): Page geometry math in points (468pt printable width), dimension presets, and caption alignment.
- [`recipes/token-optimization-cheatsheet.md`](file:///c:/Users/nguye/Material/tools/tool_dev/antigravity-google-suite/recipes/token-optimization-cheatsheet.md): Benchmarks, tool call sequences, and surgical editing snippets saving 70% to 90% tokens.

---

## Project Workspace Starter Kit (Use in Your Own Project)

Want Antigravity to understand and manipulate Google Docs and Sheets directly inside your own application codebase? We provide a pre-packaged starter kit under [`workspace-template/`](file:///c:/Users/nguye/Material/tools/tool_dev/antigravity-google-suite/workspace-template):

```text
your-project-folder/
├── .agents/
│   └── rules/
│       └── project-google-context.md   # Automatic Antigravity discovery rule
├── google-workspace.json               # Maps "spec" & "tracker" to actual Google IDs
├── DOCS_INDEX.md                       # Local outline cache (< 200 tokens)
└── WORKSPACE_GUIDE.md                  # Comprehensive user guide
```

### 1-Click Scaffolding:
Run from this repository:
```powershell
.\setup.ps1 -Action InitProject -TargetDir "C:\Projects\MyAwesomeApp"
```
Or select **`[6] Scaffold Project Workspace`** from the interactive menu!

### How Antigravity Uses It:
1. **Never type URLs or IDs again**: Antigravity automatically resolves *"the spec"* to your configured Doc ID and *"the sprint tracker"* to your Sheet ID.
2. **Instant Understanding**: Antigravity reads local `DOCS_INDEX.md` in ~150 tokens to know where headings, sections, and tables live before calling Google APIs.
3. **Natural Prompting**:
   - *"Read Section 3 of our spec and explain the database schema."*
   - *"Add a new task 'Implement Redis cache' to our sprint tracker with priority High."*
   - *"In the technical spec, update Section 2.1 with postgres connection parameters."*

---

## Credential Management & Revocation

If you need to rotate keys, switch Google accounts, or revoke all permissions:

### Option A: Via the Interactive Menu
Run `.\setup.ps1`:
- Select **[2] Update OAuth Credentials**: Allows updating `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` across both local configuration and IDE settings.
- Select **[3] Re-authenticate Account**: Triggers a fresh browser consent screen without altering configuration keys.
- Select **[4] Revoke Permissions & Uninstall**:
  1. Sends a revocation request directly to Google Identity (`https://oauth2.googleapis.com/revoke`), immediately invalidating access on your Google account.
  2. Deletes local token storage (`~/.config/google-docs-mcp/token.json`).
  3. Removes the `google-docs` entry from Antigravity IDE's configuration (`~/.gemini/config/mcp_config.json`).
  4. Offers to clean up local `.env` and environment variables.

### Option B: Manual Revocation
- **Google Account Permissions**: Visit [myaccount.google.com/permissions](https://myaccount.google.com/permissions) to view and revoke third-party app authorizations directly.
- **Local Stored Tokens**: Delete `%USERPROFILE%\.config\google-docs-mcp\token.json`.
- **IDE Configuration**: Remove `"google-docs"` from `%USERPROFILE%\.gemini\config\mcp_config.json`.

---

## Example Prompt Templates

You can interact with your Google Workspace using natural language in Antigravity IDE:

### Google Docs:
- *"Create a Google Doc titled 'Q4 Engineering Roadmap' with sections for Goals, Architecture, and Timeline."*
- *"Read the document at [DOCUMENT_ID] as markdown and provide a 3-bullet executive summary."*
- *"In document [DOCUMENT_ID], find the section 'Budget Estimates' and insert a 3-column table with projected infrastructure costs."*

### Google Sheets:
- *"Create a Google Sheet titled '2026 Sprint Velocity' with columns: Sprint, Planned Points, Completed Points, Completion Rate."*
- *"Read the range A1:D10 from spreadsheet [SHEET_ID] and calculate the average completion rate."*
- *"Append 5 new test result rows to the end of spreadsheet [SHEET_ID]."*

### Google Drive:
- *"Search my Google Drive for files containing 'Architecture Spec' created in the last 30 days."*
- *"Create a directory named 'Release Artifacts' and move file [FILE_ID] into it."*

---

## Troubleshooting & FAQ

#### 1. "Access blocked: This app has not been verified"
- **Cause**: The authenticated Google account is not listed under Test Users in the Google Cloud Console.
- **Resolution**: In Google Cloud Console, navigate to **APIs & Services** > **OAuth consent screen** > **Test users**, click **Add Users**, and add your email address.

#### 2. "Apps Script API has not been used..."
- If generating Apps Script projects, verify that the Google Apps Script API is enabled at [script.google.com/home/usersettings](https://script.google.com/home/usersettings).

#### 3. MCP Server does not appear in Antigravity IDE
- Verify that `~/.gemini/config/mcp_config.json` contains the `google-docs` entry.
- Trigger **`Reload Window`** via `Ctrl + Shift + P`.
- Run `.\setup.ps1` and choose **[5] View Diagnostics & Connection Status** to diagnose file paths and token state.

---

## Contributing & Pull Requests

Contributions, bug reports, and feature proposals are warmly welcome!
- Check out our [Contributing Guide](CONTRIBUTING.md) to get started.
- Adhere to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
- Follow the token discipline guidelines defined in [`AGENTS.md`](AGENTS.md).
- Submit Pull Requests against the `main` branch of [github.com/duc-long/antigravity-google-suite](https://github.com/duc-long/antigravity-google-suite).

---

## License

This project is open-source software licensed under the [MIT License](LICENSE).
Copyright (c) 2026 Duc Long.