This is page 1 of 3. Use http://codebase.md/a-bonus/google-docs-mcp?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .DS_Store
├── .gitignore
├── .repomix
│ └── bundles.json
├── assets
│ └── google.docs.mcp.1.gif
├── claude.md
├── docs
│ └── index.html
├── google docs mcp.mp4
├── index.js
├── LICENSE
├── package-lock.json
├── package.json
├── pages
│ └── pages.md
├── README.md
├── repomix-output.txt.xml
├── SAMPLE_TASKS.md
├── src
│ ├── auth.ts
│ ├── backup
│ │ ├── auth.ts.bak
│ │ └── server.ts.bak
│ ├── googleDocsApiHelpers.ts
│ ├── server.ts
│ └── types.ts
├── tests
│ ├── helpers.test.js
│ └── types.test.js
├── tsconfig.json
└── vscode.md
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Node dependencies
2 | node_modules/
3 | dist/
4 |
5 | # Credentials / Tokens
6 | credentials.json
7 | token.json
8 |
9 | # Log files
10 | *.log
11 |
12 | # Environment variables (if you use a .env file later)
13 | .env*
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Ultimate Google Docs & Drive MCP Server
2 |
3 | 
4 |
5 | Connect Claude Desktop (or other MCP clients) to your Google Docs and Google Drive!
6 |
7 | > 🔥 **Check out [15 powerful tasks](SAMPLE_TASKS.md) you can accomplish with this enhanced server!**
8 | > 📁 **NEW:** Complete Google Drive file management capabilities!
9 |
10 | This comprehensive server uses the Model Context Protocol (MCP) and the `fastmcp` library to provide tools for reading, writing, formatting, structuring Google Documents, and managing your entire Google Drive. It acts as a powerful bridge, allowing AI assistants like Claude to interact with your documents and files programmatically with advanced capabilities.
11 |
12 | **Features:**
13 |
14 | ### Document Access & Editing
15 | - **Read Documents:** Read content with `readGoogleDoc` (plain text, JSON structure, or markdown)
16 | - **Append to Documents:** Add text to documents with `appendToGoogleDoc`
17 | - **Insert Text:** Place text at specific positions with `insertText`
18 | - **Delete Content:** Remove content from a document with `deleteRange`
19 |
20 | ### Formatting & Styling
21 | - **Text Formatting:** Apply rich styling with `applyTextStyle` (bold, italic, colors, etc.)
22 | - **Paragraph Formatting:** Control paragraph layout with `applyParagraphStyle` (alignment, spacing, etc.)
23 | - **Find & Format:** Format by text content using `formatMatchingText` (legacy support)
24 |
25 | ### Document Structure
26 | - **Tables:** Create tables with `insertTable`
27 | - **Page Breaks:** Insert page breaks with `insertPageBreak`
28 | - **Images:** Insert images from URLs with `insertImageFromUrl`, or upload local images with `insertLocalImage`
29 | - **Experimental Features:** Tools like `fixListFormatting` for automatic list detection
30 |
31 | ### 🆕 Comment Management
32 | - **List Comments:** View all comments in a document with `listComments` (shows author, date, and quoted text)
33 | - **Get Comment Details:** Get specific comment with replies using `getComment`
34 | - **Add Comments:** Create new comments anchored to text with `addComment`
35 | - **Reply to Comments:** Add replies to existing comments with `replyToComment`
36 | - **Resolve Comments:** Mark comments as resolved with `resolveComment`
37 | - **Delete Comments:** Remove comments from documents with `deleteComment`
38 |
39 | ### 🆕 Google Drive File Management
40 | - **Document Discovery:** Find and list documents with `listGoogleDocs`, `searchGoogleDocs`, `getRecentGoogleDocs`
41 | - **Document Information:** Get detailed metadata with `getDocumentInfo`
42 | - **Folder Management:** Create folders (`createFolder`), list contents (`listFolderContents`), get info (`getFolderInfo`)
43 | - **File Operations:** Move (`moveFile`), copy (`copyFile`), rename (`renameFile`), delete (`deleteFile`)
44 | - **Document Creation:** Create new docs (`createDocument`) or from templates (`createFromTemplate`)
45 |
46 | ### Integration
47 | - **Google Authentication:** Secure OAuth 2.0 authentication with full Drive access
48 | - **MCP Compliant:** Designed for use with Claude and other MCP clients
49 | - **VS Code Integration:** [Setup guide](vscode.md) for VS Code MCP extension
50 |
51 | ---
52 |
53 | ## Prerequisites
54 |
55 | Before you start, make sure you have:
56 |
57 | 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).
58 | 2. **Git:** Required for cloning this repository. ([Download Git](https://git-scm.com/downloads)).
59 | 3. **A Google Account:** The account that owns or has access to the Google Docs you want to interact with.
60 | 4. **Command Line Familiarity:** Basic comfort using a terminal or command prompt (like Terminal on macOS/Linux, or Command Prompt/PowerShell on Windows).
61 | 5. **Claude Desktop (Optional):** If your goal is to connect this server to Claude, you'll need the Claude Desktop application installed.
62 |
63 | ---
64 |
65 | ## Setup Instructions
66 |
67 | Follow these steps carefully to get your own instance of the server running.
68 |
69 | ### Step 1: Google Cloud Project & Credentials (The Important Bit!)
70 |
71 | This server needs permission to talk to Google APIs on your behalf. You'll create special "keys" (credentials) that only your server will use.
72 |
73 | 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.
74 | 2. **Create or Select a Project:**
75 | - 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".
76 | - If you have existing projects, you can select one or create a new one.
77 | 3. **Enable APIs:** You need to turn on the specific Google services this server uses.
78 | - In the search bar at the top, type "APIs & Services" and select "Library".
79 | - Search for "**Google Docs API**" and click on it. Then click the "**ENABLE**" button.
80 | - Search for "**Google Drive API**" and click on it. Then click the "**ENABLE**" button (this is often needed for finding files or permissions).
81 | 4. **Configure OAuth Consent Screen:** This screen tells users (usually just you) what your app wants permission for.
82 | - On the left menu, click "APIs & Services" -> "**OAuth consent screen**".
83 | - Choose User Type: Select "**External**" and click "CREATE".
84 | - Fill in App Information:
85 | - **App name:** Give it a name users will see (e.g., "Claude Docs MCP Access").
86 | - **User support email:** Select your email address.
87 | - **Developer contact information:** Enter your email address.
88 | - Click "**SAVE AND CONTINUE**".
89 | - **Scopes:** Click "**ADD OR REMOVE SCOPES**". Search for and add the following scopes:
90 | - `https://www.googleapis.com/auth/documents` (Allows reading/writing docs)
91 | - `https://www.googleapis.com/auth/drive.file` (Allows access to specific files opened/created by the app)
92 | - Click "**UPDATE**".
93 | - Click "**SAVE AND CONTINUE**".
94 | - **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.
95 | - Click "**SAVE AND CONTINUE**". Review the summary and click "**BACK TO DASHBOARD**".
96 | 5. **Create Credentials (The Keys!):**
97 | - On the left menu, click "APIs & Services" -> "**Credentials**".
98 | - Click "**+ CREATE CREDENTIALS**" at the top and choose "**OAuth client ID**".
99 | - **Application type:** Select "**Desktop app**" from the dropdown.
100 | - **Name:** Give it a name (e.g., "MCP Docs Desktop Client").
101 | - Click "**CREATE**".
102 | 6. **⬇️ DOWNLOAD THE CREDENTIALS FILE:** A box will pop up showing your Client ID. Click the "**DOWNLOAD JSON**" button.
103 | - Save this file. It will likely be named something like `client_secret_....json`.
104 | - **IMPORTANT:** Rename the downloaded file to exactly `credentials.json`.
105 | 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).
106 |
107 | ### Step 2: Get the Server Code
108 |
109 | 1. **Clone the Repository:** Open your terminal/command prompt and run:
110 | ```bash
111 | git clone https://github.com/a-bonus/google-docs-mcp.git mcp-googledocs-server
112 | ```
113 | 2. **Navigate into Directory:**
114 | ```bash
115 | cd mcp-googledocs-server
116 | ```
117 | 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.
118 |
119 | ### Step 3: Install Dependencies
120 |
121 | Your server needs some helper libraries specified in the `package.json` file.
122 |
123 | 1. In your terminal (make sure you are inside the `mcp-googledocs-server` directory), run:
124 | ```bash
125 | npm install
126 | ```
127 | This will download and install all the necessary packages into a `node_modules` folder.
128 |
129 | ### Step 4: Build the Server Code
130 |
131 | The server is written in TypeScript (`.ts`), but we need to compile it into JavaScript (`.js`) that Node.js can run directly.
132 |
133 | 1. In your terminal, run:
134 | ```bash
135 | npm run build
136 | ```
137 | This uses the TypeScript compiler (`tsc`) to create a `dist` folder containing the compiled JavaScript files.
138 |
139 | ### Step 5: First Run & Google Authorization (One Time Only)
140 |
141 | 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.
142 |
143 | 1. In your terminal, run the _compiled_ server using `node`:
144 | ```bash
145 | node ./dist/server.js
146 | ```
147 | 2. **Watch the Terminal:** The script will print:
148 | - Status messages (like "Attempting to authorize...").
149 | - An "Authorize this app by visiting this url:" message followed by a long `https://accounts.google.com/...` URL.
150 | 3. **Authorize in Browser:**
151 | - Copy the entire long URL from the terminal.
152 | - Paste the URL into your web browser and press Enter.
153 | - Log in with the **same Google account** you added as a Test User in Step 1.4.
154 | - 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**".
155 | 4. **Get the Authorization Code:**
156 | - 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!**
157 | - Look **carefully** at the URL in your browser's address bar. It will look like `http://localhost/?code=4/0Axxxxxxxxxxxxxx&scope=...`
158 | - Copy the long string of characters **between `code=` and the `&scope` part**. This is your single-use authorization code.
159 | 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.
160 | 6. **Press Enter.**
161 | 7. **Success!** The script should print:
162 | - "Authentication successful!"
163 | - "Token stored to .../token.json"
164 | - 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).
165 | 8. ✅ **Check:** You should now see a new file named `token.json` in your `mcp-googledocs-server` folder.
166 | 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.
167 |
168 | ### Step 6: Configure Claude Desktop (Optional)
169 |
170 | If you want to use this server with Claude Desktop, you need to tell Claude how to run it.
171 |
172 | 1. **Find Your Absolute Path:** You need the full path to the server code.
173 | - In your terminal, make sure you are still inside the `mcp-googledocs-server` directory.
174 | - Run the `pwd` command (on macOS/Linux) or `cd` (on Windows, just displays the path).
175 | - Copy the full path (e.g., `/Users/yourname/projects/mcp-googledocs-server` or `C:\Users\yourname\projects\mcp-googledocs-server`).
176 | 2. **Locate `mcp_config.json`:** Find Claude's configuration file:
177 | - **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/`)
178 | - **Windows:** `%APPDATA%\Claude\mcp_config.json` (Paste `%APPDATA%\Claude` into File Explorer's address bar)
179 | - **Linux:** `~/.config/Claude/mcp_config.json`
180 | - _If the `Claude` folder or `mcp_config.json` file doesn't exist, create them._
181 | 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**:
182 |
183 | ```json
184 | {
185 | "mcpServers": {
186 | "google-docs-mcp": {
187 | "command": "node",
188 | "args": [
189 | "/PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js"
190 | ],
191 | "env": {}
192 | }
193 | // Add commas here if you have other servers defined
194 | }
195 | // Other Claude settings might be here
196 | }
197 | ```
198 |
199 | - **Make sure the path in `"args"` is correct and absolute!**
200 | - If the file already existed, carefully merge this entry into the existing `mcpServers` object. Ensure the JSON is valid (check commas!).
201 |
202 | 4. **Save `mcp_config.json`.**
203 | 5. **Restart Claude Desktop:** Close Claude completely and reopen it.
204 |
205 | ---
206 |
207 | ## Usage with Claude Desktop
208 |
209 | Once configured, you should be able to use the tools in your chats with Claude:
210 |
211 | - "Use the `google-docs-mcp` server to read the document with ID `YOUR_GOOGLE_DOC_ID`."
212 | - "Can you get the content of Google Doc `YOUR_GOOGLE_DOC_ID`?"
213 | - "Append 'This was added by Claude!' to document `YOUR_GOOGLE_DOC_ID` using the `google-docs-mcp` tool."
214 |
215 | ### Advanced Usage Examples:
216 | - **Text Styling**: "Use `applyTextStyle` to make the text 'Important Section' bold and red (#FF0000) in document `YOUR_GOOGLE_DOC_ID`."
217 | - **Paragraph Styling**: "Use `applyParagraphStyle` to center-align the paragraph containing 'Title Here' in document `YOUR_GOOGLE_DOC_ID`."
218 | - **Table Creation**: "Insert a 3x4 table at index 500 in document `YOUR_GOOGLE_DOC_ID` using the `insertTable` tool."
219 | - **Image Insertion**: "Use `insertImageFromUrl` to insert an image from 'https://example.com/image.png' at index 100 in document `YOUR_GOOGLE_DOC_ID`."
220 | - **Local Image Upload**: "Use `insertLocalImage` to upload '/path/to/image.jpg' and insert it at index 200 in document `YOUR_GOOGLE_DOC_ID`."
221 | - **Legacy Formatting**: "Use `formatMatchingText` to find the second instance of 'Project Alpha' and make it blue (#0000FF) in doc `YOUR_GOOGLE_DOC_ID`."
222 |
223 | Remember to replace `YOUR_GOOGLE_DOC_ID` with the actual ID from a Google Doc's URL (the long string between `/d/` and `/edit`).
224 |
225 | 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.
226 |
227 | ---
228 |
229 | ## Image Insertion
230 |
231 | This server provides two ways to insert images into Google Documents:
232 |
233 | ### 1. Insert from Public URL (`insertImageFromUrl`)
234 |
235 | Inserts an image directly from a publicly accessible URL. The image URL must be accessible without authentication.
236 |
237 | **Parameters:**
238 | - `documentId`: The Google Document ID
239 | - `imageUrl`: Publicly accessible URL (http:// or https://)
240 | - `index`: Position in the document (1-based indexing)
241 | - `width` (optional): Image width in points
242 | - `height` (optional): Image height in points
243 |
244 | **Example:**
245 | ```
246 | "Insert an image from https://example.com/logo.png at index 100 in document YOUR_DOC_ID"
247 | ```
248 |
249 | ### 2. Upload Local Image (`insertLocalImage`)
250 |
251 | Uploads a local image file to Google Drive and inserts it into the document. This is a two-step process that:
252 | 1. Uploads the image to Google Drive (by default to the same folder as the document)
253 | 2. Makes the image publicly readable
254 | 3. Inserts the image into the document using its Drive URL
255 |
256 | **Parameters:**
257 | - `documentId`: The Google Document ID
258 | - `localImagePath`: Absolute path to the local image file
259 | - `index`: Position in the document (1-based indexing)
260 | - `width` (optional): Image width in points
261 | - `height` (optional): Image height in points
262 | - `uploadToSameFolder` (optional, default: true): If true, uploads to the document's folder; if false, uploads to Drive root
263 |
264 | **Supported formats:** .jpg, .jpeg, .png, .gif, .bmp, .webp, .svg
265 |
266 | **Example:**
267 | ```
268 | "Upload and insert the image at /Users/myname/Pictures/chart.png at index 200 in document YOUR_DOC_ID with width 400 and height 300"
269 | ```
270 |
271 | **Note:** The uploaded image will be made publicly readable so it can be displayed in the document. The image file will remain in your Google Drive and can be managed separately.
272 |
273 | ---
274 |
275 | ## Security & Token Storage
276 |
277 | - **`.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`**.
278 | - **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.
279 |
280 | ---
281 |
282 | ## Troubleshooting
283 |
284 | - **Claude shows "Failed" or "Could not attach":**
285 | - Double-check the absolute path in `mcp_config.json`.
286 | - Ensure you ran `npm run build` successfully and the `dist` folder exists.
287 | - 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.
288 | - Check the Claude Desktop logs (see the official MCP debugging guide).
289 | - Make sure all `console.log` status messages in the server code were changed to `console.error`.
290 | - **Google Authorization Errors:**
291 | - Ensure you enabled the correct APIs (Docs, Drive).
292 | - Make sure you added your email as a Test User on the OAuth Consent Screen.
293 | - Verify the `credentials.json` file is correctly placed in the project root.
294 |
295 | ---
296 |
297 | ## License
298 |
299 | 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).
300 |
```
--------------------------------------------------------------------------------
/claude.md:
--------------------------------------------------------------------------------
```markdown
1 | Okay, this is a significant undertaking. Building the "absolute best" server involves adding many complex features. I will provide:
2 | The full code for a substantially enhanced server.ts and the necessary new helper files (googleDocsApiHelpers.ts, types.ts). This code will include implementations for several key advanced features discussed and well-defined stubs for others, indicating where further development would go.
3 | Step-by-step instructions on how to integrate this new code into your existing project structure.
4 | Disclaimer: This code is extensive and demonstrates the structure and approach for advanced features. It includes implementations for key examples but leaves many others as stubs (// TODO: Implement... or throwing NotImplementedError). Thorough testing and potentially significant refinement would be needed for production use, especially for complex logic like fixListFormatting or robust index handling across multiple edits. Error handling is included but could be further enhanced.
5 | Phase 1: The Code
6 |
7 | 1. New File: src/types.ts
8 | // src/types.ts
9 | import { z } from 'zod';
10 | import { docs_v1 } from 'googleapis';
11 |
12 | // --- Helper function for hex color validation ---
13 | export const hexColorRegex = /^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/;
14 | export const validateHexColor = (color: string) => hexColorRegex.test(color);
15 |
16 | // --- Helper function for Hex to RGB conversion ---
17 | export function hexToRgbColor(hex: string): docs_v1.Schema$RgbColor | null {
18 | if (!hex) return null;
19 | let hexClean = hex.startsWith('#') ? hex.slice(1) : hex;
20 |
21 | if (hexClean.length === 3) {
22 | hexClean = hexClean[0] + hexClean[0] + hexClean[1] + hexClean[1] + hexClean[2] + hexClean[2];
23 | }
24 | if (hexClean.length !== 6) return null;
25 | const bigint = parseInt(hexClean, 16);
26 | if (isNaN(bigint)) return null;
27 |
28 | const r = ((bigint >> 16) & 255) / 255;
29 | const g = ((bigint >> 8) & 255) / 255;
30 | const b = (bigint & 255) / 255;
31 |
32 | return { red: r, green: g, blue: b };
33 | }
34 |
35 | // --- Zod Schema Fragments for Reusability ---
36 |
37 | export const DocumentIdParameter = z.object({
38 | documentId: z.string().describe('The ID of the Google Document (from the URL).'),
39 | });
40 |
41 | export const RangeParameters = z.object({
42 | startIndex: z.number().int().min(1).describe('The starting index of the text range (inclusive, starts from 1).'),
43 | endIndex: z.number().int().min(1).describe('The ending index of the text range (exclusive).'),
44 | }).refine(data => data.endIndex > data.startIndex, {
45 | message: "endIndex must be greater than startIndex",
46 | path: ["endIndex"],
47 | });
48 |
49 | export const OptionalRangeParameters = z.object({
50 | 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.'),
51 | 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.'),
52 | }).refine(data => !data.startIndex || !data.endIndex || data.endIndex > data.startIndex, {
53 | message: "If both startIndex and endIndex are provided, endIndex must be greater than startIndex",
54 | path: ["endIndex"],
55 | });
56 |
57 | export const TextFindParameter = z.object({
58 | textToFind: z.string().min(1).describe('The exact text string to locate.'),
59 | matchInstance: z.number().int().min(1).optional().default(1).describe('Which instance of the text to target (1st, 2nd, etc.). Defaults to 1.'),
60 | });
61 |
62 | // --- Style Parameter Schemas ---
63 |
64 | export const TextStyleParameters = z.object({
65 | bold: z.boolean().optional().describe('Apply bold formatting.'),
66 | italic: z.boolean().optional().describe('Apply italic formatting.'),
67 | underline: z.boolean().optional().describe('Apply underline formatting.'),
68 | strikethrough: z.boolean().optional().describe('Apply strikethrough formatting.'),
69 | fontSize: z.number().min(1).optional().describe('Set font size (in points, e.g., 12).'),
70 | fontFamily: z.string().optional().describe('Set font family (e.g., "Arial", "Times New Roman").'),
71 | foregroundColor: z.string()
72 | .refine(validateHexColor, { message: "Invalid hex color format (e.g., #FF0000 or #F00)" })
73 | .optional()
74 | .describe('Set text color using hex format (e.g., "#FF0000").'),
75 | backgroundColor: z.string()
76 | .refine(validateHexColor, { message: "Invalid hex color format (e.g., #00FF00 or #0F0)" })
77 | .optional()
78 | .describe('Set text background color using hex format (e.g., "#FFFF00").'),
79 | linkUrl: z.string().url().optional().describe('Make the text a hyperlink pointing to this URL.'),
80 | // 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
81 | }).describe("Parameters for character-level text formatting.");
82 |
83 | // Subset of TextStyle used for passing to helpers
84 | export type TextStyleArgs = z.infer<typeof TextStyleParameters>;
85 |
86 | export const ParagraphStyleParameters = z.object({
87 | alignment: z.enum(['LEFT', 'CENTER', 'RIGHT', 'JUSTIFIED']).optional().describe('Paragraph alignment.'),
88 | indentStart: z.number().min(0).optional().describe('Left indentation in points.'),
89 | indentEnd: z.number().min(0).optional().describe('Right indentation in points.'),
90 | spaceAbove: z.number().min(0).optional().describe('Space before the paragraph in points.'),
91 | spaceBelow: z.number().min(0).optional().describe('Space after the paragraph in points.'),
92 | namedStyleType: z.enum([
93 | 'NORMAL_TEXT', 'TITLE', 'SUBTITLE',
94 | 'HEADING_1', 'HEADING_2', 'HEADING_3', 'HEADING_4', 'HEADING_5', 'HEADING_6'
95 | ]).optional().describe('Apply a built-in named paragraph style (e.g., HEADING_1).'),
96 | keepWithNext: z.boolean().optional().describe('Keep this paragraph together with the next one on the same page.'),
97 | // Borders are more complex, might need separate objects/tools
98 | // 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
99 | }).describe("Parameters for paragraph-level formatting.");
100 |
101 | // Subset of ParagraphStyle used for passing to helpers
102 | export type ParagraphStyleArgs = z.infer<typeof ParagraphStyleParameters>;
103 |
104 | // --- Combination Schemas for Tools ---
105 |
106 | export const ApplyTextStyleToolParameters = DocumentIdParameter.extend({
107 | // Target EITHER by range OR by finding text
108 | target: z.union([
109 | RangeParameters,
110 | TextFindParameter
111 | ]).describe("Specify the target range either by start/end indices or by finding specific text."),
112 | style: TextStyleParameters.refine(
113 | styleArgs => Object.values(styleArgs).some(v => v !== undefined),
114 | { message: "At least one text style option must be provided." }
115 | ).describe("The text styling to apply.")
116 | });
117 | export type ApplyTextStyleToolArgs = z.infer<typeof ApplyTextStyleToolParameters>;
118 |
119 | export const ApplyParagraphStyleToolParameters = DocumentIdParameter.extend({
120 | // Target EITHER by range OR by finding text (tool logic needs to find paragraph boundaries)
121 | target: z.union([
122 | RangeParameters, // User provides paragraph start/end (less likely)
123 | TextFindParameter.extend({
124 | applyToContainingParagraph: z.literal(true).default(true).describe("Must be true. Indicates the style applies to the whole paragraph containing the found text.")
125 | }),
126 | z.object({ // Target by specific index within the paragraph
127 | indexWithinParagraph: z.number().int().min(1).describe("An index located anywhere within the target paragraph.")
128 | })
129 | ]).describe("Specify the target paragraph either by start/end indices, by finding text within it, or by providing an index within it."),
130 | style: ParagraphStyleParameters.refine(
131 | styleArgs => Object.values(styleArgs).some(v => v !== undefined),
132 | { message: "At least one paragraph style option must be provided." }
133 | ).describe("The paragraph styling to apply.")
134 | });
135 | export type ApplyParagraphStyleToolArgs = z.infer<typeof ApplyParagraphStyleToolParameters>;
136 |
137 | // --- Error Class ---
138 | // Use FastMCP's UserError for client-facing issues
139 | // Define a custom error for internal issues if needed
140 | export class NotImplementedError extends Error {
141 | constructor(message = "This feature is not yet implemented.") {
142 | super(message);
143 | this.name = "NotImplementedError";
144 | }
145 | }
146 | Use code with caution.
147 | TypeScript 2. New File: src/googleDocsApiHelpers.ts
148 | // src/googleDocsApiHelpers.ts
149 | import { google, docs_v1 } from 'googleapis';
150 | import { OAuth2Client } from 'google-auth-library';
151 | import { UserError } from 'fastmcp';
152 | import { TextStyleArgs, ParagraphStyleArgs, hexToRgbColor, NotImplementedError } from './types.js';
153 |
154 | type Docs = docs_v1.Docs; // Alias for convenience
155 |
156 | // --- Constants ---
157 | const MAX_BATCH_UPDATE_REQUESTS = 50; // Google API limits batch size
158 |
159 | // --- Core Helper to Execute Batch Updates ---
160 | export async function executeBatchUpdate(docs: Docs, documentId: string, requests: docs_v1.Schema$Request[]): Promise<docs_v1.Schema$BatchUpdateDocumentResponse> {
161 | if (!requests || requests.length === 0) {
162 | // console.warn("executeBatchUpdate called with no requests.");
163 | return {}; // Nothing to do
164 | }
165 |
166 | // TODO: Consider splitting large request arrays into multiple batches if needed
167 | if (requests.length > MAX_BATCH_UPDATE_REQUESTS) {
168 | console.warn(`Attempting batch update with ${requests.length} requests, exceeding typical limits. May fail.`);
169 | }
170 |
171 | try {
172 | const response = await docs.documents.batchUpdate({
173 | documentId: documentId,
174 | requestBody: { requests },
175 | });
176 | return response.data;
177 | } catch (error: any) {
178 | console.error(`Google API batchUpdate Error for doc ${documentId}:`, error.response?.data || error.message);
179 | // Translate common API errors to UserErrors
180 | if (error.code === 400 && error.message.includes('Invalid requests')) {
181 | // Try to extract more specific info if available
182 | const details = error.response?.data?.error?.details;
183 | let detailMsg = '';
184 | if (details && Array.isArray(details)) {
185 | detailMsg = details.map(d => d.description || JSON.stringify(d)).join('; ');
186 | }
187 | throw new UserError(`Invalid request sent to Google Docs API. Details: ${detailMsg || error.message}`);
188 | }
189 | if (error.code === 404) throw new UserError(`Document not found (ID: ${documentId}). Check the ID.`);
190 | if (error.code === 403) throw new UserError(`Permission denied for document (ID: ${documentId}). Ensure the authenticated user has edit access.`);
191 | // Generic internal error for others
192 | throw new Error(`Google API Error (${error.code}): ${error.message}`);
193 | }
194 |
195 | }
196 |
197 | // --- Text Finding Helper ---
198 | // NOTE: This is a simplified version. A robust version needs to handle
199 | // text spanning multiple TextRuns, pagination, tables etc.
200 | export async function findTextRange(docs: Docs, documentId: string, textToFind: string, instance: number = 1): Promise<{ startIndex: number; endIndex: number } | null> {
201 | try {
202 | const res = await docs.documents.get({
203 | documentId,
204 | fields: 'body(content(paragraph(elements(startIndex,endIndex,textRun(content)))))',
205 | });
206 |
207 | if (!res.data.body?.content) return null;
208 |
209 | let fullText = '';
210 | const segments: { text: string, start: number, end: number }[] = [];
211 | res.data.body.content.forEach(element => {
212 | element.paragraph?.elements?.forEach(pe => {
213 | if (pe.textRun?.content && pe.startIndex && pe.endIndex) {
214 | const content = pe.textRun.content;
215 | fullText += content;
216 | segments.push({ text: content, start: pe.startIndex, end: pe.endIndex });
217 | }
218 | });
219 | });
220 |
221 | let startIndex = -1;
222 | let endIndex = -1;
223 | let foundCount = 0;
224 | let searchStartIndex = 0;
225 |
226 | while (foundCount < instance) {
227 | const currentIndex = fullText.indexOf(textToFind, searchStartIndex);
228 | if (currentIndex === -1) break;
229 |
230 | foundCount++;
231 | if (foundCount === instance) {
232 | const targetStartInFullText = currentIndex;
233 | const targetEndInFullText = currentIndex + textToFind.length;
234 | let currentPosInFullText = 0;
235 |
236 | for (const seg of segments) {
237 | const segStartInFullText = currentPosInFullText;
238 | const segTextLength = seg.text.length;
239 | const segEndInFullText = segStartInFullText + segTextLength;
240 |
241 | if (startIndex === -1 && targetStartInFullText >= segStartInFullText && targetStartInFullText < segEndInFullText) {
242 | startIndex = seg.start + (targetStartInFullText - segStartInFullText);
243 | }
244 | if (targetEndInFullText > segStartInFullText && targetEndInFullText <= segEndInFullText) {
245 | endIndex = seg.start + (targetEndInFullText - segStartInFullText);
246 | break;
247 | }
248 | currentPosInFullText = segEndInFullText;
249 | }
250 |
251 | if (startIndex === -1 || endIndex === -1) { // Mapping failed for this instance
252 | startIndex = -1; endIndex = -1;
253 | // Continue searching from *after* this failed mapping attempt
254 | searchStartIndex = currentIndex + 1;
255 | foundCount--; // Decrement count as this instance wasn't successfully mapped
256 | continue;
257 | }
258 | // Successfully mapped
259 | return { startIndex, endIndex };
260 | }
261 | // Prepare for next search iteration
262 | searchStartIndex = currentIndex + 1;
263 | }
264 |
265 | return null; // Instance not found or mapping failed for all attempts
266 | } catch (error: any) {
267 | console.error(`Error finding text "${textToFind}" in doc ${documentId}: ${error.message}`);
268 | if (error.code === 404) throw new UserError(`Document not found while searching text (ID: ${documentId}).`);
269 | if (error.code === 403) throw new UserError(`Permission denied while searching text in doc (ID: ${documentId}).`);
270 | throw new Error(`Failed to retrieve doc for text searching: ${error.message}`);
271 | }
272 |
273 | }
274 |
275 | // --- Paragraph Boundary Helper ---
276 | // Finds the paragraph containing a given index. Very simplified.
277 | // A robust version needs to understand structural elements better.
278 | export async function getParagraphRange(docs: Docs, documentId: string, indexWithin: number): Promise<{ startIndex: number; endIndex: number } | null> {
279 | try {
280 | const res = await docs.documents.get({
281 | documentId,
282 | // Request paragraph elements and their ranges
283 | fields: 'body(content(startIndex,endIndex,paragraph))',
284 | });
285 |
286 | if (!res.data.body?.content) return null;
287 |
288 | for (const element of res.data.body.content) {
289 | if (element.paragraph && element.startIndex && element.endIndex) {
290 | // Check if the provided index falls within this paragraph element's range
291 | // API ranges are typically [startIndex, endIndex)
292 | if (indexWithin >= element.startIndex && indexWithin < element.endIndex) {
293 | return { startIndex: element.startIndex, endIndex: element.endIndex };
294 | }
295 | }
296 | }
297 | return null; // Index not found within any paragraph element
298 |
299 | } catch (error: any) {
300 | console.error(`Error getting paragraph range for index ${indexWithin} in doc ${documentId}: ${error.message}`);
301 | if (error.code === 404) throw new UserError(`Document not found while finding paragraph range (ID: ${documentId}).`);
302 | if (error.code === 403) throw new UserError(`Permission denied while finding paragraph range in doc (ID: ${documentId}).`);
303 | throw new Error(`Failed to retrieve doc for paragraph range finding: ${error.message}`);
304 | }
305 |
306 | }
307 |
308 | // --- Style Request Builders ---
309 |
310 | export function buildUpdateTextStyleRequest(
311 | startIndex: number,
312 | endIndex: number,
313 | style: TextStyleArgs
314 | ): { request: docs_v1.Schema$Request, fields: string[] } | null {
315 | const textStyle: docs_v1.Schema$TextStyle = {};
316 | const fieldsToUpdate: string[] = [];
317 |
318 | if (style.bold !== undefined) { textStyle.bold = style.bold; fieldsToUpdate.push('bold'); }
319 | if (style.italic !== undefined) { textStyle.italic = style.italic; fieldsToUpdate.push('italic'); }
320 | if (style.underline !== undefined) { textStyle.underline = style.underline; fieldsToUpdate.push('underline'); }
321 | if (style.strikethrough !== undefined) { textStyle.strikethrough = style.strikethrough; fieldsToUpdate.push('strikethrough'); }
322 | if (style.fontSize !== undefined) { textStyle.fontSize = { magnitude: style.fontSize, unit: 'PT' }; fieldsToUpdate.push('fontSize'); }
323 | if (style.fontFamily !== undefined) { textStyle.weightedFontFamily = { fontFamily: style.fontFamily }; fieldsToUpdate.push('weightedFontFamily'); }
324 | if (style.foregroundColor !== undefined) {
325 | const rgbColor = hexToRgbColor(style.foregroundColor);
326 | if (!rgbColor) throw new UserError(`Invalid foreground hex color format: ${style.foregroundColor}`);
327 | textStyle.foregroundColor = { color: { rgbColor: rgbColor } }; fieldsToUpdate.push('foregroundColor');
328 | }
329 | if (style.backgroundColor !== undefined) {
330 | const rgbColor = hexToRgbColor(style.backgroundColor);
331 | if (!rgbColor) throw new UserError(`Invalid background hex color format: ${style.backgroundColor}`);
332 | textStyle.backgroundColor = { color: { rgbColor: rgbColor } }; fieldsToUpdate.push('backgroundColor');
333 | }
334 | if (style.linkUrl !== undefined) {
335 | textStyle.link = { url: style.linkUrl }; fieldsToUpdate.push('link');
336 | }
337 | // TODO: Handle clearing formatting
338 |
339 | if (fieldsToUpdate.length === 0) return null; // No styles to apply
340 |
341 | const request: docs_v1.Schema$Request = {
342 | updateTextStyle: {
343 | range: { startIndex, endIndex },
344 | textStyle: textStyle,
345 | fields: fieldsToUpdate.join(','),
346 | }
347 | };
348 | return { request, fields: fieldsToUpdate };
349 |
350 | }
351 |
352 | export function buildUpdateParagraphStyleRequest(
353 | startIndex: number,
354 | endIndex: number,
355 | style: ParagraphStyleArgs
356 | ): { request: docs_v1.Schema$Request, fields: string[] } | null {
357 | const paragraphStyle: docs_v1.Schema$ParagraphStyle = {};
358 | const fieldsToUpdate: string[] = [];
359 |
360 | if (style.alignment !== undefined) { paragraphStyle.alignment = style.alignment; fieldsToUpdate.push('alignment'); }
361 | if (style.indentStart !== undefined) { paragraphStyle.indentStart = { magnitude: style.indentStart, unit: 'PT' }; fieldsToUpdate.push('indentStart'); }
362 | if (style.indentEnd !== undefined) { paragraphStyle.indentEnd = { magnitude: style.indentEnd, unit: 'PT' }; fieldsToUpdate.push('indentEnd'); }
363 | if (style.spaceAbove !== undefined) { paragraphStyle.spaceAbove = { magnitude: style.spaceAbove, unit: 'PT' }; fieldsToUpdate.push('spaceAbove'); }
364 | if (style.spaceBelow !== undefined) { paragraphStyle.spaceBelow = { magnitude: style.spaceBelow, unit: 'PT' }; fieldsToUpdate.push('spaceBelow'); }
365 | if (style.namedStyleType !== undefined) { paragraphStyle.namedStyleType = style.namedStyleType; fieldsToUpdate.push('namedStyleType'); }
366 | if (style.keepWithNext !== undefined) { paragraphStyle.keepWithNext = style.keepWithNext; fieldsToUpdate.push('keepWithNext'); }
367 | // TODO: Handle borders, clearing formatting
368 |
369 | if (fieldsToUpdate.length === 0) return null; // No styles to apply
370 |
371 | const request: docs_v1.Schema$Request = {
372 | updateParagraphStyle: {
373 | range: { startIndex, endIndex },
374 | paragraphStyle: paragraphStyle,
375 | fields: fieldsToUpdate.join(','),
376 | }
377 | };
378 | return { request, fields: fieldsToUpdate };
379 |
380 | }
381 |
382 | // --- Specific Feature Helpers ---
383 |
384 | export async function createTable(docs: Docs, documentId: string, rows: number, columns: number, index: number): Promise<docs_v1.Schema$BatchUpdateDocumentResponse> {
385 | if (rows < 1 || columns < 1) {
386 | throw new UserError("Table must have at least 1 row and 1 column.");
387 | }
388 | const request: docs_v1.Schema$Request = {
389 | insertTable: {
390 | location: { index },
391 | rows: rows,
392 | columns: columns,
393 | }
394 | };
395 | return executeBatchUpdate(docs, documentId, [request]);
396 | }
397 |
398 | export async function insertText(docs: Docs, documentId: string, text: string, index: number): Promise<docs_v1.Schema$BatchUpdateDocumentResponse> {
399 | if (!text) return {}; // Nothing to insert
400 | const request: docs_v1.Schema$Request = {
401 | insertText: {
402 | location: { index },
403 | text: text,
404 | }
405 | };
406 | return executeBatchUpdate(docs, documentId, [request]);
407 | }
408 |
409 | // --- Complex / Stubbed Helpers ---
410 |
411 | export async function findParagraphsMatchingStyle(
412 | docs: Docs,
413 | documentId: string,
414 | styleCriteria: any // Define a proper type for criteria (e.g., { fontFamily: 'Arial', bold: true })
415 | ): Promise<{ startIndex: number; endIndex: number }[]> {
416 | // TODO: Implement logic
417 | // 1. Get document content with paragraph elements and their styles.
418 | // 2. Iterate through paragraphs.
419 | // 3. For each paragraph, check if its computed style matches the criteria.
420 | // 4. Return ranges of matching paragraphs.
421 | console.warn("findParagraphsMatchingStyle is not implemented.");
422 | throw new NotImplementedError("Finding paragraphs by style criteria is not yet implemented.");
423 | // return [];
424 | }
425 |
426 | export async function detectAndFormatLists(
427 | docs: Docs,
428 | documentId: string,
429 | startIndex?: number,
430 | endIndex?: number
431 | ): Promise<docs_v1.Schema$BatchUpdateDocumentResponse> {
432 | // TODO: Implement complex logic
433 | // 1. Get document content (paragraphs, text runs) in the specified range (or whole doc).
434 | // 2. Iterate through paragraphs.
435 | // 3. Identify sequences of paragraphs starting with list-like markers (e.g., "-", "\*", "1.", "a)").
436 | // 4. Determine nesting levels based on indentation or marker patterns.
437 | // 5. Generate CreateParagraphBulletsRequests for the identified sequences.
438 | // 6. Potentially delete the original marker text.
439 | // 7. Execute the batch update.
440 | console.warn("detectAndFormatLists is not implemented.");
441 | throw new NotImplementedError("Automatic list detection and formatting is not yet implemented.");
442 | // return {};
443 | }
444 |
445 | export async function addCommentHelper(docs: Docs, documentId: string, text: string, startIndex: number, endIndex: number): Promise<void> {
446 | // NOTE: Adding comments typically requires the Google Drive API v3 and different scopes!
447 | // 'https://www.googleapis.com/auth/drive' or more specific comment scopes.
448 | // This helper is a placeholder assuming Drive API client (`drive`) is available and authorized.
449 | /_
450 | const drive = google.drive({version: 'v3', auth: authClient}); // Assuming authClient is available
451 | await drive.comments.create({
452 | fileId: documentId,
453 | requestBody: {
454 | content: text,
455 | anchor: JSON.stringify({ // Anchor format might need verification
456 | 'type': 'workbook#textAnchor', // Or appropriate type for Docs
457 | 'refs': [{
458 | 'docRevisionId': 'head', // Or specific revision
459 | 'range': {
460 | 'start': startIndex,
461 | 'end': endIndex,
462 | }
463 | }]
464 | })
465 | },
466 | fields: 'id'
467 | });
468 | _/
469 | console.warn("addCommentHelper requires Google Drive API and is not implemented.");
470 | throw new NotImplementedError("Adding comments requires Drive API setup and is not yet implemented.");
471 | }
472 |
473 | // Add more helpers as needed...
474 | Use code with caution.
475 | TypeScript 3. Updated File: src/server.ts (Replace the entire content with this)
476 | // src/server.ts
477 | import { FastMCP, UserError } from 'fastmcp';
478 | import { z } from 'zod';
479 | import { google, docs_v1 } from 'googleapis';
480 | import { authorize } from './auth.js';
481 | import { OAuth2Client } from 'google-auth-library';
482 |
483 | // Import types and helpers
484 | import {
485 | DocumentIdParameter,
486 | RangeParameters,
487 | OptionalRangeParameters,
488 | TextFindParameter,
489 | TextStyleParameters,
490 | TextStyleArgs,
491 | ParagraphStyleParameters,
492 | ParagraphStyleArgs,
493 | ApplyTextStyleToolParameters, ApplyTextStyleToolArgs,
494 | ApplyParagraphStyleToolParameters, ApplyParagraphStyleToolArgs,
495 | NotImplementedError
496 | } from './types.js';
497 | import \* as GDocsHelpers from './googleDocsApiHelpers.js';
498 |
499 | let authClient: OAuth2Client | null = null;
500 | let googleDocs: docs_v1.Docs | null = null;
501 |
502 | // --- Initialization ---
503 | async function initializeGoogleClient() {
504 | if (googleDocs) return { authClient, googleDocs };
505 | if (!authClient) { // Check authClient instead of googleDocs to allow re-attempt
506 | try {
507 | console.error("Attempting to authorize Google API client...");
508 | const client = await authorize();
509 | authClient = client; // Assign client here
510 | googleDocs = google.docs({ version: 'v1', auth: authClient });
511 | console.error("Google API client authorized successfully.");
512 | } catch (error) {
513 | console.error("FATAL: Failed to initialize Google API client:", error);
514 | authClient = null; // Reset on failure
515 | googleDocs = null;
516 | // Decide if server should exit or just fail tools
517 | throw new Error("Google client initialization failed. Cannot start server tools.");
518 | }
519 | }
520 | // Ensure googleDocs is set if authClient is valid
521 | if (authClient && !googleDocs) {
522 | googleDocs = google.docs({ version: 'v1', auth: authClient });
523 | }
524 |
525 | if (!googleDocs) {
526 | throw new Error("Google Docs client could not be initialized.");
527 | }
528 |
529 | return { authClient, googleDocs };
530 | }
531 |
532 | const server = new FastMCP({
533 | name: 'Ultimate Google Docs MCP Server',
534 | version: '2.0.0', // Version bump!
535 | description: 'Provides advanced tools for reading, editing, formatting, and managing Google Documents.'
536 | });
537 |
538 | // --- Helper to get Docs client within tools ---
539 | async function getDocsClient() {
540 | const { googleDocs: docs } = await initializeGoogleClient();
541 | if (!docs) {
542 | throw new UserError("Google Docs client is not initialized. Authentication might have failed during startup or lost connection.");
543 | }
544 | return docs;
545 | }
546 |
547 | // === TOOL DEFINITIONS ===
548 |
549 | // --- Foundational Tools ---
550 |
551 | server.addTool({
552 | name: 'readGoogleDoc',
553 | description: 'Reads the content of a specific Google Document, optionally returning structured data.',
554 | parameters: DocumentIdParameter.extend({
555 | format: z.enum(['text', 'json', 'markdown']).optional().default('text')
556 | .describe("Output format: 'text' (plain text, possibly truncated), 'json' (raw API structure, complex), 'markdown' (experimental conversion).")
557 | }),
558 | execute: async (args, { log }) => {
559 | const docs = await getDocsClient();
560 | log.info(`Reading Google Doc: ${args.documentId}, Format: ${args.format}`);
561 |
562 | try {
563 | const fields = args.format === 'json' || args.format === 'markdown'
564 | ? '*' // Get everything for structure analysis
565 | : 'body(content(paragraph(elements(textRun(content)))))'; // Just text content
566 |
567 | const res = await docs.documents.get({
568 | documentId: args.documentId,
569 | fields: fields,
570 | });
571 | log.info(`Fetched doc: ${args.documentId}`);
572 |
573 | if (args.format === 'json') {
574 | return JSON.stringify(res.data, null, 2); // Return raw structure
575 | }
576 |
577 | if (args.format === 'markdown') {
578 | // TODO: Implement Markdown conversion logic (complex)
579 | log.warn("Markdown conversion is not implemented yet.");
580 | throw new NotImplementedError("Markdown output format is not yet implemented.");
581 | // return convertDocsJsonToMarkdown(res.data);
582 | }
583 |
584 | // Default: Text format
585 | let textContent = '';
586 | res.data.body?.content?.forEach(element => {
587 | element.paragraph?.elements?.forEach(pe => {
588 | textContent += pe.textRun?.content || '';
589 | });
590 | });
591 |
592 | if (!textContent.trim()) return "Document found, but appears empty.";
593 |
594 | // Basic truncation for text mode
595 | const maxLength = 4000; // Increased limit
596 | const truncatedContent = textContent.length > maxLength ? textContent.substring(0, maxLength) + `... [truncated ${textContent.length} chars]` : textContent;
597 | return `Content:\n---\n${truncatedContent}`;
598 |
599 | } catch (error: any) {
600 | log.error(`Error reading doc ${args.documentId}: ${error.message || error}`);
601 | // Handle errors thrown by helpers or API directly
602 | if (error instanceof UserError) throw error;
603 | if (error instanceof NotImplementedError) throw error;
604 | // Generic fallback for API errors not caught by helpers
605 | if (error.code === 404) throw new UserError(`Doc not found (ID: ${args.documentId}).`);
606 | if (error.code === 403) throw new UserError(`Permission denied for doc (ID: ${args.documentId}).`);
607 | throw new UserError(`Failed to read doc: ${error.message || 'Unknown error'}`);
608 | }
609 |
610 | },
611 | });
612 |
613 | server.addTool({
614 | name: 'appendToGoogleDoc',
615 | description: 'Appends text to the very end of a specific Google Document.',
616 | parameters: DocumentIdParameter.extend({
617 | textToAppend: z.string().min(1).describe('The text to add to the end.'),
618 | addNewlineIfNeeded: z.boolean().optional().default(true).describe("Automatically add a newline before the appended text if the doc doesn't end with one."),
619 | }),
620 | execute: async (args, { log }) => {
621 | const docs = await getDocsClient();
622 | log.info(`Appending to Google Doc: ${args.documentId}`);
623 |
624 | try {
625 | // Get the current end index
626 | const docInfo = await docs.documents.get({ documentId: args.documentId, fields: 'body(content(endIndex)),documentStyle(pageSize)' }); // Need content for endIndex
627 | let endIndex = 1;
628 | let lastCharIsNewline = false;
629 | if (docInfo.data.body?.content) {
630 | const lastElement = docInfo.data.body.content[docInfo.data.body.content.length - 1];
631 | if (lastElement?.endIndex) {
632 | endIndex = lastElement.endIndex -1; // Insert *before* the final newline of the doc typically
633 | // Crude check for last character (better check would involve reading last text run)
634 | // const lastTextRun = ... find last text run ...
635 | // if (lastTextRun?.content?.endsWith('\n')) lastCharIsNewline = true;
636 | }
637 | }
638 | // Simpler approach: Always assume insertion is needed unless explicitly told not to add newline
639 | const textToInsert = (args.addNewlineIfNeeded && endIndex > 1 ? '\n' : '') + args.textToAppend;
640 |
641 | if (!textToInsert) return "Nothing to append.";
642 |
643 | const request: docs_v1.Schema$Request = { insertText: { location: { index: endIndex }, text: textToInsert } };
644 | await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
645 |
646 | log.info(`Successfully appended to doc: ${args.documentId}`);
647 | return `Successfully appended text to document ${args.documentId}.`;
648 | } catch (error: any) {
649 | log.error(`Error appending to doc ${args.documentId}: ${error.message || error}`);
650 | if (error instanceof UserError) throw error;
651 | if (error instanceof NotImplementedError) throw error;
652 | throw new UserError(`Failed to append to doc: ${error.message || 'Unknown error'}`);
653 | }
654 |
655 | },
656 | });
657 |
658 | server.addTool({
659 | name: 'insertText',
660 | description: 'Inserts text at a specific index within the document body.',
661 | parameters: DocumentIdParameter.extend({
662 | textToInsert: z.string().min(1).describe('The text to insert.'),
663 | index: z.number().int().min(1).describe('The index (1-based) where the text should be inserted.'),
664 | }),
665 | execute: async (args, { log }) => {
666 | const docs = await getDocsClient();
667 | log.info(`Inserting text in doc ${args.documentId} at index ${args.index}`);
668 | try {
669 | await GDocsHelpers.insertText(docs, args.documentId, args.textToInsert, args.index);
670 | return `Successfully inserted text at index ${args.index}.`;
671 | } catch (error: any) {
672 | log.error(`Error inserting text in doc ${args.documentId}: ${error.message || error}`);
673 | if (error instanceof UserError) throw error;
674 | throw new UserError(`Failed to insert text: ${error.message || 'Unknown error'}`);
675 | }
676 | }
677 | });
678 |
679 | server.addTool({
680 | name: 'deleteRange',
681 | description: 'Deletes content within a specified range (start index inclusive, end index exclusive).',
682 | parameters: DocumentIdParameter.extend(RangeParameters.shape), // Use shape to avoid refine conflict if needed
683 | execute: async (args, { log }) => {
684 | const docs = await getDocsClient();
685 | log.info(`Deleting range ${args.startIndex}-${args.endIndex} in doc ${args.documentId}`);
686 | if (args.endIndex <= args.startIndex) {
687 | throw new UserError("End index must be greater than start index for deletion.");
688 | }
689 | try {
690 | const request: docs_v1.Schema$Request = {
691 | deleteContentRange: {
692 | range: { startIndex: args.startIndex, endIndex: args.endIndex }
693 | }
694 | };
695 | await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
696 | return `Successfully deleted content in range ${args.startIndex}-${args.endIndex}.`;
697 | } catch (error: any) {
698 | log.error(`Error deleting range in doc ${args.documentId}: ${error.message || error}`);
699 | if (error instanceof UserError) throw error;
700 | throw new UserError(`Failed to delete range: ${error.message || 'Unknown error'}`);
701 | }
702 | }
703 | });
704 |
705 | // --- Advanced Formatting & Styling Tools ---
706 |
707 | server.addTool({
708 | name: 'applyTextStyle',
709 | description: 'Applies character-level formatting (bold, color, font, etc.) to a specific range or found text.',
710 | parameters: ApplyTextStyleToolParameters,
711 | execute: async (args: ApplyTextStyleToolArgs, { log }) => {
712 | const docs = await getDocsClient();
713 | let { startIndex, endIndex } = args.target as any; // Will be updated if target is text
714 |
715 | log.info(`Applying text style in doc ${args.documentId}. Target: ${JSON.stringify(args.target)}, Style: ${JSON.stringify(args.style)}`);
716 |
717 | try {
718 | // Determine target range
719 | if ('textToFind' in args.target) {
720 | const range = await GDocsHelpers.findTextRange(docs, args.documentId, args.target.textToFind, args.target.matchInstance);
721 | if (!range) {
722 | throw new UserError(`Could not find instance ${args.target.matchInstance} of text "${args.target.textToFind}".`);
723 | }
724 | startIndex = range.startIndex;
725 | endIndex = range.endIndex;
726 | log.info(`Found text "${args.target.textToFind}" (instance ${args.target.matchInstance}) at range ${startIndex}-${endIndex}`);
727 | }
728 |
729 | if (startIndex === undefined || endIndex === undefined) {
730 | throw new UserError("Target range could not be determined.");
731 | }
732 | if (endIndex <= startIndex) {
733 | throw new UserError("End index must be greater than start index for styling.");
734 | }
735 |
736 | // Build the request
737 | const requestInfo = GDocsHelpers.buildUpdateTextStyleRequest(startIndex, endIndex, args.style);
738 | if (!requestInfo) {
739 | return "No valid text styling options were provided.";
740 | }
741 |
742 | await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [requestInfo.request]);
743 | return `Successfully applied text style (${requestInfo.fields.join(', ')}) to range ${startIndex}-${endIndex}.`;
744 |
745 | } catch (error: any) {
746 | log.error(`Error applying text style in doc ${args.documentId}: ${error.message || error}`);
747 | if (error instanceof UserError) throw error;
748 | if (error instanceof NotImplementedError) throw error; // Should not happen here
749 | throw new UserError(`Failed to apply text style: ${error.message || 'Unknown error'}`);
750 | }
751 | }
752 |
753 | });
754 |
755 | server.addTool({
756 | name: 'applyParagraphStyle',
757 | description: 'Applies paragraph-level formatting (alignment, spacing, named styles like Heading 1) to the paragraph(s) containing specific text, an index, or a range.',
758 | parameters: ApplyParagraphStyleToolParameters,
759 | execute: async (args: ApplyParagraphStyleToolArgs, { log }) => {
760 | const docs = await getDocsClient();
761 | let { startIndex, endIndex } = args.target as any; // Will be updated
762 |
763 | log.info(`Applying paragraph style in doc ${args.documentId}. Target: ${JSON.stringify(args.target)}, Style: ${JSON.stringify(args.style)}`);
764 |
765 | try {
766 | // Determine target paragraph range
767 | let targetIndexForLookup: number | undefined;
768 |
769 | if ('textToFind' in args.target) {
770 | const range = await GDocsHelpers.findTextRange(docs, args.documentId, args.target.textToFind, args.target.matchInstance);
771 | if (!range) {
772 | throw new UserError(`Could not find instance ${args.target.matchInstance} of text "${args.target.textToFind}" to locate paragraph.`);
773 | }
774 | targetIndexForLookup = range.startIndex; // Use the start index of found text
775 | log.info(`Found text "${args.target.textToFind}" at index ${targetIndexForLookup} to locate paragraph.`);
776 | } else if ('indexWithinParagraph' in args.target) {
777 | targetIndexForLookup = args.target.indexWithinParagraph;
778 | } else if ('startIndex' in args.target && 'endIndex' in args.target) {
779 | // User provided a range, assume it's the paragraph range
780 | startIndex = args.target.startIndex;
781 | endIndex = args.target.endIndex;
782 | log.info(`Using provided range ${startIndex}-${endIndex} for paragraph style.`);
783 | }
784 |
785 | // If we need to find the paragraph boundaries based on an index within it
786 | if (targetIndexForLookup !== undefined && (startIndex === undefined || endIndex === undefined)) {
787 | const paragraphRange = await GDocsHelpers.getParagraphRange(docs, args.documentId, targetIndexForLookup);
788 | if (!paragraphRange) {
789 | throw new UserError(`Could not determine paragraph boundaries containing index ${targetIndexForLookup}.`);
790 | }
791 | startIndex = paragraphRange.startIndex;
792 | endIndex = paragraphRange.endIndex;
793 | log.info(`Determined paragraph range as ${startIndex}-${endIndex} based on index ${targetIndexForLookup}.`);
794 | }
795 |
796 |
797 | if (startIndex === undefined || endIndex === undefined) {
798 | throw new UserError("Target paragraph range could not be determined.");
799 | }
800 | if (endIndex <= startIndex) {
801 | throw new UserError("Paragraph end index must be greater than start index for styling.");
802 | }
803 |
804 | // Build the request
805 | const requestInfo = GDocsHelpers.buildUpdateParagraphStyleRequest(startIndex, endIndex, args.style);
806 | if (!requestInfo) {
807 | return "No valid paragraph styling options were provided.";
808 | }
809 |
810 | await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [requestInfo.request]);
811 | return `Successfully applied paragraph style (${requestInfo.fields.join(', ')}) to range ${startIndex}-${endIndex}.`;
812 |
813 | } catch (error: any) {
814 | log.error(`Error applying paragraph style in doc ${args.documentId}: ${error.message || error}`);
815 | if (error instanceof UserError) throw error;
816 | if (error instanceof NotImplementedError) throw error;
817 | throw new UserError(`Failed to apply paragraph style: ${error.message || 'Unknown error'}`);
818 | }
819 | }
820 |
821 | });
822 |
823 | // --- Structure & Content Tools ---
824 |
825 | server.addTool({
826 | name: 'insertTable',
827 | description: 'Inserts a new table with the specified dimensions at a given index.',
828 | parameters: DocumentIdParameter.extend({
829 | rows: z.number().int().min(1).describe('Number of rows for the new table.'),
830 | columns: z.number().int().min(1).describe('Number of columns for the new table.'),
831 | index: z.number().int().min(1).describe('The index (1-based) where the table should be inserted.'),
832 | }),
833 | execute: async (args, { log }) => {
834 | const docs = await getDocsClient();
835 | log.info(`Inserting ${args.rows}x${args.columns} table in doc ${args.documentId} at index ${args.index}`);
836 | try {
837 | await GDocsHelpers.createTable(docs, args.documentId, args.rows, args.columns, args.index);
838 | // The API response contains info about the created table, but might be too complex to return here.
839 | return `Successfully inserted a ${args.rows}x${args.columns} table at index ${args.index}.`;
840 | } catch (error: any) {
841 | log.error(`Error inserting table in doc ${args.documentId}: ${error.message || error}`);
842 | if (error instanceof UserError) throw error;
843 | throw new UserError(`Failed to insert table: ${error.message || 'Unknown error'}`);
844 | }
845 | }
846 | });
847 |
848 | server.addTool({
849 | name: 'editTableCell',
850 | description: 'Edits the content and/or basic style of a specific table cell. Requires knowing table start index.',
851 | parameters: DocumentIdParameter.extend({
852 | tableStartIndex: z.number().int().min(1).describe("The starting index of the TABLE element itself (tricky to find, may require reading structure first)."),
853 | rowIndex: z.number().int().min(0).describe("Row index (0-based)."),
854 | columnIndex: z.number().int().min(0).describe("Column index (0-based)."),
855 | textContent: z.string().optional().describe("Optional: New text content for the cell. Replaces existing content."),
856 | // Combine basic styles for simplicity here. More advanced cell styling might need separate tools.
857 | textStyle: TextStyleParameters.optional().describe("Optional: Text styles to apply."),
858 | paragraphStyle: ParagraphStyleParameters.optional().describe("Optional: Paragraph styles (like alignment) to apply."),
859 | // cellBackgroundColor: z.string().optional()... // Cell-specific styles are complex
860 | }),
861 | execute: async (args, { log }) => {
862 | const docs = await getDocsClient();
863 | log.info(`Editing cell (${args.rowIndex}, ${args.columnIndex}) in table starting at ${args.tableStartIndex}, doc ${args.documentId}`);
864 |
865 | // TODO: Implement complex logic
866 | // 1. Find the cell's content range based on tableStartIndex, rowIndex, columnIndex. This is NON-TRIVIAL.
867 | // Requires getting the document, finding the table element, iterating through rows/cells to calculate indices.
868 | // 2. If textContent is provided, generate a DeleteContentRange request for the cell's current content.
869 | // 3. Generate an InsertText request for the new textContent at the cell's start index.
870 | // 4. If textStyle is provided, generate UpdateTextStyle requests for the new text range.
871 | // 5. If paragraphStyle is provided, generate UpdateParagraphStyle requests for the cell's paragraph range.
872 | // 6. Execute batch update.
873 |
874 | log.error("editTableCell is not implemented due to complexity of finding cell indices.");
875 | throw new NotImplementedError("Editing table cells is complex and not yet implemented.");
876 | // return `Edit request for cell (${args.rowIndex}, ${args.columnIndex}) submitted (Not Implemented).`;
877 | }
878 |
879 | });
880 |
881 | server.addTool({
882 | name: 'insertPageBreak',
883 | description: 'Inserts a page break at the specified index.',
884 | parameters: DocumentIdParameter.extend({
885 | index: z.number().int().min(1).describe('The index (1-based) where the page break should be inserted.'),
886 | }),
887 | execute: async (args, { log }) => {
888 | const docs = await getDocsClient();
889 | log.info(`Inserting page break in doc ${args.documentId} at index ${args.index}`);
890 | try {
891 | const request: docs_v1.Schema$Request = {
892 | insertPageBreak: {
893 | location: { index: args.index }
894 | }
895 | };
896 | await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
897 | return `Successfully inserted page break at index ${args.index}.`;
898 | } catch (error: any) {
899 | log.error(`Error inserting page break in doc ${args.documentId}: ${error.message || error}`);
900 | if (error instanceof UserError) throw error;
901 | throw new UserError(`Failed to insert page break: ${error.message || 'Unknown error'}`);
902 | }
903 | }
904 | });
905 |
906 | // --- Intelligent Assistance Tools (Examples/Stubs) ---
907 |
908 | server.addTool({
909 | name: 'fixListFormatting',
910 | description: 'EXPERIMENTAL: Attempts to detect paragraphs that look like lists (e.g., starting with -, \*, 1.) and convert them to proper Google Docs bulleted or numbered lists. Best used on specific sections.',
911 | parameters: DocumentIdParameter.extend({
912 | // Optional range to limit the scope, otherwise scans whole doc (potentially slow/risky)
913 | range: OptionalRangeParameters.optional().describe("Optional: Limit the fixing process to a specific range.")
914 | }),
915 | execute: async (args, { log }) => {
916 | const docs = await getDocsClient();
917 | log.warn(`Executing EXPERIMENTAL fixListFormatting for doc ${args.documentId}. Range: ${JSON.stringify(args.range)}`);
918 | try {
919 | await GDocsHelpers.detectAndFormatLists(docs, args.documentId, args.range?.startIndex, args.range?.endIndex);
920 | return `Attempted to fix list formatting. Please review the document for accuracy.`;
921 | } catch (error: any) {
922 | log.error(`Error fixing list formatting in doc ${args.documentId}: ${error.message || error}`);
923 | if (error instanceof UserError) throw error;
924 | if (error instanceof NotImplementedError) throw error; // Expected if helper not implemented
925 | throw new UserError(`Failed to fix list formatting: ${error.message || 'Unknown error'}`);
926 | }
927 | }
928 | });
929 |
930 | server.addTool({
931 | name: 'addComment',
932 | description: 'Adds a comment anchored to a specific text range. REQUIRES DRIVE API SCOPES/SETUP.',
933 | parameters: DocumentIdParameter.extend(RangeParameters.shape).extend({
934 | commentText: z.string().min(1).describe("The content of the comment."),
935 | }),
936 | execute: async (args, { log }) => {
937 | log.info(`Attempting to add comment "${args.commentText}" to range ${args.startIndex}-${args.endIndex} in doc ${args.documentId}`);
938 | // Requires Drive API client and appropriate scopes.
939 | // const { authClient } = await initializeGoogleClient(); // Get auth client if needed
940 | // if (!authClient) throw new UserError("Authentication client not available for Drive API.");
941 | try {
942 | // await GDocsHelpers.addCommentHelper(driveClient, args.documentId, args.commentText, args.startIndex, args.endIndex);
943 | log.error("addComment requires Drive API setup which is not implemented.");
944 | throw new NotImplementedError("Adding comments requires Drive API setup and is not yet implemented in this server.");
945 | // return `Comment added to range ${args.startIndex}-${args.endIndex}.`;
946 | } catch (error: any) {
947 | log.error(`Error adding comment in doc ${args.documentId}: ${error.message || error}`);
948 | if (error instanceof UserError) throw error;
949 | if (error instanceof NotImplementedError) throw error;
950 | throw new UserError(`Failed to add comment: ${error.message || 'Unknown error'}`);
951 | }
952 | }
953 | });
954 |
955 | // --- Add Stubs for other advanced features ---
956 | // (findElement, getDocumentMetadata, replaceText, list management, image handling, section breaks, footnotes, etc.)
957 | // Example Stub:
958 | server.addTool({
959 | name: 'findElement',
960 | description: 'Finds elements (paragraphs, tables, etc.) based on various criteria. (Not Implemented)',
961 | parameters: DocumentIdParameter.extend({
962 | // Define complex query parameters...
963 | textQuery: z.string().optional(),
964 | elementType: z.enum(['paragraph', 'table', 'list', 'image']).optional(),
965 | // styleQuery...
966 | }),
967 | execute: async (args, { log }) => {
968 | log.warn("findElement tool called but is not implemented.");
969 | throw new NotImplementedError("Finding elements by complex criteria is not yet implemented.");
970 | }
971 | });
972 |
973 | // --- Server Startup ---
974 | async function startServer() {
975 | try {
976 | await initializeGoogleClient(); // Authorize BEFORE starting listeners
977 | console.error("Starting Ultimate Google Docs MCP server...");
978 |
979 | // Using stdio as before
980 | const configToUse = {
981 | transportType: "stdio" as const,
982 | };
983 | server.start(configToUse);
984 | console.error(`MCP Server running using ${configToUse.transportType}. Awaiting client connection...`);
985 |
986 | } catch(startError: any) {
987 | console.error("FATAL: Server failed to start:", startError.message || startError);
988 | process.exit(1);
989 | }
990 | }
991 |
992 | startServer(); // Removed .catch here, let errors propagate if startup fails critically
993 | Use code with caution.
994 | TypeScript
995 | Phase 2: Step-by-Step Update Instructions
996 | Create src/types.ts:
997 | In your project's src directory, create a new file named types.ts.
998 | Copy the entire content from Phase 1, Section 1 (src/types.ts) into this new file. Save it.
999 | Create src/googleDocsApiHelpers.ts:
1000 | In your project's src directory, create another new file named googleDocsApiHelpers.ts.
1001 | Copy the entire content from Phase 1, Section 2 (src/googleDocsApiHelpers.ts) into this new file. Save it.
1002 | Replace src/server.ts:
1003 | Open your existing src/server.ts file.
1004 | Delete all of its current content.
1005 | Copy the entire content from Phase 1, Section 3 (Updated File: src/server.ts) into the now empty src/server.ts file. Save it.
1006 | Check src/auth.ts:
1007 | No changes are strictly required unless you plan to implement features needing the Drive API (like comments). For now, leave it as is. If you add Drive features later, you'll need to add Drive API scopes (like https://www.googleapis.com/auth/drive) to the SCOPES array in auth.ts and potentially re-authorize (delete token.json and run the server once).
1008 | Install Dependencies (If any were added):
1009 | Open your terminal in the project root directory.
1010 | Run npm install. (In this case, no new dependencies were added, but it's good practice).
1011 | Build the Code:
1012 | In your terminal, run the build command:
1013 | npm run build
1014 | Use code with caution.
1015 | Bash
1016 | This should compile the new .ts files into JavaScript in the dist directory. Check for any compilation errors in the terminal output. Fix them if necessary (typos, import issues, etc.).
1017 | Update mcp_config.json (Optional - Check Path):
1018 | The command to run the server likely hasn't changed (node /path/to/your/project/dist/server.js). Double-check that the path in your Claude Desktop mcp_config.json still correctly points to the compiled dist/server.js file.
1019 | Re-authorize (If Scopes Changed):
1020 | If you did change scopes in auth.ts (not required by the code provided), you must delete the token.json file in your project root.
1021 | Run the server manually once to go through the Google authorization flow again:
1022 | node ./dist/server.js
1023 | Use code with caution.
1024 | Bash
1025 | Follow the on-screen instructions to authorize in your browser and paste the code back into the terminal.
1026 | Update Documentation (README.md / docs/index.html):
1027 | This is crucial! Your documentation is now outdated.
1028 | Edit your README.md and/or docs/index.html.
1029 | Remove descriptions of old/removed tools (like the original formatText).
1030 | Add detailed descriptions and usage examples for the new tools (applyTextStyle, applyParagraphStyle, insertTable, insertText, deleteRange, fixListFormatting, addComment, etc.). Explain their parameters clearly.
1031 | Mention which tools are experimental or not fully implemented.
1032 | Test Thoroughly:
1033 | Restart Claude Desktop (if using it).
1034 | Start testing the new tools one by one with specific prompts.
1035 | Begin with simple cases (e.g., applying bold using applyTextStyle with text finding).
1036 | Test edge cases (text not found, invalid indices, invalid hex colors).
1037 | Test the tools that rely on helpers (e.g., applyParagraphStyle which uses getParagraphRange and findTextRange).
1038 | Expect the unimplemented tools to return the "Not Implemented" error.
1039 | Monitor the terminal where Claude Desktop runs the server (or run it manually) for error messages (console.error logs).
1040 | You now have the code structure and implementation examples for a significantly more powerful Google Docs MCP server. Remember that the unimplemented features and complex helpers will require further development effort. Good luck!
1041 |
```
--------------------------------------------------------------------------------
/pages/pages.md:
--------------------------------------------------------------------------------
```markdown
1 |
```
--------------------------------------------------------------------------------
/.repomix/bundles.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "bundles": {}
3 | }
```
--------------------------------------------------------------------------------
/index.js:
--------------------------------------------------------------------------------
```javascript
1 | #!/usr/bin/env node
2 |
3 | // Entry point for the Google Docs MCP Server
4 | // This imports and runs the compiled server from the dist directory
5 |
6 | import './dist/server.js';
7 |
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | // tsconfig.json
2 | {
3 | "compilerOptions": {
4 | "target": "ES2022",
5 | "module": "NodeNext",
6 | "moduleResolution": "NodeNext",
7 | "outDir": "./dist",
8 | "rootDir": "./src",
9 | "strict": true,
10 | "esModuleInterop": true,
11 | "skipLibCheck": true,
12 | "forceConsistentCasingInFileNames": true,
13 | "resolveJsonModule": true
14 | },
15 | "include": ["src/**/*"],
16 | "exclude": ["node_modules"]
17 | }
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "mcp-googledocs-server",
3 | "version": "1.0.0",
4 | "type": "module",
5 | "main": "index.js",
6 | "scripts": {
7 | "test": "node --test tests/",
8 | "build": "tsc"
9 | },
10 | "keywords": [],
11 | "author": "",
12 | "license": "ISC",
13 | "description": "",
14 | "dependencies": {
15 | "fastmcp": "^1.21.0",
16 | "google-auth-library": "^9.15.1",
17 | "googleapis": "^148.0.0",
18 | "zod": "^3.24.2"
19 | },
20 | "devDependencies": {
21 | "@types/node": "^22.14.1",
22 | "tsx": "^4.19.3",
23 | "typescript": "^5.8.3"
24 | }
25 | }
26 |
```
--------------------------------------------------------------------------------
/tests/types.test.js:
--------------------------------------------------------------------------------
```javascript
1 | // tests/types.test.js
2 | import { hexToRgbColor, validateHexColor } from '../dist/types.js';
3 | import assert from 'node:assert';
4 | import { describe, it } from 'node:test';
5 |
6 | describe('Color Validation and Conversion', () => {
7 | // Test hypothesis 3: Hex color validation and conversion
8 |
9 | describe('validateHexColor', () => {
10 | it('should validate correct hex colors with hash', () => {
11 | assert.strictEqual(validateHexColor('#FF0000'), true); // 6 digits red
12 | assert.strictEqual(validateHexColor('#F00'), true); // 3 digits red
13 | assert.strictEqual(validateHexColor('#00FF00'), true); // 6 digits green
14 | assert.strictEqual(validateHexColor('#0F0'), true); // 3 digits green
15 | });
16 |
17 | it('should validate correct hex colors without hash', () => {
18 | assert.strictEqual(validateHexColor('FF0000'), true); // 6 digits red
19 | assert.strictEqual(validateHexColor('F00'), true); // 3 digits red
20 | assert.strictEqual(validateHexColor('00FF00'), true); // 6 digits green
21 | assert.strictEqual(validateHexColor('0F0'), true); // 3 digits green
22 | });
23 |
24 | it('should reject invalid hex colors', () => {
25 | assert.strictEqual(validateHexColor(''), false); // Empty
26 | assert.strictEqual(validateHexColor('#XYZ'), false); // Invalid characters
27 | assert.strictEqual(validateHexColor('#12345'), false); // Invalid length (5)
28 | assert.strictEqual(validateHexColor('#1234567'), false);// Invalid length (7)
29 | assert.strictEqual(validateHexColor('invalid'), false); // Not a hex color
30 | assert.strictEqual(validateHexColor('#12'), false); // Too short
31 | });
32 | });
33 |
34 | describe('hexToRgbColor', () => {
35 | it('should convert 6-digit hex colors with hash correctly', () => {
36 | const result = hexToRgbColor('#FF0000');
37 | assert.deepStrictEqual(result, { red: 1, green: 0, blue: 0 }); // Red
38 |
39 | const resultGreen = hexToRgbColor('#00FF00');
40 | assert.deepStrictEqual(resultGreen, { red: 0, green: 1, blue: 0 }); // Green
41 |
42 | const resultBlue = hexToRgbColor('#0000FF');
43 | assert.deepStrictEqual(resultBlue, { red: 0, green: 0, blue: 1 }); // Blue
44 |
45 | const resultPurple = hexToRgbColor('#800080');
46 | assert.deepStrictEqual(resultPurple, { red: 0.5019607843137255, green: 0, blue: 0.5019607843137255 }); // Purple
47 | });
48 |
49 | it('should convert 3-digit hex colors correctly', () => {
50 | const result = hexToRgbColor('#F00');
51 | assert.deepStrictEqual(result, { red: 1, green: 0, blue: 0 }); // Red from shorthand
52 |
53 | const resultWhite = hexToRgbColor('#FFF');
54 | assert.deepStrictEqual(resultWhite, { red: 1, green: 1, blue: 1 }); // White from shorthand
55 | });
56 |
57 | it('should convert hex colors without hash correctly', () => {
58 | const result = hexToRgbColor('FF0000');
59 | assert.deepStrictEqual(result, { red: 1, green: 0, blue: 0 }); // Red without hash
60 | });
61 |
62 | it('should return null for invalid hex colors', () => {
63 | assert.strictEqual(hexToRgbColor(''), null); // Empty
64 | assert.strictEqual(hexToRgbColor('#XYZ'), null); // Invalid characters
65 | assert.strictEqual(hexToRgbColor('#12345'), null); // Invalid length
66 | assert.strictEqual(hexToRgbColor('invalid'), null); // Not a hex color
67 | });
68 | });
69 | });
```
--------------------------------------------------------------------------------
/src/auth.ts:
--------------------------------------------------------------------------------
```typescript
1 | // src/auth.ts
2 | import { google } from 'googleapis';
3 | import { OAuth2Client } from 'google-auth-library';
4 | import * as fs from 'fs/promises';
5 | import * as path from 'path';
6 | import * as readline from 'readline/promises';
7 | import { fileURLToPath } from 'url';
8 |
9 | // --- Calculate paths relative to this script file (ESM way) ---
10 | const __filename = fileURLToPath(import.meta.url);
11 | const __dirname = path.dirname(__filename);
12 | const projectRootDir = path.resolve(__dirname, '..');
13 |
14 | const TOKEN_PATH = path.join(projectRootDir, 'token.json');
15 | const CREDENTIALS_PATH = path.join(projectRootDir, 'credentials.json');
16 | // --- End of path calculation ---
17 |
18 | const SCOPES = [
19 | 'https://www.googleapis.com/auth/documents',
20 | 'https://www.googleapis.com/auth/drive' // Full Drive access for listing, searching, and document discovery
21 | ];
22 |
23 | async function loadSavedCredentialsIfExist(): Promise<OAuth2Client | null> {
24 | try {
25 | const content = await fs.readFile(TOKEN_PATH);
26 | const credentials = JSON.parse(content.toString());
27 | const { client_secret, client_id, redirect_uris } = await loadClientSecrets();
28 | const client = new google.auth.OAuth2(client_id, client_secret, redirect_uris?.[0]);
29 | client.setCredentials(credentials);
30 | return client;
31 | } catch (err) {
32 | return null;
33 | }
34 | }
35 |
36 | async function loadClientSecrets() {
37 | const content = await fs.readFile(CREDENTIALS_PATH);
38 | const keys = JSON.parse(content.toString());
39 | const key = keys.installed || keys.web;
40 | if (!key) throw new Error("Could not find client secrets in credentials.json.");
41 | return {
42 | client_id: key.client_id,
43 | client_secret: key.client_secret,
44 | redirect_uris: key.redirect_uris || ['http://localhost:3000/'], // Default for web clients
45 | client_type: keys.web ? 'web' : 'installed'
46 | };
47 | }
48 |
49 | async function saveCredentials(client: OAuth2Client): Promise<void> {
50 | const { client_secret, client_id } = await loadClientSecrets();
51 | const payload = JSON.stringify({
52 | type: 'authorized_user',
53 | client_id: client_id,
54 | client_secret: client_secret,
55 | refresh_token: client.credentials.refresh_token,
56 | });
57 | await fs.writeFile(TOKEN_PATH, payload);
58 | console.error('Token stored to', TOKEN_PATH);
59 | }
60 |
61 | async function authenticate(): Promise<OAuth2Client> {
62 | const { client_secret, client_id, redirect_uris, client_type } = await loadClientSecrets();
63 | // For web clients, use the configured redirect URI; for desktop clients, use 'urn:ietf:wg:oauth:2.0:oob'
64 | const redirectUri = client_type === 'web' ? redirect_uris[0] : 'urn:ietf:wg:oauth:2.0:oob';
65 | console.error(`DEBUG: Using redirect URI: ${redirectUri}`);
66 | console.error(`DEBUG: Client type: ${client_type}`);
67 | const oAuth2Client = new google.auth.OAuth2(client_id, client_secret, redirectUri);
68 |
69 | const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
70 |
71 | const authorizeUrl = oAuth2Client.generateAuthUrl({
72 | access_type: 'offline',
73 | scope: SCOPES.join(' '),
74 | });
75 |
76 | console.error('DEBUG: Generated auth URL:', authorizeUrl);
77 | console.error('Authorize this app by visiting this url:', authorizeUrl);
78 | const code = await rl.question('Enter the code from that page here: ');
79 | rl.close();
80 |
81 | try {
82 | const { tokens } = await oAuth2Client.getToken(code);
83 | oAuth2Client.setCredentials(tokens);
84 | if (tokens.refresh_token) { // Save only if we got a refresh token
85 | await saveCredentials(oAuth2Client);
86 | } else {
87 | console.error("Did not receive refresh token. Token might expire.");
88 | }
89 | console.error('Authentication successful!');
90 | return oAuth2Client;
91 | } catch (err) {
92 | console.error('Error retrieving access token', err);
93 | throw new Error('Authentication failed');
94 | }
95 | }
96 |
97 | export async function authorize(): Promise<OAuth2Client> {
98 | let client = await loadSavedCredentialsIfExist();
99 | if (client) {
100 | // Optional: Add token refresh logic here if needed, though library often handles it.
101 | console.error('Using saved credentials.');
102 | return client;
103 | }
104 | console.error('Starting authentication flow...');
105 | client = await authenticate();
106 | return client;
107 | }
108 |
```
--------------------------------------------------------------------------------
/tests/helpers.test.js:
--------------------------------------------------------------------------------
```javascript
1 | // tests/helpers.test.js
2 | import { findTextRange } from '../dist/googleDocsApiHelpers.js';
3 | import assert from 'node:assert';
4 | import { describe, it, mock } from 'node:test';
5 |
6 | describe('Text Range Finding', () => {
7 | // Test hypothesis 1: Text range finding works correctly
8 |
9 | describe('findTextRange', () => {
10 | it('should find text within a single text run correctly', async () => {
11 | // Mock the docs.documents.get method to return a predefined structure
12 | const mockDocs = {
13 | documents: {
14 | get: mock.fn(async () => ({
15 | data: {
16 | body: {
17 | content: [
18 | {
19 | paragraph: {
20 | elements: [
21 | {
22 | startIndex: 1,
23 | endIndex: 25,
24 | textRun: {
25 | content: 'This is a test sentence.'
26 | }
27 | }
28 | ]
29 | }
30 | }
31 | ]
32 | }
33 | }
34 | }))
35 | }
36 | };
37 |
38 | // Test finding "test" in the sample text
39 | const result = await findTextRange(mockDocs, 'doc123', 'test', 1);
40 | assert.deepStrictEqual(result, { startIndex: 11, endIndex: 15 });
41 |
42 | // Verify the docs.documents.get was called with the right parameters
43 | assert.strictEqual(mockDocs.documents.get.mock.calls.length, 1);
44 | assert.deepStrictEqual(
45 | mockDocs.documents.get.mock.calls[0].arguments[0],
46 | {
47 | documentId: 'doc123',
48 | fields: 'body(content(paragraph(elements(startIndex,endIndex,textRun(content)))))'
49 | }
50 | );
51 | });
52 |
53 | it('should find the nth instance of text correctly', async () => {
54 | // Mock with a document that has repeated text
55 | const mockDocs = {
56 | documents: {
57 | get: mock.fn(async () => ({
58 | data: {
59 | body: {
60 | content: [
61 | {
62 | paragraph: {
63 | elements: [
64 | {
65 | startIndex: 1,
66 | endIndex: 41,
67 | textRun: {
68 | content: 'Test test test. This is a test sentence.'
69 | }
70 | }
71 | ]
72 | }
73 | }
74 | ]
75 | }
76 | }
77 | }))
78 | }
79 | };
80 |
81 | // Find the 3rd instance of "test"
82 | const result = await findTextRange(mockDocs, 'doc123', 'test', 3);
83 | assert.deepStrictEqual(result, { startIndex: 27, endIndex: 31 });
84 | });
85 |
86 | it('should return null if text is not found', async () => {
87 | const mockDocs = {
88 | documents: {
89 | get: mock.fn(async () => ({
90 | data: {
91 | body: {
92 | content: [
93 | {
94 | paragraph: {
95 | elements: [
96 | {
97 | startIndex: 1,
98 | endIndex: 25,
99 | textRun: {
100 | content: 'This is a sample sentence.'
101 | }
102 | }
103 | ]
104 | }
105 | }
106 | ]
107 | }
108 | }
109 | }))
110 | }
111 | };
112 |
113 | // Try to find text that doesn't exist
114 | const result = await findTextRange(mockDocs, 'doc123', 'test', 1);
115 | assert.strictEqual(result, null);
116 | });
117 |
118 | it('should handle text spanning multiple text runs', async () => {
119 | const mockDocs = {
120 | documents: {
121 | get: mock.fn(async () => ({
122 | data: {
123 | body: {
124 | content: [
125 | {
126 | paragraph: {
127 | elements: [
128 | {
129 | startIndex: 1,
130 | endIndex: 6,
131 | textRun: {
132 | content: 'This '
133 | }
134 | },
135 | {
136 | startIndex: 6,
137 | endIndex: 11,
138 | textRun: {
139 | content: 'is a '
140 | }
141 | },
142 | {
143 | startIndex: 11,
144 | endIndex: 20,
145 | textRun: {
146 | content: 'test case'
147 | }
148 | }
149 | ]
150 | }
151 | }
152 | ]
153 | }
154 | }
155 | }))
156 | }
157 | };
158 |
159 | // Find text that spans runs: "a test"
160 | const result = await findTextRange(mockDocs, 'doc123', 'a test', 1);
161 | assert.deepStrictEqual(result, { startIndex: 9, endIndex: 15 });
162 | });
163 | });
164 | });
```
--------------------------------------------------------------------------------
/vscode.md:
--------------------------------------------------------------------------------
```markdown
1 | # VS Code Integration Guide
2 |
3 | This guide shows you how to integrate the Ultimate Google Docs & Drive MCP Server with VS Code using the MCP extension.
4 |
5 | ## Prerequisites
6 |
7 | Before setting up VS Code integration, make sure you have:
8 |
9 | 1. **Completed the main setup** - Follow the [README.md](README.md) setup instructions first
10 | 2. **VS Code installed** - Download from [code.visualstudio.com](https://code.visualstudio.com/)
11 | 3. **Working MCP server** - Verify your server works with Claude Desktop first
12 |
13 | ## Installation
14 |
15 | ### Step 1: Install the MCP Extension
16 |
17 | 1. Open VS Code
18 | 2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
19 | 3. Search for "MCP" or "Model Context Protocol"
20 | 4. Install the official MCP extension
21 |
22 | ### Step 2: Configure the MCP Server
23 |
24 | 1. Open VS Code Settings (Ctrl+, / Cmd+,)
25 | 2. Search for "MCP" in settings
26 | 3. Find "MCP: Servers" configuration
27 | 4. Add a new server configuration:
28 |
29 | ```json
30 | {
31 | "google-docs-drive": {
32 | "command": "node",
33 | "args": ["${workspaceFolder}/dist/server.js"],
34 | "env": {
35 | "NODE_ENV": "production"
36 | }
37 | }
38 | }
39 | ```
40 |
41 | ### Step 3: Verify Configuration
42 |
43 | 1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
44 | 2. Type "MCP: Restart Servers" and run it
45 | 3. Check the Output panel and select "MCP" from the dropdown
46 | 4. You should see your server connecting successfully
47 |
48 | ## Usage
49 |
50 | Once configured, you can use the MCP server with AI assistants in VS Code:
51 |
52 | ### Document Operations
53 |
54 | ```
55 | "List my recent Google Docs from the last 7 days"
56 | "Read the content of document ID: 1ABC..."
57 | "Create a new document called 'Project Notes' in my Work folder"
58 | "Search for documents containing 'meeting notes'"
59 | ```
60 |
61 | ### File Management
62 |
63 | ```
64 | "Show me the contents of my root Drive folder"
65 | "Create a folder called 'Project X' in folder ID: 1DEF..."
66 | "Move document ID: 1GHI... to the Project X folder"
67 | "Copy my template document and rename it to 'New Report'"
68 | ```
69 |
70 | ### Document Editing
71 |
72 | ```
73 | "Add a heading 'Summary' to the beginning of document ID: 1JKL..."
74 | "Format all text containing 'important' as bold in my document"
75 | "Insert a table with 3 columns and 5 rows at the end of the document"
76 | "Apply paragraph formatting to make all headings centered"
77 | ```
78 |
79 | ## Troubleshooting
80 |
81 | ### Server Not Starting
82 |
83 | 1. **Check the path** - Ensure the absolute path in your configuration is correct
84 | 2. **Verify build** - Run `npm run build` in your project directory
85 | 3. **Check permissions** - Ensure `token.json` and `credentials.json` exist and are readable
86 |
87 | ### Authentication Issues
88 |
89 | 1. **Re-authorize** - Delete `token.json` and run the server manually once:
90 | ```bash
91 | cd /path/to/your/google-docs-mcp
92 | node dist/server.js
93 | ```
94 | 2. **Follow the authorization flow** again
95 | 3. **Restart VS Code** after successful authorization
96 |
97 | ### Tool Not Found Errors
98 |
99 | 1. **Restart MCP servers** using Command Palette
100 | 2. **Check server logs** in VS Code Output panel (MCP channel)
101 |
102 | ## Available Tools
103 |
104 | The server provides these tools in VS Code:
105 |
106 | ### Document Discovery
107 | - `listGoogleDocs` - List documents with filtering
108 | - `searchGoogleDocs` - Search by name/content
109 | - `getRecentGoogleDocs` - Get recently modified docs
110 | - `getDocumentInfo` - Get detailed document metadata
111 |
112 | ### Document Editing
113 | - `readGoogleDoc` - Read document content
114 | - `appendToGoogleDoc` - Add text to end
115 | - `insertText` - Insert at specific position
116 | - `deleteRange` - Remove content
117 | - `applyTextStyle` - Format text (bold, italic, colors)
118 | - `applyParagraphStyle` - Format paragraphs (alignment, spacing)
119 | - `formatMatchingText` - Find and format text
120 | - `insertTable` - Create tables
121 | - `insertPageBreak` - Add page breaks
122 |
123 | ### File Management
124 | - `createFolder` - Create new folders
125 | - `listFolderContents` - List folder contents
126 | - `getFolderInfo` - Get folder metadata
127 | - `moveFile` - Move files/folders
128 | - `copyFile` - Copy files/folders
129 | - `renameFile` - Rename files/folders
130 | - `deleteFile` - Delete files/folders
131 | - `createDocument` - Create new documents
132 | - `createFromTemplate` - Create from templates
133 |
134 | ## Tips for Better Integration
135 |
136 | 1. **Use specific document IDs** - More reliable than document names
137 | 2. **Combine operations** - Create and format documents in single requests
138 | 3. **Check tool results** - Review what was actually done before proceeding
139 | 4. **Use templates** - Create template documents for consistent formatting
140 |
141 | ## Security Notes
142 |
143 | - The server uses OAuth 2.0 for secure authentication
144 | - Credentials are stored locally in `token.json` and `credentials.json`
145 | - Never share these files or commit them to version control
146 | - The server only has access to your Google Drive, not other Google services
147 |
148 | ## Example Workflows
149 |
150 | ### Create a Formatted Report
151 |
152 | ```
153 | 1. "Create a new document called 'Monthly Report' in my Reports folder"
154 | 2. "Add the title 'Monthly Performance Report' as a centered Heading 1"
155 | 3. "Insert a table with 4 columns and 6 rows for the data"
156 | 4. "Add section headings for Executive Summary, Key Metrics, and Action Items"
157 | ```
158 |
159 | ### Organize Project Documents
160 |
161 | ```
162 | 1. "Create a folder called 'Q1 Project' in my Work folder"
163 | 2. "Search for all documents containing 'Q1' in the title"
164 | 3. "Move the found documents to the Q1 Project folder"
165 | 4. "Create a new document called 'Q1 Project Overview' in that folder"
166 | ```
167 |
168 | This integration brings the full power of Google Docs and Drive management directly into your VS Code workflow!
169 |
```
--------------------------------------------------------------------------------
/src/types.ts:
--------------------------------------------------------------------------------
```typescript
1 | // src/types.ts
2 | import { z } from 'zod';
3 | import { docs_v1 } from 'googleapis';
4 |
5 | // --- Helper function for hex color validation ---
6 | export const hexColorRegex = /^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/;
7 | export const validateHexColor = (color: string) => hexColorRegex.test(color);
8 |
9 | // --- Helper function for Hex to RGB conversion ---
10 | export function hexToRgbColor(hex: string): docs_v1.Schema$RgbColor | null {
11 | if (!hex) return null;
12 | let hexClean = hex.startsWith('#') ? hex.slice(1) : hex;
13 |
14 | if (hexClean.length === 3) {
15 | hexClean = hexClean[0] + hexClean[0] + hexClean[1] + hexClean[1] + hexClean[2] + hexClean[2];
16 | }
17 | if (hexClean.length !== 6) return null;
18 | const bigint = parseInt(hexClean, 16);
19 | if (isNaN(bigint)) return null;
20 |
21 | const r = ((bigint >> 16) & 255) / 255;
22 | const g = ((bigint >> 8) & 255) / 255;
23 | const b = (bigint & 255) / 255;
24 |
25 | return { red: r, green: g, blue: b };
26 | }
27 |
28 | // --- Zod Schema Fragments for Reusability ---
29 |
30 | export const DocumentIdParameter = z.object({
31 | documentId: z.string().describe('The ID of the Google Document (from the URL).'),
32 | });
33 |
34 | export const RangeParameters = z.object({
35 | startIndex: z.number().int().min(1).describe('The starting index of the text range (inclusive, starts from 1).'),
36 | endIndex: z.number().int().min(1).describe('The ending index of the text range (exclusive).'),
37 | }).refine(data => data.endIndex > data.startIndex, {
38 | message: "endIndex must be greater than startIndex",
39 | path: ["endIndex"],
40 | });
41 |
42 | export const OptionalRangeParameters = z.object({
43 | 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.'),
44 | 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.'),
45 | }).refine(data => !data.startIndex || !data.endIndex || data.endIndex > data.startIndex, {
46 | message: "If both startIndex and endIndex are provided, endIndex must be greater than startIndex",
47 | path: ["endIndex"],
48 | });
49 |
50 | export const TextFindParameter = z.object({
51 | textToFind: z.string().min(1).describe('The exact text string to locate.'),
52 | matchInstance: z.number().int().min(1).optional().default(1).describe('Which instance of the text to target (1st, 2nd, etc.). Defaults to 1.'),
53 | });
54 |
55 | // --- Style Parameter Schemas ---
56 |
57 | export const TextStyleParameters = z.object({
58 | bold: z.boolean().optional().describe('Apply bold formatting.'),
59 | italic: z.boolean().optional().describe('Apply italic formatting.'),
60 | underline: z.boolean().optional().describe('Apply underline formatting.'),
61 | strikethrough: z.boolean().optional().describe('Apply strikethrough formatting.'),
62 | fontSize: z.number().min(1).optional().describe('Set font size (in points, e.g., 12).'),
63 | fontFamily: z.string().optional().describe('Set font family (e.g., "Arial", "Times New Roman").'),
64 | foregroundColor: z.string()
65 | .refine(validateHexColor, { message: "Invalid hex color format (e.g., #FF0000 or #F00)" })
66 | .optional()
67 | .describe('Set text color using hex format (e.g., "#FF0000").'),
68 | backgroundColor: z.string()
69 | .refine(validateHexColor, { message: "Invalid hex color format (e.g., #00FF00 or #0F0)" })
70 | .optional()
71 | .describe('Set text background color using hex format (e.g., "#FFFF00").'),
72 | linkUrl: z.string().url().optional().describe('Make the text a hyperlink pointing to this URL.'),
73 | // 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
74 | }).describe("Parameters for character-level text formatting.");
75 |
76 | // Subset of TextStyle used for passing to helpers
77 | export type TextStyleArgs = z.infer<typeof TextStyleParameters>;
78 |
79 | export const ParagraphStyleParameters = z.object({
80 | alignment: z.enum(['LEFT', 'CENTER', 'RIGHT', 'JUSTIFIED']).optional().describe('Paragraph alignment.'),
81 | indentStart: z.number().min(0).optional().describe('Left indentation in points.'),
82 | indentEnd: z.number().min(0).optional().describe('Right indentation in points.'),
83 | spaceAbove: z.number().min(0).optional().describe('Space before the paragraph in points.'),
84 | spaceBelow: z.number().min(0).optional().describe('Space after the paragraph in points.'),
85 | namedStyleType: z.enum([
86 | 'NORMAL_TEXT', 'TITLE', 'SUBTITLE',
87 | 'HEADING_1', 'HEADING_2', 'HEADING_3', 'HEADING_4', 'HEADING_5', 'HEADING_6'
88 | ]).optional().describe('Apply a built-in named paragraph style (e.g., HEADING_1).'),
89 | keepWithNext: z.boolean().optional().describe('Keep this paragraph together with the next one on the same page.'),
90 | // Borders are more complex, might need separate objects/tools
91 | // 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
92 | }).describe("Parameters for paragraph-level formatting.");
93 |
94 | // Subset of ParagraphStyle used for passing to helpers
95 | export type ParagraphStyleArgs = z.infer<typeof ParagraphStyleParameters>;
96 |
97 | // --- Combination Schemas for Tools ---
98 |
99 | export const ApplyTextStyleToolParameters = DocumentIdParameter.extend({
100 | // Target EITHER by range OR by finding text
101 | target: z.union([
102 | RangeParameters,
103 | TextFindParameter
104 | ]).describe("Specify the target range either by start/end indices or by finding specific text."),
105 | style: TextStyleParameters.refine(
106 | styleArgs => Object.values(styleArgs).some(v => v !== undefined),
107 | { message: "At least one text style option must be provided." }
108 | ).describe("The text styling to apply.")
109 | });
110 | export type ApplyTextStyleToolArgs = z.infer<typeof ApplyTextStyleToolParameters>;
111 |
112 | export const ApplyParagraphStyleToolParameters = DocumentIdParameter.extend({
113 | // Target EITHER by range OR by finding text (tool logic needs to find paragraph boundaries)
114 | target: z.union([
115 | RangeParameters, // User provides paragraph start/end (less likely)
116 | TextFindParameter.extend({
117 | applyToContainingParagraph: z.literal(true).default(true).describe("Must be true. Indicates the style applies to the whole paragraph containing the found text.")
118 | }),
119 | z.object({ // Target by specific index within the paragraph
120 | indexWithinParagraph: z.number().int().min(1).describe("An index located anywhere within the target paragraph.")
121 | })
122 | ]).describe("Specify the target paragraph either by start/end indices, by finding text within it, or by providing an index within it."),
123 | style: ParagraphStyleParameters.refine(
124 | styleArgs => Object.values(styleArgs).some(v => v !== undefined),
125 | { message: "At least one paragraph style option must be provided." }
126 | ).describe("The paragraph styling to apply.")
127 | });
128 | export type ApplyParagraphStyleToolArgs = z.infer<typeof ApplyParagraphStyleToolParameters>;
129 |
130 | // --- Error Class ---
131 | // Use FastMCP's UserError for client-facing issues
132 | // Define a custom error for internal issues if needed
133 | export class NotImplementedError extends Error {
134 | constructor(message = "This feature is not yet implemented.") {
135 | super(message);
136 | this.name = "NotImplementedError";
137 | }
138 | }
```
--------------------------------------------------------------------------------
/SAMPLE_TASKS.md:
--------------------------------------------------------------------------------
```markdown
1 | # 15 Powerful Tasks with the Ultimate Google Docs & Drive MCP Server
2 |
3 | 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.
4 |
5 | ## Document Formatting & Structure Tasks
6 |
7 | ## 1. Create and Format a Document Header
8 |
9 | ```
10 | Task: "Create a professional document header for my project proposal."
11 |
12 | Steps:
13 | 1. Insert the title "Project Proposal: AI Integration Strategy" at the beginning of the document
14 | 2. Apply Heading 1 style to the title using applyParagraphStyle
15 | 3. Add a horizontal line below the title
16 | 4. Insert the date and author information
17 | 5. Apply a subtle background color to the header section
18 | ```
19 |
20 | ## 2. Generate and Format a Table of Contents
21 |
22 | ```
23 | Task: "Create a table of contents for my document based on its headings."
24 |
25 | Steps:
26 | 1. Find all text with Heading styles (1-3) using findParagraphsMatchingStyle
27 | 2. Create a "Table of Contents" section at the beginning of the document
28 | 3. Insert each heading with appropriate indentation based on its level
29 | 4. Format the TOC entries with page numbers and dotted lines
30 | 5. Apply consistent styling to the entire TOC
31 | ```
32 |
33 | ## 3. Structure a Document with Consistent Formatting
34 |
35 | ```
36 | Task: "Apply consistent formatting throughout my document based on content type."
37 |
38 | Steps:
39 | 1. Format all section headings with applyParagraphStyle (Heading styles, alignment)
40 | 2. Style all bullet points with consistent indentation and formatting
41 | 3. Format code samples with monospace font and background color
42 | 4. Apply consistent paragraph spacing throughout the document
43 | 5. Format all hyperlinks with a consistent color and underline style
44 | ```
45 |
46 | ## 4. Create a Professional Table for Data Presentation
47 |
48 | ```
49 | Task: "Create a formatted comparison table of product features."
50 |
51 | Steps:
52 | 1. Insert a table with insertTable (5 rows x 4 columns)
53 | 2. Add header row with product names
54 | 3. Add feature rows with consistent formatting
55 | 4. Apply alternating row background colors for readability
56 | 5. Format the header row with bold text and background color
57 | 6. Align numeric columns to the right
58 | ```
59 |
60 | ## 5. Prepare a Document for Formal Submission
61 |
62 | ```
63 | Task: "Format my research paper according to academic guidelines."
64 |
65 | Steps:
66 | 1. Set the title with centered alignment and appropriate font size
67 | 2. Format all headings according to the required style guide
68 | 3. Apply double spacing to the main text
69 | 4. Insert page numbers with appropriate format
70 | 5. Format citations consistently
71 | 6. Apply indentation to block quotes
72 | 7. Format the bibliography section
73 | ```
74 |
75 | ## 6. Create an Executive Summary with Highlights
76 |
77 | ```
78 | Task: "Create an executive summary that emphasizes key points from my report."
79 |
80 | Steps:
81 | 1. Insert a page break and create an "Executive Summary" section
82 | 2. Extract and format key points from the document
83 | 3. Apply bullet points for clarity
84 | 4. Highlight critical figures or statistics in bold
85 | 5. Use color to emphasize particularly important points
86 | 6. Format the summary with appropriate spacing and margins
87 | ```
88 |
89 | ## 7. Format a Document for Different Audiences
90 |
91 | ```
92 | Task: "Create two versions of my presentation - one technical and one for executives."
93 |
94 | Steps:
95 | 1. Duplicate the document content
96 | 2. For the technical version:
97 | - Add detailed technical sections
98 | - Include code examples with monospace formatting
99 | - Use technical terminology
100 | 3. For the executive version:
101 | - Emphasize business impact with bold and color
102 | - Simplify technical concepts
103 | - Add executive summary
104 | - Use more visual formatting elements
105 | ```
106 |
107 | ## 8. Create a Response Form with Structured Fields
108 |
109 | ```
110 | Task: "Create a form-like document with fields for respondents to complete."
111 |
112 | Steps:
113 | 1. Create section headers for different parts of the form
114 | 2. Insert tables for structured response areas
115 | 3. Add form fields with clear instructions
116 | 4. Use formatting to distinguish between instructions and response areas
117 | 5. Add checkbox lists using special characters with consistent formatting
118 | 6. Apply consistent spacing and alignment throughout
119 | ```
120 |
121 | ## 9. Format a Document with Multi-Level Lists
122 |
123 | ```
124 | Task: "Create a project plan with properly formatted nested task lists."
125 |
126 | Steps:
127 | 1. Insert the project title and apply Heading 1 style
128 | 2. Create main project phases with Heading 2 style
129 | 3. For each phase, create a properly formatted numbered list of tasks
130 | 4. Create sub-tasks with indented, properly formatted sub-lists
131 | 5. Apply consistent formatting to all list levels
132 | 6. Format task owners' names in bold
133 | 7. Format dates and deadlines with a consistent style
134 | ```
135 |
136 | ## 10. Prepare a Document with Advanced Layout
137 |
138 | ```
139 | Task: "Create a newsletter-style document with columns and sections."
140 |
141 | Steps:
142 | 1. Create a bold, centered title for the newsletter
143 | 2. Insert a horizontal line separator
144 | 3. Create differently formatted sections for:
145 | - Main article (left-aligned paragraphs)
146 | - Sidebar content (indented, smaller text)
147 | - Highlighted quotes (centered, italic)
148 | 4. Insert and format images with captions
149 | 5. Add a formatted footer with contact information
150 | 6. Apply consistent spacing between sections
151 | ```
152 |
153 | 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.
154 |
155 | ## Google Drive Management Tasks
156 |
157 | ## 11. Organize Project Files Automatically
158 |
159 | ```
160 | Task: "Set up a complete project structure and organize existing files."
161 |
162 | Steps:
163 | 1. Create a main project folder using createFolder
164 | 2. Create subfolders for different aspects (Documents, Templates, Archive)
165 | 3. Search for project-related documents using searchGoogleDocs
166 | 4. Move relevant documents to appropriate subfolders with moveFile
167 | 5. Create a project index document listing all resources
168 | 6. Format the index with links to all project documents
169 | ```
170 |
171 | ## 12. Create Document Templates and Generate Reports
172 |
173 | ```
174 | Task: "Set up a template system and generate standardized reports."
175 |
176 | Steps:
177 | 1. Create a Templates folder using createFolder
178 | 2. Create template documents with placeholder text ({{DATE}}, {{NAME}}, etc.)
179 | 3. Use createFromTemplate to generate new reports from templates
180 | 4. Apply text replacements to customize each report
181 | 5. Organize generated reports in appropriate folders
182 | 6. Create a tracking document listing all generated reports
183 | ```
184 |
185 | ## 13. Archive and Clean Up Old Documents
186 |
187 | ```
188 | Task: "Archive outdated documents and organize current files."
189 |
190 | Steps:
191 | 1. Create an Archive folder for old documents using createFolder
192 | 2. Use getRecentGoogleDocs to find documents older than 90 days
193 | 3. Review and move old documents to Archive using moveFile
194 | 4. Delete unnecessary duplicate files using deleteFile
195 | 5. Rename documents with consistent naming conventions using renameFile
196 | 6. Create an archive index document for reference
197 | ```
198 |
199 | ## 14. Duplicate and Distribute Document Sets
200 |
201 | ```
202 | Task: "Create personalized versions of documents for different teams."
203 |
204 | Steps:
205 | 1. Create team-specific folders using createFolder
206 | 2. Copy master documents to each team folder using copyFile
207 | 3. Rename copied documents with team-specific names using renameFile
208 | 4. Customize document content for each team using text replacement
209 | 5. Apply team-specific formatting and branding
210 | 6. Create distribution tracking documents
211 | ```
212 |
213 | ## 15. Comprehensive File Management and Reporting
214 |
215 | ```
216 | Task: "Generate a complete inventory and management report of all documents."
217 |
218 | Steps:
219 | 1. Use listFolderContents to catalog all folders and their contents
220 | 2. Use getDocumentInfo to gather detailed metadata for each document
221 | 3. Create a master inventory document with all file information
222 | 4. Format the inventory as a searchable table with columns for:
223 | - Document name and ID
224 | - Creation and modification dates
225 | - Owner and last modifier
226 | - Folder location
227 | - File size and sharing status
228 | 5. Add summary statistics and organization recommendations
229 | 6. Set up automated folder structures for better organization
230 | ```
231 |
```
--------------------------------------------------------------------------------
/docs/index.html:
--------------------------------------------------------------------------------
```html
1 | <!DOCTYPE html>
2 | <html lang="en">
3 | <head>
4 | <meta charset="UTF-8">
5 | <meta name="viewport" content="width=device-width, initial-scale=1.0">
6 | <title>FastMCP Google Docs Server Docs</title>
7 | <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
8 | <style>
9 | body { font-family: sans-serif; line-height: 1.6; padding: 20px; }
10 | pre { background-color: #f4f4f4; padding: 10px; border-radius: 5px; overflow-x: auto; }
11 | code { font-family: monospace; }
12 | h1, h2, h3 { border-bottom: 1px solid #eee; padding-bottom: 5px; margin-top: 20px; }
13 | </style>
14 | </head>
15 | <body>
16 | <div id="content"></div>
17 |
18 | <script type="text/markdown" id="markdown-content">
19 | # FastMCP Google Docs Server
20 |
21 | Connect Claude Desktop (or other MCP clients) to your Google Docs!
22 |
23 | 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.
24 |
25 | **Features:**
26 |
27 | - **Read Documents:** Provides a `readGoogleDoc` tool to fetch the text content of a specified Google Doc.
28 | - **Append to Documents:** Provides an `appendToGoogleDoc` tool to add text to the end of a specified Google Doc.
29 | - **Google Authentication:** Handles the OAuth 2.0 flow to securely authorize access to your Google Account.
30 | - **MCP Compliant:** Designed for use with MCP clients like Claude Desktop.
31 |
32 | ---
33 |
34 | ## Prerequisites
35 |
36 | Before you start, make sure you have:
37 |
38 | 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).
39 | 2. **Git:** Required for cloning this repository. ([Download Git](https://git-scm.com/downloads)).
40 | 3. **A Google Account:** The account that owns or has access to the Google Docs you want to interact with.
41 | 4. **Command Line Familiarity:** Basic comfort using a terminal or command prompt (like Terminal on macOS/Linux, or Command Prompt/PowerShell on Windows).
42 | 5. **Claude Desktop (Optional):** If your goal is to connect this server to Claude, you'll need the Claude Desktop application installed.
43 |
44 | ---
45 |
46 | ## Setup Instructions
47 |
48 | Follow these steps carefully to get your own instance of the server running.
49 |
50 | ### Step 1: Google Cloud Project & Credentials (The Important Bit!)
51 |
52 | This server needs permission to talk to Google APIs on your behalf. You'll create special "keys" (credentials) that only your server will use.
53 |
54 | 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.
55 | 2. **Create or Select a Project:**
56 | - 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".
57 | - If you have existing projects, you can select one or create a new one.
58 | 3. **Enable APIs:** You need to turn on the specific Google services this server uses.
59 | - In the search bar at the top, type "APIs & Services" and select "Library".
60 | - Search for "**Google Docs API**" and click on it. Then click the "**ENABLE**" button.
61 | - Search for "**Google Drive API**" and click on it. Then click the "**ENABLE**" button (this is often needed for finding files or permissions).
62 | 4. **Configure OAuth Consent Screen:** This screen tells users (usually just you) what your app wants permission for.
63 | - On the left menu, click "APIs & Services" -> "**OAuth consent screen**".
64 | - Choose User Type: Select "**External**" and click "CREATE".
65 | - Fill in App Information:
66 | - **App name:** Give it a name users will see (e.g., "Claude Docs MCP Access").
67 | - **User support email:** Select your email address.
68 | - **Developer contact information:** Enter your email address.
69 | - Click "**SAVE AND CONTINUE**".
70 | - **Scopes:** Click "**ADD OR REMOVE SCOPES**". Search for and add the following scopes:
71 | - `https://www.googleapis.com/auth/documents` (Allows reading/writing docs)
72 | - `https://www.googleapis.com/auth/drive.file` (Allows access to specific files opened/created by the app)
73 | - Click "**UPDATE**".
74 | - Click "**SAVE AND CONTINUE**".
75 | - **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.
76 | - Click "**SAVE AND CONTINUE**". Review the summary and click "**BACK TO DASHBOARD**".
77 | 5. **Create Credentials (The Keys!):**
78 | - On the left menu, click "APIs & Services" -> "**Credentials**".
79 | - Click "**+ CREATE CREDENTIALS**" at the top and choose "**OAuth client ID**".
80 | - **Application type:** Select "**Desktop app**" from the dropdown.
81 | - **Name:** Give it a name (e.g., "MCP Docs Desktop Client").
82 | - Click "**CREATE**".
83 | 6. **⬇️ DOWNLOAD THE CREDENTIALS FILE:** A box will pop up showing your Client ID. Click the "**DOWNLOAD JSON**" button.
84 | - Save this file. It will likely be named something like `client_secret_....json`.
85 | - **IMPORTANT:** Rename the downloaded file to exactly `credentials.json`.
86 | 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).
87 |
88 | ### Step 2: Get the Server Code
89 |
90 | 1. **Clone the Repository:** Open your terminal/command prompt and run:
91 | ```bash
92 | git clone https://github.com/a-bonus/google-docs-mcp.git mcp-googledocs-server
93 | ```
94 | 2. **Navigate into Directory:**
95 | ```bash
96 | cd mcp-googledocs-server
97 | ```
98 | 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.
99 |
100 | ### Step 3: Install Dependencies
101 |
102 | Your server needs some helper libraries specified in the `package.json` file.
103 |
104 | 1. In your terminal (make sure you are inside the `mcp-googledocs-server` directory), run:
105 | ```bash
106 | npm install
107 | ```
108 | This will download and install all the necessary packages into a `node_modules` folder.
109 |
110 | ### Step 4: Build the Server Code
111 |
112 | The server is written in TypeScript (`.ts`), but we need to compile it into JavaScript (`.js`) that Node.js can run directly.
113 |
114 | 1. In your terminal, run:
115 | ```bash
116 | npm run build
117 | ```
118 | This uses the TypeScript compiler (`tsc`) to create a `dist` folder containing the compiled JavaScript files.
119 |
120 | ### Step 5: First Run & Google Authorization (One Time Only)
121 |
122 | 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.
123 |
124 | 1. In your terminal, run the _compiled_ server using `node`:
125 | ```bash
126 | node ./dist/server.js
127 | ```
128 | 2. **Watch the Terminal:** The script will print:
129 | - Status messages (like "Attempting to authorize...").
130 | - An "Authorize this app by visiting this url:" message followed by a long `https://accounts.google.com/...` URL.
131 | 3. **Authorize in Browser:**
132 | - Copy the entire long URL from the terminal.
133 | - Paste the URL into your web browser and press Enter.
134 | - Log in with the **same Google account** you added as a Test User in Step 1.4.
135 | - 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**".
136 | 4. **Get the Authorization Code:**
137 | - 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!**
138 | - Look **carefully** at the URL in your browser's address bar. It will look like `http://localhost/?code=4/0Axxxxxxxxxxxxxx&scope=...`
139 | - Copy the long string of characters **between `code=` and the `&scope` part**. This is your single-use authorization code.
140 | 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.
141 | 6. **Press Enter.**
142 | 7. **Success!** The script should print:
143 | - "Authentication successful!"
144 | - "Token stored to .../token.json"
145 | - 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).
146 | 8. ✅ **Check:** You should now see a new file named `token.json` in your `mcp-googledocs-server` folder.
147 | 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.
148 |
149 | ### Step 6: Configure Claude Desktop (Optional)
150 |
151 | If you want to use this server with Claude Desktop, you need to tell Claude how to run it.
152 |
153 | 1. **Find Your Absolute Path:** You need the full path to the server code.
154 | - In your terminal, make sure you are still inside the `mcp-googledocs-server` directory.
155 | - Run the `pwd` command (on macOS/Linux) or `cd` (on Windows, just displays the path).
156 | - Copy the full path (e.g., `/Users/yourname/projects/mcp-googledocs-server` or `C:\Users\yourname\projects\mcp-googledocs-server`).
157 | 2. **Locate `mcp_config.json`:** Find Claude's configuration file:
158 | - **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/`)
159 | - **Windows:** `%APPDATA%\Claude\mcp_config.json` (Paste `%APPDATA%\Claude` into File Explorer's address bar)
160 | - **Linux:** `~/.config/Claude/mcp_config.json`
161 | - _If the `Claude` folder or `mcp_config.json` file doesn't exist, create them._
162 | 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**:
163 |
164 | ```json
165 | {
166 | "mcpServers": {
167 | "google-docs-mcp": {
168 | "command": "node",
169 | "args": [
170 | "/PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js"
171 | ],
172 | "env": {}
173 | }
174 | // Add commas here if you have other servers defined
175 | }
176 | // Other Claude settings might be here
177 | }
178 | ```
179 |
180 | - **Make sure the path in `"args"` is correct and absolute!**
181 | - If the file already existed, carefully merge this entry into the existing `mcpServers` object. Ensure the JSON is valid (check commas!).
182 |
183 | 4. **Save `mcp_config.json`.**
184 | 5. **Restart Claude Desktop:** Close Claude completely and reopen it.
185 |
186 | ---
187 |
188 | ## Usage with Claude Desktop
189 |
190 | Once configured, you should be able to use the tools in your chats with Claude:
191 |
192 | - "Use the `google-docs-mcp` server to read the document with ID `YOUR_GOOGLE_DOC_ID`."
193 | - "Can you get the content of Google Doc `YOUR_GOOGLE_DOC_ID`?"
194 | - "Append 'This was added by Claude!' to document `YOUR_GOOGLE_DOC_ID` using the `google-docs-mcp` tool."
195 |
196 | Remember to replace `YOUR_GOOGLE_DOC_ID` with the actual ID from a Google Doc's URL (the long string between `/d/` and `/edit`).
197 |
198 | 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.
199 |
200 | ---
201 |
202 | ## Security & Token Storage
203 |
204 | - **`.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`**.
205 | - **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.
206 |
207 | ---
208 |
209 | ## Troubleshooting
210 |
211 | - **Claude shows "Failed" or "Could not attach":**
212 | - Double-check the absolute path in `mcp_config.json`.
213 | - Ensure you ran `npm run build` successfully and the `dist` folder exists.
214 | - 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.
215 | - Check the Claude Desktop logs (see the official MCP debugging guide).
216 | - Make sure all `console.log` status messages in the server code were changed to `console.error`.
217 | - **Google Authorization Errors:**
218 | - Ensure you enabled the correct APIs (Docs, Drive).
219 | - Make sure you added your email as a Test User on the OAuth Consent Screen.
220 | - Verify the `credentials.json` file is correctly placed in the project root.
221 |
222 | ---
223 |
224 | ## License
225 |
226 | 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).
227 |
228 | ---
229 |
```
--------------------------------------------------------------------------------
/src/googleDocsApiHelpers.ts:
--------------------------------------------------------------------------------
```typescript
1 | // src/googleDocsApiHelpers.ts
2 | import { google, docs_v1 } from 'googleapis';
3 | import { OAuth2Client } from 'google-auth-library';
4 | import { UserError } from 'fastmcp';
5 | import { TextStyleArgs, ParagraphStyleArgs, hexToRgbColor, NotImplementedError } from './types.js';
6 |
7 | type Docs = docs_v1.Docs; // Alias for convenience
8 |
9 | // --- Constants ---
10 | const MAX_BATCH_UPDATE_REQUESTS = 50; // Google API limits batch size
11 |
12 | // --- Core Helper to Execute Batch Updates ---
13 | export async function executeBatchUpdate(docs: Docs, documentId: string, requests: docs_v1.Schema$Request[]): Promise<docs_v1.Schema$BatchUpdateDocumentResponse> {
14 | if (!requests || requests.length === 0) {
15 | // console.warn("executeBatchUpdate called with no requests.");
16 | return {}; // Nothing to do
17 | }
18 |
19 | // TODO: Consider splitting large request arrays into multiple batches if needed
20 | if (requests.length > MAX_BATCH_UPDATE_REQUESTS) {
21 | console.warn(`Attempting batch update with ${requests.length} requests, exceeding typical limits. May fail.`);
22 | }
23 |
24 | try {
25 | const response = await docs.documents.batchUpdate({
26 | documentId: documentId,
27 | requestBody: { requests },
28 | });
29 | return response.data;
30 | } catch (error: any) {
31 | console.error(`Google API batchUpdate Error for doc ${documentId}:`, error.response?.data || error.message);
32 | // Translate common API errors to UserErrors
33 | if (error.code === 400 && error.message.includes('Invalid requests')) {
34 | // Try to extract more specific info if available
35 | const details = error.response?.data?.error?.details;
36 | let detailMsg = '';
37 | if (details && Array.isArray(details)) {
38 | detailMsg = details.map(d => d.description || JSON.stringify(d)).join('; ');
39 | }
40 | throw new UserError(`Invalid request sent to Google Docs API. Details: ${detailMsg || error.message}`);
41 | }
42 | if (error.code === 404) throw new UserError(`Document not found (ID: ${documentId}). Check the ID.`);
43 | if (error.code === 403) throw new UserError(`Permission denied for document (ID: ${documentId}). Ensure the authenticated user has edit access.`);
44 | // Generic internal error for others
45 | throw new Error(`Google API Error (${error.code}): ${error.message}`);
46 | }
47 |
48 | }
49 |
50 | // --- Text Finding Helper ---
51 | // This improved version is more robust in handling various text structure scenarios
52 | export async function findTextRange(docs: Docs, documentId: string, textToFind: string, instance: number = 1): Promise<{ startIndex: number; endIndex: number } | null> {
53 | try {
54 | // Request more detailed information about the document structure
55 | const res = await docs.documents.get({
56 | documentId,
57 | // Request more fields to handle various container types (not just paragraphs)
58 | fields: 'body(content(paragraph(elements(startIndex,endIndex,textRun(content))),table,sectionBreak,tableOfContents,startIndex,endIndex))',
59 | });
60 |
61 | if (!res.data.body?.content) {
62 | console.warn(`No content found in document ${documentId}`);
63 | return null;
64 | }
65 |
66 | // More robust text collection and index tracking
67 | let fullText = '';
68 | const segments: { text: string, start: number, end: number }[] = [];
69 |
70 | // Process all content elements, including structural ones
71 | const collectTextFromContent = (content: any[]) => {
72 | content.forEach(element => {
73 | // Handle paragraph elements
74 | if (element.paragraph?.elements) {
75 | element.paragraph.elements.forEach((pe: any) => {
76 | if (pe.textRun?.content && pe.startIndex !== undefined && pe.endIndex !== undefined) {
77 | const content = pe.textRun.content;
78 | fullText += content;
79 | segments.push({
80 | text: content,
81 | start: pe.startIndex,
82 | end: pe.endIndex
83 | });
84 | }
85 | });
86 | }
87 |
88 | // Handle table elements - this is simplified and might need expansion
89 | if (element.table && element.table.tableRows) {
90 | element.table.tableRows.forEach((row: any) => {
91 | if (row.tableCells) {
92 | row.tableCells.forEach((cell: any) => {
93 | if (cell.content) {
94 | collectTextFromContent(cell.content);
95 | }
96 | });
97 | }
98 | });
99 | }
100 |
101 | // Add handling for other structural elements as needed
102 | });
103 | };
104 |
105 | collectTextFromContent(res.data.body.content);
106 |
107 | // Sort segments by starting position to ensure correct ordering
108 | segments.sort((a, b) => a.start - b.start);
109 |
110 | console.log(`Document ${documentId} contains ${segments.length} text segments and ${fullText.length} characters in total.`);
111 |
112 | // Find the specified instance of the text
113 | let startIndex = -1;
114 | let endIndex = -1;
115 | let foundCount = 0;
116 | let searchStartIndex = 0;
117 |
118 | while (foundCount < instance) {
119 | const currentIndex = fullText.indexOf(textToFind, searchStartIndex);
120 | if (currentIndex === -1) {
121 | console.log(`Search text "${textToFind}" not found for instance ${foundCount + 1} (requested: ${instance})`);
122 | break;
123 | }
124 |
125 | foundCount++;
126 | console.log(`Found instance ${foundCount} of "${textToFind}" at position ${currentIndex} in full text`);
127 |
128 | if (foundCount === instance) {
129 | const targetStartInFullText = currentIndex;
130 | const targetEndInFullText = currentIndex + textToFind.length;
131 | let currentPosInFullText = 0;
132 |
133 | console.log(`Target text range in full text: ${targetStartInFullText}-${targetEndInFullText}`);
134 |
135 | for (const seg of segments) {
136 | const segStartInFullText = currentPosInFullText;
137 | const segTextLength = seg.text.length;
138 | const segEndInFullText = segStartInFullText + segTextLength;
139 |
140 | // Map from reconstructed text position to actual document indices
141 | if (startIndex === -1 && targetStartInFullText >= segStartInFullText && targetStartInFullText < segEndInFullText) {
142 | startIndex = seg.start + (targetStartInFullText - segStartInFullText);
143 | console.log(`Mapped start to segment ${seg.start}-${seg.end}, position ${startIndex}`);
144 | }
145 |
146 | if (targetEndInFullText > segStartInFullText && targetEndInFullText <= segEndInFullText) {
147 | endIndex = seg.start + (targetEndInFullText - segStartInFullText);
148 | console.log(`Mapped end to segment ${seg.start}-${seg.end}, position ${endIndex}`);
149 | break;
150 | }
151 |
152 | currentPosInFullText = segEndInFullText;
153 | }
154 |
155 | if (startIndex === -1 || endIndex === -1) {
156 | console.warn(`Failed to map text "${textToFind}" instance ${instance} to actual document indices`);
157 | // Reset and try next occurrence
158 | startIndex = -1;
159 | endIndex = -1;
160 | searchStartIndex = currentIndex + 1;
161 | foundCount--;
162 | continue;
163 | }
164 |
165 | console.log(`Successfully mapped "${textToFind}" to document range ${startIndex}-${endIndex}`);
166 | return { startIndex, endIndex };
167 | }
168 |
169 | // Prepare for next search iteration
170 | searchStartIndex = currentIndex + 1;
171 | }
172 |
173 | console.warn(`Could not find instance ${instance} of text "${textToFind}" in document ${documentId}`);
174 | return null; // Instance not found or mapping failed for all attempts
175 | } catch (error: any) {
176 | console.error(`Error finding text "${textToFind}" in doc ${documentId}: ${error.message || 'Unknown error'}`);
177 | if (error.code === 404) throw new UserError(`Document not found while searching text (ID: ${documentId}).`);
178 | if (error.code === 403) throw new UserError(`Permission denied while searching text in doc ${documentId}.`);
179 | throw new Error(`Failed to retrieve doc for text searching: ${error.message || 'Unknown error'}`);
180 | }
181 | }
182 |
183 | // --- Paragraph Boundary Helper ---
184 | // Enhanced version to handle document structural elements more robustly
185 | export async function getParagraphRange(docs: Docs, documentId: string, indexWithin: number): Promise<{ startIndex: number; endIndex: number } | null> {
186 | try {
187 | console.log(`Finding paragraph containing index ${indexWithin} in document ${documentId}`);
188 |
189 | // Request more detailed document structure to handle nested elements
190 | const res = await docs.documents.get({
191 | documentId,
192 | // Request more comprehensive structure information
193 | fields: 'body(content(startIndex,endIndex,paragraph,table,sectionBreak,tableOfContents))',
194 | });
195 |
196 | if (!res.data.body?.content) {
197 | console.warn(`No content found in document ${documentId}`);
198 | return null;
199 | }
200 |
201 | // Find paragraph containing the index
202 | // We'll look at all structural elements recursively
203 | const findParagraphInContent = (content: any[]): { startIndex: number; endIndex: number } | null => {
204 | for (const element of content) {
205 | // Check if we have element boundaries defined
206 | if (element.startIndex !== undefined && element.endIndex !== undefined) {
207 | // Check if index is within this element's range first
208 | if (indexWithin >= element.startIndex && indexWithin < element.endIndex) {
209 | // If it's a paragraph, we've found our target
210 | if (element.paragraph) {
211 | console.log(`Found paragraph containing index ${indexWithin}, range: ${element.startIndex}-${element.endIndex}`);
212 | return {
213 | startIndex: element.startIndex,
214 | endIndex: element.endIndex
215 | };
216 | }
217 |
218 | // If it's a table, we need to check cells recursively
219 | if (element.table && element.table.tableRows) {
220 | console.log(`Index ${indexWithin} is within a table, searching cells...`);
221 | for (const row of element.table.tableRows) {
222 | if (row.tableCells) {
223 | for (const cell of row.tableCells) {
224 | if (cell.content) {
225 | const result = findParagraphInContent(cell.content);
226 | if (result) return result;
227 | }
228 | }
229 | }
230 | }
231 | }
232 |
233 | // For other structural elements, we didn't find a paragraph
234 | // but we know the index is within this element
235 | console.warn(`Index ${indexWithin} is within element (${element.startIndex}-${element.endIndex}) but not in a paragraph`);
236 | }
237 | }
238 | }
239 |
240 | return null;
241 | };
242 |
243 | const paragraphRange = findParagraphInContent(res.data.body.content);
244 |
245 | if (!paragraphRange) {
246 | console.warn(`Could not find paragraph containing index ${indexWithin}`);
247 | } else {
248 | console.log(`Returning paragraph range: ${paragraphRange.startIndex}-${paragraphRange.endIndex}`);
249 | }
250 |
251 | return paragraphRange;
252 |
253 | } catch (error: any) {
254 | console.error(`Error getting paragraph range for index ${indexWithin} in doc ${documentId}: ${error.message || 'Unknown error'}`);
255 | if (error.code === 404) throw new UserError(`Document not found while finding paragraph (ID: ${documentId}).`);
256 | if (error.code === 403) throw new UserError(`Permission denied while accessing doc ${documentId}.`);
257 | throw new Error(`Failed to find paragraph: ${error.message || 'Unknown error'}`);
258 | }
259 | }
260 |
261 | // --- Style Request Builders ---
262 |
263 | export function buildUpdateTextStyleRequest(
264 | startIndex: number,
265 | endIndex: number,
266 | style: TextStyleArgs
267 | ): { request: docs_v1.Schema$Request, fields: string[] } | null {
268 | const textStyle: docs_v1.Schema$TextStyle = {};
269 | const fieldsToUpdate: string[] = [];
270 |
271 | if (style.bold !== undefined) { textStyle.bold = style.bold; fieldsToUpdate.push('bold'); }
272 | if (style.italic !== undefined) { textStyle.italic = style.italic; fieldsToUpdate.push('italic'); }
273 | if (style.underline !== undefined) { textStyle.underline = style.underline; fieldsToUpdate.push('underline'); }
274 | if (style.strikethrough !== undefined) { textStyle.strikethrough = style.strikethrough; fieldsToUpdate.push('strikethrough'); }
275 | if (style.fontSize !== undefined) { textStyle.fontSize = { magnitude: style.fontSize, unit: 'PT' }; fieldsToUpdate.push('fontSize'); }
276 | if (style.fontFamily !== undefined) { textStyle.weightedFontFamily = { fontFamily: style.fontFamily }; fieldsToUpdate.push('weightedFontFamily'); }
277 | if (style.foregroundColor !== undefined) {
278 | const rgbColor = hexToRgbColor(style.foregroundColor);
279 | if (!rgbColor) throw new UserError(`Invalid foreground hex color format: ${style.foregroundColor}`);
280 | textStyle.foregroundColor = { color: { rgbColor: rgbColor } }; fieldsToUpdate.push('foregroundColor');
281 | }
282 | if (style.backgroundColor !== undefined) {
283 | const rgbColor = hexToRgbColor(style.backgroundColor);
284 | if (!rgbColor) throw new UserError(`Invalid background hex color format: ${style.backgroundColor}`);
285 | textStyle.backgroundColor = { color: { rgbColor: rgbColor } }; fieldsToUpdate.push('backgroundColor');
286 | }
287 | if (style.linkUrl !== undefined) {
288 | textStyle.link = { url: style.linkUrl }; fieldsToUpdate.push('link');
289 | }
290 | // TODO: Handle clearing formatting
291 |
292 | if (fieldsToUpdate.length === 0) return null; // No styles to apply
293 |
294 | const request: docs_v1.Schema$Request = {
295 | updateTextStyle: {
296 | range: { startIndex, endIndex },
297 | textStyle: textStyle,
298 | fields: fieldsToUpdate.join(','),
299 | }
300 | };
301 | return { request, fields: fieldsToUpdate };
302 |
303 | }
304 |
305 | export function buildUpdateParagraphStyleRequest(
306 | startIndex: number,
307 | endIndex: number,
308 | style: ParagraphStyleArgs
309 | ): { request: docs_v1.Schema$Request, fields: string[] } | null {
310 | // Create style object and track which fields to update
311 | const paragraphStyle: docs_v1.Schema$ParagraphStyle = {};
312 | const fieldsToUpdate: string[] = [];
313 |
314 | console.log(`Building paragraph style request for range ${startIndex}-${endIndex} with options:`, style);
315 |
316 | // Process alignment option (LEFT, CENTER, RIGHT, JUSTIFIED)
317 | if (style.alignment !== undefined) {
318 | paragraphStyle.alignment = style.alignment;
319 | fieldsToUpdate.push('alignment');
320 | console.log(`Setting alignment to ${style.alignment}`);
321 | }
322 |
323 | // Process indentation options
324 | if (style.indentStart !== undefined) {
325 | paragraphStyle.indentStart = { magnitude: style.indentStart, unit: 'PT' };
326 | fieldsToUpdate.push('indentStart');
327 | console.log(`Setting left indent to ${style.indentStart}pt`);
328 | }
329 |
330 | if (style.indentEnd !== undefined) {
331 | paragraphStyle.indentEnd = { magnitude: style.indentEnd, unit: 'PT' };
332 | fieldsToUpdate.push('indentEnd');
333 | console.log(`Setting right indent to ${style.indentEnd}pt`);
334 | }
335 |
336 | // Process spacing options
337 | if (style.spaceAbove !== undefined) {
338 | paragraphStyle.spaceAbove = { magnitude: style.spaceAbove, unit: 'PT' };
339 | fieldsToUpdate.push('spaceAbove');
340 | console.log(`Setting space above to ${style.spaceAbove}pt`);
341 | }
342 |
343 | if (style.spaceBelow !== undefined) {
344 | paragraphStyle.spaceBelow = { magnitude: style.spaceBelow, unit: 'PT' };
345 | fieldsToUpdate.push('spaceBelow');
346 | console.log(`Setting space below to ${style.spaceBelow}pt`);
347 | }
348 |
349 | // Process named style types (headings, etc.)
350 | if (style.namedStyleType !== undefined) {
351 | paragraphStyle.namedStyleType = style.namedStyleType;
352 | fieldsToUpdate.push('namedStyleType');
353 | console.log(`Setting named style to ${style.namedStyleType}`);
354 | }
355 |
356 | // Process page break control
357 | if (style.keepWithNext !== undefined) {
358 | paragraphStyle.keepWithNext = style.keepWithNext;
359 | fieldsToUpdate.push('keepWithNext');
360 | console.log(`Setting keepWithNext to ${style.keepWithNext}`);
361 | }
362 |
363 | // Verify we have styles to apply
364 | if (fieldsToUpdate.length === 0) {
365 | console.warn("No paragraph styling options were provided");
366 | return null; // No styles to apply
367 | }
368 |
369 | // Build the request object
370 | const request: docs_v1.Schema$Request = {
371 | updateParagraphStyle: {
372 | range: { startIndex, endIndex },
373 | paragraphStyle: paragraphStyle,
374 | fields: fieldsToUpdate.join(','),
375 | }
376 | };
377 |
378 | console.log(`Created paragraph style request with fields: ${fieldsToUpdate.join(', ')}`);
379 | return { request, fields: fieldsToUpdate };
380 | }
381 |
382 | // --- Specific Feature Helpers ---
383 |
384 | export async function createTable(docs: Docs, documentId: string, rows: number, columns: number, index: number): Promise<docs_v1.Schema$BatchUpdateDocumentResponse> {
385 | if (rows < 1 || columns < 1) {
386 | throw new UserError("Table must have at least 1 row and 1 column.");
387 | }
388 | const request: docs_v1.Schema$Request = {
389 | insertTable: {
390 | location: { index },
391 | rows: rows,
392 | columns: columns,
393 | }
394 | };
395 | return executeBatchUpdate(docs, documentId, [request]);
396 | }
397 |
398 | export async function insertText(docs: Docs, documentId: string, text: string, index: number): Promise<docs_v1.Schema$BatchUpdateDocumentResponse> {
399 | if (!text) return {}; // Nothing to insert
400 | const request: docs_v1.Schema$Request = {
401 | insertText: {
402 | location: { index },
403 | text: text,
404 | }
405 | };
406 | return executeBatchUpdate(docs, documentId, [request]);
407 | }
408 |
409 | // --- Complex / Stubbed Helpers ---
410 |
411 | export async function findParagraphsMatchingStyle(
412 | docs: Docs,
413 | documentId: string,
414 | styleCriteria: any // Define a proper type for criteria (e.g., { fontFamily: 'Arial', bold: true })
415 | ): Promise<{ startIndex: number; endIndex: number }[]> {
416 | // TODO: Implement logic
417 | // 1. Get document content with paragraph elements and their styles.
418 | // 2. Iterate through paragraphs.
419 | // 3. For each paragraph, check if its computed style matches the criteria.
420 | // 4. Return ranges of matching paragraphs.
421 | console.warn("findParagraphsMatchingStyle is not implemented.");
422 | throw new NotImplementedError("Finding paragraphs by style criteria is not yet implemented.");
423 | // return [];
424 | }
425 |
426 | export async function detectAndFormatLists(
427 | docs: Docs,
428 | documentId: string,
429 | startIndex?: number,
430 | endIndex?: number
431 | ): Promise<docs_v1.Schema$BatchUpdateDocumentResponse> {
432 | // TODO: Implement complex logic
433 | // 1. Get document content (paragraphs, text runs) in the specified range (or whole doc).
434 | // 2. Iterate through paragraphs.
435 | // 3. Identify sequences of paragraphs starting with list-like markers (e.g., "-", "*", "1.", "a)").
436 | // 4. Determine nesting levels based on indentation or marker patterns.
437 | // 5. Generate CreateParagraphBulletsRequests for the identified sequences.
438 | // 6. Potentially delete the original marker text.
439 | // 7. Execute the batch update.
440 | console.warn("detectAndFormatLists is not implemented.");
441 | throw new NotImplementedError("Automatic list detection and formatting is not yet implemented.");
442 | // return {};
443 | }
444 |
445 | export async function addCommentHelper(docs: Docs, documentId: string, text: string, startIndex: number, endIndex: number): Promise<void> {
446 | // NOTE: Adding comments typically requires the Google Drive API v3 and different scopes!
447 | // 'https://www.googleapis.com/auth/drive' or more specific comment scopes.
448 | // This helper is a placeholder assuming Drive API client (`drive`) is available and authorized.
449 | /*
450 | const drive = google.drive({version: 'v3', auth: authClient}); // Assuming authClient is available
451 | await drive.comments.create({
452 | fileId: documentId,
453 | requestBody: {
454 | content: text,
455 | anchor: JSON.stringify({ // Anchor format might need verification
456 | 'type': 'workbook#textAnchor', // Or appropriate type for Docs
457 | 'refs': [{
458 | 'docRevisionId': 'head', // Or specific revision
459 | 'range': {
460 | 'start': startIndex,
461 | 'end': endIndex,
462 | }
463 | }]
464 | })
465 | },
466 | fields: 'id'
467 | });
468 | */
469 | console.warn("addCommentHelper requires Google Drive API and is not implemented.");
470 | throw new NotImplementedError("Adding comments requires Drive API setup and is not yet implemented.");
471 | }
472 |
473 | // --- Image Insertion Helpers ---
474 |
475 | /**
476 | * Inserts an inline image into a document from a publicly accessible URL
477 | * @param docs - Google Docs API client
478 | * @param documentId - The document ID
479 | * @param imageUrl - Publicly accessible URL to the image
480 | * @param index - Position in the document where image should be inserted (1-based)
481 | * @param width - Optional width in points
482 | * @param height - Optional height in points
483 | * @returns Promise with batch update response
484 | */
485 | export async function insertInlineImage(
486 | docs: Docs,
487 | documentId: string,
488 | imageUrl: string,
489 | index: number,
490 | width?: number,
491 | height?: number
492 | ): Promise<docs_v1.Schema$BatchUpdateDocumentResponse> {
493 | // Validate URL format
494 | try {
495 | new URL(imageUrl);
496 | } catch (e) {
497 | throw new UserError(`Invalid image URL format: ${imageUrl}`);
498 | }
499 |
500 | // Build the insertInlineImage request
501 | const request: docs_v1.Schema$Request = {
502 | insertInlineImage: {
503 | location: { index },
504 | uri: imageUrl,
505 | ...(width && height && {
506 | objectSize: {
507 | height: { magnitude: height, unit: 'PT' },
508 | width: { magnitude: width, unit: 'PT' }
509 | }
510 | })
511 | }
512 | };
513 |
514 | return executeBatchUpdate(docs, documentId, [request]);
515 | }
516 |
517 | /**
518 | * Uploads a local image file to Google Drive and returns its public URL
519 | * @param drive - Google Drive API client
520 | * @param localFilePath - Path to the local image file
521 | * @param parentFolderId - Optional parent folder ID (defaults to root)
522 | * @returns Promise with the public webContentLink URL
523 | */
524 | export async function uploadImageToDrive(
525 | drive: any, // drive_v3.Drive type
526 | localFilePath: string,
527 | parentFolderId?: string
528 | ): Promise<string> {
529 | const fs = await import('fs');
530 | const path = await import('path');
531 |
532 | // Verify file exists
533 | if (!fs.existsSync(localFilePath)) {
534 | throw new UserError(`Image file not found: ${localFilePath}`);
535 | }
536 |
537 | // Get file name and mime type
538 | const fileName = path.basename(localFilePath);
539 | const mimeTypeMap: { [key: string]: string } = {
540 | '.jpg': 'image/jpeg',
541 | '.jpeg': 'image/jpeg',
542 | '.png': 'image/png',
543 | '.gif': 'image/gif',
544 | '.bmp': 'image/bmp',
545 | '.webp': 'image/webp',
546 | '.svg': 'image/svg+xml'
547 | };
548 |
549 | const ext = path.extname(localFilePath).toLowerCase();
550 | const mimeType = mimeTypeMap[ext] || 'application/octet-stream';
551 |
552 | // Upload file to Drive
553 | const fileMetadata: any = {
554 | name: fileName,
555 | mimeType: mimeType
556 | };
557 |
558 | if (parentFolderId) {
559 | fileMetadata.parents = [parentFolderId];
560 | }
561 |
562 | const media = {
563 | mimeType: mimeType,
564 | body: fs.createReadStream(localFilePath)
565 | };
566 |
567 | const uploadResponse = await drive.files.create({
568 | requestBody: fileMetadata,
569 | media: media,
570 | fields: 'id,webViewLink,webContentLink'
571 | });
572 |
573 | const fileId = uploadResponse.data.id;
574 | if (!fileId) {
575 | throw new Error('Failed to upload image to Drive - no file ID returned');
576 | }
577 |
578 | // Make the file publicly readable
579 | await drive.permissions.create({
580 | fileId: fileId,
581 | requestBody: {
582 | role: 'reader',
583 | type: 'anyone'
584 | }
585 | });
586 |
587 | // Get the webContentLink
588 | const fileInfo = await drive.files.get({
589 | fileId: fileId,
590 | fields: 'webContentLink'
591 | });
592 |
593 | const webContentLink = fileInfo.data.webContentLink;
594 | if (!webContentLink) {
595 | throw new Error('Failed to get public URL for uploaded image');
596 | }
597 |
598 | return webContentLink;
599 | }
```