mcp-google-gdrive 0.1.0

package/SPEC.md

@@ -0,0 +1,917 @@
+# mcp-google-gdrive — Development Specification
+
+## 1. Project Overview
+
+MCP server providing Claude Code with full read/write access to a personal Google Drive account. Implements Google Drive API v3 operations as MCP tools with automatic Google Workspace format conversion.
+
+### Key Facts
+
+| Item | Value |
+|------|-------|
+| Package name | mcp-google-gdrive |
+| Version | 0.1.0 |
+| Runtime | Node.js 18+ (ESM), verified 22.22.0 in WSL |
+| MCP SDK | @modelcontextprotocol/sdk ^1.26.0 |
+| Validation | zod ^3.25.0 |
+| Auth | Google OAuth2 (desktop app flow) |
+| API | Google Drive API v3 |
+| Extra deps | googleapis ^144.0.0, turndown ^7.2.0, marked ^15.0.0 |
+| Location | WSL ~/projects/mcp-servers/mcp-google-gdrive/ |
+| Entry point | src/index.js |
+| Transport | stdio (JSON-RPC) |
+| License | MIT |
+
+---
+
+## 2. Prerequisites and Setup
+
+### 2.1 System Requirements
+
+- Node.js 18+ (verified: v22.22.0 in WSL Fedora 43)
+- npm 10+ (verified: 10.9.4)
+- Google account with Drive access
+- Web browser accessible from WSL (for one-time OAuth2 consent)
+
+### 2.2 Google Cloud Console Setup
+
+1. Go to https://console.cloud.google.com/
+2. Create a new project (e.g., "PAI MCP Servers")
+3. Enable the Google Drive API:
+   - APIs & Services → Library → search "Google Drive API" → Enable
+4. Configure OAuth consent screen:
+   - APIs & Services → OAuth consent screen
+   - User type: External (or Internal if using Google Workspace)
+   - App name: "PAI Google Drive MCP"
+   - Scopes: Add `https://www.googleapis.com/auth/drive` (full Drive access)
+   - Test users: Add your Google email
+5. Create OAuth2 credentials:
+   - APIs & Services → Credentials → Create Credentials → OAuth client ID
+   - Application type: Desktop app
+   - Name: "mcp-google-gdrive"
+   - Download the JSON file → save as `credentials.json`
+
+### 2.3 Required OAuth2 Scopes
+
+| Scope | Purpose |
+|-------|---------|
+| `https://www.googleapis.com/auth/drive` | Full read/write access to all Drive files |
+| `https://www.googleapis.com/auth/drive.file` | Access to files created/opened by this app only (alternative, more restrictive) |
+
+Recommendation: Use `drive` scope for full access. This is a personal tool — scope restriction adds friction without meaningful security benefit for a single-user local tool.
+
+### 2.4 Token Storage
+
+- Credentials file: `~/.config/mcp-google-gdrive/credentials.json`
+- Token file: `~/.config/mcp-google-gdrive/token.json`
+- Token contains: access_token, refresh_token, expiry_date
+- Refresh tokens do not expire unless revoked or unused for 6 months
+- Access tokens expire after 1 hour; auto-refresh via googleapis client
+
+### 2.5 First-Run OAuth2 Flow (WSL → Windows Browser)
+
+Since WSL doesn't have a native browser, the first-run consent flow requires:
+
+1. Server starts, detects no token.json
+2. Generates authorization URL and prints it to stderr
+3. User copies URL to Windows browser, completes consent
+4. Google redirects to `http://localhost:PORT/callback` with auth code
+5. Server exchanges auth code for tokens, saves to token.json
+6. Subsequent runs use refresh token automatically
+
+Alternative approach if localhost redirect doesn't work in WSL:
+- Use `redirect_uri: urn:ietf:wg:oauth:2.0:oob` (manual copy-paste of auth code)
+- Server prompts "Enter the authorization code:" on stderr
+- User pastes code from browser
+
+### 2.6 Project Scaffolding
+
+```
+mcp-google-gdrive/
+  ├── .gitignore
+  ├── LICENSE (MIT)
+  ├── README.md
+  ├── package.json
+  └── src/
+      └── index.js
+```
+
+### 2.7 package.json
+
+```json
+{
+  "name": "mcp-google-gdrive",
+  "version": "0.1.0",
+  "description": "MCP server for Google Drive API with full file management and Workspace format conversion",
+  "type": "module",
+  "bin": {
+    "mcp-google-gdrive": "./src/index.js"
+  },
+  "main": "./src/index.js",
+  "scripts": {
+    "start": "node src/index.js",
+    "auth": "node src/index.js --auth"
+  },
+  "keywords": [
+    "mcp",
+    "google-drive",
+    "google-workspace",
+    "file-management"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sleepytimeshon/mcp-google-gdrive.git"
+  },
+  "homepage": "https://github.com/sleepytimeshon/mcp-google-gdrive#readme",
+  "bugs": {
+    "url": "https://github.com/sleepytimeshon/mcp-google-gdrive/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "googleapis": "^144.0.0",
+    "marked": "^15.0.0",
+    "turndown": "^7.2.0",
+    "zod": "^3.25.0"
+  }
+}
+```
+
+### 2.8 .gitignore
+
+```
+node_modules/
+credentials.json
+token.json
+```
+
+---
+
+## 3. Architecture
+
+See section 11 for full C4 model diagrams (Context, Container, Deployment) and security posture.
+
+### 3.1 Internal Components
+
+| Component | Responsibility |
+|-----------|---------------|
+| MCP Protocol Handler | McpServer + StdioServerTransport, receives tool calls |
+| Tool Registry | 14 registerTool calls with Zod schemas and annotations |
+| Auth Manager | OAuth2 token load/refresh/save using googleapis auth client |
+| Drive API Client | Thin wrapper around googleapis drive.files.* methods |
+| Format Converter | HTML→Markdown (turndown), MD→HTML (marked), Sheets→CSV/JSON parsing |
+
+### 3.2 Data Flow
+
+```
+Claude Code (Windows)
+  │ stdio (JSON-RPC)
+  ▼
+MCP Server (WSL Node.js)
+  │
+  ├── Auth Manager → token.json (local file)
+  │
+  ├── Drive API Client → Google Drive API v3 (HTTPS)
+  │     │
+  │     └── Response (file content, metadata, etc.)
+  │
+  └── Format Converter (if Google Workspace type)
+        │
+        └── Converted content (Markdown, CSV, JSON, text)
+  │
+  ▼
+MCP Response → Claude Code
+```
+
+---
+
+## 4. Tool Specifications
+
+### Naming Convention
+
+Tools use snake_case prefixed with `gdrive_` to namespace and avoid collisions:
+
+| Tool Name | Operation | Read/Write |
+|-----------|-----------|------------|
+| gdrive_list_files | List/search files | Read |
+| gdrive_get_metadata | Get file metadata | Read |
+| gdrive_read_file | Read file content | Read |
+| gdrive_create_file | Create/upload file | Write |
+| gdrive_update_file | Update file content | Write |
+| gdrive_delete_file | Trash or delete file | Write (destructive) |
+| gdrive_move_file | Move file between folders | Write |
+| gdrive_copy_file | Copy a file | Write |
+| gdrive_create_folder | Create a folder | Write |
+| gdrive_export_doc | Export Google Doc | Read |
+| gdrive_export_sheet | Export Google Sheet | Read |
+| gdrive_export_slides | Export Google Slides | Read |
+| gdrive_create_doc | Create Google Doc from Markdown | Write |
+| gdrive_update_doc | Update Google Doc content | Write |
+
+### 4.1 gdrive_list_files
+
+List files in Google Drive with optional search query and folder filtering.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.list |
+| Annotations | readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| query | string | no | — | Drive search query (e.g., "name contains 'report'") |
+| folderId | string | no | — | List files in this folder only |
+| pageSize | number | no | 20 | Results per page (max 100) |
+| pageToken | string | no | — | Token for next page of results |
+| orderBy | string | no | "modifiedTime desc" | Sort order |
+
+Response: JSON array of file objects with id, name, mimeType, modifiedTime, size, parents.
+
+### 4.2 gdrive_get_metadata
+
+Get detailed metadata for a specific file.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.get (fields parameter for metadata) |
+| Annotations | readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| fileId | string | yes | — | Google Drive file ID |
+
+Response: Full file metadata — id, name, mimeType, size, createdTime, modifiedTime, parents, webViewLink, owners, shared, description.
+
+### 4.3 gdrive_read_file
+
+Read file content with automatic format detection and conversion.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.get (alt=media) for binary; files.export for Workspace types |
+| Annotations | readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| fileId | string | yes | — | Google Drive file ID |
+
+Auto-detection logic:
+- `application/vnd.google-apps.document` → export as HTML → convert to Markdown via turndown
+- `application/vnd.google-apps.spreadsheet` → export as CSV (first sheet)
+- `application/vnd.google-apps.presentation` → export as plain text
+- `application/vnd.google-apps.drawing` → export as PNG (base64)
+- `text/*` → download raw content
+- Other binary → download up to 10MB, return metadata if larger
+
+Response: File content as text, or metadata + size warning for oversized binary files.
+
+### 4.4 gdrive_create_file
+
+Create a new file in Google Drive.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.create (with media upload) |
+| Annotations | readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| name | string | yes | — | File name including extension |
+| content | string | yes | — | File content (text) |
+| mimeType | string | no | auto-detect | MIME type of content |
+| parentFolderId | string | no | root | Parent folder ID |
+
+Response: Created file metadata (id, name, webViewLink).
+
+### 4.5 gdrive_update_file
+
+Update content of an existing file.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.update (with media upload) |
+| Annotations | readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| fileId | string | yes | — | File ID to update |
+| content | string | yes | — | New file content |
+| mimeType | string | no | preserve original | MIME type of new content |
+
+Response: Updated file metadata (id, name, modifiedTime).
+
+### 4.6 gdrive_delete_file
+
+Delete or trash a file.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.update (trashed: true) or files.delete |
+| Annotations | readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| fileId | string | yes | — | File ID to delete |
+| permanent | boolean | no | false | true = permanent delete, false = move to trash |
+
+Response: Confirmation message with file name and action taken.
+
+### 4.7 gdrive_move_file
+
+Move a file to a different folder.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.update (addParents + removeParents) |
+| Annotations | readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| fileId | string | yes | — | File ID to move |
+| destinationFolderId | string | yes | — | Target folder ID |
+
+Response: Updated file metadata with new parent.
+
+### 4.8 gdrive_copy_file
+
+Copy a file, optionally to a different folder with a new name.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.copy |
+| Annotations | readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| fileId | string | yes | — | Source file ID |
+| name | string | no | "Copy of {original}" | Name for the copy |
+| parentFolderId | string | no | same as original | Destination folder ID |
+
+Response: New file metadata (id, name, webViewLink).
+
+### 4.9 gdrive_create_folder
+
+Create a new folder.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.create (mimeType: application/vnd.google-apps.folder) |
+| Annotations | readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| name | string | yes | — | Folder name |
+| parentFolderId | string | no | root | Parent folder ID |
+
+Response: Created folder metadata (id, name, webViewLink).
+
+### 4.10 gdrive_export_doc
+
+Export a Google Doc to a specified format. Default: Markdown.
+
+Note: For the default Markdown export, this tool produces the same result as gdrive_read_file on a Google Doc. The distinction: read_file always returns Markdown (optimized for Claude's consumption), while export_doc lets you choose the output format (HTML, plain text, DOCX, PDF).
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.export |
+| Annotations | readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| fileId | string | yes | — | Google Doc file ID |
+| format | enum | no | "markdown" | "markdown", "html", "plain_text", "docx", "pdf" |
+
+Format mapping:
+- "markdown" → export as text/html → convert via turndown → return Markdown
+- "html" → export as text/html → return raw HTML
+- "plain_text" → export as text/plain
+- "docx" → export as application/vnd.openxmlformats-officedocument.wordprocessingml.document (base64)
+- "pdf" → export as application/pdf (base64)
+
+Response: Exported content in requested format.
+
+### 4.11 gdrive_export_sheet
+
+Export a Google Sheet to CSV or JSON.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.export |
+| Annotations | readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| fileId | string | yes | — | Google Sheet file ID |
+| format | enum | no | "csv" | "csv" or "json" |
+| sheetName | string | no | first sheet | Specific sheet/tab name (NOTE: requires Sheets API — see limitation below) |
+
+Limitation: The Drive API `files.export` exports the first sheet only for CSV. Exporting a specific sheet by name requires the Google Sheets API (`spreadsheets.values.get`). If sheetName is specified, the implementation should fall back to the Sheets API. This may require adding the `https://www.googleapis.com/auth/spreadsheets.readonly` scope.
+
+Format mapping:
+- "csv" → export as text/csv
+- "json" → export as text/csv → parse to JSON array of objects (headers as keys)
+
+Response: Sheet data in requested format.
+
+### 4.12 gdrive_export_slides
+
+Export Google Slides to text or PDF.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.export |
+| Annotations | readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| fileId | string | yes | — | Google Slides file ID |
+| format | enum | no | "text" | "text" or "pdf" |
+
+Format mapping:
+- "text" → export as text/plain
+- "pdf" → export as application/pdf (base64)
+
+Response: Slides content in requested format.
+
+### 4.13 gdrive_create_doc
+
+Create a new Google Doc from Markdown content.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.create (with conversion) |
+| Annotations | readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| name | string | yes | — | Document title |
+| markdownContent | string | yes | — | Markdown content to convert |
+| parentFolderId | string | no | root | Parent folder ID |
+
+Implementation: Convert Markdown → HTML, upload as text/html with `mimeType: application/vnd.google-apps.document` to trigger Google's conversion.
+
+Response: Created doc metadata (id, name, webViewLink).
+
+### 4.14 gdrive_update_doc
+
+Update an existing Google Doc with new Markdown content.
+
+| Field | Value |
+|-------|-------|
+| Drive API | files.update (with media upload and conversion) |
+| Annotations | readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true |
+
+Parameters:
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| fileId | string | yes | — | Google Doc file ID |
+| markdownContent | string | yes | — | New Markdown content (replaces entire doc) |
+
+Implementation: Convert Markdown → HTML, upload as text/html to replace doc content.
+
+Response: Updated doc metadata (id, name, modifiedTime).
+
+---
+
+## 5. Format Conversion Strategy
+
+### 5.1 Google Workspace MIME Types
+
+| Google Type | MIME Type | Default Export |
+|-------------|-----------|----------------|
+| Document | application/vnd.google-apps.document | HTML → Markdown (turndown) |
+| Spreadsheet | application/vnd.google-apps.spreadsheet | text/csv |
+| Presentation | application/vnd.google-apps.presentation | text/plain |
+| Drawing | application/vnd.google-apps.drawing | image/png |
+| Form | application/vnd.google-apps.form | N/A (not supported) |
+
+### 5.2 Turndown Configuration
+
+```javascript
+const turndownService = new TurndownService({
+  headingStyle: "atx",        // # style headings
+  codeBlockStyle: "fenced",   // ``` code blocks
+  bulletListMarker: "-",
+  emDelimiter: "_",
+  strongDelimiter: "**",
+});
+```
+
+### 5.3 Markdown → HTML for Doc Creation
+
+For creating/updating Google Docs from Markdown, a simple MD→HTML conversion is needed. Options:
+- **marked** (npm) — lightweight, fast, well-maintained
+- **showdown** (npm) — CommonMark compliant
+- Recommendation: Use **marked** (~200KB, zero deps, CommonMark)
+
+This adds one more dependency: `marked ^15.0.0`
+
+Updated dependencies:
+```json
+{
+  "googleapis": "^144.0.0",
+  "turndown": "^7.2.0",
+  "marked": "^15.0.0",
+  "@modelcontextprotocol/sdk": "^1.26.0",
+  "zod": "^3.25.0"
+}
+```
+
+---
+
+## 6. Error Handling Strategy
+
+### 6.1 Error Categories
+
+| Category | HTTP Code | MCP Response | User Message |
+|----------|-----------|--------------|--------------|
+| Auth expired | 401 | Error | "Authentication expired. Run `mcp-google-gdrive --auth` to re-authenticate." |
+| Token missing | — | Error | "No token.json found. Run `mcp-google-gdrive --auth` for first-time setup." |
+| File not found | 404 | Error | "File not found: {fileId}. Verify the file ID exists and you have access." |
+| Permission denied | 403 | Error | "Permission denied for file {fileId}. Check sharing settings." |
+| Rate limited | 429 | Error | "Rate limited by Google API. Wait and retry." (NOTE: write limit is 3 req/sec/account, hard cap) |
+| Quota exceeded | 403 (reason: dailyLimitExceeded) | Error | "Daily API quota exceeded. Try again tomorrow." |
+| File too large | — | Error | "File exceeds 10MB limit. File metadata: {name}, {size}." |
+| Invalid file type | — | Error | "Cannot export: {mimeType} is not a Google Workspace file." |
+| Network error | — | Error | "Network error connecting to Google APIs. Check internet connection." |
+
+### 6.2 Error Response Format
+
+All errors return standard MCP error content:
+```javascript
+return {
+  content: [{ type: "text", text: `Error: ${message}` }],
+  isError: true
+};
+```
+
+### 6.3 Token Auto-Refresh
+
+The googleapis client handles token refresh automatically:
+- On 401 response, client uses refresh_token to get new access_token
+- New access_token saved to token.json
+- Original request retried with new token
+- If refresh fails (revoked token), return auth expired error
+
+---
+
+## 7. File Size Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Text file < 10MB | Return full content |
+| Text file > 10MB | Return first 10MB + warning + total size |
+| Binary file < 10MB | Return base64-encoded content |
+| Binary file > 10MB | Return metadata only: name, size, mimeType, webViewLink |
+| Google Doc/Sheet/Slides | Always export (size is post-conversion, usually small) |
+
+---
+
+## 8. Claude Code MCP Configuration
+
+Add to `~/.claude/settings.json` under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "google-drive": {
+      "command": "wsl",
+      "args": ["-d", "FedoraLinux-43", "--", "bash", "-c", "node ~/projects/mcp-servers/mcp-google-gdrive/src/index.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+Alternative using npx (after npm link):
+```json
+{
+  "mcpServers": {
+    "google-drive": {
+      "command": "wsl",
+      "args": ["-d", "FedoraLinux-43", "--", "npx", "mcp-google-gdrive"],
+      "env": {}
+    }
+  }
+}
+```
+
+---
+
+## 9. Build Phases
+
+### Phase 1: Core (MVP) — Priority: Immediate
+
+1. Project scaffolding (package.json, .gitignore, LICENSE, README)
+2. OAuth2 auth flow (credentials.json → token.json, auto-refresh)
+3. gdrive_list_files (search and browse)
+4. gdrive_read_file (with auto-detection for Docs/Sheets/Slides)
+5. gdrive_get_metadata
+6. gdrive_create_file
+7. gdrive_create_folder
+8. Claude Code MCP configuration and end-to-end test
+
+Rationale: These 5 tools cover the primary use case (browse, read, create). Auth must work first. End-to-end test validates the WSL↔Windows↔Google pipeline.
+
+### Phase 2: Full CRUD — Priority: Next
+
+9. gdrive_update_file
+10. gdrive_delete_file
+11. gdrive_move_file
+12. gdrive_copy_file
+
+Rationale: Complete file management operations. Each builds on the Phase 1 foundation.
+
+### Phase 3: Workspace — Priority: After CRUD
+
+13. gdrive_export_doc (with turndown HTML→MD)
+14. gdrive_export_sheet (CSV + JSON)
+15. gdrive_export_slides
+16. gdrive_create_doc (MD→HTML→Google Doc)
+17. gdrive_update_doc
+
+Rationale: Format conversion is valuable but builds on top of working read/write. Turndown and marked dependencies only needed for this phase.
+
+### Phase 4: Polish — Priority: As needed
+
+18. README with full documentation
+19. Error handling hardening
+20. Edge case coverage (shared drives, shortcuts, trashed files)
+21. npm publish (if desired)
+
+---
+
+## 10. BDD Acceptance Criteria
+
+### gdrive_list_files
+
+**Story:** As a Claude Code user, I want to list and search files in my Drive so that I can find files to work with.
+
+- Given a Drive with files, when I call gdrive_list_files with no params, then I receive up to 20 files sorted by modifiedTime desc with id, name, mimeType, modifiedTime, size, parents.
+- Given a folder with ID "abc123", when I call gdrive_list_files with folderId "abc123", then I receive only files whose parents include "abc123".
+- Given a query "name contains 'report'", when I call gdrive_list_files with that query, then I receive only files matching the search.
+- Given more than 20 files match, when I call gdrive_list_files with pageSize 20, then the response includes a nextPageToken for pagination.
+- Given an invalid folderId, when I call gdrive_list_files, then I receive an error with "File not found" message.
+
+### gdrive_get_metadata
+
+**Story:** As a Claude Code user, I want to get detailed file metadata so that I can make informed decisions about file operations.
+
+- Given a valid fileId, when I call gdrive_get_metadata, then I receive id, name, mimeType, size, createdTime, modifiedTime, parents, webViewLink, owners, shared, description.
+- Given an invalid fileId, when I call gdrive_get_metadata, then I receive a 404 error with descriptive message.
+
+### gdrive_read_file
+
+**Story:** As a Claude Code user, I want to read file contents so that I can analyze and work with Drive data.
+
+- Given a text file (text/plain), when I call gdrive_read_file, then I receive the raw text content.
+- Given a Google Doc, when I call gdrive_read_file, then the Doc is exported as HTML and converted to Markdown via turndown.
+- Given a Google Sheet, when I call gdrive_read_file, then the first sheet is exported as CSV.
+- Given a Google Slides presentation, when I call gdrive_read_file, then slides are exported as plain text.
+- Given a binary file under 10MB, when I call gdrive_read_file, then I receive base64-encoded content.
+- Given a binary file over 10MB, when I call gdrive_read_file, then I receive metadata (name, size, mimeType, webViewLink) with a size warning.
+
+### gdrive_create_file
+
+**Story:** As a Claude Code user, I want to create files in Drive so that I can store new content.
+
+- Given a name "notes.txt" and content "hello world", when I call gdrive_create_file, then a new file is created in root and I receive id, name, webViewLink.
+- Given a parentFolderId, when I call gdrive_create_file with that param, then the file is created inside that folder.
+- Given an invalid parentFolderId, when I call gdrive_create_file, then I receive a 404 error.
+
+### gdrive_update_file
+
+**Story:** As a Claude Code user, I want to update file contents so that I can modify existing Drive files.
+
+- Given a valid fileId and new content, when I call gdrive_update_file, then the file content is replaced and I receive id, name, modifiedTime.
+- Given an invalid fileId, when I call gdrive_update_file, then I receive a 404 error.
+- Given a file I don't own, when I call gdrive_update_file, then I receive a 403 permission denied error.
+
+### gdrive_delete_file
+
+**Story:** As a Claude Code user, I want to delete files so that I can manage Drive contents.
+
+- Given a valid fileId with permanent=false (default), when I call gdrive_delete_file, then the file is moved to trash and I receive confirmation.
+- Given a valid fileId with permanent=true, when I call gdrive_delete_file, then the file is permanently deleted and I receive confirmation.
+- Given an invalid fileId, when I call gdrive_delete_file, then I receive a 404 error.
+
+### gdrive_move_file
+
+**Story:** As a Claude Code user, I want to move files between folders so that I can organize my Drive.
+
+- Given a file in folder A and destination folder B, when I call gdrive_move_file, then the file's parents change from A to B.
+- Given an invalid destinationFolderId, when I call gdrive_move_file, then I receive a 404 error.
+
+### gdrive_copy_file
+
+**Story:** As a Claude Code user, I want to copy files so that I can duplicate content.
+
+- Given a valid fileId, when I call gdrive_copy_file with no name, then a copy is created named "Copy of {original}" in the same folder.
+- Given a valid fileId and name "backup.txt", when I call gdrive_copy_file, then the copy is created with the specified name.
+- Given a parentFolderId, when I call gdrive_copy_file with that param, then the copy is placed in the specified folder.
+
+### gdrive_create_folder
+
+**Story:** As a Claude Code user, I want to create folders so that I can organize Drive files.
+
+- Given a name "Projects", when I call gdrive_create_folder, then a folder is created in root with mimeType application/vnd.google-apps.folder and I receive id, name, webViewLink.
+- Given a parentFolderId, when I call gdrive_create_folder with that param, then the folder is created as a subfolder.
+
+### gdrive_export_doc
+
+**Story:** As a Claude Code user, I want to export Google Docs in various formats so that I can work with their content.
+
+- Given a Google Doc fileId with format="markdown" (default), when I call gdrive_export_doc, then the doc is exported as HTML and converted to Markdown via turndown.
+- Given format="html", when I call gdrive_export_doc, then I receive raw HTML content.
+- Given format="plain_text", when I call gdrive_export_doc, then I receive plain text content.
+- Given a non-Doc fileId, when I call gdrive_export_doc, then I receive an error "Cannot export: {mimeType} is not a Google Workspace file."
+
+### gdrive_export_sheet
+
+**Story:** As a Claude Code user, I want to export Google Sheets so that I can analyze spreadsheet data.
+
+- Given a Google Sheet fileId with format="csv" (default), when I call gdrive_export_sheet, then I receive CSV content of the first sheet.
+- Given format="json", when I call gdrive_export_sheet, then I receive a JSON array of objects with column headers as keys.
+- Given a sheetName param, when I call gdrive_export_sheet, then only that specific sheet/tab is exported.
+- Given a non-Sheet fileId, when I call gdrive_export_sheet, then I receive an error.
+
+### gdrive_export_slides
+
+**Story:** As a Claude Code user, I want to export Google Slides so that I can work with presentation content.
+
+- Given a Google Slides fileId with format="text" (default), when I call gdrive_export_slides, then I receive plain text content of all slides.
+- Given format="pdf", when I call gdrive_export_slides, then I receive base64-encoded PDF content.
+
+### gdrive_create_doc
+
+**Story:** As a Claude Code user, I want to create Google Docs from Markdown so that I can produce formatted documents.
+
+- Given a name and markdownContent, when I call gdrive_create_doc, then a new Google Doc is created with the Markdown converted to HTML and then to Google Doc format, and I receive id, name, webViewLink.
+- Given a parentFolderId, when I call gdrive_create_doc with that param, then the doc is created in that folder.
+
+### gdrive_update_doc
+
+**Story:** As a Claude Code user, I want to update Google Docs with new Markdown so that I can revise formatted documents.
+
+- Given a valid Google Doc fileId and markdownContent, when I call gdrive_update_doc, then the entire doc content is replaced with the new Markdown (converted via MD→HTML→Doc), and I receive id, name, modifiedTime.
+- Given a non-Doc fileId, when I call gdrive_update_doc, then I receive an error.
+
+---
+
+## 11. Design Document (C4 Architecture)
+
+### 11.1 Business Posture
+
+| Priority | Goal | Description |
+|----------|------|-------------|
+| P0 | Full Drive access for AI assistant | Give Claude Code (Pallas) read/write access to personal Google Drive, closing the last major Google integration gap in PAI |
+| P1 | Workspace format interop | Convert Google Docs, Sheets, Slides into AI-consumable formats (Markdown, CSV, JSON, plain text) |
+| P2 | File lifecycle management | Create, read, update, delete, search, move, copy operations on Drive files and folders |
+| P3 | Local-only deployment | Run entirely on local hardware (WSL2) with no cloud hosting, no exposed endpoints |
+
+### 11.2 Security Posture
+
+Existing Controls:
+- SC-1: OAuth2 desktop app flow (Google-recommended, PKCE)
+- SC-2: Token stored at ~/.config/mcp-google-gdrive/token.json with 0600 permissions
+- SC-3: Single scope (drive), no Gmail or Calendar scopes
+- SC-4: stdio transport only — no network listeners, no HTTP endpoints
+- SC-5: Single-user model, runs as local user
+- SC-6: WSL2 VM isolation from Windows host
+- SC-7: Stateless between invocations (no database, no cache)
+
+Accepted Risks:
+- AR-1: Full Drive scope (required for Workspace export/conversion)
+- AR-2: Token on local filesystem (single-user machine, encrypted disk + file permissions sufficient)
+- AR-3: No audit logging (personal tool; Google Admin audit log available if needed)
+- AR-4: AI can invoke destructive operations (Drive trash provides recovery; user approves tool calls)
+
+### 11.3 C4 Context Diagram
+
+```mermaid
+C4Context
+    title System Context - Google Drive MCP Server
+
+    Person(user, "Shon", "PAI user interacting via Claude Code")
+    System(claudeCode, "Claude Code", "AI coding assistant running on Windows 11")
+    System(mcpServer, "mcp-google-gdrive", "MCP server in WSL providing Drive tools")
+    System_Ext(googleApi, "Google Drive API v3", "Google cloud service for file storage")
+    System_Ext(googleDrive, "Google Drive", "Personal cloud storage with files and Workspace docs")
+
+    Rel(user, claudeCode, "Sends requests via CLI/IDE")
+    Rel(claudeCode, mcpServer, "JSON-RPC over stdio", "MCP protocol")
+    Rel(mcpServer, googleApi, "HTTPS REST calls", "OAuth2 bearer token")
+    Rel(googleApi, googleDrive, "Internal Google infrastructure")
+```
+
+| Element | Type | Responsibilities |
+|---------|------|-----------------|
+| Shon | Person | Issues file management commands through Claude Code |
+| Claude Code | System | Discovers MCP tools, selects appropriate tool for user request, displays results |
+| mcp-google-gdrive | System | Authenticates to Google, translates MCP tool calls to Drive API requests, converts formats |
+| Google Drive API v3 | External System | Provides REST endpoints for file CRUD, export, metadata |
+| Google Drive | External System | Stores files, Google Workspace documents, folder structure |
+
+### 11.4 C4 Container Diagram
+
+```mermaid
+C4Container
+    title Container Diagram - mcp-google-gdrive
+
+    Person(user, "Claude Code", "MCP client")
+
+    Container_Boundary(server, "mcp-google-gdrive (Node.js ESM)") {
+        Container(protocol, "MCP Protocol Handler", "McpServer + StdioServerTransport", "Receives JSON-RPC tool calls, routes to handlers")
+        Container(registry, "Tool Registry", "14 registerTool calls + Zod schemas", "Validates inputs, dispatches to API client")
+        Container(auth, "Auth Manager", "googleapis OAuth2Client", "Loads/refreshes/saves OAuth2 tokens")
+        Container(client, "Drive API Client", "googleapis drive.files.*", "Executes Drive API v3 HTTP requests")
+        Container(converter, "Format Converter", "turndown + marked", "HTML→MD, MD→HTML, CSV→JSON")
+    }
+
+    System_Ext(google, "Google Drive API v3", "REST API")
+    System_Ext(tokenFile, "~/.config/mcp-google-gdrive/token.json", "Local file")
+
+    Rel(user, protocol, "stdio JSON-RPC")
+    Rel(protocol, registry, "Tool call dispatch")
+    Rel(registry, client, "API request")
+    Rel(registry, converter, "Format conversion")
+    Rel(client, auth, "Get access token")
+    Rel(auth, tokenFile, "Read/write tokens")
+    Rel(client, google, "HTTPS REST")
+```
+
+| Container | Type | Responsibilities | Tech |
+|-----------|------|-----------------|------|
+| MCP Protocol Handler | Process | Accept stdio input, parse JSON-RPC, return responses | @modelcontextprotocol/sdk |
+| Tool Registry | Module | Define 14 tools with Zod schemas and annotations | zod |
+| Auth Manager | Module | OAuth2 token lifecycle (load, refresh, save) | googleapis |
+| Drive API Client | Module | HTTP calls to Drive API endpoints | googleapis |
+| Format Converter | Module | Bidirectional format conversion for Workspace files | turndown, marked |
+
+### 11.5 C4 Deployment Diagram
+
+```mermaid
+C4Deployment
+    title Deployment Diagram - mcp-google-gdrive
+
+    Deployment_Node(win, "Windows 11 Pro", "Host OS") {
+        Deployment_Node(vscode, "VSCode + Claude Code") {
+            Container(cc, "Claude Code Extension", "MCP Client")
+        }
+        Deployment_Node(wsl, "WSL2 - Fedora 43", "Linux VM") {
+            Deployment_Node(node, "Node.js v22", "JavaScript Runtime") {
+                Container(mcp, "mcp-google-gdrive", "MCP Server Process")
+            }
+            Deployment_Node(config, "~/.config/mcp-google-gdrive/") {
+                Container(creds, "credentials.json", "OAuth2 client credentials")
+                Container(token, "token.json", "OAuth2 access + refresh tokens")
+            }
+        }
+    }
+
+    Deployment_Node(gcloud, "Google Cloud", "External") {
+        Container(driveApi, "Drive API v3", "REST Service")
+    }
+
+    Rel(cc, mcp, "stdio (JSON-RPC)")
+    Rel(mcp, creds, "Read on startup")
+    Rel(mcp, token, "Read/write for auth")
+    Rel(mcp, driveApi, "HTTPS REST calls")
+```
+
+### 11.6 Risk Assessment
+
+Critical process: OAuth2 token management. If tokens are compromised, attacker has full Drive access.
+
+Data sensitivity:
+- credentials.json: MEDIUM (contains client_id and client_secret — enables auth flow but not data access alone)
+- token.json: HIGH (contains refresh_token — grants persistent Drive access)
+- File content in transit: MEDIUM (encrypted via HTTPS to Google, plaintext via stdio locally)
+
+Mitigations: File permissions (0600), .gitignore exclusion, WSL2 VM boundary, no network exposure.