@brainwavesio/google-docs-mcp 1.0.0

package/SAMPLE_TASKS.md

@@ -0,0 +1,230 @@
+# 15 Powerful Tasks with the Ultimate Google Docs & Drive MCP Server
+
+This document showcases practical examples of what you can accomplish with the enhanced Google Docs & Drive MCP Server. These examples demonstrate how AI assistants like Claude can perform sophisticated document formatting, structuring, and file management tasks through the MCP interface.
+
+## Document Formatting & Structure Tasks
+
+## 1. Create and Format a Document Header
+
+```
+Task: "Create a professional document header for my project proposal."
+
+Steps:
+1. Insert the title "Project Proposal: AI Integration Strategy" at the beginning of the document
+2. Apply Heading 1 style to the title using applyParagraphStyle
+3. Add a horizontal line below the title
+4. Insert the date and author information
+5. Apply a subtle background color to the header section
+```
+
+## 2. Generate and Format a Table of Contents
+
+```
+Task: "Create a table of contents for my document based on its headings."
+
+Steps:
+1. Find all text with Heading styles (1-3) using findParagraphsMatchingStyle
+2. Create a "Table of Contents" section at the beginning of the document
+3. Insert each heading with appropriate indentation based on its level
+4. Format the TOC entries with page numbers and dotted lines
+5. Apply consistent styling to the entire TOC
+```
+
+## 3. Structure a Document with Consistent Formatting
+
+```
+Task: "Apply consistent formatting throughout my document based on content type."
+
+Steps:
+1. Format all section headings with applyParagraphStyle (Heading styles, alignment)
+2. Style all bullet points with consistent indentation and formatting
+3. Format code samples with monospace font and background color
+4. Apply consistent paragraph spacing throughout the document
+5. Format all hyperlinks with a consistent color and underline style
+```
+
+## 4. Create a Professional Table for Data Presentation
+
+```
+Task: "Create a formatted comparison table of product features."
+
+Steps:
+1. Insert a table with insertTable (5 rows x 4 columns)
+2. Add header row with product names
+3. Add feature rows with consistent formatting
+4. Apply alternating row background colors for readability
+5. Format the header row with bold text and background color
+6. Align numeric columns to the right
+```
+
+## 5. Prepare a Document for Formal Submission
+
+```
+Task: "Format my research paper according to academic guidelines."
+
+Steps:
+1. Set the title with centered alignment and appropriate font size
+2. Format all headings according to the required style guide
+3. Apply double spacing to the main text
+4. Insert page numbers with appropriate format
+5. Format citations consistently
+6. Apply indentation to block quotes
+7. Format the bibliography section
+```
+
+## 6. Create an Executive Summary with Highlights
+
+```
+Task: "Create an executive summary that emphasizes key points from my report."
+
+Steps:
+1. Insert a page break and create an "Executive Summary" section
+2. Extract and format key points from the document
+3. Apply bullet points for clarity
+4. Highlight critical figures or statistics in bold
+5. Use color to emphasize particularly important points
+6. Format the summary with appropriate spacing and margins
+```
+
+## 7. Format a Document for Different Audiences
+
+```
+Task: "Create two versions of my presentation - one technical and one for executives."
+
+Steps:
+1. Duplicate the document content
+2. For the technical version:
+   - Add detailed technical sections
+   - Include code examples with monospace formatting
+   - Use technical terminology
+3. For the executive version:
+   - Emphasize business impact with bold and color
+   - Simplify technical concepts
+   - Add executive summary
+   - Use more visual formatting elements
+```
+
+## 8. Create a Response Form with Structured Fields
+
+```
+Task: "Create a form-like document with fields for respondents to complete."
+
+Steps:
+1. Create section headers for different parts of the form
+2. Insert tables for structured response areas
+3. Add form fields with clear instructions
+4. Use formatting to distinguish between instructions and response areas
+5. Add checkbox lists using special characters with consistent formatting
+6. Apply consistent spacing and alignment throughout
+```
+
+## 9. Format a Document with Multi-Level Lists
+
+```
+Task: "Create a project plan with properly formatted nested task lists."
+
+Steps:
+1. Insert the project title and apply Heading 1 style
+2. Create main project phases with Heading 2 style
+3. For each phase, create a properly formatted numbered list of tasks
+4. Create sub-tasks with indented, properly formatted sub-lists
+5. Apply consistent formatting to all list levels
+6. Format task owners' names in bold
+7. Format dates and deadlines with a consistent style
+```
+
+## 10. Prepare a Document with Advanced Layout
+
+```
+Task: "Create a newsletter-style document with columns and sections."
+
+Steps:
+1. Create a bold, centered title for the newsletter
+2. Insert a horizontal line separator
+3. Create differently formatted sections for:
+   - Main article (left-aligned paragraphs)
+   - Sidebar content (indented, smaller text)
+   - Highlighted quotes (centered, italic)
+4. Insert and format images with captions
+5. Add a formatted footer with contact information
+6. Apply consistent spacing between sections
+```
+
+These examples demonstrate the power and flexibility of the enhanced Google Docs & Drive MCP Server, showcasing how AI assistants can help with sophisticated document formatting, structuring, and comprehensive file management tasks.
+
+## Google Drive Management Tasks
+
+## 11. Organize Project Files Automatically
+
+```
+Task: "Set up a complete project structure and organize existing files."
+
+Steps:
+1. Create a main project folder using createFolder
+2. Create subfolders for different aspects (Documents, Templates, Archive)
+3. Search for project-related documents using searchGoogleDocs
+4. Move relevant documents to appropriate subfolders with moveFile
+5. Create a project index document listing all resources
+6. Format the index with links to all project documents
+```
+
+## 12. Create Document Templates and Generate Reports
+
+```
+Task: "Set up a template system and generate standardized reports."
+
+Steps:
+1. Create a Templates folder using createFolder
+2. Create template documents with placeholder text ({{DATE}}, {{NAME}}, etc.)
+3. Use createFromTemplate to generate new reports from templates
+4. Apply text replacements to customize each report
+5. Organize generated reports in appropriate folders
+6. Create a tracking document listing all generated reports
+```
+
+## 13. Archive and Clean Up Old Documents
+
+```
+Task: "Archive outdated documents and organize current files."
+
+Steps:
+1. Create an Archive folder for old documents using createFolder
+2. Use getRecentGoogleDocs to find documents older than 90 days
+3. Review and move old documents to Archive using moveFile
+4. Delete unnecessary duplicate files using deleteFile
+5. Rename documents with consistent naming conventions using renameFile
+6. Create an archive index document for reference
+```
+
+## 14. Duplicate and Distribute Document Sets
+
+```
+Task: "Create personalized versions of documents for different teams."
+
+Steps:
+1. Create team-specific folders using createFolder
+2. Copy master documents to each team folder using copyFile
+3. Rename copied documents with team-specific names using renameFile
+4. Customize document content for each team using text replacement
+5. Apply team-specific formatting and branding
+6. Create distribution tracking documents
+```
+
+## 15. Comprehensive File Management and Reporting
+
+```
+Task: "Generate a complete inventory and management report of all documents."
+
+Steps:
+1. Use listFolderContents to catalog all folders and their contents
+2. Use getDocumentInfo to gather detailed metadata for each document
+3. Create a master inventory document with all file information
+4. Format the inventory as a searchable table with columns for:
+   - Document name and ID
+   - Creation and modification dates
+   - Owner and last modifier
+   - Folder location
+   - File size and sharing status
+5. Add summary statistics and organization recommendations
+6. Set up automated folder structures for better organization
+```

package/claude.md

@@ -0,0 +1,46 @@
+# Google Docs MCP Server
+
+FastMCP server with 42 tools for Google Docs, Sheets, and Drive.
+
+## Tool Categories
+
+| Category | Count | Examples |
+|----------|-------|----------|
+| Docs | 5 | `readGoogleDoc`, `appendToGoogleDoc`, `insertText`, `deleteRange`, `listDocumentTabs` |
+| Formatting | 3 | `applyTextStyle`, `applyParagraphStyle`, `formatMatchingText` |
+| Structure | 7 | `insertTable`, `insertPageBreak`, `insertImageFromUrl`, `insertLocalImage`, `editTableCell`*, `findElement`*, `fixListFormatting`* |
+| Comments | 6 | `listComments`, `getComment`, `addComment`, `replyToComment`, `resolveComment`, `deleteComment` |
+| Sheets | 8 | `readSpreadsheet`, `writeSpreadsheet`, `appendSpreadsheetRows`, `clearSpreadsheetRange`, `createSpreadsheet`, `listGoogleSheets` |
+| Drive | 13 | `listGoogleDocs`, `searchGoogleDocs`, `getDocumentInfo`, `createFolder`, `moveFile`, `copyFile`, `createDocument` |
+
+*Not fully implemented
+
+## Known Limitations
+
+- **Comment anchoring:** Programmatically created comments appear in "All Comments" but aren't visibly anchored to text in the UI
+- **Resolved status:** May not persist in Google Docs UI (Drive API limitation)
+- **editTableCell:** Not implemented (complex cell index calculation)
+- **fixListFormatting:** Experimental, may not work reliably
+
+## Parameter Patterns
+
+- **Document ID:** Extract from URL: `docs.google.com/document/d/DOCUMENT_ID/edit`
+- **Text targeting:** Use `textToFind` + `matchInstance` OR `startIndex`/`endIndex`
+- **Colors:** Hex format `#RRGGBB` or `#RGB`
+- **Alignment:** `START`, `END`, `CENTER`, `JUSTIFIED` (not LEFT/RIGHT)
+- **Indices:** 1-based, ranges are [start, end)
+- **Tabs:** Optional `tabId` parameter (defaults to first tab)
+
+## Source Files (for implementation details)
+
+| File | Contains |
+|------|----------|
+| `src/types.ts` | Zod schemas, hex color validation, style parameter definitions |
+| `src/googleDocsApiHelpers.ts` | `findTextRange`, `executeBatchUpdate`, style request builders |
+| `src/googleSheetsApiHelpers.ts` | A1 notation parsing, range operations |
+| `src/server.ts` | All 42 tool definitions with full parameter schemas |
+
+## See Also
+
+- `README.md` - Setup instructions and usage examples
+- `SAMPLE_TASKS.md` - 15 example workflows

package/docs/index.html

@@ -0,0 +1,228 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>FastMCP Google Docs Server Docs</title>
+    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+    <style>
+        body { font-family: sans-serif; line-height: 1.6; padding: 20px; }
+        pre { background-color: #f4f4f4; padding: 10px; border-radius: 5px; overflow-x: auto; }
+        code { font-family: monospace; }
+        h1, h2, h3 { border-bottom: 1px solid #eee; padding-bottom: 5px; margin-top: 20px; }
+    </style>
+</head>
+<body>
+    <div id="content"></div>
+
+    <script type="text/markdown" id="markdown-content">
+# FastMCP Google Docs Server
+
+Connect Claude Desktop (or other MCP clients) to your Google Docs!
+
+This server uses the Model Context Protocol (MCP) and the `fastmcp` library to provide tools for reading and appending text to Google Documents. It acts as a bridge, allowing AI assistants like Claude to interact with your documents programmatically.
+
+**Features:**
+
+- **Read Documents:** Provides a `readGoogleDoc` tool to fetch the text content of a specified Google Doc.
+- **Append to Documents:** Provides an `appendToGoogleDoc` tool to add text to the end of a specified Google Doc.
+- **Google Authentication:** Handles the OAuth 2.0 flow to securely authorize access to your Google Account.
+- **MCP Compliant:** Designed for use with MCP clients like Claude Desktop.
+
+---
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+1.  **Node.js and npm:** A recent version of Node.js (which includes npm) installed on your computer. You can download it from [nodejs.org](https://nodejs.org/). (Version 18 or higher recommended).
+2.  **Git:** Required for cloning this repository. ([Download Git](https://git-scm.com/downloads)).
+3.  **A Google Account:** The account that owns or has access to the Google Docs you want to interact with.
+4.  **Command Line Familiarity:** Basic comfort using a terminal or command prompt (like Terminal on macOS/Linux, or Command Prompt/PowerShell on Windows).
+5.  **Claude Desktop (Optional):** If your goal is to connect this server to Claude, you'll need the Claude Desktop application installed.
+
+---
+
+## Setup Instructions
+
+Follow these steps carefully to get your own instance of the server running.
+
+### Step 1: Google Cloud Project & Credentials (The Important Bit!)
+
+This server needs permission to talk to Google APIs on your behalf. You'll create special "keys" (credentials) that only your server will use.
+
+1.  **Go to Google Cloud Console:** Open your web browser and go to the [Google Cloud Console](https://console.cloud.google.com/). You might need to log in with your Google Account.
+2.  **Create or Select a Project:**
+    - If you don't have a project, click the project dropdown near the top and select "NEW PROJECT". Give it a name (e.g., "My MCP Docs Server") and click "CREATE".
+    - If you have existing projects, you can select one or create a new one.
+3.  **Enable APIs:** You need to turn on the specific Google services this server uses.
+    - In the search bar at the top, type "APIs & Services" and select "Library".
+    - Search for "**Google Docs API**" and click on it. Then click the "**ENABLE**" button.
+    - Search for "**Google Drive API**" and click on it. Then click the "**ENABLE**" button (this is often needed for finding files or permissions).
+4.  **Configure OAuth Consent Screen:** This screen tells users (usually just you) what your app wants permission for.
+    - On the left menu, click "APIs & Services" -> "**OAuth consent screen**".
+    - Choose User Type: Select "**External**" and click "CREATE".
+    - Fill in App Information:
+      - **App name:** Give it a name users will see (e.g., "Claude Docs MCP Access").
+      - **User support email:** Select your email address.
+      - **Developer contact information:** Enter your email address.
+    - Click "**SAVE AND CONTINUE**".
+    - **Scopes:** Click "**ADD OR REMOVE SCOPES**". Search for and add the following scopes:
+      - `https://www.googleapis.com/auth/documents` (Allows reading/writing docs)
+      - `https://www.googleapis.com/auth/drive.file` (Allows access to specific files opened/created by the app)
+      - Click "**UPDATE**".
+    - Click "**SAVE AND CONTINUE**".
+    - **Test Users:** Click "**ADD USERS**". Enter the same Google email address you are logged in with. Click "**ADD**". This allows _you_ to use the app while it's in "testing" mode.
+    - Click "**SAVE AND CONTINUE**". Review the summary and click "**BACK TO DASHBOARD**".
+5.  **Create Credentials (The Keys!):**
+    - On the left menu, click "APIs & Services" -> "**Credentials**".
+    - Click "**+ CREATE CREDENTIALS**" at the top and choose "**OAuth client ID**".
+    - **Application type:** Select "**Desktop app**" from the dropdown.
+    - **Name:** Give it a name (e.g., "MCP Docs Desktop Client").
+    - Click "**CREATE**".
+6.  **⬇️ DOWNLOAD THE CREDENTIALS FILE:** A box will pop up showing your Client ID. Click the "**DOWNLOAD JSON**" button.
+    - Save this file. It will likely be named something like `client_secret_....json`.
+    - **IMPORTANT:** Rename the downloaded file to exactly `credentials.json`.
+7.  ⚠️ **SECURITY WARNING:** Treat this `credentials.json` file like a password! Do not share it publicly, and **never commit it to GitHub.** Anyone with this file could potentially pretend to be _your application_ (though they'd still need user consent to access data).
+
+### Step 2: Get the Server Code
+
+1.  **Clone the Repository:** Open your terminal/command prompt and run:
+    ```bash
+    git clone https://github.com/a-bonus/google-docs-mcp.git mcp-googledocs-server
+    ```
+2.  **Navigate into Directory:**
+    ```bash
+    cd mcp-googledocs-server
+    ```
+3.  **Place Credentials:** Move or copy the `credentials.json` file you downloaded and renamed (from Step 1.6) directly into this `mcp-googledocs-server` folder.
+
+### Step 3: Install Dependencies
+
+Your server needs some helper libraries specified in the `package.json` file.
+
+1.  In your terminal (make sure you are inside the `mcp-googledocs-server` directory), run:
+    ```bash
+    npm install
+    ```
+    This will download and install all the necessary packages into a `node_modules` folder.
+
+### Step 4: Build the Server Code
+
+The server is written in TypeScript (`.ts`), but we need to compile it into JavaScript (`.js`) that Node.js can run directly.
+
+1.  In your terminal, run:
+    ```bash
+    npm run build
+    ```
+    This uses the TypeScript compiler (`tsc`) to create a `dist` folder containing the compiled JavaScript files.
+
+### Step 5: First Run & Google Authorization (One Time Only)
+
+Now you need to run the server once manually to grant it permission to access your Google account data. This will create a `token.json` file that saves your permission grant.
+
+1.  In your terminal, run the _compiled_ server using `node`:
+    ```bash
+    node ./dist/server.js
+    ```
+2.  **Watch the Terminal:** The script will print:
+    - Status messages (like "Attempting to authorize...").
+    - An "Authorize this app by visiting this url:" message followed by a long `https://accounts.google.com/...` URL.
+3.  **Authorize in Browser:**
+    - Copy the entire long URL from the terminal.
+    - Paste the URL into your web browser and press Enter.
+    - Log in with the **same Google account** you added as a Test User in Step 1.4.
+    - Google will show a screen asking for permission for your app ("Claude Docs MCP Access" or similar) to access Google Docs/Drive. Review and click "**Allow**" or "**Grant**".
+4.  **Get the Authorization Code:**
+    - After clicking Allow, your browser will likely try to redirect to `http://localhost` and show a **"This site can't be reached" error**. **THIS IS NORMAL!**
+    - Look **carefully** at the URL in your browser's address bar. It will look like `http://localhost/?code=4/0Axxxxxxxxxxxxxx&scope=...`
+    - Copy the long string of characters **between `code=` and the `&scope` part**. This is your single-use authorization code.
+5.  **Paste Code into Terminal:** Go back to your terminal where the script is waiting ("Enter the code from that page here:"). Paste the code you just copied.
+6.  **Press Enter.**
+7.  **Success!** The script should print:
+    - "Authentication successful!"
+    - "Token stored to .../token.json"
+    - It will then finish starting and likely print "Awaiting MCP client connection via stdio..." or similar, and then exit (or you can press `Ctrl+C` to stop it).
+8.  ✅ **Check:** You should now see a new file named `token.json` in your `mcp-googledocs-server` folder.
+9.  ⚠️ **SECURITY WARNING:** This `token.json` file contains the key that allows the server to access your Google account _without_ asking again. Protect it like a password. **Do not commit it to GitHub.** The included `.gitignore` file should prevent this automatically.
+
+### Step 6: Configure Claude Desktop (Optional)
+
+If you want to use this server with Claude Desktop, you need to tell Claude how to run it.
+
+1.  **Find Your Absolute Path:** You need the full path to the server code.
+    - In your terminal, make sure you are still inside the `mcp-googledocs-server` directory.
+    - Run the `pwd` command (on macOS/Linux) or `cd` (on Windows, just displays the path).
+    - Copy the full path (e.g., `/Users/yourname/projects/mcp-googledocs-server` or `C:\Users\yourname\projects\mcp-googledocs-server`).
+2.  **Locate `mcp_config.json`:** Find Claude's configuration file:
+    - **macOS:** `~/Library/Application Support/Claude/mcp_config.json` (You might need to use Finder's "Go" -> "Go to Folder..." menu and paste `~/Library/Application Support/Claude/`)
+    - **Windows:** `%APPDATA%\Claude\mcp_config.json` (Paste `%APPDATA%\Claude` into File Explorer's address bar)
+    - **Linux:** `~/.config/Claude/mcp_config.json`
+    - _If the `Claude` folder or `mcp_config.json` file doesn't exist, create them._
+3.  **Edit `mcp_config.json`:** Open the file in a text editor. Add or modify the `mcpServers` section like this, **replacing `/PATH/TO/YOUR/CLONED/REPO` with the actual absolute path you copied in Step 6.1**:
+
+    ```json
+    {
+      "mcpServers": {
+        "google-docs-mcp": {
+          "command": "node",
+          "args": [
+            "/PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js"
+          ],
+          "env": {}
+        }
+        // Add commas here if you have other servers defined
+      }
+      // Other Claude settings might be here
+    }
+    ```
+
+    - **Make sure the path in `"args"` is correct and absolute!**
+    - If the file already existed, carefully merge this entry into the existing `mcpServers` object. Ensure the JSON is valid (check commas!).
+
+4.  **Save `mcp_config.json`.**
+5.  **Restart Claude Desktop:** Close Claude completely and reopen it.
+
+---
+
+## Usage with Claude Desktop
+
+Once configured, you should be able to use the tools in your chats with Claude:
+
+- "Use the `google-docs-mcp` server to read the document with ID `YOUR_GOOGLE_DOC_ID`."
+- "Can you get the content of Google Doc `YOUR_GOOGLE_DOC_ID`?"
+- "Append 'This was added by Claude!' to document `YOUR_GOOGLE_DOC_ID` using the `google-docs-mcp` tool."
+
+Remember to replace `YOUR_GOOGLE_DOC_ID` with the actual ID from a Google Doc's URL (the long string between `/d/` and `/edit`).
+
+Claude will automatically launch your server in the background when needed using the command you provided. You do **not** need to run `node ./dist/server.js` manually anymore.
+
+---
+
+## Security & Token Storage
+
+- **`.gitignore`:** This repository includes a `.gitignore` file which should prevent you from accidentally committing your sensitive `credentials.json` and `token.json` files. **Do not remove these lines from `.gitignore`**.
+- **Token Storage:** This server stores the Google authorization token (`token.json`) directly in the project folder for simplicity during setup. In production or more security-sensitive environments, consider storing this token more securely, such as using system keychains, encrypted files, or dedicated secret management services.
+
+---
+
+## Troubleshooting
+
+- **Claude shows "Failed" or "Could not attach":**
+  - Double-check the absolute path in `mcp_config.json`.
+  - Ensure you ran `npm run build` successfully and the `dist` folder exists.
+  - Try running the command from `mcp_config.json` manually in your terminal: `node /PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js`. Look for any errors printed.
+  - Check the Claude Desktop logs (see the official MCP debugging guide).
+  - Make sure all `console.log` status messages in the server code were changed to `console.error`.
+- **Google Authorization Errors:**
+  - Ensure you enabled the correct APIs (Docs, Drive).
+  - Make sure you added your email as a Test User on the OAuth Consent Screen.
+  - Verify the `credentials.json` file is correctly placed in the project root.
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the `LICENSE` file for details. (Note: You should add a `LICENSE` file containing the MIT License text to your repository).
+
+---

package/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// Entry point for the Google Docs MCP Server
+// This imports and runs the compiled server from the dist directory
+
+import './dist/server.js';

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@brainwavesio/google-docs-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "google-docs-mcp": "./index.js"
+  },
+  "scripts": {
+    "test": "node --test tests/",
+    "build": "tsc",
+    "prepare": "tsc"
+  },
+  "keywords": [
+    "mcp",
+    "google-docs",
+    "google-sheets",
+    "google-drive",
+    "claude",
+    "model-context-protocol"
+  ],
+  "author": "BrainWaves (fork of a-bonus/google-docs-mcp)",
+  "license": "MIT",
+  "description": "MCP server for Google Docs, Sheets, and Drive integration with Claude and other MCP clients",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brainwavesio/google-docs-mcp.git"
+  },
+  "dependencies": {
+    "fastmcp": "^3.24.0",
+    "google-auth-library": "^9.15.1",
+    "googleapis": "^148.0.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  }
+}