mcp-google-extras 1.0.2 → 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

@@ -87,17 +87,20 @@ async function loadClientSecrets() {
     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–3. Try loading .env files (config dir first, then project root)
+    // 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 };
     }
-    // 4–5. Try credentials.json (config dir first, then 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) {
@@ -117,8 +120,8 @@ async function loadClientSecrets() {
     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 ${configDirDisplay}/.env with GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET\n` +
-        `  3. Place your credentials.json (from Google Cloud Console) in ${configDirDisplay}/`
+        `  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`
     );
 }
 // ---------------------------------------------------------------------------

package/package.json

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