mcp-google-extras 1.0.2 → 1.0.5

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/dist/tools/drive/index.js

@@ -10,6 +10,8 @@ import { register as renameFile } from './renameFile.js';
 import { register as deleteFile } from './deleteFile.js';
 import { register as createDocument } from './createDocument.js';
 import { register as createFromTemplate } from './createFromTemplate.js';
+import { register as listSharedDrives } from './listSharedDrives.js';
+import { register as listSharedWithMe } from './listSharedWithMe.js';
 export function registerDriveTools(server) {
     listGoogleDocs(server);
     searchGoogleDocs(server);
@@ -23,4 +25,6 @@ export function registerDriveTools(server) {
     deleteFile(server);
     createDocument(server);
     createFromTemplate(server);
+    listSharedDrives(server);
+    listSharedWithMe(server);
 }

package/dist/tools/drive/listSharedDrives.js

@@ -0,0 +1,52 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'listSharedDrives',
+        description: 'Lists all Shared Drives (Team Drives) the user has access to. Use the returned drive ID with listFolderContents to browse its contents.',
+        parameters: z.object({
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(50)
+                .describe('Maximum number of shared drives to return.'),
+            pageToken: z
+                .string()
+                .optional()
+                .describe('Token for fetching the next page of results.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info('Listing shared drives');
+            try {
+                const response = await drive.drives.list({
+                    pageSize: args.maxResults,
+                    pageToken: args.pageToken || undefined,
+                    fields: 'nextPageToken,drives(id,name,createdTime,hidden)',
+                });
+                const drives = (response.data.drives || []).map((d) => ({
+                    id: d.id,
+                    name: d.name,
+                    createdTime: d.createdTime,
+                    hidden: d.hidden || false,
+                }));
+                const result = {
+                    drives,
+                    nextPageToken: response.data.nextPageToken || null,
+                    totalCount: drives.length,
+                };
+                return JSON.stringify(result, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing shared drives: ${error.message || error}`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure the Drive API scope includes shared drives.');
+                throw new UserError(`Failed to list shared drives: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/listSharedWithMe.js

@@ -0,0 +1,97 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'listSharedWithMe',
+        description: 'Lists files and folders that have been shared with the user ("Shared with me"). Returns items shared by others that are not in the user\'s own Drive. Use folder IDs with listFolderContents to navigate into shared folders.',
+        parameters: z.object({
+            mimeType: z
+                .string()
+                .optional()
+                .describe('Filter by MIME type. Use "application/vnd.google-apps.folder" for folders only, "application/vnd.google-apps.document" for Docs, "application/vnd.google-apps.spreadsheet" for Sheets, etc.'),
+            query: z
+                .string()
+                .optional()
+                .describe('Search query to filter shared items by name (uses "contains" matching).'),
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(50)
+                .describe('Maximum number of items to return.'),
+            pageToken: z
+                .string()
+                .optional()
+                .describe('Token for fetching the next page of results.'),
+            orderBy: z
+                .enum(['name', 'modifiedTime', 'sharedWithMeTime'])
+                .optional()
+                .default('sharedWithMeTime')
+                .describe('How to sort results. Defaults to most recently shared first.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info('Listing shared with me');
+            try {
+                let queryParts = ['sharedWithMe=true', 'trashed=false'];
+                if (args.mimeType) {
+                    queryParts.push(`mimeType='${args.mimeType}'`);
+                }
+                if (args.query) {
+                    queryParts.push(`name contains '${args.query.replace(/'/g, "\\'")}'`);
+                }
+                const orderBy = args.orderBy === 'sharedWithMeTime'
+                    ? 'sharedWithMeTime desc'
+                    : args.orderBy === 'modifiedTime'
+                        ? 'modifiedTime desc'
+                        : 'name';
+                const response = await drive.files.list({
+                    q: queryParts.join(' and '),
+                    pageSize: args.maxResults,
+                    pageToken: args.pageToken || undefined,
+                    orderBy,
+                    fields: 'nextPageToken,files(id,name,mimeType,modifiedTime,sharedWithMeTime,sharingUser(displayName,emailAddress),webViewLink,owners(displayName))',
+                    supportsAllDrives: true,
+                    includeItemsFromAllDrives: true,
+                });
+                const items = response.data.files || [];
+                const folders = items
+                    .filter((f) => f.mimeType === 'application/vnd.google-apps.folder')
+                    .map((f) => ({
+                    id: f.id,
+                    name: f.name,
+                    sharedWithMeTime: f.sharedWithMeTime,
+                    sharedBy: f.sharingUser?.displayName || f.owners?.[0]?.displayName || null,
+                    sharedByEmail: f.sharingUser?.emailAddress || null,
+                }));
+                const files = items
+                    .filter((f) => f.mimeType !== 'application/vnd.google-apps.folder')
+                    .map((f) => ({
+                    id: f.id,
+                    name: f.name,
+                    mimeType: f.mimeType,
+                    modifiedTime: f.modifiedTime,
+                    sharedWithMeTime: f.sharedWithMeTime,
+                    sharedBy: f.sharingUser?.displayName || f.owners?.[0]?.displayName || null,
+                    sharedByEmail: f.sharingUser?.emailAddress || null,
+                }));
+                const result = {
+                    folders,
+                    files,
+                    nextPageToken: response.data.nextPageToken || null,
+                    totalCount: items.length,
+                };
+                return JSON.stringify(result, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing shared items: ${error.message || error}`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have the correct Drive API scopes.');
+                throw new UserError(`Failed to list shared items: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/package.json

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