@brainwavesio/google-docs-mcp 1.0.1 → 1.1.0

package/README.md

@@ -8,13 +8,12 @@ Connect Claude Desktop (or other MCP clients) to your Google Docs, Google Sheets
 
 ## Quick Start (npx)
 
-If you have Google OAuth credentials, you can run this server without cloning:
+**1. Get Google OAuth credentials** from [Google Cloud Console](https://console.cloud.google.com/):
+   - Create a project and enable Google Docs, Sheets, and Drive APIs
+   - Create OAuth 2.0 credentials (Desktop app type)
+   - Download the client ID and secret
 
-```bash
-npx @brainwavesio/google-docs-mcp
-```
-
-Or configure in Claude Desktop's `mcp_config.json`:
+**2. Configure Claude Desktop** (`mcp_config.json` or `.mcp.json`):
 
 ```json
 {
@@ -24,15 +23,16 @@ Or configure in Claude Desktop's `mcp_config.json`:
       "args": ["@brainwavesio/google-docs-mcp"],
       "env": {
         "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
-        "GOOGLE_CLIENT_SECRET": "your-client-secret",
-        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
+        "GOOGLE_CLIENT_SECRET": "your-client-secret"
       }
     }
   }
 }
 ```
 
-See [Environment Variable Authentication](#alternative-environment-variable-authentication-npx--containers) for details on getting a refresh token.
+**3. First run:** The server will automatically open your browser for Google authorization. After you approve, the token is saved to `~/.config/google-docs-mcp/token.json` for future use.
+
+That's it! No manual token copying required.
 
 ---
 
@@ -268,36 +268,28 @@ When `GOOGLE_IMPERSONATE_USER` is set, the server will impersonate that user whe
 
 ### Alternative: Environment Variable Authentication (npx / Containers)
 
-For running via `npx` or in containerized environments where you can't rely on local files, you can pass OAuth credentials entirely via environment variables.
+For running via `npx` or in containerized environments, pass OAuth credentials via environment variables.
 
-**Option A: Individual environment variables**
+**Required environment variables:**
 
 ```bash
-# Your OAuth client credentials (from credentials.json)
 export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
 export GOOGLE_CLIENT_SECRET="your-client-secret"
-export GOOGLE_REFRESH_TOKEN="your-refresh-token"
 ```
 
-**Option B: Full credentials JSON as env var**
+**Optional:** If you already have a refresh token, you can skip the browser auth:
 
 ```bash
-# The entire contents of credentials.json as a single env var
-export GOOGLE_CREDENTIALS_JSON='{"installed":{"client_id":"...","client_secret":"..."}}'
 export GOOGLE_REFRESH_TOKEN="your-refresh-token"
 ```
 
-**Getting a refresh token:**
-
-If you have the client ID and secret but no refresh token yet, run the server with just those set:
-
-```bash
-GOOGLE_CLIENT_ID="..." GOOGLE_CLIENT_SECRET="..." npx @brainwavesio/google-docs-mcp
-```
+**How authentication works:**
 
-The server will prompt you through the OAuth flow and print the refresh token for you to save.
+1. On first run, if no saved token exists, the server opens your browser for Google authorization
+2. After you approve, the token is saved to `~/.config/google-docs-mcp/token.json`
+3. Subsequent runs use the saved token automatically
 
-**Claude Desktop config with env vars:**
+**Claude Desktop config:**
 
 ```json
 {
@@ -307,8 +299,7 @@ The server will prompt you through the OAuth flow and print the refresh token fo
       "args": ["@brainwavesio/google-docs-mcp"],
       "env": {
         "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
-        "GOOGLE_CLIENT_SECRET": "your-client-secret",
-        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
+        "GOOGLE_CLIENT_SECRET": "your-client-secret"
       }
     }
   }

package/dist/auth.js

@@ -3,203 +3,311 @@ import { google } from 'googleapis';
 import { JWT } from 'google-auth-library';
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import * as readline from 'readline/promises';
+import * as http from 'http';
+import * as os from 'os';
 import { fileURLToPath } from 'url';
-// --- Calculate paths relative to this script file (ESM way) ---
+import open from 'open';
+// --- Config directory for persistent token storage ---
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'google-docs-mcp');
+const TOKEN_PATH = path.join(CONFIG_DIR, 'token.json');
+// --- Legacy paths (for backwards compatibility) ---
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const projectRootDir = path.resolve(__dirname, '..');
-const TOKEN_PATH = path.join(projectRootDir, 'token.json');
-const CREDENTIALS_PATH = path.join(projectRootDir, 'credentials.json');
-// --- End of path calculation ---
+const LEGACY_TOKEN_PATH = path.join(projectRootDir, 'token.json');
+const LEGACY_CREDENTIALS_PATH = path.join(projectRootDir, 'credentials.json');
 const SCOPES = [
     'https://www.googleapis.com/auth/documents',
     'https://www.googleapis.com/auth/drive',
     'https://www.googleapis.com/auth/spreadsheets'
 ];
-// --- Environment variable authentication ---
-// Supports OAuth credentials via env vars for containerized/npx usage:
-// - GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN
-// - Or GOOGLE_CREDENTIALS_JSON (full credentials.json content as string)
-function hasEnvCredentials() {
-    return !!((process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET && process.env.GOOGLE_REFRESH_TOKEN) ||
-        process.env.GOOGLE_CREDENTIALS_JSON);
-}
-async function authorizeWithEnvCredentials() {
-    let clientId;
-    let clientSecret;
-    let refreshToken;
-    if (process.env.GOOGLE_CREDENTIALS_JSON) {
-        // Parse the full credentials.json from env var
-        const keys = JSON.parse(process.env.GOOGLE_CREDENTIALS_JSON);
-        const key = keys.installed || keys.web;
-        if (!key) {
-            throw new Error('GOOGLE_CREDENTIALS_JSON must contain "installed" or "web" key');
-        }
-        clientId = key.client_id;
-        clientSecret = key.client_secret;
-        refreshToken = process.env.GOOGLE_REFRESH_TOKEN;
+// --- Ensure config directory exists ---
+async function ensureConfigDir() {
+    try {
+        await fs.mkdir(CONFIG_DIR, { recursive: true });
     }
-    else {
-        clientId = process.env.GOOGLE_CLIENT_ID;
-        clientSecret = process.env.GOOGLE_CLIENT_SECRET;
-        refreshToken = process.env.GOOGLE_REFRESH_TOKEN;
-    }
-    const client = new google.auth.OAuth2(clientId, clientSecret);
-    if (refreshToken) {
-        client.setCredentials({ refresh_token: refreshToken });
-        console.error('Using OAuth credentials from environment variables.');
-        return client;
+    catch (err) {
+        // Directory might already exist
     }
-    // No refresh token - need to do interactive auth flow
-    console.error('No GOOGLE_REFRESH_TOKEN found. Starting interactive OAuth flow...');
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const authorizeUrl = client.generateAuthUrl({
-        access_type: 'offline',
-        scope: SCOPES.join(' '),
-    });
-    console.error('Authorize this app by visiting this url:', authorizeUrl);
-    const code = await rl.question('Enter the code from that page here: ');
-    rl.close();
-    const { tokens } = await client.getToken(code);
-    client.setCredentials(tokens);
-    if (tokens.refresh_token) {
-        console.error('\n=== SAVE THIS REFRESH TOKEN ===');
-        console.error('Add this to your environment:');
-        console.error(`GOOGLE_REFRESH_TOKEN=${tokens.refresh_token}`);
-        console.error('===============================\n');
-    }
-    console.error('Authentication successful!');
-    return client;
 }
-// --- End of environment variable authentication ---
-// --- Service Account Authentication ---
-async function authorizeWithServiceAccount() {
-    const serviceAccountPath = process.env.SERVICE_ACCOUNT_PATH;
-    const impersonateUser = process.env.GOOGLE_IMPERSONATE_USER;
+// --- Save token to config directory ---
+async function saveToken(credentials) {
+    await ensureConfigDir();
+    const payload = JSON.stringify({
+        type: 'authorized_user',
+        client_id: credentials.client_id,
+        client_secret: credentials.client_secret,
+        refresh_token: credentials.refresh_token,
+    }, null, 2);
+    await fs.writeFile(TOKEN_PATH, payload);
+    console.error(`Token saved to ${TOKEN_PATH}`);
+}
+// --- Load token from config directory or legacy location ---
+async function loadSavedToken() {
+    // Try new config location first
     try {
-        const keyFileContent = await fs.readFile(serviceAccountPath, 'utf8');
-        const serviceAccountKey = JSON.parse(keyFileContent);
-        const auth = new JWT({
-            email: serviceAccountKey.client_email,
-            key: serviceAccountKey.private_key,
-            scopes: SCOPES,
-            subject: impersonateUser,
-        });
-        await auth.authorize();
-        if (impersonateUser) {
-            console.error(`Service Account authentication successful, impersonating: ${impersonateUser}`);
-        }
-        else {
-            console.error('Service Account authentication successful!');
+        const content = await fs.readFile(TOKEN_PATH, 'utf8');
+        const token = JSON.parse(content);
+        if (token.refresh_token) {
+            return token;
         }
-        return auth;
     }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            console.error(`FATAL: Service account key file not found at path: ${serviceAccountPath}`);
-            throw new Error(`Service account key file not found. Please check the path in SERVICE_ACCOUNT_PATH.`);
-        }
-        console.error('FATAL: Error loading or authorizing the service account key:', error.message);
-        throw new Error('Failed to authorize using the service account. Ensure the key file is valid and the path is correct.');
+    catch (err) {
+        // Not found in config dir, try legacy location
     }
-}
-// --- End of Service Account Authentication ---
-// --- File-based OAuth (original behavior) ---
-async function loadSavedCredentialsIfExist() {
+    // Try legacy token.json in project root
     try {
-        const content = await fs.readFile(TOKEN_PATH);
-        const credentials = JSON.parse(content.toString());
-        const { client_secret, client_id, redirect_uris } = await loadClientSecrets();
-        const client = new google.auth.OAuth2(client_id, client_secret, redirect_uris?.[0]);
-        client.setCredentials(credentials);
-        return client;
+        const content = await fs.readFile(LEGACY_TOKEN_PATH, 'utf8');
+        const token = JSON.parse(content);
+        if (token.refresh_token) {
+            return token;
+        }
     }
     catch (err) {
-        return null;
+        // Not found
     }
+    return null;
 }
-async function loadClientSecrets() {
-    const content = await fs.readFile(CREDENTIALS_PATH);
-    const keys = JSON.parse(content.toString());
-    const key = keys.installed || keys.web;
-    if (!key)
-        throw new Error("Could not find client secrets in credentials.json.");
-    return {
-        client_id: key.client_id,
-        client_secret: key.client_secret,
-        redirect_uris: key.redirect_uris || ['http://localhost:3000/'],
-        client_type: keys.web ? 'web' : 'installed'
-    };
-}
-async function saveCredentials(client) {
-    const { client_secret, client_id } = await loadClientSecrets();
-    const payload = JSON.stringify({
-        type: 'authorized_user',
-        client_id: client_id,
-        client_secret: client_secret,
-        refresh_token: client.credentials.refresh_token,
+// --- Browser-based OAuth flow ---
+async function authenticateWithBrowser(clientId, clientSecret) {
+    return new Promise((resolve, reject) => {
+        // Find an available port
+        const server = http.createServer();
+        server.listen(0, '127.0.0.1', async () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                reject(new Error('Failed to start local server'));
+                return;
+            }
+            const port = address.port;
+            const redirectUri = `http://127.0.0.1:${port}/callback`;
+            const client = new google.auth.OAuth2(clientId, clientSecret, redirectUri);
+            const authorizeUrl = client.generateAuthUrl({
+                access_type: 'offline',
+                scope: SCOPES,
+                prompt: 'consent', // Force consent to ensure we get a refresh token
+            });
+            console.error('\n========================================');
+            console.error('Opening browser for Google authorization...');
+            console.error('If the browser does not open, visit this URL:');
+            console.error(authorizeUrl);
+            console.error('========================================\n');
+            // Handle the OAuth callback
+            server.on('request', async (req, res) => {
+                if (!req.url?.startsWith('/callback')) {
+                    res.writeHead(404);
+                    res.end('Not found');
+                    return;
+                }
+                const url = new URL(req.url, `http://127.0.0.1:${port}`);
+                const code = url.searchParams.get('code');
+                const error = url.searchParams.get('error');
+                if (error) {
+                    res.writeHead(400, { 'Content-Type': 'text/html' });
+                    res.end(`
+            <html>
+              <body style="font-family: system-ui; padding: 40px; text-align: center;">
+                <h1>Authorization Failed</h1>
+                <p>Error: ${error}</p>
+                <p>You can close this window.</p>
+              </body>
+            </html>
+          `);
+                    server.close();
+                    reject(new Error(`Authorization failed: ${error}`));
+                    return;
+                }
+                if (!code) {
+                    res.writeHead(400, { 'Content-Type': 'text/html' });
+                    res.end(`
+            <html>
+              <body style="font-family: system-ui; padding: 40px; text-align: center;">
+                <h1>Authorization Failed</h1>
+                <p>No authorization code received.</p>
+                <p>You can close this window.</p>
+              </body>
+            </html>
+          `);
+                    server.close();
+                    reject(new Error('No authorization code received'));
+                    return;
+                }
+                try {
+                    const { tokens } = await client.getToken(code);
+                    client.setCredentials(tokens);
+                    if (tokens.refresh_token) {
+                        await saveToken({
+                            client_id: clientId,
+                            client_secret: clientSecret,
+                            refresh_token: tokens.refresh_token,
+                        });
+                    }
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end(`
+            <html>
+              <body style="font-family: system-ui; padding: 40px; text-align: center;">
+                <h1>Authorization Successful!</h1>
+                <p>You can close this window and return to your application.</p>
+                <script>window.close();</script>
+              </body>
+            </html>
+          `);
+                    server.close();
+                    console.error('Authorization successful!');
+                    resolve(client);
+                }
+                catch (err) {
+                    res.writeHead(500, { 'Content-Type': 'text/html' });
+                    res.end(`
+            <html>
+              <body style="font-family: system-ui; padding: 40px; text-align: center;">
+                <h1>Authorization Failed</h1>
+                <p>Failed to exchange code for tokens.</p>
+                <p>You can close this window.</p>
+              </body>
+            </html>
+          `);
+                    server.close();
+                    reject(err);
+                }
+            });
+            // Set a timeout for the auth flow
+            const timeout = setTimeout(() => {
+                server.close();
+                reject(new Error('Authorization timed out after 5 minutes'));
+            }, 5 * 60 * 1000);
+            server.on('close', () => {
+                clearTimeout(timeout);
+            });
+            // Open the browser
+            try {
+                await open(authorizeUrl);
+            }
+            catch (err) {
+                console.error('Failed to open browser automatically.');
+                console.error('Please open the URL above manually.');
+            }
+        });
+        server.on('error', (err) => {
+            reject(err);
+        });
     });
-    await fs.writeFile(TOKEN_PATH, payload);
-    console.error('Token stored to', TOKEN_PATH);
 }
-async function authenticate() {
-    const { client_secret, client_id, redirect_uris, client_type } = await loadClientSecrets();
-    const redirectUri = client_type === 'web' ? redirect_uris[0] : 'urn:ietf:wg:oauth:2.0:oob';
-    console.error(`DEBUG: Using redirect URI: ${redirectUri}`);
-    console.error(`DEBUG: Client type: ${client_type}`);
-    const oAuth2Client = new google.auth.OAuth2(client_id, client_secret, redirectUri);
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const authorizeUrl = oAuth2Client.generateAuthUrl({
-        access_type: 'offline',
-        scope: SCOPES.join(' '),
-    });
-    console.error('DEBUG: Generated auth URL:', authorizeUrl);
-    console.error('Authorize this app by visiting this url:', authorizeUrl);
-    const code = await rl.question('Enter the code from that page here: ');
-    rl.close();
-    try {
-        const { tokens } = await oAuth2Client.getToken(code);
-        oAuth2Client.setCredentials(tokens);
-        if (tokens.refresh_token) {
-            await saveCredentials(oAuth2Client);
+// --- Get OAuth credentials from env vars or files ---
+function getClientCredentials() {
+    // Check environment variables first
+    if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+        return {
+            clientId: process.env.GOOGLE_CLIENT_ID,
+            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+        };
+    }
+    // Check for GOOGLE_CREDENTIALS_JSON env var
+    if (process.env.GOOGLE_CREDENTIALS_JSON) {
+        try {
+            const keys = JSON.parse(process.env.GOOGLE_CREDENTIALS_JSON);
+            const key = keys.installed || keys.web;
+            if (key) {
+                return {
+                    clientId: key.client_id,
+                    clientSecret: key.client_secret,
+                };
+            }
+        }
+        catch (err) {
+            console.error('Failed to parse GOOGLE_CREDENTIALS_JSON');
         }
-        else {
-            console.error("Did not receive refresh token. Token might expire.");
+    }
+    return null;
+}
+// --- Load credentials.json file (legacy support) ---
+async function loadCredentialsFile() {
+    try {
+        const content = await fs.readFile(LEGACY_CREDENTIALS_PATH, 'utf8');
+        const keys = JSON.parse(content);
+        const key = keys.installed || keys.web;
+        if (key) {
+            return {
+                clientId: key.client_id,
+                clientSecret: key.client_secret,
+            };
         }
-        console.error('Authentication successful!');
-        return oAuth2Client;
     }
     catch (err) {
-        console.error('Error retrieving access token', err);
-        throw new Error('Authentication failed');
+        // File not found or invalid
     }
+    return null;
+}
+// --- Service Account Authentication ---
+async function authorizeWithServiceAccount() {
+    const serviceAccountPath = process.env.SERVICE_ACCOUNT_PATH;
+    const impersonateUser = process.env.GOOGLE_IMPERSONATE_USER;
+    const keyFileContent = await fs.readFile(serviceAccountPath, 'utf8');
+    const serviceAccountKey = JSON.parse(keyFileContent);
+    const auth = new JWT({
+        email: serviceAccountKey.client_email,
+        key: serviceAccountKey.private_key,
+        scopes: SCOPES,
+        subject: impersonateUser,
+    });
+    await auth.authorize();
+    if (impersonateUser) {
+        console.error(`Service Account authentication successful, impersonating: ${impersonateUser}`);
+    }
+    else {
+        console.error('Service Account authentication successful!');
+    }
+    return auth;
 }
-// --- End of file-based OAuth ---
 // --- Main exported function ---
 // Priority order:
 // 1. Service account (SERVICE_ACCOUNT_PATH)
-// 2. Environment variables (GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET + GOOGLE_REFRESH_TOKEN, or GOOGLE_CREDENTIALS_JSON)
-// 3. File-based OAuth (credentials.json + token.json)
+// 2. Saved token + env credentials
+// 3. Env var refresh token (GOOGLE_REFRESH_TOKEN)
+// 4. Browser-based OAuth flow
+// 5. Legacy file-based credentials
 export async function authorize() {
     // 1. Check for service account
     if (process.env.SERVICE_ACCOUNT_PATH) {
-        console.error('Service account path detected. Attempting service account authentication...');
+        console.error('Service account path detected. Using service account authentication...');
         return authorizeWithServiceAccount();
     }
-    // 2. Check for env var credentials
-    if (hasEnvCredentials()) {
-        console.error('Environment variable credentials detected. Using env-based authentication...');
-        return authorizeWithEnvCredentials();
+    // Get client credentials from env or files
+    let credentials = getClientCredentials();
+    // 2. Check for saved token
+    const savedToken = await loadSavedToken();
+    if (savedToken) {
+        // Use saved token - prefer env credentials if available, otherwise use token's credentials
+        const clientId = credentials?.clientId || savedToken.client_id;
+        const clientSecret = credentials?.clientSecret || savedToken.client_secret;
+        const client = new google.auth.OAuth2(clientId, clientSecret);
+        client.setCredentials({ refresh_token: savedToken.refresh_token });
+        console.error('Using saved credentials from ~/.config/google-docs-mcp/');
+        return client;
     }
-    // 3. Fall back to file-based OAuth
-    console.error('Using file-based OAuth flow...');
-    let client = await loadSavedCredentialsIfExist();
-    if (client) {
-        console.error('Using saved credentials.');
+    // 3. Check for refresh token in env var
+    if (credentials && process.env.GOOGLE_REFRESH_TOKEN) {
+        const client = new google.auth.OAuth2(credentials.clientId, credentials.clientSecret);
+        client.setCredentials({ refresh_token: process.env.GOOGLE_REFRESH_TOKEN });
+        // Save this token for future use
+        await saveToken({
+            client_id: credentials.clientId,
+            client_secret: credentials.clientSecret,
+            refresh_token: process.env.GOOGLE_REFRESH_TOKEN,
+        });
+        console.error('Using refresh token from environment variable.');
         return client;
     }
-    console.error('Starting authentication flow...');
-    client = await authenticate();
-    return client;
+    // 4. Try to load credentials from file if not in env
+    if (!credentials) {
+        credentials = await loadCredentialsFile();
+    }
+    // 5. If we have client credentials, do browser-based OAuth
+    if (credentials) {
+        console.error('No saved token found. Starting browser-based authentication...');
+        return authenticateWithBrowser(credentials.clientId, credentials.clientSecret);
+    }
+    // No credentials available
+    throw new Error('No Google credentials found. Please set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables, ' +
+        'or place a credentials.json file in the project directory.');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainwavesio/google-docs-mcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -30,6 +30,7 @@
     "fastmcp": "^3.24.0",
     "google-auth-library": "^9.15.1",
     "googleapis": "^148.0.0",
+    "open": "^10.1.0",
     "zod": "^3.24.2"
   },
   "devDependencies": {