@brainwavesio/google-docs-mcp 1.0.0 → 1.1.0

package/src/types.ts

@@ -1,136 +0,0 @@
-// src/types.ts
-import { z } from 'zod';
-import { docs_v1 } from 'googleapis';
-
-// --- Helper function for hex color validation ---
-export const hexColorRegex = /^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/;
-export const validateHexColor = (color: string) => hexColorRegex.test(color);
-
-// --- Helper function for Hex to RGB conversion ---
-export function hexToRgbColor(hex: string): docs_v1.Schema$RgbColor | null {
-if (!hex) return null;
-let hexClean = hex.startsWith('#') ? hex.slice(1) : hex;
-
-if (hexClean.length === 3) {
-hexClean = hexClean[0] + hexClean[0] + hexClean[1] + hexClean[1] + hexClean[2] + hexClean[2];
-}
-if (hexClean.length !== 6) return null;
-const bigint = parseInt(hexClean, 16);
-if (isNaN(bigint)) return null;
-
-const r = ((bigint >> 16) & 255) / 255;
-const g = ((bigint >> 8) & 255) / 255;
-const b = (bigint & 255) / 255;
-
-return { red: r, green: g, blue: b };
-}
-
-// --- Zod Schema Fragments for Reusability ---
-
-export const DocumentIdParameter = z.object({
-documentId: z.string().describe('The ID of the Google Document (from the URL).'),
-});
-
-export const RangeParameters = z.object({
-startIndex: z.number().int().min(1).describe('The starting index of the text range (inclusive, starts from 1).'),
-endIndex: z.number().int().min(1).describe('The ending index of the text range (exclusive).'),
-}).refine(data => data.endIndex > data.startIndex, {
-message: "endIndex must be greater than startIndex",
-path: ["endIndex"],
-});
-
-export const OptionalRangeParameters = z.object({
-startIndex: z.number().int().min(1).optional().describe('Optional: The starting index of the text range (inclusive, starts from 1). If omitted, might apply to a found element or whole paragraph.'),
-endIndex: z.number().int().min(1).optional().describe('Optional: The ending index of the text range (exclusive). If omitted, might apply to a found element or whole paragraph.'),
-}).refine(data => !data.startIndex || !data.endIndex || data.endIndex > data.startIndex, {
-message: "If both startIndex and endIndex are provided, endIndex must be greater than startIndex",
-path: ["endIndex"],
-});
-
-export const TextFindParameter = z.object({
-textToFind: z.string().min(1).describe('The exact text string to locate.'),
-matchInstance: z.number().int().min(1).optional().default(1).describe('Which instance of the text to target (1st, 2nd, etc.). Defaults to 1.'),
-});
-
-// --- Style Parameter Schemas ---
-
-export const TextStyleParameters = z.object({
-bold: z.boolean().optional().describe('Apply bold formatting.'),
-italic: z.boolean().optional().describe('Apply italic formatting.'),
-underline: z.boolean().optional().describe('Apply underline formatting.'),
-strikethrough: z.boolean().optional().describe('Apply strikethrough formatting.'),
-fontSize: z.number().min(1).optional().describe('Set font size (in points, e.g., 12).'),
-fontFamily: z.string().optional().describe('Set font family (e.g., "Arial", "Times New Roman").'),
-foregroundColor: z.string()
-.refine(validateHexColor, { message: "Invalid hex color format (e.g., #FF0000 or #F00)" })
-.optional()
-.describe('Set text color using hex format (e.g., "#FF0000").'),
-backgroundColor: z.string()
-.refine(validateHexColor, { message: "Invalid hex color format (e.g., #00FF00 or #0F0)" })
-.optional()
-.describe('Set text background color using hex format (e.g., "#FFFF00").'),
-linkUrl: z.string().url().optional().describe('Make the text a hyperlink pointing to this URL.'),
-// clearDirectFormatting: z.boolean().optional().describe('If true, attempts to clear all direct text formatting within the range before applying new styles.') // Harder to implement perfectly
-}).describe("Parameters for character-level text formatting.");
-
-// Subset of TextStyle used for passing to helpers
-export type TextStyleArgs = z.infer<typeof TextStyleParameters>;
-
-export const ParagraphStyleParameters = z.object({
-alignment: z.enum(['START', 'END', 'CENTER', 'JUSTIFIED']).optional().describe('Paragraph alignment. START=left for LTR languages, END=right for LTR languages.'),
-indentStart: z.number().min(0).optional().describe('Left indentation in points.'),
-indentEnd: z.number().min(0).optional().describe('Right indentation in points.'),
-spaceAbove: z.number().min(0).optional().describe('Space before the paragraph in points.'),
-spaceBelow: z.number().min(0).optional().describe('Space after the paragraph in points.'),
-namedStyleType: z.enum([
-'NORMAL_TEXT', 'TITLE', 'SUBTITLE',
-'HEADING_1', 'HEADING_2', 'HEADING_3', 'HEADING_4', 'HEADING_5', 'HEADING_6'
-]).optional().describe('Apply a built-in named paragraph style (e.g., HEADING_1).'),
-keepWithNext: z.boolean().optional().describe('Keep this paragraph together with the next one on the same page.'),
-// Borders are more complex, might need separate objects/tools
-// clearDirectFormatting: z.boolean().optional().describe('If true, attempts to clear all direct paragraph formatting within the range before applying new styles.') // Harder to implement perfectly
-}).describe("Parameters for paragraph-level formatting.");
-
-// Subset of ParagraphStyle used for passing to helpers
-export type ParagraphStyleArgs = z.infer<typeof ParagraphStyleParameters>;
-
-// --- Combination Schemas for Tools ---
-
-export const ApplyTextStyleToolParameters = DocumentIdParameter.extend({
-// Target EITHER by range OR by finding text
-target: z.union([
-RangeParameters,
-TextFindParameter
-]).describe("Specify the target range either by start/end indices or by finding specific text."),
-style: TextStyleParameters.refine(
-styleArgs => Object.values(styleArgs).some(v => v !== undefined),
-{ message: "At least one text style option must be provided." }
-).describe("The text styling to apply.")
-});
-export type ApplyTextStyleToolArgs = z.infer<typeof ApplyTextStyleToolParameters>;
-
-export const ApplyParagraphStyleToolParameters = DocumentIdParameter.extend({
-// Target EITHER by range OR by finding text (tool logic needs to find paragraph boundaries)
-target: z.union([
-RangeParameters, // User provides paragraph start/end (less likely)
-TextFindParameter, // Find text within paragraph to apply style
-z.object({ // Target by specific index within the paragraph
-indexWithinParagraph: z.number().int().min(1).describe("An index located anywhere within the target paragraph.")
-})
-]).describe("Specify the target paragraph either by start/end indices, by finding text within it, or by providing an index within it."),
-style: ParagraphStyleParameters.refine(
-styleArgs => Object.values(styleArgs).some(v => v !== undefined),
-{ message: "At least one paragraph style option must be provided." }
-).describe("The paragraph styling to apply.")
-});
-export type ApplyParagraphStyleToolArgs = z.infer<typeof ApplyParagraphStyleToolParameters>;
-
-// --- Error Class ---
-// Use FastMCP's UserError for client-facing issues
-// Define a custom error for internal issues if needed
-export class NotImplementedError extends Error {
-constructor(message = "This feature is not yet implemented.") {
-super(message);
-this.name = "NotImplementedError";
-}
-}

package/tests/helpers.test.js

@@ -1,164 +0,0 @@
-// tests/helpers.test.js
-import { findTextRange } from '../dist/googleDocsApiHelpers.js';
-import assert from 'node:assert';
-import { describe, it, mock } from 'node:test';
-
-describe('Text Range Finding', () => {
-  // Test hypothesis 1: Text range finding works correctly
-  
-  describe('findTextRange', () => {
-    it('should find text within a single text run correctly', async () => {
-      // Mock the docs.documents.get method to return a predefined structure
-      const mockDocs = {
-        documents: {
-          get: mock.fn(async () => ({
-            data: {
-              body: {
-                content: [
-                  {
-                    paragraph: {
-                      elements: [
-                        {
-                          startIndex: 1,
-                          endIndex: 25,
-                          textRun: {
-                            content: 'This is a test sentence.'
-                          }
-                        }
-                      ]
-                    }
-                  }
-                ]
-              }
-            }
-          }))
-        }
-      };
-
-      // Test finding "test" in the sample text
-      const result = await findTextRange(mockDocs, 'doc123', 'test', 1);
-      assert.deepStrictEqual(result, { startIndex: 11, endIndex: 15 });
-      
-      // Verify the docs.documents.get was called with the right parameters
-      assert.strictEqual(mockDocs.documents.get.mock.calls.length, 1);
-      assert.deepStrictEqual(
-        mockDocs.documents.get.mock.calls[0].arguments[0], 
-        {
-          documentId: 'doc123',
-          fields: 'body(content(paragraph(elements(startIndex,endIndex,textRun(content)))))'
-        }
-      );
-    });
-    
-    it('should find the nth instance of text correctly', async () => {
-      // Mock with a document that has repeated text
-      const mockDocs = {
-        documents: {
-          get: mock.fn(async () => ({
-            data: {
-              body: {
-                content: [
-                  {
-                    paragraph: {
-                      elements: [
-                        {
-                          startIndex: 1,
-                          endIndex: 41,
-                          textRun: {
-                            content: 'Test test test. This is a test sentence.'
-                          }
-                        }
-                      ]
-                    }
-                  }
-                ]
-              }
-            }
-          }))
-        }
-      };
-
-      // Find the 3rd instance of "test"
-      const result = await findTextRange(mockDocs, 'doc123', 'test', 3);
-      assert.deepStrictEqual(result, { startIndex: 27, endIndex: 31 });
-    });
-
-    it('should return null if text is not found', async () => {
-      const mockDocs = {
-        documents: {
-          get: mock.fn(async () => ({
-            data: {
-              body: {
-                content: [
-                  {
-                    paragraph: {
-                      elements: [
-                        {
-                          startIndex: 1,
-                          endIndex: 25,
-                          textRun: {
-                            content: 'This is a sample sentence.'
-                          }
-                        }
-                      ]
-                    }
-                  }
-                ]
-              }
-            }
-          }))
-        }
-      };
-
-      // Try to find text that doesn't exist
-      const result = await findTextRange(mockDocs, 'doc123', 'test', 1);
-      assert.strictEqual(result, null);
-    });
-
-    it('should handle text spanning multiple text runs', async () => {
-      const mockDocs = {
-        documents: {
-          get: mock.fn(async () => ({
-            data: {
-              body: {
-                content: [
-                  {
-                    paragraph: {
-                      elements: [
-                        {
-                          startIndex: 1,
-                          endIndex: 6,
-                          textRun: {
-                            content: 'This '
-                          }
-                        },
-                        {
-                          startIndex: 6,
-                          endIndex: 11,
-                          textRun: {
-                            content: 'is a '
-                          }
-                        },
-                        {
-                          startIndex: 11,
-                          endIndex: 20,
-                          textRun: {
-                            content: 'test case'
-                          }
-                        }
-                      ]
-                    }
-                  }
-                ]
-              }
-            }
-          }))
-        }
-      };
-
-      // Find text that spans runs: "a test"
-      const result = await findTextRange(mockDocs, 'doc123', 'a test', 1);
-      assert.deepStrictEqual(result, { startIndex: 9, endIndex: 15 });
-    });
-  });
-});

package/tests/types.test.js

@@ -1,69 +0,0 @@
-// tests/types.test.js
-import { hexToRgbColor, validateHexColor } from '../dist/types.js';
-import assert from 'node:assert';
-import { describe, it } from 'node:test';
-
-describe('Color Validation and Conversion', () => {
-  // Test hypothesis 3: Hex color validation and conversion
-
-  describe('validateHexColor', () => {
-    it('should validate correct hex colors with hash', () => {
-      assert.strictEqual(validateHexColor('#FF0000'), true); // 6 digits red
-      assert.strictEqual(validateHexColor('#F00'), true);    // 3 digits red
-      assert.strictEqual(validateHexColor('#00FF00'), true); // 6 digits green
-      assert.strictEqual(validateHexColor('#0F0'), true);    // 3 digits green
-    });
-
-    it('should validate correct hex colors without hash', () => {
-      assert.strictEqual(validateHexColor('FF0000'), true);  // 6 digits red
-      assert.strictEqual(validateHexColor('F00'), true);     // 3 digits red
-      assert.strictEqual(validateHexColor('00FF00'), true);  // 6 digits green
-      assert.strictEqual(validateHexColor('0F0'), true);     // 3 digits green
-    });
-
-    it('should reject invalid hex colors', () => {
-      assert.strictEqual(validateHexColor(''), false);        // Empty
-      assert.strictEqual(validateHexColor('#XYZ'), false);    // Invalid characters
-      assert.strictEqual(validateHexColor('#12345'), false);  // Invalid length (5)
-      assert.strictEqual(validateHexColor('#1234567'), false);// Invalid length (7)
-      assert.strictEqual(validateHexColor('invalid'), false); // Not a hex color
-      assert.strictEqual(validateHexColor('#12'), false);     // Too short
-    });
-  });
-
-  describe('hexToRgbColor', () => {
-    it('should convert 6-digit hex colors with hash correctly', () => {
-      const result = hexToRgbColor('#FF0000');
-      assert.deepStrictEqual(result, { red: 1, green: 0, blue: 0 }); // Red
-      
-      const resultGreen = hexToRgbColor('#00FF00');
-      assert.deepStrictEqual(resultGreen, { red: 0, green: 1, blue: 0 }); // Green
-      
-      const resultBlue = hexToRgbColor('#0000FF');
-      assert.deepStrictEqual(resultBlue, { red: 0, green: 0, blue: 1 }); // Blue
-      
-      const resultPurple = hexToRgbColor('#800080');
-      assert.deepStrictEqual(resultPurple, { red: 0.5019607843137255, green: 0, blue: 0.5019607843137255 }); // Purple
-    });
-
-    it('should convert 3-digit hex colors correctly', () => {
-      const result = hexToRgbColor('#F00');
-      assert.deepStrictEqual(result, { red: 1, green: 0, blue: 0 }); // Red from shorthand
-      
-      const resultWhite = hexToRgbColor('#FFF');
-      assert.deepStrictEqual(resultWhite, { red: 1, green: 1, blue: 1 }); // White from shorthand
-    });
-
-    it('should convert hex colors without hash correctly', () => {
-      const result = hexToRgbColor('FF0000');
-      assert.deepStrictEqual(result, { red: 1, green: 0, blue: 0 }); // Red without hash
-    });
-
-    it('should return null for invalid hex colors', () => {
-      assert.strictEqual(hexToRgbColor(''), null);        // Empty
-      assert.strictEqual(hexToRgbColor('#XYZ'), null);    // Invalid characters
-      assert.strictEqual(hexToRgbColor('#12345'), null);  // Invalid length
-      assert.strictEqual(hexToRgbColor('invalid'), null); // Not a hex color
-    });
-  });
-});

package/tsconfig.json

@@ -1,17 +0,0 @@
-// tsconfig.json
-{
-    "compilerOptions": {
-      "target": "ES2022",
-      "module": "NodeNext",
-      "moduleResolution": "NodeNext",
-      "outDir": "./dist",
-      "rootDir": "./src",
-      "strict": true,
-      "esModuleInterop": true,
-      "skipLibCheck": true,
-      "forceConsistentCasingInFileNames": true,
-      "resolveJsonModule": true
-    },
-    "include": ["src/**/*"],
-    "exclude": ["node_modules"]
-  }

package/vscode.md

@@ -1,168 +0,0 @@
-# VS Code Integration Guide
-
-This guide shows you how to integrate the Ultimate Google Docs & Drive MCP Server with VS Code using the MCP extension.
-
-## Prerequisites
-
-Before setting up VS Code integration, make sure you have:
-
-1. **Completed the main setup** - Follow the [README.md](README.md) setup instructions first
-2. **VS Code installed** - Download from [code.visualstudio.com](https://code.visualstudio.com/)
-3. **Working MCP server** - Verify your server works with Claude Desktop first
-
-## Installation
-
-### Step 1: Install the MCP Extension
-
-1. Open VS Code
-2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
-3. Search for "MCP" or "Model Context Protocol"
-4. Install the official MCP extension
-
-### Step 2: Configure the MCP Server
-
-1. Open VS Code Settings (Ctrl+, / Cmd+,)
-2. Search for "MCP" in settings
-3. Find "MCP: Servers" configuration
-4. Add a new server configuration:
-
-```json
-{
-  "google-docs-drive": {
-    "command": "node",
-    "args": ["${workspaceFolder}/dist/server.js"],
-    "env": {
-      "NODE_ENV": "production"
-    }
-  }
-}
-```
-
-### Step 3: Verify Configuration
-
-1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
-2. Type "MCP: Restart Servers" and run it
-3. Check the Output panel and select "MCP" from the dropdown
-4. You should see your server connecting successfully
-
-## Usage
-
-Once configured, you can use the MCP server with AI assistants in VS Code:
-
-### Document Operations
-
-```
-"List my recent Google Docs from the last 7 days"
-"Read the content of document ID: 1ABC..."
-"Create a new document called 'Project Notes' in my Work folder"
-"Search for documents containing 'meeting notes'"
-```
-
-### File Management
-
-```
-"Show me the contents of my root Drive folder"
-"Create a folder called 'Project X' in folder ID: 1DEF..."
-"Move document ID: 1GHI... to the Project X folder"
-"Copy my template document and rename it to 'New Report'"
-```
-
-### Document Editing
-
-```
-"Add a heading 'Summary' to the beginning of document ID: 1JKL..."
-"Format all text containing 'important' as bold in my document"
-"Insert a table with 3 columns and 5 rows at the end of the document"
-"Apply paragraph formatting to make all headings centered"
-```
-
-## Troubleshooting
-
-### Server Not Starting
-
-1. **Check the path** - Ensure the absolute path in your configuration is correct
-2. **Verify build** - Run `npm run build` in your project directory
-3. **Check permissions** - Ensure `token.json` and `credentials.json` exist and are readable
-
-### Authentication Issues
-
-1. **Re-authorize** - Delete `token.json` and run the server manually once:
-   ```bash
-   cd /path/to/your/google-docs-mcp
-   node dist/server.js
-   ```
-2. **Follow the authorization flow** again
-3. **Restart VS Code** after successful authorization
-
-### Tool Not Found Errors
-
-1. **Restart MCP servers** using Command Palette
-2. **Check server logs** in VS Code Output panel (MCP channel)
-
-## Available Tools
-
-The server provides these tools in VS Code:
-
-### Document Discovery
-- `listGoogleDocs` - List documents with filtering
-- `searchGoogleDocs` - Search by name/content
-- `getRecentGoogleDocs` - Get recently modified docs
-- `getDocumentInfo` - Get detailed document metadata
-
-### Document Editing
-- `readGoogleDoc` - Read document content
-- `appendToGoogleDoc` - Add text to end
-- `insertText` - Insert at specific position
-- `deleteRange` - Remove content
-- `applyTextStyle` - Format text (bold, italic, colors)
-- `applyParagraphStyle` - Format paragraphs (alignment, spacing)
-- `formatMatchingText` - Find and format text
-- `insertTable` - Create tables
-- `insertPageBreak` - Add page breaks
-
-### File Management
-- `createFolder` - Create new folders
-- `listFolderContents` - List folder contents
-- `getFolderInfo` - Get folder metadata
-- `moveFile` - Move files/folders
-- `copyFile` - Copy files/folders
-- `renameFile` - Rename files/folders
-- `deleteFile` - Delete files/folders
-- `createDocument` - Create new documents
-- `createFromTemplate` - Create from templates
-
-## Tips for Better Integration
-
-1. **Use specific document IDs** - More reliable than document names
-2. **Combine operations** - Create and format documents in single requests
-3. **Check tool results** - Review what was actually done before proceeding
-4. **Use templates** - Create template documents for consistent formatting
-
-## Security Notes
-
-- The server uses OAuth 2.0 for secure authentication
-- Credentials are stored locally in `token.json` and `credentials.json`
-- Never share these files or commit them to version control
-- The server only has access to your Google Drive, not other Google services
-
-## Example Workflows
-
-### Create a Formatted Report
-
-```
-1. "Create a new document called 'Monthly Report' in my Reports folder"
-2. "Add the title 'Monthly Performance Report' as a centered Heading 1"
-3. "Insert a table with 4 columns and 6 rows for the data"
-4. "Add section headings for Executive Summary, Key Metrics, and Action Items"
-```
-
-### Organize Project Documents
-
-```
-1. "Create a folder called 'Q1 Project' in my Work folder"
-2. "Search for all documents containing 'Q1' in the title"
-3. "Move the found documents to the Q1 Project folder"
-4. "Create a new document called 'Q1 Project Overview' in that folder"
-```
-
-This integration brings the full power of Google Docs and Drive management directly into your VS Code workflow!