Google Docs & Drive MCP Server

# GoogleDocsMCP - AgenticLedger Integration Guide ## 🚀 Quick Start This MCP server provides comprehensive Google Docs and Drive integration for the AgenticLedger platform with 30+ production-ready tools. ### Prerequisites - Node.js 18+ installed - Google Cloud Project with Docs API + Drive API enabled - OAuth 2.0 credentials configured ### Installation 1. **Navigate to the server directory:** ```bash cd "C:\Users\oreph\Documents\AgenticLedger\Custom MCP SERVERS\GoogleDocsMCP" ``` 2. **Install dependencies (if not already done):** ```bash npm install ``` 3. **Build the server (if not already built):** ```bash npm run build ``` 4. **Set up OAuth 2.0 credentials:** - Follow `GOOGLE_CLOUD_SETUP.md` for detailed instructions - Place `credentials.json` in this directory - Run first-time authorization to create `token.json` 5. **First-time authorization:** ```bash node dist/server.js # Follow the OAuth flow in your browser # token.json will be created automatically ``` 6. **Test the integration:** ```bash npm run test:integration ``` --- ## 📁 File Structure ``` GoogleDocsMCP/ ├── dist/ # Compiled JavaScript (ready to run) │ ├── server.js # Main server file │ ├── auth.js # Authentication logic │ ├── googleDocsApiHelpers.js # API helpers │ └── types.js # Type definitions ├── src/ # TypeScript source code │ ├── server.ts # Server implementation │ ├── auth.ts # OAuth 2.0 authentication │ ├── googleDocsApiHelpers.ts # Helper functions │ └── types.ts # Zod schemas and types ├── GOOGLE_CLOUD_SETUP.md # OAuth setup guide (detailed) ├── PLATFORM_INTEGRATION_REPORT.md # Complete tool documentation ├── ABILITIES_LIMITATIONS.md # AI agent guide ├── CLAUDE.md # Advanced implementation details ├── README.md # Original server README ├── README_AGENTICLEDGER.md # This file ├── test-integration.ts # Integration test suite ├── credentials.example.json # Example OAuth format ├── token.example.json # Example token format └── package.json # Dependencies and scripts ``` --- ## 🔧 Configuration ### OAuth 2.0 Setup 1. **Create OAuth credentials (see GOOGLE_CLOUD_SETUP.md)** 2. **Download credentials.json** 3. **Run first-time authorization:** ```bash node dist/server.js ``` 4. **Follow browser flow to authorize** 5. **token.json created automatically** ### AgenticLedger MCP Config Add to your AgenticLedger MCP configuration: ```json { "mcpServers": { "google-docs": { "command": "node", "args": [ "C:/Users/oreph/Documents/AgenticLedger/Custom MCP SERVERS/GoogleDocsMCP/dist/server.js" ], "env": {} } } } ``` **Important:** - Use absolute path to `server.js` - `credentials.json` and `token.json` must be in same directory as `server.js` - Tokens auto-refresh (no manual intervention needed) --- ## 🛠️ Available Tools (30+ Total) ### Document Access & Editing (5 tools) - `readGoogleDoc` - Read document (text/json/markdown) - `appendToGoogleDoc` - Append text to end - `insertText` - Insert at specific index - `deleteRange` - Delete content range - `listDocumentTabs` - List tabs in multi-tab docs ### Formatting & Styling (3 tools) - `applyTextStyle` - Character formatting (bold, colors, etc.) - `applyParagraphStyle` - Paragraph formatting (alignment, spacing) - `formatMatchingText` - Legacy formatting (use applyTextStyle) ### Document Structure (4 tools) - `insertTable` - Create tables - `insertPageBreak` - Insert page breaks - `insertImageFromUrl` - Insert image from URL - `insertLocalImage` - Upload and insert local image ### Comment Management (6 tools) - `listComments` - List all comments - `getComment` - Get specific comment details - `addComment` - Create comment anchored to text - `replyToComment` - Reply to comment - `resolveComment` - Mark as resolved - `deleteComment` - Remove comment ### Google Drive Integration (12 tools) - `listGoogleDocs` - List all documents - `searchGoogleDocs` - Search by name/content - `getRecentGoogleDocs` - Get recent docs - `getDocumentInfo` - Get file metadata - `createDocument` - Create new document - `createFromTemplate` - Create from template - `createFolder` - Create folder - `listFolderContents` - List folder files - `getFolderInfo` - Get folder metadata - `moveFile` - Move to different folder - `copyFile` - Create copy - `renameFile` - Rename document - `deleteFile` - Delete (move to trash) ### Experimental (1 tool) - `fixListFormatting` - Auto-detect lists (not implemented) --- ## 📊 Example Usage ### Example 1: Read Document ```typescript const result = await readGoogleDoc({ documentId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms", format: "text" // or "json" or "markdown" }); console.log(result.data.title); console.log(result.data.content); ``` ### Example 2: Append Text ```typescript await appendToGoogleDoc({ documentId: "1BxiMVs0XRA...", textToAppend: "\n\nNew section added by AI Agent", addNewlineIfNeeded: true }); ``` ### Example 3: Apply Formatting ```typescript // Format by text content await applyTextStyle({ documentId: "1BxiMVs0XRA...", target: { textToFind: "Important Note", matchInstance: 1 // First occurrence }, style: { bold: true, foregroundColor: "#FF0000", // Red fontSize: 14 } }); // Or format by index range await applyTextStyle({ documentId: "1BxiMVs0XRA...", target: { startIndex: 1, endIndex: 20 }, style: { italic: true } }); ``` ### Example 4: Insert Table ```typescript await insertTable({ documentId: "1BxiMVs0XRA...", rows: 3, columns: 4, index: 100 // Insert at index 100 }); ``` ### Example 5: Work with Multi-Tab Documents ```typescript // List tabs first const tabs = await listDocumentTabs({ documentId: "1BxiMVs0XRA..." }); console.log(tabs.data.tabs); // [ // { tabId: "abc", title: "Introduction", index: 0 }, // { tabId: "def", title: "Chapter 1", index: 1 } // ] // Read specific tab await readGoogleDoc({ documentId: "1BxiMVs0XRA...", tabId: "abc" // Target specific tab }); ``` ### Example 6: Create New Document ```typescript const newDoc = await createDocument({ title: "AI Generated Report", folderId: "your-folder-id" // Optional }); console.log(newDoc.data.documentId); console.log(newDoc.data.url); ``` --- ## ✅ Integration Testing ### Run Tests ```bash npm run test:integration ``` ### Test Requirements 1. OAuth credentials configured (`credentials.json`) 2. First-time authorization completed (`token.json` exists) 3. Google Docs API + Drive API enabled 4. Optional: Set `TEST_DOCUMENT_ID` environment variable **Note:** If `TEST_DOCUMENT_ID` not set, tests will create a new document automatically. ### Expected Results - ✅ All core tests should pass - ⏱️ Total duration: ~8-10 seconds - 📄 Results saved to `test-results.json` --- ## 📚 Documentation ### For Developers - **PLATFORM_INTEGRATION_REPORT.md**: Complete tool documentation with API test results, parameters, responses, and examples ### For AI Agents - **ABILITIES_LIMITATIONS.md**: Smart workarounds, best practices, index management, and optimization strategies ### For Setup - **GOOGLE_CLOUD_SETUP.md**: Step-by-step OAuth 2.0 configuration ### For Advanced Features - **CLAUDE.md**: Advanced implementation details, helper functions, and extensibility --- ## 🔐 Security Best Practices 1. **Never commit credentials:** - `credentials.json` (OAuth client secrets) - `token.json` (access/refresh tokens) 2. **OAuth security:** - Tokens expire after 1 hour (auto-refresh) - Refresh tokens stored securely in `token.json` - Revoke access: https://myaccount.google.com/permissions 3. **Access control:** - User-based authentication (not service accounts) - Only accesses documents user owns or has been shared - Explicit OAuth scope approval required 4. **Monitor usage:** - Check Google Cloud Console API dashboard - Set up quota alerts - Review authorized apps periodically --- ## 🚨 Troubleshooting ### "Token has been expired or revoked" **Solution:** ```bash # Delete token and re-authorize rm token.json node dist/server.js # Complete OAuth flow again ``` ### "ENOENT: credentials.json not found" **Solution:** - Follow `GOOGLE_CLOUD_SETUP.md` to create OAuth credentials - Download `credentials.json` from Google Cloud Console - Place in GoogleDocsMCP directory ### "Permission denied" **Solution:** - User must own or have edit access to document - Verify document ID is correct - Check OAuth scopes include necessary permissions ### "This site can't be reached" during OAuth **This is normal!** - Copy authorization code from URL bar - Paste into terminal prompt - Don't worry about the error page ### "API not enabled" **Solution:** - Enable "Google Docs API" in Cloud Console - Enable "Google Drive API" in Cloud Console - Wait a few minutes for propagation --- ## 🎯 Performance Tips ### 1. Read Once, Process Locally ```typescript // ❌ Slow: Multiple reads const doc1 = await readGoogleDoc({ documentId, format: 'text' }); const doc2 = await readGoogleDoc({ documentId, format: 'json' }); // ✅ Fast: Read once const doc = await readGoogleDoc({ documentId, format: 'json' }); // Parse JSON locally for both text and structure ``` ### 2. Work from End to Start ```typescript // When making multiple edits, work backwards // This prevents index shifting // ✅ Correct order (end → start) await deleteRange({ startIndex: 200, endIndex: 210 }); await deleteRange({ startIndex: 100, endIndex: 110 }); await deleteRange({ startIndex: 50, endIndex: 60 }); // ❌ Wrong order (start → end) - indices shift! ``` ### 3. Use Multi-Tab Awareness ```typescript // Check for tabs first const tabs = await listDocumentTabs({ documentId }); if (tabs.data.tabCount > 1) { // Handle multi-tab logic for (const tab of tabs.data.tabs) { await appendToGoogleDoc({ documentId, tabId: tab.tabId, textToAppend: "Added to each tab" }); } } ``` ### 4. Cache Document Structure ```typescript // Cache for repeated operations let cachedDoc = null; async function getCachedDoc(documentId) { if (!cachedDoc) { cachedDoc = await readGoogleDoc({ documentId, format: 'json' }); } return cachedDoc; } // Invalidate cache after edits async function editAndInvalidate() { await insertText({ ... }); cachedDoc = null; // Force re-read } ``` --- ## 📈 API Quotas **Google Docs API Limits:** - Read requests: 300 per minute per user - Write requests: 300 per minute per user - Per-project: 25,000 requests per day **Google Drive API Limits:** - Queries: 20,000 per 100 seconds per user - Per-project: 1,000,000,000 requests per day **Tips to Stay Within Limits:** - Read once, edit multiple times - Use Drive API sparingly (cache results) - Implement delays for bulk operations --- ## 🔄 Multi-Tab Document Support Google Docs now supports multiple tabs per document. This server fully supports tabs: ### Tab-Aware Tools ```typescript // Tools that accept tabId parameter: - readGoogleDoc - appendToGoogleDoc - insertText - deleteRange - (formatting tools work within tab context) ``` ### Working with Tabs ```typescript // 1. List tabs const { tabs } = await listDocumentTabs({ documentId }); // 2. Target specific tab await readGoogleDoc({ documentId, tabId: tabs[0].tabId }); // 3. Works without tabId (targets first tab/legacy doc body) await appendToGoogleDoc({ documentId, textToAppend: "Works with single-tab or legacy docs too" }); ``` --- ## 🆘 Getting Help 1. **Check documentation:** - `PLATFORM_INTEGRATION_REPORT.md` - Tool reference - `ABILITIES_LIMITATIONS.md` - AI agent guide - `GOOGLE_CLOUD_SETUP.md` - OAuth help - `CLAUDE.md` - Advanced features 2. **Run diagnostics:** ```bash # Test server node dist/server.js # Test API access npm run test:integration # Check OAuth status ls -l credentials.json token.json # Check Google Cloud Console # APIs & Services > Dashboard > Google Docs API ``` 3. **Common resources:** - Google Docs API: https://developers.google.com/docs/api - Google Drive API: https://developers.google.com/drive/api - MCP Protocol: https://modelcontextprotocol.io - fastmcp: https://github.com/jlowin/fastmcp --- ## 📝 Version Info - **Version:** 1.0.0 - **Technology:** TypeScript 5.8+, Node.js 18+, fastmcp 1.21+ - **Authentication:** OAuth 2.0 (User Authorization) - **APIs:** Google Docs API v1, Google Drive API v3 - **Status:** ✅ Production Ready --- ## 🎉 Success Checklist Before deploying to AgenticLedger: - [ ] Google Cloud Project created - [ ] Docs API + Drive API enabled - [ ] OAuth consent screen configured - [ ] OAuth credentials created - [ ] `credentials.json` downloaded and placed - [ ] `npm install` completed - [ ] `npm run build` successful - [ ] First-time authorization completed (token.json exists) - [ ] `npm run test:integration` passes - [ ] MCP config added to AgenticLedger - [ ] Basic operations tested --- ## 🚀 Next Steps 1. Complete the success checklist above 2. Review `PLATFORM_INTEGRATION_REPORT.md` for tool details 3. Configure AgenticLedger MCP settings 4. Understand multi-tab document support 5. Review `ABILITIES_LIMITATIONS.md` for AI agent best practices 6. Start building agents! --- ## 💡 Pro Tips ### For AI Agent Development 1. **Always read before writing** - Understand document structure first 2. **Use tab awareness** - Check for multi-tab documents 3. **Format after insertion** - Safer than formatting during 4. **Work backwards** - Prevent index shifting 5. **Cache structure** - Read JSON once, reference many times ### For Users 1. **Version history is your friend** - Use it for undo 2. **Share documents** - OAuth user must have access 3. **Start simple** - Test basic operations before complex workflows 4. **Monitor tokens** - They auto-refresh, but check periodically --- ## 🤝 Comparison: Docs vs Sheets **Use GoogleDocsMCP when:** - Creating reports, letters, proposals - Need rich text formatting - Working with narrative content - Require document structure (headings, TOC) - Need comment collaboration **Use GoogleSheetsMCP when:** - Working with tabular data - Need calculations/formulas - Creating charts and graphs - Data analysis tasks - Structured records (databases) **Both servers:** - TypeScript-based - Production-ready - Full AgenticLedger integration - Comprehensive documentation - Real API testing --- **Created:** 2025-11-03 **Platform:** AgenticLedger **License:** MIT