# Google Docs MCP Tools

This module provides comprehensive Google Docs integration tools for FastMCP Google MCP servers, enabling rich document creation and management through the Model Context Protocol (MCP).

## Overview

The Google Docs MCP tools leverage Google's APIs to provide seamless document operations with automatic rich content formatting. The tools use a sophisticated approach that combines Google Drive API's HTML-to-Docs conversion with intelligent content type detection for optimal formatting results.

## Key Features

- ✅ **Rich Content Support**: Automatic conversion of Markdown and HTML to properly formatted Google Docs
- ✅ **Intelligent Content Detection**: Automatically detects plain text, Markdown, and HTML content types  
- ✅ **Google's Native Conversion**: Uses Google Drive API's built-in HTML-to-Docs conversion for reliable formatting
- ✅ **Comprehensive Search**: Search documents by name with flexible filtering
- ✅ **Multi-format Support**: Read content from Google Docs and Office files (.docx, etc.)
- ✅ **Folder Organization**: List and organize documents within Drive folders
- ✅ **Fallback Authentication**: Robust authentication with middleware injection and direct service fallback

## Architecture

### Authentication Pattern
- **Primary**: Middleware-based service injection (no decorators required)
- **Fallback**: Direct service creation when middleware unavailable
- **Automatic**: Google service authentication and token refresh
- **User-friendly**: Comprehensive error handling with clear guidance

### Content Processing Pipeline
1. **Content Type Detection**: Uses regex patterns to identify Markdown, HTML, or plain text
2. **Format Conversion**: Converts Markdown to HTML using lightweight converter
3. **Drive API Upload**: Uploads HTML content with `mimeType: 'application/vnd.google-apps.document'`
4. **Google Conversion**: Google automatically converts HTML to formatted Google Doc
5. **Result**: Properly formatted document with headings, lists, tables, links, and styling

## Available Tools

### 1. `create_doc` - Create Rich Google Documents

Creates new Google Docs with automatic rich formatting support.

**Parameters:**
- `user_google_email` (string): User's Google email for authentication
- `title` (string): Document title
- `content` (string, optional): Initial content with automatic format detection

**Supported Content Types:**
- **Plain Text**: Simple text insertion
- **Markdown**: Full Markdown support including:
  - Headers (`# ## ###`)
  - Bold/Italic (`**bold** *italic*`)
  - Links (`[text](url)`)
  - Lists (`- item` or `1. item`)
- **HTML**: Complete HTML support including:
  - All heading levels (`<h1>` to `<h6>`)
  - Text formatting (`<strong>`, `<em>`, `<u>`)
  - Lists (`<ul>`, `<ol>`, `<li>`)
  - Tables (`<table>`, `<tr>`, `<td>`)
  - Links (`<a href="">`)
  - Styled content with CSS

**Example Usage:**
```python
# Markdown content
result = await create_doc(
    user_google_email="user@example.com",
    title="Project Report",
    content="""
# Executive Summary

This report covers **key findings** and *recommendations*.

## Key Points
- Revenue increased by 25%
- Customer satisfaction improved
- [Detailed metrics](https://example.com)

## Next Steps
1. Implement feedback system
2. Expand to new markets
3. Review quarterly results
"""
)

# HTML content
result = await create_doc(
    user_google_email="user@example.com", 
    title="Formatted Document",
    content="""
<h1>Professional Report</h1>
<p>This document contains <strong>rich formatting</strong> with <em>proper styling</em>.</p>
<table border="1">
    <tr><th>Metric</th><th>Value</th></tr>
    <tr><td>Revenue</td><td>$1.2M</td></tr>
</table>
"""
)
```

**Returns:**
```
Created Google Doc 'Project Report' (ID: 1abc...) for user@example.com with markdown formatting. 
Link: https://docs.google.com/document/d/1abc.../edit
```

### 2. `search_docs` - Find Documents by Name

Searches for Google Docs using name-based filtering.

**Parameters:**
- `user_google_email` (string): User's Google email
- `query` (string): Search query (partial name matching)
- `page_size` (int, optional): Max results to return (default: 10)

**Example Usage:**
```python
result = await search_docs(
    user_google_email="user@example.com",
    query="project report",
    page_size=20
)
```

**Returns:**
```
Found 3 Google Docs matching 'project report':
- Q3 Project Report (ID: 1abc...) Modified: 2025-08-30T14:30:00Z Link: https://docs.google.com/...
- Annual Project Summary (ID: 1def...) Modified: 2025-08-29T09:15:00Z Link: https://docs.google.com/...
- Project Status Report (ID: 1ghi...) Modified: 2025-08-28T16:45:00Z Link: https://docs.google.com/...
```

### 3. `get_doc_content` - Read Document Content

Retrieves content from Google Docs and other Drive files with format detection.

**Parameters:**
- `user_google_email` (string): User's Google email
- `document_id` (string): Google Doc or Drive file ID

**Supported File Types:**
- Native Google Docs (`application/vnd.google-apps.document`)
- Microsoft Word files (`.docx`)
- Other text-based formats

**Example Usage:**
```python
content = await get_doc_content(
    user_google_email="user@example.com",
    document_id="1abc123def456ghi789"
)
```

**Returns:**
```
File: "Project Report" (ID: 1abc123..., Type: application/vnd.google-apps.document)
Link: https://docs.google.com/document/d/1abc123.../edit

--- CONTENT ---
Executive Summary
This report covers key findings and recommendations.

Key Points
Revenue increased by 25%
Customer satisfaction improved
Detailed metrics

Next Steps
Implement feedback system
Expand to new markets
Review quarterly results
```

### 4. `list_docs_in_folder` - Browse Folder Contents

Lists Google Docs within a specific Drive folder with structured output.

**Parameters:**
- `user_google_email` (string): User's Google email
- `folder_id` (string, optional): Drive folder ID (default: 'root')
- `page_size` (int, optional): Max results (default: 100)

**Example Usage:**
```python
docs_list = await list_docs_in_folder(
    user_google_email="user@example.com",
    folder_id="1BxY2CzD3EfG4HiJ5KlM6",
    page_size=50
)
```

**Returns Structured Object:**
```json
{
  "docs": [
    {
      "id": "1abc123def456",
      "name": "Q3 Report",
      "modifiedTime": "2025-08-30T14:30:00Z",
      "webViewLink": "https://docs.google.com/document/d/1abc123def456/edit"
    }
  ],
  "count": 1,
  "folderId": "1BxY2CzD3EfG4HiJ5KlM6",
  "folderName": null,
  "userEmail": "user@example.com",
  "error": null
}
```

## Content Formatting Examples

### Markdown to Google Docs
The tool automatically converts Markdown syntax to proper Google Docs formatting:

**Input Markdown:**
```markdown
# Main Title
## Subtitle
This is **bold text** and *italic text*.
- Bullet point 1
- Bullet point 2
[Link to Google](https://google.com)
```

**Result:** Properly formatted Google Doc with:
- H1 heading "Main Title"
- H2 heading "Subtitle" 
- Bold and italic text formatting
- Bulleted list
- Clickable link

### HTML to Google Docs
Full HTML support with advanced formatting:

**Input HTML:**
```html
<h1 style="color: blue;">Professional Report</h1>
<p>This contains <strong>bold</strong> and <em>italic</em> formatting.</p>
<table border="1">
  <tr><th>Name</th><th>Score</th></tr>
  <tr><td>Alice</td><td>95%</td></tr>
</table>
<blockquote>Important note in blockquote format</blockquote>
```

**Result:** Google Doc with:
- Styled blue heading
- Formatted text with bold/italic
- Properly formatted table
- Blockquote styling

## Error Handling

The tools provide comprehensive error handling with user-friendly messages:

### Authentication Issues
```
❌ No Credentials Found

No authentication credentials found for user@example.com.

To authenticate:
1. Run `start_google_auth` with your email: user@example.com
2. Follow the authentication flow in your browser
3. Grant Drive permissions when prompted
4. Return here after seeing the success page
```

### Permission Problems
```
❌ Permission denied. Make sure you have access to Google Drive.
```

### Invalid Document IDs
```
❌ Document not found: 1invalid_id_here
```

## Technical Implementation

### Why This Approach Works Better

Instead of manually parsing Markdown/HTML and converting to Google Docs API requests, this implementation:

1. **Leverages Google's Conversion Engine**: Uses Google Drive API's built-in HTML-to-Docs conversion
2. **Simpler Code**: ~150 lines vs 400+ lines of manual parsing
3. **Better Results**: Google's converter handles edge cases and complex formatting
4. **More Reliable**: Battle-tested conversion logic maintained by Google
5. **Comprehensive Support**: Tables, lists, styling, special characters all work

### Content Processing Flow
```
User Content Input
       ↓
Content Type Detection (regex patterns)
       ↓
Markdown → HTML Conversion (if needed)
       ↓
Drive API Upload (HTML → Google Doc)
       ↓
Google's Conversion Engine
       ↓
Formatted Google Document
```

## Dependencies

- `google-api-python-client`: Google APIs integration
- `fastmcp`: FastMCP server framework  
- `auth.service_helpers`: Authentication utilities
- `googleapiclient.http`: Media upload support

## Authentication Requirements

The tools require Google OAuth2 authentication with the following scopes:
- `https://www.googleapis.com/auth/documents` - Google Docs access
- `https://www.googleapis.com/auth/drive` - Google Drive access
- `https://www.googleapis.com/auth/drive.file` - File creation/modification

## Best Practices

1. **Content Formatting**: Use Markdown for simple formatting, HTML for complex layouts
2. **Error Handling**: Always check return messages for authentication issues
3. **File Organization**: Use `list_docs_in_folder` to organize documents by folder
4. **Search Efficiency**: Use specific search terms with `search_docs` for better results
5. **Content Size**: Keep content reasonable size for optimal conversion performance

## Changelog

### Latest Version Features
- ✅ **Automatic Content Detection**: Intelligently detects Markdown, HTML, and plain text
- ✅ **Drive API Conversion**: Uses Google's native HTML-to-Docs conversion
- ✅ **Enhanced Error Handling**: User-friendly authentication guidance
- ✅ **Structured Responses**: JSON responses for `list_docs_in_folder`
- ✅ **Fallback Authentication**: Robust middleware + direct service patterns

---

*This documentation covers the Google Docs MCP tools in FastMCP Google MCP. For more information about setting up authentication or other MCP tools, see the main FastMCP Google MCP documentation.*