minimal-gdocs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rowan Bradley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# minimal-gdocs
+
+A minimal MCP server for creating and updating Google Docs from markdown. Built for [Claude Code](https://claude.ai/claude-code).
+
+## Features
+
+- **Create Google Docs** from markdown with native formatting
+- **Update existing docs** (replace or append)
+- **List recent docs** with optional search
+- **Full markdown support:**
+  - Headings (H1-H6)
+  - Bold, italic, and **nested *formatting***
+  - Bullet and numbered lists
+  - Links
+  - Horizontal rules
+  - Code blocks (monospace)
+
+## Design Philosophy
+
+minimal-gdocs intentionally stays minimal:
+- **4 core tools** covering the essential document lifecycle
+- **Zero configuration** beyond OAuth credentials
+- **No batch operations** or complex workflows
+- **~274 tokens** of context overhead (vs ~3,000 for full-featured alternatives)
+
+If you need advanced features (comments, sheets, drive management, sharing), consider [google-docs-mcp](https://github.com/a-bonus/google-docs-mcp) instead.
+
+## Installation
+
+```bash
+git clone https://github.com/rowbradley/minimal-gdocs.git
+cd minimal-gdocs
+npm install
+npm run build
+```
+
+Or via npm (once published):
+```bash
+npx minimal-gdocs
+```
+
+## Google Cloud Setup
+
+You need Google OAuth credentials. Choose **one** of these methods:
+
+### Option A: Google Cloud Console (Web)
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project (or select existing)
+3. Enable the **Google Docs API**:
+   - Go to "APIs & Services" → "Library"
+   - Search "Google Docs API" → Enable
+4. Create OAuth credentials:
+   - Go to "APIs & Services" → "Credentials"
+   - Click "Create Credentials" → "OAuth client ID"
+   - Application type: **Desktop app**
+   - Download the JSON file
+5. Rename it to `credentials.json` and place in project root
+
+### Option B: gcloud CLI
+
+```bash
+# Install gcloud if needed: https://cloud.google.com/sdk/docs/install
+
+# Login and set project
+gcloud auth login
+gcloud projects create minimal-gdocs-project --name="Minimal GDocs"
+gcloud config set project minimal-gdocs-project
+
+# Enable Docs API
+gcloud services enable docs.googleapis.com
+
+# Create OAuth credentials
+gcloud auth application-default login --scopes=https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/drive.file
+
+# For MCP server, you still need OAuth client credentials:
+# Go to console.cloud.google.com → APIs & Services → Credentials
+# Create "OAuth client ID" → Desktop app → Download JSON
+```
+
+## Claude Code Configuration
+
+Add to your Claude Code `settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "gdocs": {
+      "command": "node",
+      "args": ["/path/to/minimal-gdocs/dist/index.js"]
+    }
+  }
+}
+```
+
+Or if installed globally via npm:
+```json
+{
+  "mcpServers": {
+    "gdocs": {
+      "command": "npx",
+      "args": ["minimal-gdocs"]
+    }
+  }
+}
+```
+
+## First Run
+
+On first use, the server will:
+1. Open your browser for Google OAuth consent
+2. Ask you to authorize access to Google Docs
+3. Save the token locally (in `token.json`)
+
+Subsequent runs use the saved token automatically.
+
+## Usage
+
+Once configured, Claude Code can use these tools:
+
+### create_google_doc
+```
+Create a Google Doc from markdown:
+- title: Document title
+- content: Markdown content
+- folderId: (optional) Google Drive folder ID
+```
+
+### update_google_doc
+```
+Update an existing doc:
+- docId: The Google Doc ID
+- content: New markdown content
+- mode: "replace" or "append"
+```
+
+### list_recent_docs
+```
+List your recent Google Docs:
+- limit: (optional) Max docs to return
+- query: (optional) Search filter
+```
+
+### get_doc_url
+```
+Get URLs for a doc:
+- docId: The Google Doc ID
+Returns: edit URL, view URL, PDF export URL
+```
+
+## Example
+
+In Claude Code:
+```
+"Publish this to Google Docs"
+
+# My Document
+
+Here's some **bold** and *italic* text.
+
+- Bullet one
+- Bullet two
+
+1. Numbered item
+2. Another item
+```
+
+Creates a properly formatted Google Doc with native styling.
+
+## License
+
+MIT

package/credentials.example.json

@@ -0,0 +1,11 @@
+{
+  "installed": {
+    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
+    "project_id": "your-project-id",
+    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+    "token_uri": "https://oauth2.googleapis.com/token",
+    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+    "client_secret": "YOUR_CLIENT_SECRET",
+    "redirect_uris": ["http://localhost"]
+  }
+}

package/dist/auth.d.ts

@@ -0,0 +1,2 @@
+import { OAuth2Client } from 'google-auth-library';
+export declare function getAuthClient(): Promise<OAuth2Client>;

package/dist/auth.js

@@ -0,0 +1,83 @@
+import { google } from 'googleapis';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as http from 'http';
+import open from 'open';
+const SCOPES = [
+    'https://www.googleapis.com/auth/documents',
+    'https://www.googleapis.com/auth/drive.file',
+    'https://www.googleapis.com/auth/drive.metadata.readonly'
+];
+const CREDENTIALS_PATH = path.join(import.meta.dirname, '..', 'credentials.json');
+const TOKEN_PATH = path.join(import.meta.dirname, '..', 'token.json');
+export async function getAuthClient() {
+    const credentials = JSON.parse(fs.readFileSync(CREDENTIALS_PATH, 'utf-8'));
+    const { client_id, client_secret } = credentials.installed;
+    const oAuth2Client = new google.auth.OAuth2(client_id, client_secret, 'http://localhost:3000/oauth2callback');
+    // Check for existing token
+    if (fs.existsSync(TOKEN_PATH)) {
+        const token = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf-8'));
+        oAuth2Client.setCredentials(token);
+        // Check if token is expired and refresh if needed
+        if (token.expiry_date && token.expiry_date < Date.now()) {
+            try {
+                const { credentials } = await oAuth2Client.refreshAccessToken();
+                oAuth2Client.setCredentials(credentials);
+                fs.writeFileSync(TOKEN_PATH, JSON.stringify(credentials));
+            }
+            catch (error) {
+                // Token refresh failed, need to re-authenticate
+                return await authenticateWithBrowser(oAuth2Client);
+            }
+        }
+        return oAuth2Client;
+    }
+    // No token, need to authenticate
+    return await authenticateWithBrowser(oAuth2Client);
+}
+async function authenticateWithBrowser(oAuth2Client) {
+    return new Promise((resolve, reject) => {
+        const authUrl = oAuth2Client.generateAuthUrl({
+            access_type: 'offline',
+            scope: SCOPES,
+            prompt: 'consent'
+        });
+        // Create a simple server to receive the callback
+        const server = http.createServer(async (req, res) => {
+            if (req.url?.startsWith('/oauth2callback')) {
+                const url = new URL(req.url, 'http://localhost:3000');
+                const code = url.searchParams.get('code');
+                if (code) {
+                    try {
+                        const { tokens } = await oAuth2Client.getToken(code);
+                        oAuth2Client.setCredentials(tokens);
+                        fs.writeFileSync(TOKEN_PATH, JSON.stringify(tokens));
+                        res.writeHead(200, { 'Content-Type': 'text/html' });
+                        res.end('<html><body><h1>Authentication successful!</h1><p>You can close this window.</p></body></html>');
+                        server.close();
+                        resolve(oAuth2Client);
+                    }
+                    catch (error) {
+                        res.writeHead(500, { 'Content-Type': 'text/html' });
+                        res.end('<html><body><h1>Authentication failed</h1></body></html>');
+                        server.close();
+                        reject(error);
+                    }
+                }
+                else {
+                    res.writeHead(400, { 'Content-Type': 'text/html' });
+                    res.end('<html><body><h1>No code received</h1></body></html>');
+                }
+            }
+        });
+        server.listen(3000, () => {
+            console.error('Opening browser for authentication...');
+            open(authUrl);
+        });
+        // Timeout after 2 minutes
+        setTimeout(() => {
+            server.close();
+            reject(new Error('Authentication timed out'));
+        }, 120000);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { google } from 'googleapis';
+import { getAuthClient } from './auth.js';
+import { markdownToDocsRequests } from './utils/markdown-to-docs.js';
+const server = new Server({ name: 'gdocs-minimal', version: '1.0.0' }, { capabilities: { tools: {} } });
+// Tool definitions
+const TOOLS = [
+    {
+        name: 'create_google_doc',
+        description: 'Create a new Google Doc from markdown content',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: 'Document title' },
+                content: { type: 'string', description: 'Markdown content for the document' },
+                folderId: { type: 'string', description: 'Optional Google Drive folder ID to create the doc in' }
+            },
+            required: ['title', 'content']
+        }
+    },
+    {
+        name: 'update_google_doc',
+        description: 'Update an existing Google Doc with new markdown content',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                docId: { type: 'string', description: 'Google Doc ID' },
+                content: { type: 'string', description: 'New markdown content' },
+                mode: { type: 'string', enum: ['replace', 'append'], description: 'Replace all content or append to end' }
+            },
+            required: ['docId', 'content']
+        }
+    },
+    {
+        name: 'list_recent_docs',
+        description: 'List recent Google Docs from your Drive',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: { type: 'number', description: 'Maximum number of docs to return (default 10)' },
+                query: { type: 'string', description: 'Optional search query to filter docs by name' }
+            }
+        }
+    },
+    {
+        name: 'get_doc_url',
+        description: 'Get the URL for a Google Doc',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                docId: { type: 'string', description: 'Google Doc ID' }
+            },
+            required: ['docId']
+        }
+    }
+];
+// Register tool list handler
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS
+}));
+// Register tool call handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        const auth = await getAuthClient();
+        const docs = google.docs({ version: 'v1', auth });
+        const drive = google.drive({ version: 'v3', auth });
+        switch (name) {
+            case 'create_google_doc': {
+                const { title, content, folderId } = args;
+                // Create the document
+                const createResponse = await docs.documents.create({
+                    requestBody: { title }
+                });
+                const docId = createResponse.data.documentId;
+                // Convert markdown to Docs API requests and apply
+                const requests = markdownToDocsRequests(content);
+                if (requests.length > 0) {
+                    await docs.documents.batchUpdate({
+                        documentId: docId,
+                        requestBody: { requests }
+                    });
+                }
+                // Move to folder if specified
+                if (folderId) {
+                    await drive.files.update({
+                        fileId: docId,
+                        addParents: folderId,
+                        fields: 'id, parents'
+                    });
+                }
+                const url = `https://docs.google.com/document/d/${docId}/edit`;
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ docId, url, title }, null, 2) }]
+                };
+            }
+            case 'update_google_doc': {
+                const { docId, content, mode = 'replace' } = args;
+                if (mode === 'replace') {
+                    // Get current document to find content length
+                    const doc = await docs.documents.get({ documentId: docId });
+                    const endIndex = doc.data.body?.content?.slice(-1)[0]?.endIndex || 1;
+                    // Delete existing content (except the trailing newline)
+                    if (endIndex > 2) {
+                        await docs.documents.batchUpdate({
+                            documentId: docId,
+                            requestBody: {
+                                requests: [{ deleteContentRange: { range: { startIndex: 1, endIndex: endIndex - 1 } } }]
+                            }
+                        });
+                    }
+                }
+                // Insert new content
+                const requests = markdownToDocsRequests(content);
+                if (requests.length > 0) {
+                    // For append mode, we need to get the current end index
+                    if (mode === 'append') {
+                        const doc = await docs.documents.get({ documentId: docId });
+                        const endIndex = (doc.data.body?.content?.slice(-1)[0]?.endIndex || 1) - 1;
+                        // Adjust all request indices
+                        for (const req of requests) {
+                            if (req.insertText?.location?.index != null) {
+                                req.insertText.location.index += endIndex;
+                            }
+                            if (req.updateTextStyle?.range) {
+                                req.updateTextStyle.range.startIndex += endIndex;
+                                req.updateTextStyle.range.endIndex += endIndex;
+                            }
+                            if (req.updateParagraphStyle?.range) {
+                                req.updateParagraphStyle.range.startIndex += endIndex;
+                                req.updateParagraphStyle.range.endIndex += endIndex;
+                            }
+                            if (req.createParagraphBullets?.range) {
+                                req.createParagraphBullets.range.startIndex += endIndex;
+                                req.createParagraphBullets.range.endIndex += endIndex;
+                            }
+                        }
+                    }
+                    await docs.documents.batchUpdate({
+                        documentId: docId,
+                        requestBody: { requests }
+                    });
+                }
+                const url = `https://docs.google.com/document/d/${docId}/edit`;
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ success: true, docId, url }, null, 2) }]
+                };
+            }
+            case 'list_recent_docs': {
+                const { limit = 10, query } = args;
+                let q = "mimeType='application/vnd.google-apps.document'";
+                if (query) {
+                    q += ` and name contains '${query}'`;
+                }
+                const response = await drive.files.list({
+                    q,
+                    pageSize: limit,
+                    orderBy: 'modifiedTime desc',
+                    fields: 'files(id, name, modifiedTime, webViewLink)'
+                });
+                const docs = response.data.files?.map(file => ({
+                    id: file.id,
+                    title: file.name,
+                    modifiedTime: file.modifiedTime,
+                    url: file.webViewLink
+                })) || [];
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ docs }, null, 2) }]
+                };
+            }
+            case 'get_doc_url': {
+                const { docId } = args;
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                url: `https://docs.google.com/document/d/${docId}/edit`,
+                                viewUrl: `https://docs.google.com/document/d/${docId}/view`,
+                                exportPdfUrl: `https://docs.google.com/document/d/${docId}/export?format=pdf`
+                            }, null, 2)
+                        }]
+                };
+            }
+            default:
+                return {
+                    content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+                    isError: true
+                };
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: 'text', text: `Error: ${message}` }],
+            isError: true
+        };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('GDocs Minimal MCP server running');
+}
+main().catch(console.error);

package/dist/utils/markdown-to-docs.d.ts

@@ -0,0 +1,8 @@
+import { docs_v1 } from 'googleapis';
+type Request = docs_v1.Schema$Request;
+/**
+ * Convert markdown to Google Docs API requests
+ * Two-pass approach: collect all content first, then generate requests
+ */
+export declare function markdownToDocsRequests(markdown: string): Request[];
+export {};

package/dist/utils/markdown-to-docs.js

@@ -0,0 +1,344 @@
+/**
+ * Convert markdown to Google Docs API requests
+ * Two-pass approach: collect all content first, then generate requests
+ */
+export function markdownToDocsRequests(markdown) {
+    // Pass 1: Parse markdown into blocks
+    const blocks = parseMarkdown(markdown);
+    // Pass 2: Generate requests (inserts first, then formatting)
+    return generateRequests(blocks);
+}
+function parseMarkdown(markdown) {
+    const blocks = [];
+    const lines = markdown.split('\n');
+    let inCodeBlock = false;
+    let codeBlockContent = '';
+    for (const line of lines) {
+        // Handle code blocks
+        if (line.startsWith('```')) {
+            if (inCodeBlock) {
+                if (codeBlockContent) {
+                    blocks.push({
+                        type: 'code',
+                        cleanText: codeBlockContent,
+                        styles: []
+                    });
+                }
+                inCodeBlock = false;
+                codeBlockContent = '';
+            }
+            else {
+                inCodeBlock = true;
+            }
+            continue;
+        }
+        if (inCodeBlock) {
+            codeBlockContent += (codeBlockContent ? '\n' : '') + line;
+            continue;
+        }
+        // Skip empty lines - add empty paragraph
+        if (!line.trim()) {
+            blocks.push({ type: 'paragraph', cleanText: '', styles: [] });
+            continue;
+        }
+        // Parse the line into a block
+        blocks.push(parseLine(line));
+    }
+    return blocks;
+}
+function parseLine(line) {
+    // Headings: # Heading
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+        const { cleanText, styles } = parseInlineFormatting(headingMatch[2]);
+        return { type: 'heading', level: headingMatch[1].length, cleanText, styles };
+    }
+    // Horizontal rule: --- or *** or ___
+    if (/^[-*_]{3,}$/.test(line.trim())) {
+        return { type: 'hr', cleanText: '', styles: [] };
+    }
+    // Bullet lists: - item or * item
+    const bulletMatch = line.match(/^(\s*)[-*]\s+(.+)$/);
+    if (bulletMatch) {
+        const { cleanText, styles } = parseInlineFormatting(bulletMatch[2]);
+        return { type: 'bullet', level: Math.floor(bulletMatch[1].length / 2), cleanText, styles };
+    }
+    // Numbered lists: 1. item
+    const numberedMatch = line.match(/^(\s*)\d+\.\s+(.+)$/);
+    if (numberedMatch) {
+        const { cleanText, styles } = parseInlineFormatting(numberedMatch[2]);
+        return { type: 'numbered', level: Math.floor(numberedMatch[1].length / 2), cleanText, styles };
+    }
+    // Regular paragraph
+    const { cleanText, styles } = parseInlineFormatting(line);
+    return { type: 'paragraph', cleanText, styles };
+}
+function parseInlineFormatting(text) {
+    const styles = [];
+    const spans = [];
+    // 1. Find all links: [text](url)
+    const linkRegex = /\[([^\]]+)\]\(([^)]+)\)/g;
+    let match;
+    while ((match = linkRegex.exec(text)) !== null) {
+        spans.push({
+            type: 'link',
+            start: match.index,
+            end: match.index + match[0].length,
+            innerStart: match.index + 1, // after [
+            innerEnd: match.index + 1 + match[1].length, // before ]
+            url: match[2]
+        });
+    }
+    // 2. Find bold+italic: ***text*** (must be before bold/italic)
+    const boldItalicRegex = /\*\*\*(.+?)\*\*\*/g;
+    while ((match = boldItalicRegex.exec(text)) !== null) {
+        // Add both bold and italic spans for the same range
+        spans.push({
+            type: 'bold',
+            start: match.index,
+            end: match.index + match[0].length,
+            innerStart: match.index + 3,
+            innerEnd: match.index + 3 + match[1].length
+        });
+        spans.push({
+            type: 'italic',
+            start: match.index,
+            end: match.index + match[0].length,
+            innerStart: match.index + 3,
+            innerEnd: match.index + 3 + match[1].length
+        });
+    }
+    // 3. Find bold: **text** (non-greedy, allows nested *)
+    const boldRegex = /\*\*(.+?)\*\*/g;
+    while ((match = boldRegex.exec(text)) !== null) {
+        // Skip if this overlaps with a bold+italic span
+        const overlaps = spans.some(s => s.type === 'bold' &&
+            !(match.index >= s.end || match.index + match[0].length <= s.start));
+        if (!overlaps) {
+            spans.push({
+                type: 'bold',
+                start: match.index,
+                end: match.index + match[0].length,
+                innerStart: match.index + 2,
+                innerEnd: match.index + 2 + match[1].length
+            });
+        }
+    }
+    // 4. Find italic: *text* (not adjacent to other *)
+    const italicRegex = /(?<!\*)\*([^*]+)\*(?!\*)/g;
+    while ((match = italicRegex.exec(text)) !== null) {
+        spans.push({
+            type: 'italic',
+            start: match.index,
+            end: match.index + match[0].length,
+            innerStart: match.index + 1,
+            innerEnd: match.index + 1 + match[1].length
+        });
+    }
+    // 5. Build clean text by removing all markdown syntax
+    // Sort spans by start position
+    spans.sort((a, b) => a.start - b.start);
+    // Build a map of characters to remove
+    const toRemove = new Set();
+    for (const span of spans) {
+        if (span.type === 'link') {
+            // Remove [ ] ( url )
+            toRemove.add(span.start); // [
+            for (let i = span.innerEnd; i < span.end; i++) {
+                toRemove.add(i); // ](url)
+            }
+        }
+        else if (span.type === 'bold') {
+            // Check if this is part of a *** sequence
+            const isBoldItalic = spans.some(s => s.type === 'italic' && s.start === span.start && s.end === span.end);
+            if (isBoldItalic) {
+                // Remove ***, not **
+                toRemove.add(span.start);
+                toRemove.add(span.start + 1);
+                toRemove.add(span.start + 2);
+                toRemove.add(span.end - 3);
+                toRemove.add(span.end - 2);
+                toRemove.add(span.end - 1);
+            }
+            else {
+                toRemove.add(span.start);
+                toRemove.add(span.start + 1);
+                toRemove.add(span.end - 2);
+                toRemove.add(span.end - 1);
+            }
+        }
+        else if (span.type === 'italic') {
+            // Skip if part of bold+italic (already handled)
+            const isBoldItalic = spans.some(s => s.type === 'bold' && s.start === span.start && s.end === span.end);
+            if (!isBoldItalic) {
+                toRemove.add(span.start);
+                toRemove.add(span.end - 1);
+            }
+        }
+    }
+    // Build clean text and position mapping
+    let cleanText = '';
+    const positionMap = []; // positionMap[cleanIndex] = originalIndex
+    for (let i = 0; i < text.length; i++) {
+        if (!toRemove.has(i)) {
+            positionMap.push(i);
+            cleanText += text[i];
+        }
+    }
+    // 6. Convert spans to styles with clean text positions
+    for (const span of spans) {
+        // Find where innerStart and innerEnd map to in clean text
+        let cleanStart = -1;
+        let cleanEnd = -1;
+        for (let i = 0; i < positionMap.length; i++) {
+            if (positionMap[i] >= span.innerStart && cleanStart === -1) {
+                cleanStart = i;
+            }
+            if (positionMap[i] < span.innerEnd) {
+                cleanEnd = i + 1;
+            }
+        }
+        if (cleanStart !== -1 && cleanEnd !== -1 && cleanStart < cleanEnd) {
+            // For bold+italic, we already added both spans, so skip duplicate italic
+            const isDuplicateBoldItalic = span.type === 'italic' && spans.some(s => s.type === 'bold' && s.start === span.start && s.end === span.end);
+            if (!isDuplicateBoldItalic || span.type === 'bold') {
+                styles.push({
+                    type: span.type,
+                    start: cleanStart,
+                    end: cleanEnd,
+                    url: span.url
+                });
+            }
+            // Add italic style for bold+italic combo
+            if (span.type === 'bold') {
+                const hasMatchingItalic = spans.some(s => s.type === 'italic' && s.start === span.start && s.end === span.end);
+                if (hasMatchingItalic) {
+                    styles.push({
+                        type: 'italic',
+                        start: cleanStart,
+                        end: cleanEnd
+                    });
+                }
+            }
+        }
+    }
+    return { cleanText, styles };
+}
+function generateRequests(blocks) {
+    const insertRequests = [];
+    const formatRequests = [];
+    let currentIndex = 1; // Google Docs starts at index 1
+    for (const block of blocks) {
+        const text = block.cleanText + '\n';
+        const startIndex = currentIndex;
+        const endIndex = currentIndex + text.length;
+        // Insert text request
+        insertRequests.push({
+            insertText: {
+                location: { index: startIndex },
+                text
+            }
+        });
+        // Block-level formatting
+        if (block.type === 'heading' && block.level) {
+            formatRequests.push({
+                updateParagraphStyle: {
+                    range: { startIndex, endIndex },
+                    paragraphStyle: { namedStyleType: getHeadingStyle(block.level) },
+                    fields: 'namedStyleType'
+                }
+            });
+        }
+        else if (block.type === 'bullet') {
+            formatRequests.push({
+                createParagraphBullets: {
+                    range: { startIndex, endIndex },
+                    bulletPreset: 'BULLET_DISC_CIRCLE_SQUARE'
+                }
+            });
+        }
+        else if (block.type === 'numbered') {
+            formatRequests.push({
+                createParagraphBullets: {
+                    range: { startIndex, endIndex },
+                    bulletPreset: 'NUMBERED_DECIMAL_NESTED'
+                }
+            });
+        }
+        else if (block.type === 'code') {
+            formatRequests.push({
+                updateTextStyle: {
+                    range: { startIndex, endIndex: endIndex - 1 }, // exclude trailing newline
+                    textStyle: {
+                        weightedFontFamily: { fontFamily: 'Courier New' },
+                        fontSize: { magnitude: 10, unit: 'PT' }
+                    },
+                    fields: 'weightedFontFamily,fontSize'
+                }
+            });
+        }
+        else if (block.type === 'hr') {
+            // Google Docs doesn't have native HR - use bottom border on empty paragraph
+            formatRequests.push({
+                updateParagraphStyle: {
+                    range: { startIndex, endIndex },
+                    paragraphStyle: {
+                        borderBottom: {
+                            color: { color: { rgbColor: { red: 0.8, green: 0.8, blue: 0.8 } } },
+                            width: { magnitude: 1, unit: 'PT' },
+                            padding: { magnitude: 8, unit: 'PT' },
+                            dashStyle: 'SOLID'
+                        }
+                    },
+                    fields: 'borderBottom'
+                }
+            });
+        }
+        // Inline formatting (bold, italic, links)
+        for (const style of block.styles) {
+            const styleStart = startIndex + style.start;
+            const styleEnd = startIndex + style.end;
+            if (style.type === 'bold') {
+                formatRequests.push({
+                    updateTextStyle: {
+                        range: { startIndex: styleStart, endIndex: styleEnd },
+                        textStyle: { bold: true },
+                        fields: 'bold'
+                    }
+                });
+            }
+            else if (style.type === 'italic') {
+                formatRequests.push({
+                    updateTextStyle: {
+                        range: { startIndex: styleStart, endIndex: styleEnd },
+                        textStyle: { italic: true },
+                        fields: 'italic'
+                    }
+                });
+            }
+            else if (style.type === 'link' && style.url) {
+                formatRequests.push({
+                    updateTextStyle: {
+                        range: { startIndex: styleStart, endIndex: styleEnd },
+                        textStyle: { link: { url: style.url } },
+                        fields: 'link'
+                    }
+                });
+            }
+        }
+        currentIndex = endIndex;
+    }
+    // Return inserts first, then formatting
+    return [...insertRequests, ...formatRequests];
+}
+function getHeadingStyle(level) {
+    const styles = {
+        1: 'HEADING_1',
+        2: 'HEADING_2',
+        3: 'HEADING_3',
+        4: 'HEADING_4',
+        5: 'HEADING_5',
+        6: 'HEADING_6'
+    };
+    return styles[level] || 'NORMAL_TEXT';
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "minimal-gdocs",
+  "version": "1.0.0",
+  "description": "Minimal MCP server for creating and updating Google Docs from markdown",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "minimal-gdocs": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "google-docs",
+    "claude",
+    "markdown",
+    "anthropic"
+  ],
+  "author": "Rowan Bradley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rowbradley/minimal-gdocs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rowbradley/minimal-gdocs/issues"
+  },
+  "homepage": "https://github.com/rowbradley/minimal-gdocs#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "googleapis": "^140.0.0",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "credentials.example.json",
+    "README.md",
+    "LICENSE"
+  ]
+}