Add Gmail integration design for PA agent

Design for read-only Gmail access via MCP server, including: - Architecture using theposch/gmail-mcp - Gmail skill with search, check-unread, check-urgent patterns - Content-based urgency detection - Implementation phases with user/agent ownership 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-29 13:43:42 -08:00
parent 610d62f794
commit 51726d96a0
1 changed files with 135 additions and 0 deletions
--- a/docs/plans/2025-12-29-gmail-integration-design.md
+++ b/docs/plans/2025-12-29-gmail-integration-design.md
@@ -0,0 +1,135 @@
+# Gmail Integration for Personal Assistant
+
+**Date:** 2025-12-29
+**Status:** Approved
+
+## Overview
+
+Integrate Gmail read access into the Personal Assistant agent via MCP server, enabling email search, unread checking, and urgency detection.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Personal Assistant                    │
+│                        (Opus)                           │
+└─────────────────────────┬───────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          │               │               │
+          ▼               ▼               ▼
+   ┌──────────┐    ┌──────────┐    ┌──────────┐
+   │  Gmail   │    │  Other   │    │  Master  │
+   │  Skill   │    │  Skills  │    │  Orch    │
+   └────┬─────┘    └──────────┘    └──────────┘
+        │
+        ▼
+┌───────────────┐
+│  Gmail MCP    │  ← theposch/gmail-mcp (Python)
+│    Server     │  ← OAuth: gmail.readonly scope
+└───────┬───────┘
+        │
+        ▼
+   Gmail API
+```
+
+## Key Decisions
+
+| Aspect | Decision | Rationale |
+|--------|----------|-----------|
+| Access level | Read-only | Start minimal, upgrade later if needed |
+| Integration | MCP Server | Native Claude Code mechanism |
+| Server | theposch/gmail-mcp | Python-based, well-documented, maintained |
+| OAuth scope | gmail.readonly | Enforce read-only at OAuth level |
+| Config location | ~/.claude/mcp/ | Dedicated directory for MCP servers |
+| Tool access | Raw tools + skill | Flexibility + common patterns |
+| Urgency detection | Content-based | Keywords in subject/body, no VIP list needed |
+
+## Directory Structure
+
+```
+~/.claude/
+├── mcp/
+│   ├── servers.json              # MCP server registry
+│   └── gmail/
+│       ├── config.json           # Gmail-specific config
+│       └── venv/                 # Python virtualenv
+├── skills/
+│   └── gmail/
+│       └── SKILL.md              # Gmail skill definition
+│
+~/.gmail-mcp/
+    ├── credentials.json          # Google OAuth client (user provides)
+    └── token.json                # Refresh token (auto-managed)
+```
+
+## MCP Server Configuration
+
+**servers.json:**
+
+```json
+{
+  "gmail": {
+    "command": "~/.claude/mcp/gmail/venv/bin/python",
+    "args": ["-m", "gmail_mcp"],
+    "env": {
+      "GMAIL_CREDENTIALS_PATH": "~/.gmail-mcp/credentials.json",
+      "GMAIL_TOKEN_PATH": "~/.gmail-mcp/token.json"
+    }
+  }
+}
+```
+
+## Gmail Skill
+
+**Location:** `~/.claude/skills/gmail/SKILL.md`
+
+### Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| check-unread | Count and summarize unread emails (limit 20, group by sender/thread) |
+| check-urgent | Find emails with urgency signals in content |
+| search \<query\> | Translate natural language to Gmail query syntax |
+
+### Urgency Detection
+
+Content-based signals:
+- **Subject keywords:** urgent, asap, action required, immediate, deadline, time-sensitive, critical, important
+- **Body phrases:** "by end of day", "by EOD", "as soon as possible", "please respond", "awaiting your reply"
+
+### Policy
+
+Read-only enforced at OAuth scope level. No send, delete, or modify operations available.
+
+## Implementation Plan
+
+| Phase | Owner | Description |
+|-------|-------|-------------|
+| 1. Google Cloud Setup | User | Create project, enable Gmail API, create OAuth credentials, download credentials.json |
+| 2. MCP Server Installation | PA/Agent | Create directories, set up Python venv, install gmail-mcp |
+| 3. OAuth Flow | User | Run auth command, complete browser consent |
+| 4. Claude Code Integration | PA/Agent | Configure MCP in settings, verify tools appear |
+| 5. Skill Creation | PA/Agent | Create Gmail skill with patterns |
+| 6. PA Integration | PA/Agent | Update PA docs, test end-to-end |
+
+## Security Model
+
+- Read-only enforced at OAuth level (not just policy)
+- Tokens stored locally in ~/.gmail-mcp/, never transmitted
+- Can revoke access anytime via Google account settings
+- MCP server runs locally, emails never pass through third parties
+
+## Upgrade Path
+
+To add write capabilities later:
+
+1. Re-run OAuth flow with `gmail.modify` scope
+2. Add send/manage patterns to Gmail skill
+3. Update skill policy documentation
+4. No server changes needed
+
+## Sources
+
+- [theposch/gmail-mcp](https://github.com/theposch/gmail-mcp) - MCP server implementation
+- [GongRzhe/Gmail-MCP-Server](https://github.com/GongRzhe/Gmail-MCP-Server) - Alternative implementation