mcp-google-extras 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# mcp-google-extras
+
+An MCP server for Google Docs, Sheets, and Drive — with added support for reading `.docx` and `.pdf` files directly from Google Drive.
+
+Built on top of [@a-bonus/google-docs-mcp](https://www.npmjs.com/package/@a-bonus/google-docs-mcp) (ISC license), with additional tools for extracting text from Word documents and PDFs.
+
+## Features
+
+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
+
+### 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
+
+### 2. Configure your MCP client
+
+Add this to your MCP configuration (e.g., `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "google-docs": {
+      "command": "npx",
+      "args": ["-y", "mcp-google-extras"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your-client-id",
+        "GOOGLE_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+### 3. 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.
+
+You can also run the auth flow manually:
+
+```bash
+npx mcp-google-extras auth
+```
+
+## Tools
+
+### Google Docs
+`readDocument`, `appendText`, `appendMarkdown`, `insertText`, `deleteRange`, `modifyText`, `findAndReplace`, `insertTable`, `insertTableWithData`, `insertPageBreak`, `insertImage`, `listTabs`, `addTab`, `renameTab`, `applyTextStyle`, `applyParagraphStyle`, `addComment`, `deleteComment`, `getComment`, `listComments`, `replyToComment`, `resolveComment`, `replaceDocumentWithMarkdown`
+
+### Google Sheets
+`readSpreadsheet`, `writeSpreadsheet`, `batchWrite`, `appendRows`, `clearRange`, `createSpreadsheet`, `getSpreadsheetInfo`, `addSheet`, `deleteSheet`, `duplicateSheet`, `renameSheet`, `formatCells`, `readCellFormat`, `autoResizeColumns`, `freezeRowsAndColumns`, `setColumnWidths`, `addConditionalFormatting`, `copyFormatting`, `setDropdownValidation`, `createTable`, `deleteTable`, `getTable`, `listTables`, `appendTableRows`, `updateTableRange`, `insertChart`, `deleteChart`, `groupRows`, `ungroupAllRows`
+
+### Google Drive
+`listDocuments`, `searchDocuments`, `getDocumentInfo`, `createFolder`, `listFolderContents`, `getFolderInfo`, `moveFile`, `copyFile`, `renameFile`, `deleteFile`, `createDocument`, `createDocumentFromTemplate`, `listSpreadsheets`
+
+### Extras (new)
+`readFile`, `searchFileContents`
+
+## Environment Variables
+
+| 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 |
+| `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 |
+
+## License
+
+ISC (based on [@a-bonus/google-docs-mcp](https://www.npmjs.com/package/@a-bonus/google-docs-mcp))

package/dist/auth.js

@@ -0,0 +1,225 @@
+// src/auth.ts
+import { google } from 'googleapis';
+import { JWT } from 'google-auth-library';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import * as http from 'http';
+import { fileURLToPath } from 'url';
+import { logger } from './logger.js';
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRootDir = path.resolve(__dirname, '..');
+/** Credentials file path (legacy dev workflow fallback). */
+const CREDENTIALS_PATH = path.join(projectRootDir, 'credentials.json');
+/**
+ * Token storage directory following XDG Base Directory spec.
+ * Uses $XDG_CONFIG_HOME if set, otherwise ~/.config.
+ *
+ * When GOOGLE_MCP_PROFILE is set, tokens are stored in a subdirectory
+ * per profile, allowing multiple Google accounts (one per project).
+ */
+function getConfigDir() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const base = xdg || path.join(os.homedir(), '.config');
+    const baseDir = path.join(base, 'google-docs-mcp');
+    const profile = process.env.GOOGLE_MCP_PROFILE;
+    return profile ? path.join(baseDir, profile) : baseDir;
+}
+function getTokenPath() {
+    return path.join(getConfigDir(), 'token.json');
+}
+// ---------------------------------------------------------------------------
+// Scopes
+// ---------------------------------------------------------------------------
+const SCOPES = [
+    'https://www.googleapis.com/auth/documents',
+    'https://www.googleapis.com/auth/drive',
+    'https://www.googleapis.com/auth/spreadsheets',
+    'https://www.googleapis.com/auth/script.external_request',
+];
+// ---------------------------------------------------------------------------
+// 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)
+ */
+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 };
+    }
+    // 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,
+        };
+    }
+    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.');
+        }
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Service account auth (unchanged)
+// ---------------------------------------------------------------------------
+async function authorizeWithServiceAccount() {
+    const serviceAccountPath = process.env.SERVICE_ACCOUNT_PATH;
+    const impersonateUser = process.env.GOOGLE_IMPERSONATE_USER;
+    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) {
+            logger.info(`Service Account authentication successful, impersonating: ${impersonateUser}`);
+        }
+        else {
+            logger.info('Service Account authentication successful!');
+        }
+        return auth;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            logger.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.');
+        }
+        logger.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.');
+    }
+}
+// ---------------------------------------------------------------------------
+// Token persistence (XDG path)
+// ---------------------------------------------------------------------------
+async function loadSavedCredentialsIfExist() {
+    try {
+        const tokenPath = getTokenPath();
+        const content = await fs.readFile(tokenPath, 'utf8');
+        const credentials = JSON.parse(content);
+        const { client_secret, client_id } = await loadClientSecrets();
+        const client = new google.auth.OAuth2(client_id, client_secret);
+        client.setCredentials(credentials);
+        return client;
+    }
+    catch {
+        return null;
+    }
+}
+async function saveCredentials(client) {
+    const { client_secret, client_id } = await loadClientSecrets();
+    const configDir = getConfigDir();
+    await fs.mkdir(configDir, { recursive: true });
+    const tokenPath = getTokenPath();
+    const payload = JSON.stringify({
+        type: 'authorized_user',
+        client_id,
+        client_secret,
+        refresh_token: client.credentials.refresh_token,
+    }, null, 2);
+    await fs.writeFile(tokenPath, payload);
+    logger.info('Token stored to', tokenPath);
+}
+// ---------------------------------------------------------------------------
+// Interactive OAuth browser flow
+// ---------------------------------------------------------------------------
+async function authenticate() {
+    const { client_secret, client_id } = await loadClientSecrets();
+    // Start a temporary local server to receive the OAuth callback
+    const server = http.createServer();
+    await new Promise((resolve) => server.listen(0, 'localhost', resolve));
+    const port = server.address().port;
+    const redirectUri = `http://localhost:${port}`;
+    const oAuth2Client = new google.auth.OAuth2(client_id, client_secret, redirectUri);
+    const authorizeUrl = oAuth2Client.generateAuthUrl({
+        access_type: 'offline',
+        scope: SCOPES.join(' '),
+    });
+    logger.info('Authorize this app by visiting this url:', authorizeUrl);
+    // Wait for the OAuth callback
+    const code = await new Promise((resolve, reject) => {
+        server.on('request', (req, res) => {
+            const url = new URL(req.url, `http://localhost:${port}`);
+            const authCode = url.searchParams.get('code');
+            const error = url.searchParams.get('error');
+            if (error) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('<h1>Authorization failed</h1><p>You can close this tab.</p>');
+                reject(new Error(`Authorization error: ${error}`));
+                server.close();
+                return;
+            }
+            if (authCode) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('<h1>Authorization successful!</h1><p>You can close this tab.</p>');
+                resolve(authCode);
+                server.close();
+            }
+        });
+    });
+    const { tokens } = await oAuth2Client.getToken(code);
+    oAuth2Client.setCredentials(tokens);
+    if (tokens.refresh_token) {
+        await saveCredentials(oAuth2Client);
+    }
+    else {
+        logger.warn('Did not receive refresh token. Token might expire.');
+    }
+    logger.info('Authentication successful!');
+    return oAuth2Client;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Main authorization entry point used by the server at startup.
+ *
+ * Resolution order:
+ *   1. SERVICE_ACCOUNT_PATH env var -> service account JWT
+ *   2. Saved token in ~/.config/google-docs-mcp/token.json -> OAuth2Client
+ *   3. Interactive browser OAuth flow -> OAuth2Client (saves token for next time)
+ */
+export async function authorize() {
+    if (process.env.SERVICE_ACCOUNT_PATH) {
+        logger.info('Service account path detected. Attempting service account authentication...');
+        return authorizeWithServiceAccount();
+    }
+    logger.info('Attempting OAuth 2.0 authentication...');
+    const client = await loadSavedCredentialsIfExist();
+    if (client) {
+        logger.info('Using saved credentials.');
+        return client;
+    }
+    logger.info('No saved token found. Starting interactive authentication flow...');
+    return authenticate();
+}
+/**
+ * Forces the interactive OAuth browser flow, ignoring any saved token.
+ * Used by the `auth` CLI subcommand to let users (re-)authorize.
+ */
+export async function runAuthFlow() {
+    await authenticate();
+}

package/dist/cachedToolsList.js

@@ -0,0 +1,38 @@
+// FastMCP's default tools/list handler runs toJsonSchema() for every tool on every request.
+// Hosts that poll tools/list frequently (or many concurrent sessions) then burn a full CPU core.
+// We precompute the list once before stdio connects, then replace the handler to return that snapshot.
+import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { toJsonSchema } from 'xsschema';
+import { logger } from './logger.js';
+export function collectToolsWhileRegistering(server, out) {
+    const add = server.addTool.bind(server);
+    server.addTool = (tool) => {
+        out.push(tool);
+        add(tool);
+    };
+}
+export async function buildCachedToolsListPayload(tools) {
+    return {
+        tools: await Promise.all(tools.map(async (tool) => ({
+            annotations: tool.annotations,
+            description: tool.description,
+            inputSchema: tool.parameters
+                ? await toJsonSchema(tool.parameters)
+                : {
+                    additionalProperties: false,
+                    properties: {},
+                    type: 'object',
+                },
+            name: tool.name,
+        }))),
+    };
+}
+export function installCachedToolsListHandler(server, listPayload) {
+    const session = server.sessions[0];
+    if (!session) {
+        logger.warn('No MCP session; skipping tools/list cache install.');
+        return;
+    }
+    session.server.setRequestHandler(ListToolsRequestSchema, async () => listPayload);
+    logger.debug(`Installed cached tools/list (${listPayload.tools.length} tools).`);
+}

package/dist/clients.js

@@ -0,0 +1,92 @@
+// src/clients.ts
+import { google } from 'googleapis';
+import { UserError } from 'fastmcp';
+import { authorize } from './auth.js';
+import { logger } from './logger.js';
+let authClient = null;
+let googleDocs = null;
+let googleDrive = null;
+let googleSheets = null;
+let googleScript = null;
+// --- Initialization ---
+export async function initializeGoogleClient() {
+    if (googleDocs && googleDrive && googleSheets)
+        return { authClient, googleDocs, googleDrive, googleSheets, googleScript };
+    if (!authClient) {
+        try {
+            logger.info('Attempting to authorize Google API client...');
+            const client = await authorize();
+            authClient = client;
+            googleDocs = google.docs({ version: 'v1', auth: authClient });
+            googleDrive = google.drive({ version: 'v3', auth: authClient });
+            googleSheets = google.sheets({ version: 'v4', auth: authClient });
+            googleScript = google.script({ version: 'v1', auth: authClient });
+            logger.info('Google API client authorized successfully.');
+        }
+        catch (error) {
+            logger.error('FATAL: 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.');
+        }
+    }
+    if (authClient && !googleDocs) {
+        googleDocs = google.docs({ version: 'v1', auth: authClient });
+    }
+    if (authClient && !googleDrive) {
+        googleDrive = google.drive({ version: 'v3', auth: authClient });
+    }
+    if (authClient && !googleSheets) {
+        googleSheets = google.sheets({ version: 'v4', auth: authClient });
+    }
+    if (authClient && !googleScript) {
+        googleScript = google.script({ version: 'v1', auth: authClient });
+    }
+    if (!googleDocs || !googleDrive || !googleSheets) {
+        throw new Error('Google Docs, Drive, and Sheets clients could not be initialized.');
+    }
+    return { authClient, googleDocs, googleDrive, googleSheets, googleScript };
+}
+// --- Helper to get Docs client within tools ---
+export async function getDocsClient() {
+    const { googleDocs: docs } = await initializeGoogleClient();
+    if (!docs) {
+        throw new UserError('Google Docs client is not initialized. Authentication might have failed during startup or lost connection.');
+    }
+    return docs;
+}
+// --- Helper to get Drive client within tools ---
+export async function getDriveClient() {
+    const { googleDrive: drive } = await initializeGoogleClient();
+    if (!drive) {
+        throw new UserError('Google Drive client is not initialized. Authentication might have failed during startup or lost connection.');
+    }
+    return drive;
+}
+// --- Helper to get Sheets client within tools ---
+export async function getSheetsClient() {
+    const { googleSheets: sheets } = await initializeGoogleClient();
+    if (!sheets) {
+        throw new UserError('Google Sheets client is not initialized. Authentication might have failed during startup or lost connection.');
+    }
+    return sheets;
+}
+// --- Helper to get Auth client for direct API usage ---
+export async function getAuthClient() {
+    const { authClient: client } = await initializeGoogleClient();
+    if (!client) {
+        throw new UserError('Auth client is not initialized. Authentication might have failed during startup or lost connection.');
+    }
+    return client;
+}
+// --- Helper to get Script client within tools ---
+export async function getScriptClient() {
+    const { googleScript: script } = await initializeGoogleClient();
+    if (!script) {
+        throw new UserError('Google Script client is not initialized. Authentication might have failed during startup or lost connection.');
+    }
+    return script;
+}