# gws-mcp (Google Workspace MCP Server)

A Model Context Protocol (MCP) server providing safe, auditable, and comprehensive control over **Google Drive**, **Google Sheets**, **Google Docs**, and **Google Slides**.

Built for AI agents and scheduled pipelines to create, read, edit, format, and organize Google Workspace resources with safety-first guardrails (`dry_run` previews and append-only audit logs).

---

## 🌟 Key Features

- **Safe-by-Default Execution**: Every mutating tool implements a two-phase `plan()` $\to$ `execute()` pipeline with dry-run support. Passing `dry_run: true` computes the exact diff without modifying resources.
- **Append-Only Audit Logging**: All mutations record intent and outcome entries to a local JSONL audit trail without logging customer data or PII.
- **Dual Authentication Modes**:
  - **Service Account** (`AUTH_MODE=service_account`): Ideal for backend automations, CRMs, and scheduled workers operating on shared files.
  - **User OAuth 2.0** (`AUTH_MODE=oauth`): For interactive user sessions with support for creating new files in personal Google Drives.
- **Rich Formatting Engine**: Pixel-level styling, typography, RGB colors, alignments, wrap rules, bullet lists, dimension management, tables, and images.

---

## 🧰 Complete Tool Catalog (24 Tools)

### 📊 Google Sheets (9 Tools)
1. **`sheets_read_range`** — Read cell values using standard A1 notation (e.g. `"Leads!A1:F50"`).
2. **`sheets_append_rows`** — Append rows with deduplication keys (`dedupKey`) and formula injection defense.
3. **`sheets_update_range`** — Overwrite cell values or write to new columns with before/after diffs in dry-run mode.
4. **`sheets_format`** — Format cells: bold, italic, strikethrough, underline, font size, font family, text RGB, background RGB, number formats, horizontal/vertical alignment (`TOP`/`MIDDLE`/`BOTTOM`), text wrapping (`WRAP`/`CLIP`/`OVERFLOW`), column widths, row heights, and freeze panes.
5. **`sheets_manage_dimensions`** — Structural operations: insert blank rows/columns anywhere, delete row/column ranges, or append dimensions to expand sheet boundaries.
6. **`sheets_clear`** — Clear `VALUES`, `FORMAT`, or `ALL` across a range without deleting grid rows.
7. **`sheets_add_tab`** — Create new tabs with optional header row initialization.
8. **`sheets_duplicate_tab`** — Clone an existing tab (preserving formulas, styles, and data) into a new tab.
9. **`sheets_delete_tab`** — Delete a tab by name (with safeguards against deleting the last remaining tab).

### 📄 Google Docs (8 Tools)
1. **`docs_read`** — Read complete plain text content from documents, tables, and outlines.
2. **`docs_style`** — Format text and paragraphs: headings (`HEADING_1` to `HEADING_6`, `TITLE`, `SUBTITLE`), bold, italic, underline, strikethrough, font size, font family, foreground RGB, background highlight RGB, hyperlinks (`link`), paragraph alignment, line spacing, and paragraph margins (`spaceAbove`, `spaceBelow`).
3. **`docs_insert_text`** — Insert text at specific character indices or append to body/headers/footers.
4. **`docs_replace_text`** — Search and replace template placeholders (e.g. `{{client_name}}`) case-sensitively or insensitively.
5. **`docs_insert_table`** — Insert $R \times C$ tables at any character position or append to the end.
6. **`docs_insert_image`** — Insert **inline** or **floating/positioned** images with custom dimensions, offsets, and text wrap modes (`WRAP_TEXT`, `IN_FRONT_OF_TEXT`, `BEHIND_TEXT`, etc.).
7. **`docs_insert_bullets`** — Convert paragraphs into bulleted lists (`BULLET_DISC_CIRCLE_SQUARE`, `BULLET_CHECKBOX`, `NUMBERED_DECIMAL_ALPHA_ROMAN`, etc.) or remove bullets.
8. **`docs_delete_content`** — Remove character ranges or sections from document body, headers, or footers.

### 📽️ Google Slides (6 Tools)
1. **`slides_read`** — Read presentation structure, slide IDs, elements, and extracted text.
2. **`slides_create`** — Create a new blank presentation or copy from a template deck.
3. **`slides_add_slide`** — Insert a new slide with predefined layouts (`TITLE_AND_BODY`, `SECTION_HEADER`, `MAIN_POINT`, `BLANK`, etc.).
4. **`slides_duplicate_slide`** — Duplicate a designed slide layout to populate repeated items (e.g. case studies, portfolios).
5. **`slides_replace_text`** — Find and replace `{{placeholders}}` across the entire deck.
6. **`slides_insert_image`** — Insert images onto slides at specific $(X, Y)$ positions and sizes.

### 🔍 Google Drive (5 Tools)
1. **`drive_find`** — Search files and folders by name and MIME type with pagination and truncation awareness.
2. **`drive_create`** — Create a new Google Doc, Google Sheet, Google Slides presentation, or Drive folder.
3. **`drive_copy`** — Duplicate an existing file or template.
4. **`drive_share`** — Share files or folders with user emails (`reader`, `commenter`, `writer`/`editor`).
5. **`drive_move`** — Move files between folders or rename files.

---

## 🚀 Setup & Installation

### 1. Prerequisites
- Node.js 20+
- A Google Cloud Project with the following APIs enabled:
  - Google Drive API
  - Google Sheets API
  - Google Docs API
  - Google Slides API

### 2. Configure Environment

Copy `.env.example` to `.env`:

```bash
cp .env.example .env
```

#### Option A: Service Account (Recommended for Automations)
1. In Google Cloud Console, create a Service Account and download its JSON key file.
2. Share the target Google Drive folders/files with the service account email.
3. In `.env`:
   ```bash
   AUTH_MODE=service_account
   GOOGLE_SA_KEY_PATH=./sa-key.json
   ```

#### Option B: User OAuth 2.0 (For Personal User Drives)
1. In Google Cloud Console, create an OAuth 2.0 Client ID (Desktop or Web application).
2. In `.env`:
   ```bash
   AUTH_MODE=oauth
   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_REFRESH_TOKEN=your-refresh-token
   ```

---

## 🔌 Connecting to Claude Desktop / MCP Clients

Add the server to your `claude_desktop_config.json` or MCP settings:

```json
{
  "mcpServers": {
    "gws": {
      "command": "node",
      "args": ["/absolute/path/to/gws-mcp/dist/server/stdio.js"],
      "env": {
        "AUTH_MODE": "service_account",
        "GOOGLE_SA_KEY_PATH": "/absolute/path/to/sa-key.json",
        "AUDIT_LOG_PATH": "/absolute/path/to/gws-mcp/audit.jsonl"
      }
    }
  }
}
```

---

## 🧪 Development & Testing

```bash
# Run unit and contract test suites (100% offline via nock mocks)
npm test

# Check TypeScript types
npm run typecheck

# Build for production
npm run build

# Run integration tests against live Google Cloud APIs (optional)
GWS_INTEGRATION=1 npm run test:integration
```