mcp-google-extras 1.0.1 → 1.0.4

package/README.md

@@ -11,19 +11,51 @@ All 44 tools from `@a-bonus/google-docs-mcp`, plus:
 - **readFile** — Read the full text content of a `.docx` or `.pdf` file from Google Drive by file ID
 - **searchFileContents** — Search Google Drive and extract matching text snippets from inside `.docx` and `.pdf` files
 
-## Setup
+## Getting Started
 
-### 1. Create Google OAuth credentials
+### Step 1: Create Google OAuth Credentials
 
 1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
 2. Create a project (or use an existing one)
-3. Enable the Google Docs API, Google Sheets API, and Google Drive API
-4. Create OAuth 2.0 credentials (Desktop application type)
-5. Note your Client ID and Client Secret
+3. Enable the **Google Docs API**, **Google Sheets API**, and **Google Drive API**
+4. Go to **Credentials** → **Create Credentials** → **OAuth Client ID**
+5. Select **Desktop application** as the application type
+6. Download the credentials or note your **Client ID** and **Client Secret**
 
-### 2. Configure your MCP client
+### Step 2: Provide Your Credentials
 
-Add this to your MCP configuration (e.g., `.mcp.json`):
+Choose **one** of the following methods (whichever you prefer):
+
+#### Option A: Use `credentials.json`
+
+Download the JSON file from Google Cloud Console and place it in either location:
+
+```
+~/.config/google-docs-mcp/credentials.json   (recommended — shared across projects)
+./credentials.json                            (local to your project)
+```
+
+That's it — no env vars needed. The server will find it automatically.
+
+#### Option B: Create a `.env` file
+
+Create a `.env` file in either location:
+
+```
+~/.config/google-docs-mcp/.env   (recommended — shared across projects)
+./.env                           (local to your project)
+```
+
+With the following contents:
+
+```env
+GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your-client-secret
+```
+
+#### Option C: Set env vars in your MCP config
+
+Add the credentials directly to your MCP configuration:
 
 ```json
 {
@@ -40,16 +72,68 @@ Add this to your MCP configuration (e.g., `.mcp.json`):
 }
 ```
 
-### 3. Authenticate
+> **Credential lookup order:** env vars → `~/.config/google-docs-mcp/.env` → project root `.env` → `~/.config/google-docs-mcp/credentials.json` → project root `credentials.json`
+
+### Step 3: Add to Your MCP Client
+
+#### Claude Code (recommended)
+
+If you used Option A or B above:
+
+```bash
+claude mcp add google-docs -- npx -y mcp-google-extras
+```
+
+Or with env vars (Option C):
+
+```bash
+claude mcp add google-docs \
+  -e GOOGLE_CLIENT_ID=your-client-id \
+  -e GOOGLE_CLIENT_SECRET=your-client-secret \
+  -- npx -y mcp-google-extras
+```
+
+#### Other MCP clients
+
+Add this to your MCP configuration (e.g., `.mcp.json`, `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "google-docs": {
+      "command": "npx",
+      "args": ["-y", "mcp-google-extras"]
+    }
+  }
+}
+```
+
+If using Option C, add an `"env"` block with your `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`.
+
+### Step 4: Authenticate
 
-On first run, the server will open your browser for Google OAuth consent. The token is saved to `~/.config/google-docs-mcp/token.json` for future use.
+On your first tool call, the server will automatically open your browser for Google OAuth consent. Sign in and grant access — the token is saved to `~/.config/google-docs-mcp/token.json` for future use.
 
-You can also run the auth flow manually:
+You can also run the auth flow manually anytime:
 
 ```bash
 npx mcp-google-extras auth
 ```
 
+### Multi-Account Support
+
+Set the `GOOGLE_MCP_PROFILE` env var to use separate tokens per profile:
+
+```json
+{
+  "env": {
+    "GOOGLE_MCP_PROFILE": "work"
+  }
+}
+```
+
+This stores tokens in `~/.config/google-docs-mcp/work/` instead of the default directory.
+
 ## Tools
 
 ### Google Docs
@@ -68,13 +152,15 @@ npx mcp-google-extras auth
 
 | Variable | Required | Description |
 |---|---|---|
-| `GOOGLE_CLIENT_ID` | Yes | OAuth 2.0 Client ID |
-| `GOOGLE_CLIENT_SECRET` | Yes | OAuth 2.0 Client Secret |
-| `GOOGLE_MCP_PROFILE` | No | Profile name for multi-account support |
+| `GOOGLE_CLIENT_ID` | No* | OAuth 2.0 Client ID |
+| `GOOGLE_CLIENT_SECRET` | No* | OAuth 2.0 Client Secret |
+| `GOOGLE_MCP_PROFILE` | No | Profile name for multi-account support (see above) |
 | `LOG_LEVEL` | No | `debug`, `info`, `warn`, `error`, or `silent` |
 | `SERVICE_ACCOUNT_PATH` | No | Path to service account JSON key (alternative to OAuth) |
 | `GOOGLE_IMPERSONATE_USER` | No | Email to impersonate with service account |
 
+\* Not required as env vars if you provide credentials via `.env` file or `credentials.json` (see [Step 2](#step-2-provide-your-credentials)).
+
 ## License
 
 ISC (based on [@a-bonus/google-docs-mcp](https://www.npmjs.com/package/@a-bonus/google-docs-mcp))

package/dist/auth.js

@@ -5,6 +5,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
 import * as http from 'http';
+import { exec } from 'child_process';
 import { fileURLToPath } from 'url';
 import { logger } from './logger.js';
 // ---------------------------------------------------------------------------
@@ -42,42 +43,86 @@ const SCOPES = [
     'https://www.googleapis.com/auth/script.external_request',
 ];
 // ---------------------------------------------------------------------------
+// .env file loader
+// ---------------------------------------------------------------------------
+async function loadEnvFile(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf8');
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#')) continue;
+            const eqIdx = trimmed.indexOf('=');
+            if (eqIdx === -1) continue;
+            const key = trimmed.slice(0, eqIdx).trim();
+            let value = trimmed.slice(eqIdx + 1).trim();
+            // Strip surrounding quotes
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            if (!process.env[key]) {
+                process.env[key] = value;
+            }
+        }
+        return true;
+    } catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
 // Client secrets resolution
 // ---------------------------------------------------------------------------
 /**
  * Resolves OAuth client ID and secret.
  *
  * Priority:
- *   1. GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET env vars (npx / production)
- *   2. credentials.json in the project root (local dev fallback)
+ *   1. GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET env vars (including from MCP config)
+ *   2. .env file in config dir (~/.config/google-docs-mcp/.env)
+ *   3. .env file in project root
+ *   4. credentials.json in config dir (~/.config/google-docs-mcp/credentials.json)
+ *   5. credentials.json in project root (legacy dev fallback)
  */
 async function loadClientSecrets() {
-    // 1. Environment variables
-    const envId = process.env.GOOGLE_CLIENT_ID;
-    const envSecret = process.env.GOOGLE_CLIENT_SECRET;
-    if (envId && envSecret) {
-        return { client_id: envId, client_secret: envSecret };
+    // 1. Check env vars first (may already be set via MCP config)
+    if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+        return { client_id: process.env.GOOGLE_CLIENT_ID, client_secret: process.env.GOOGLE_CLIENT_SECRET };
     }
-    // 2. credentials.json fallback
-    try {
-        const content = await fs.readFile(CREDENTIALS_PATH, 'utf8');
-        const keys = JSON.parse(content);
-        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,
-        };
+    // 2–4. Try loading .env files (config dir, cwd, then package root)
+    const configDir = getConfigDir();
+    const cwd = process.cwd();
+    await loadEnvFile(path.join(configDir, '.env'));
+    await loadEnvFile(path.join(cwd, '.env'));
+    await loadEnvFile(path.join(projectRootDir, '.env'));
+    if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+        logger.info('Loaded client credentials from .env file.');
+        return { client_id: process.env.GOOGLE_CLIENT_ID, client_secret: process.env.GOOGLE_CLIENT_SECRET };
     }
-    catch (err) {
-        if (err.code === 'ENOENT') {
-            throw new Error('No OAuth credentials found. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET ' +
-                'environment variables, or place a credentials.json file in the project root.');
+    // 5–7. Try credentials.json (config dir, cwd, then package root)
+    const credentialsPaths = [
+        path.join(configDir, 'credentials.json'),
+        path.join(cwd, 'credentials.json'),
+        CREDENTIALS_PATH,
+    ];
+    for (const credPath of credentialsPaths) {
+        try {
+            const content = await fs.readFile(credPath, 'utf8');
+            const keys = JSON.parse(content);
+            const key = keys.installed || keys.web;
+            if (key) {
+                logger.info('Loaded client credentials from', credPath);
+                return { client_id: key.client_id, client_secret: key.client_secret };
+            }
+        } catch (err) {
+            if (err.code !== 'ENOENT') throw err;
         }
-        throw err;
     }
+    const configDirDisplay = configDir.replace(os.homedir(), '~');
+    throw new Error(
+        'No OAuth credentials found. Provide them in any of these ways:\n' +
+        `  1. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET env vars in your MCP config\n` +
+        `  2. Create a .env file with GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in ${configDirDisplay}/ or your project directory\n` +
+        `  3. Place your credentials.json (from Google Cloud Console) in ${configDirDisplay}/ or your project directory`
+    );
 }
 // ---------------------------------------------------------------------------
 // Service account auth (unchanged)
@@ -144,6 +189,25 @@ async function saveCredentials(client) {
     logger.info('Token stored to', tokenPath);
 }
 // ---------------------------------------------------------------------------
+// Auto-open browser (cross-platform)
+// ---------------------------------------------------------------------------
+function openBrowser(url) {
+    const platform = process.platform;
+    let cmd;
+    if (platform === 'win32') {
+        cmd = `start "" "${url}"`;
+    } else if (platform === 'darwin') {
+        cmd = `open "${url}"`;
+    } else {
+        cmd = `xdg-open "${url}"`;
+    }
+    exec(cmd, (err) => {
+        if (err) {
+            logger.warn('Could not auto-open browser. Please open this URL manually.');
+        }
+    });
+}
+// ---------------------------------------------------------------------------
 // Interactive OAuth browser flow
 // ---------------------------------------------------------------------------
 async function authenticate() {
@@ -158,7 +222,9 @@ async function authenticate() {
         access_type: 'offline',
         scope: SCOPES.join(' '),
     });
-    logger.info('Authorize this app by visiting this url:', authorizeUrl);
+    logger.info('Opening browser for authorization...');
+    logger.info('If the browser does not open, visit this URL:', authorizeUrl);
+    openBrowser(authorizeUrl);
     // Wait for the OAuth callback
     const code = await new Promise((resolve, reject) => {
         server.on('request', (req, res) => {

package/dist/clients.js

@@ -24,13 +24,17 @@ export async function initializeGoogleClient() {
             logger.info('Google API client authorized successfully.');
         }
         catch (error) {
-            logger.error('FATAL: Failed to initialize Google API client:', error);
+            logger.error('Failed to initialize Google API client:', error);
             authClient = null;
             googleDocs = null;
             googleDrive = null;
             googleSheets = null;
             googleScript = null;
-            throw new Error('Google client initialization failed. Cannot start server tools.');
+            throw new UserError(
+                'Google authentication required. A browser window should have opened automatically. ' +
+                'If not, run: npx mcp-google-extras auth\n\n' +
+                'Details: ' + (error.message || error)
+            );
         }
     }
     if (authClient && !googleDocs) {

package/dist/index.js

@@ -8,7 +8,6 @@
 //   mcp-google-extras auth     Run the interactive OAuth flow
 import { FastMCP } from 'fastmcp';
 import { buildCachedToolsListPayload, collectToolsWhileRegistering, installCachedToolsListHandler, } from './cachedToolsList.js';
-import { initializeGoogleClient } from './clients.js';
 import { registerAllTools } from './tools/index.js';
 import { logger } from './logger.js';
 // --- Auth subcommand ---
@@ -40,13 +39,12 @@ const registeredTools = [];
 collectToolsWhileRegistering(server, registeredTools);
 registerAllTools(server);
 try {
-    await initializeGoogleClient();
-    logger.info('Starting Ultimate Google Docs & Sheets MCP server...');
+    logger.info('Starting mcp-google-extras server...');
     const cachedToolsList = await buildCachedToolsListPayload(registeredTools);
     await server.start({ transportType: 'stdio' });
     installCachedToolsListHandler(server, cachedToolsList);
     logger.info('MCP Server running using stdio. Awaiting client connection...');
-    logger.info('Process-level error handling configured to prevent crashes from timeout errors.');
+    logger.info('Google auth will run automatically on first tool call.');
 }
 catch (startError) {
     logger.error('FATAL: Server failed to start:', startError.message || startError);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-extras",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "type": "module",
   "description": "MCP server for Google Docs, Sheets, Drive, plus .docx and .pdf file reading",
   "bin": {