google-tools-mcp 1.1.3 → 1.2.0

package/README.md

@@ -22,7 +22,28 @@ claude mcp add -s user google -- npx -y google-tools-mcp
 
 You can be up and running in under 5 minutes.
 
-### Step 1: Create Google OAuth Credentials
+### Guided Setup (recommended)
+
+Run the setup wizard — it opens the right Google Cloud Console pages for you and saves your credentials automatically:
+
+```bash
+npx -y google-tools-mcp setup
+```
+
+The wizard walks you through:
+1. Enabling all required Google APIs (opens in your browser)
+2. Configuring the OAuth consent screen
+3. Creating OAuth credentials
+4. Authenticating with Google
+
+After setup, just add it to your MCP client (see [Step 3](#step-3-add-to-your-mcp-client) below).
+
+### Manual Setup
+
+<details>
+<summary>Click to expand manual setup instructions</summary>
+
+#### 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)
@@ -32,7 +53,7 @@ You can be up and running in under 5 minutes.
 6. Select **Desktop application** as the application type
 7. Download the credentials or note your **Client ID** and **Client Secret**
 
-### Step 2: Provide Your Credentials
+#### Step 2: Provide Your Credentials
 
 Choose **one** of the following methods (whichever you prefer):
 
@@ -84,6 +105,8 @@ Add the credentials directly to your MCP configuration:
 
 > **Credential lookup order:** env vars → `~/.config/google-tools-mcp/.env` → project root `.env` → `~/.config/google-tools-mcp/credentials.json` → project root `credentials.json`
 
+</details>
+
 ### Step 3: Add to Your MCP Client
 
 #### Claude Code (recommended)

package/dist/auth.js

@@ -166,6 +166,23 @@ async function loadSavedCredentialsIfExist() {
         const tokenPath = getTokenPath();
         const content = await fs.readFile(tokenPath, 'utf8');
         const credentials = JSON.parse(content);
+
+        // Check that the saved token covers all current SCOPES.
+        // Tokens without a scopes field (pre-upgrade) or with missing scopes
+        // are stale — delete and force re-auth via browser automatically.
+        if (!Array.isArray(credentials.scopes)) {
+            logger.info('Saved token has no scopes record (pre-upgrade token). Re-authentication required for new scopes.');
+            try { await fs.unlink(tokenPath); } catch {}
+            return null;
+        }
+        const saved = new Set(credentials.scopes);
+        const missing = SCOPES.filter(s => !saved.has(s));
+        if (missing.length > 0) {
+            logger.info(`Saved token is missing scope(s): ${missing.join(', ')}. Re-authentication required.`);
+            try { await fs.unlink(tokenPath); } catch {}
+            return null;
+        }
+
         const { client_secret, client_id } = await loadClientSecrets();
         const client = new google.auth.OAuth2(client_id, client_secret);
         client.setCredentials(credentials);
@@ -185,6 +202,7 @@ async function saveCredentials(client) {
         client_id,
         client_secret,
         refresh_token: client.credentials.refresh_token,
+        scopes: SCOPES,
     }, null, 2);
     await fs.writeFile(tokenPath, payload);
     logger.info('Token stored to', tokenPath);

package/dist/index.js

@@ -7,10 +7,23 @@
 // Usage:
 //   google-tools-mcp          Start the MCP server (default)
 //   google-tools-mcp auth     Run the interactive OAuth flow
+//   google-tools-mcp setup    Guided setup: enable APIs, create credentials, authenticate
 import { FastMCP } from 'fastmcp';
 import { registerAllTools } from './tools/index.js';
 import { logger } from './logger.js';
 
+// --- Setup subcommand ---
+if (process.argv[2] === 'setup') {
+    const { runSetup } = await import('./setup.js');
+    try {
+        await runSetup();
+        process.exit(0);
+    } catch (error) {
+        console.error('\nSetup failed:', error.message || error);
+        process.exit(1);
+    }
+}
+
 // --- Auth subcommand ---
 if (process.argv[2] === 'auth') {
     const { runAuthFlow } = await import('./auth.js');

package/dist/setup.js

@@ -0,0 +1,132 @@
+// Guided setup wizard for google-tools-mcp.
+// Opens the right Google Cloud Console URLs and saves credentials.
+import * as readline from 'readline';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { exec } from 'child_process';
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const APIS = [
+    'docs.googleapis.com',
+    'sheets.googleapis.com',
+    'drive.googleapis.com',
+    'gmail.googleapis.com',
+    'calendar-json.googleapis.com',
+    'forms.googleapis.com',
+    'slides.googleapis.com',
+];
+
+const ENABLE_APIS_URL =
+    `https://console.cloud.google.com/flows/enableapi?apiid=${APIS.join(',')}`;
+
+const CREATE_CREDENTIALS_URL =
+    'https://console.cloud.google.com/apis/credentials/oauthclient';
+
+const CONSENT_SCREEN_URL =
+    'https://console.cloud.google.com/apis/credentials/consent';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+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, () => {});
+}
+
+function prompt(rl, question) {
+    return new Promise((resolve) => rl.question(question, resolve));
+}
+
+function getConfigDir() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const base = xdg || path.join(os.homedir(), '.config');
+    const baseDir = path.join(base, 'google-tools-mcp');
+    const profile = process.env.GOOGLE_MCP_PROFILE;
+    return profile ? path.join(baseDir, profile) : baseDir;
+}
+
+// ---------------------------------------------------------------------------
+// Setup flow
+// ---------------------------------------------------------------------------
+export async function runSetup() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    console.log('\n🔧 google-tools-mcp setup\n');
+
+    // Step 1: Enable APIs
+    console.log('Step 1: Enable Google APIs');
+    console.log('─────────────────────────');
+    console.log('Opening Google Cloud Console to enable all required APIs.');
+    console.log('If you don\'t have a project yet, it will ask you to create one.\n');
+    openBrowser(ENABLE_APIS_URL);
+    await prompt(rl, 'Press Enter when done...');
+
+    // Step 2: OAuth consent screen
+    console.log('\nStep 2: Configure OAuth consent screen');
+    console.log('──────────────────────────────────────');
+    console.log('Opening the OAuth consent screen configuration.');
+    console.log('  • Choose "External" for the user type');
+    console.log('  • Fill in the app name (anything is fine, e.g. "MCP")');
+    console.log('  • Add your email as a test user\n');
+    openBrowser(CONSENT_SCREEN_URL);
+    await prompt(rl, 'Press Enter when done...');
+
+    // Step 3: Create OAuth credentials
+    console.log('\nStep 3: Create OAuth Client ID');
+    console.log('──────────────────────────────');
+    console.log('Opening the credentials page.');
+    console.log('  • Select "Desktop application" as the type');
+    console.log('  • Click Create, then copy the Client ID and Client Secret\n');
+    openBrowser(CREATE_CREDENTIALS_URL);
+    await prompt(rl, 'Press Enter when you have your Client ID and Secret...');
+
+    // Step 4: Collect credentials
+    console.log('');
+    const clientId = (await prompt(rl, 'Client ID: ')).trim();
+    const clientSecret = (await prompt(rl, 'Client Secret: ')).trim();
+
+    if (!clientId || !clientSecret) {
+        rl.close();
+        throw new Error('Client ID and Client Secret are required.');
+    }
+
+    // Save to config dir
+    const configDir = getConfigDir();
+    await fs.mkdir(configDir, { recursive: true });
+    const envPath = path.join(configDir, '.env');
+    const envContent = `GOOGLE_CLIENT_ID=${clientId}\nGOOGLE_CLIENT_SECRET=${clientSecret}\n`;
+    await fs.writeFile(envPath, envContent);
+    const displayPath = envPath.replace(os.homedir(), '~');
+    console.log(`\nCredentials saved to ${displayPath}`);
+
+    // Step 5: Run OAuth flow
+    console.log('\nStep 4: Authenticate with Google');
+    console.log('────────────────────────────────');
+    console.log('Opening browser for OAuth consent...\n');
+    rl.close();
+
+    // Set env vars so auth picks them up immediately
+    process.env.GOOGLE_CLIENT_ID = clientId;
+    process.env.GOOGLE_CLIENT_SECRET = clientSecret;
+
+    const { runAuthFlow } = await import('./auth.js');
+    await runAuthFlow();
+
+    console.log('\n✅ Setup complete! You\'re ready to use google-tools-mcp.');
+    console.log('\nAdd it to Claude Code:');
+    console.log('  claude mcp add -s user google -- npx -y google-tools-mcp\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-tools-mcp",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "The easiest MCP server for Google Workspace — Drive, Docs, Sheets, Gmail, Calendar, and Forms. 153 tools with one-click browser auth. Read Word docs, PDFs, and spreadsheets straight from Drive.",
   "type": "module",
   "bin": {