# GoogleDocsMCP - AgenticLedger Platform
## Google Docs & Drive MCP Server

[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Google Docs API](https://img.shields.io/badge/Google%20Docs-API%20v1-4285F4?logo=google-docs&logoColor=white)](https://developers.google.com/docs/api)
[![Google Drive API](https://img.shields.io/badge/Google%20Drive-API%20v3-0F9D58?logo=google-drive&logoColor=white)](https://developers.google.com/drive/api)

**Production-ready MCP server providing comprehensive Google Docs and Drive integration for the AgenticLedger AI Agent Platform.**

## 🚀 Features

- **30+ Production-Ready Tools** - Document editing, formatting, comments, Drive file operations
- **OAuth 2.0 Authentication** - Secure user-based authorization with automatic token refresh
- **Multi-Tab Document Support** - Work with new Google Docs multi-tab feature
- **Rich Text Formatting** - Bold, italic, colors, fonts, paragraph styles, named styles
- **Comment Management** - Full CRUD operations on document comments
- **Google Drive Integration** - List, search, create, move, copy, delete documents
- **Type-Safe** - Full TypeScript with Zod schema validation
- **100% Documented** - Comprehensive guides for developers and AI agents

## 📦 Quick Start

### Installation

```bash
# Clone repository
git clone https://github.com/oregpt/Agenticledger_MCP_DocsOnly.git
cd Agenticledger_MCP_DocsOnly

# Install dependencies
npm install

# Build
npm run build
```

### Authentication Setup

1. **Create Google Cloud Project** (see [GOOGLE_CLOUD_SETUP.md](GOOGLE_CLOUD_SETUP.md))
2. **Enable Google Docs API + Google Drive API**
3. **Configure OAuth Consent Screen**
4. **Create OAuth 2.0 credentials** and download `credentials.json`
5. **Place `credentials.json` in this directory**
6. **Run first-time authorization:**

```bash
node dist/server.js
# Follow OAuth flow in browser
# token.json will be created automatically
```

### Run Tests

```bash
npm run test:integration
```

## 🛠️ Available Tools (30+)

<details>
<summary><b>Document Access & Editing (5 tools)</b></summary>

- `readGoogleDoc` - Read document (text/json/markdown formats)
- `appendToGoogleDoc` - Append text to end of document
- `insertText` - Insert text at specific index
- `deleteRange` - Delete content range
- `listDocumentTabs` - List tabs in multi-tab documents

</details>

<details>
<summary><b>Formatting & Styling (3 tools)</b></summary>

- `applyTextStyle` - Character-level formatting (bold, colors, fonts)
- `applyParagraphStyle` - Paragraph formatting (alignment, spacing, styles)
- `formatMatchingText` - Legacy formatting tool

</details>

<details>
<summary><b>Document Structure (4 tools)</b></summary>

- `insertTable` - Create tables
- `insertPageBreak` - Insert page breaks
- `insertImageFromUrl` - Insert image from URL
- `insertLocalImage` - Upload and insert local image

</details>

<details>
<summary><b>Comment Management (6 tools)</b></summary>

- `listComments` - List all document comments
- `getComment` - Get specific comment details
- `addComment` - Create comment anchored to text
- `replyToComment` - Reply to existing comment
- `resolveComment` - Mark comment as resolved
- `deleteComment` - Remove comment

</details>

<details>
<summary><b>Google Drive Integration (12 tools)</b></summary>

- `listGoogleDocs` - List all documents
- `searchGoogleDocs` - Search documents by name/content
- `getRecentGoogleDocs` - Get recently modified documents
- `getDocumentInfo` - Get file metadata
- `createDocument` - Create new document
- `createFromTemplate` - Create from template
- `createFolder` - Create Drive 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)

</details>

## 📖 Documentation

### For Developers
- **[README_AGENTICLEDGER.md](README_AGENTICLEDGER.md)** - Complete integration guide
- **[PLATFORM_INTEGRATION_REPORT.md](PLATFORM_INTEGRATION_REPORT.md)** - Detailed tool documentation with API tests
- **[GOOGLE_CLOUD_SETUP.md](GOOGLE_CLOUD_SETUP.md)** - Step-by-step OAuth 2.0 setup
- **[CLAUDE.md](CLAUDE.md)** - Advanced implementation details

### For AI Agents
- **[ABILITIES_LIMITATIONS.md](ABILITIES_LIMITATIONS.md)** - Smart workarounds, best practices, index management

### Example Files
- `credentials.example.json` - OAuth credentials format
- `token.example.json` - Token format example
- `test-integration.ts` - Integration test suite

## 💡 Example Usage

### Read Document
```typescript
const result = await readGoogleDoc({
  documentId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  format: "text"  // or "json" or "markdown"
});
```

### Append Text
```typescript
await appendToGoogleDoc({
  documentId: "1BxiMVs0XRA...",
  textToAppend: "\n\nNew section added by AI Agent"
});
```

### Apply Formatting
```typescript
await applyTextStyle({
  documentId: "1BxiMVs0XRA...",
  target: {
    textToFind: "Important Note",
    matchInstance: 1
  },
  style: {
    bold: true,
    foregroundColor: "#FF0000",
    fontSize: 14
  }
});
```

### Create Document
```typescript
const newDoc = await createDocument({
  title: "AI Generated Report",
  folderId: "your-folder-id"
});
```

### Work with Multi-Tab Documents
```typescript
// List tabs
const tabs = await listDocumentTabs({
  documentId: "1BxiMVs0XRA..."
});

// Read specific tab
await readGoogleDoc({
  documentId: "1BxiMVs0XRA...",
  tabId: tabs.data.tabs[0].tabId
});
```

## 🔐 Security

- **Never commit credentials** (`credentials.json`, `token.json`)
- **OAuth tokens** expire after 1 hour (auto-refresh handled)
- **Revoke access** at https://myaccount.google.com/permissions
- **User-based authentication** - only accesses user's documents
- **Monitor usage** in Google Cloud Console

## 📊 Performance

- **Average Response Time:** 725ms per operation (includes Drive API)
- **Document Read:** ~300ms (fast, cached by Google)
- **Text Editing:** ~450ms (simple updates)
- **Drive Operations:** ~650ms (includes Drive API calls)
- **API Quotas:** 300 requests per minute per user

## 🔄 Multi-Tab Document Support

Google Docs now supports multiple tabs. This server fully supports this feature:

```typescript
// Tab-aware tools accept optional tabId parameter
- readGoogleDoc
- appendToGoogleDoc
- insertText
- deleteRange
```

**Usage:**
1. List tabs with `listDocumentTabs`
2. Target specific tab with `tabId` parameter
3. Works without `tabId` (targets first tab/legacy doc body)

## 🤝 Contributing

This is an AgenticLedger platform-customized version of [a-bonus/google-docs-mcp](https://github.com/a-bonus/google-docs-mcp).

**AgenticLedger Customizations:**
- Platform-specific documentation
- Integration test suite
- AI agent guides
- Example files and templates
- Enhanced error handling

## 📜 License

MIT License - See [LICENSE](LICENSE) file

## 🔗 Links

- **Repository:** https://github.com/oregpt/Agenticledger_MCP_DocsOnly
- **Upstream Source:** https://github.com/a-bonus/google-docs-mcp
- **AgenticLedger Platform:** [Platform Documentation]
- **Google Docs API:** https://developers.google.com/docs/api
- **Google Drive API:** https://developers.google.com/drive/api

## 📞 Support

1. **Check Documentation:**
   - [README_AGENTICLEDGER.md](README_AGENTICLEDGER.md) - Integration guide
   - [PLATFORM_INTEGRATION_REPORT.md](PLATFORM_INTEGRATION_REPORT.md) - Tool reference
   - [GOOGLE_CLOUD_SETUP.md](GOOGLE_CLOUD_SETUP.md) - OAuth help
   - [CLAUDE.md](CLAUDE.md) - Advanced features

2. **Run Diagnostics:**
   ```bash
   npm run test:integration
   ```

3. **Review Examples:**
   - See `test-integration.ts` for real API usage examples

## 🆚 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

---

**Status:** ✅ Production Ready
**Version:** 1.0.0
**Last Updated:** 2025-11-03
**Total Tools:** 30+
**Platform:** AgenticLedger