@triffon/google-docs-mcp 1.11.3-triffon

package/dist/auth.js

@@ -0,0 +1,327 @@
+// 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 * as crypto from 'crypto';
+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;
+    if (profile && !/^[\w-]+$/.test(profile)) {
+        throw new Error('GOOGLE_MCP_PROFILE must contain only alphanumeric characters, hyphens, or underscores.');
+    }
+    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',
+    'https://www.googleapis.com/auth/script.projects',
+    'https://www.googleapis.com/auth/gmail.modify',
+    'https://www.googleapis.com/auth/calendar.events',
+];
+const TOKEN_CREDENTIAL_FIELDS = ['access_token', 'refresh_token', 'scope', 'token_type'];
+export function sanitizeStoredTokenCredentials(rawCredentials) {
+    if (!rawCredentials || typeof rawCredentials !== 'object' || Array.isArray(rawCredentials)) {
+        throw new Error('Invalid saved token format.');
+    }
+    const raw = rawCredentials;
+    const credentials = {};
+    for (const field of TOKEN_CREDENTIAL_FIELDS) {
+        const value = raw[field];
+        if (typeof value === 'string' && value.length > 0) {
+            credentials[field] = value;
+        }
+    }
+    if (typeof raw.expiry_date === 'number') {
+        credentials.expiry_date = raw.expiry_date;
+    }
+    if (!credentials.refresh_token && !credentials.access_token) {
+        throw new Error('Saved token does not contain OAuth token credentials.');
+    }
+    return credentials;
+}
+export function createStoredTokenPayload(credentials) {
+    return sanitizeStoredTokenCredentials({
+        refresh_token: credentials.refresh_token,
+    });
+}
+// ---------------------------------------------------------------------------
+// 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)
+ */
+export function describeMissingCredentials(credentialsPath, envId, envSecret) {
+    // A half-configured environment is the most confusing case: the user believes
+    // they configured the server, so "no credentials found" reads as a bug.
+    if (envId && !envSecret) {
+        return ('GOOGLE_CLIENT_ID is set but GOOGLE_CLIENT_SECRET is not, so OAuth cannot start. ' +
+            'Set GOOGLE_CLIENT_SECRET as well, or remove GOOGLE_CLIENT_ID and place a ' +
+            `credentials.json file at ${credentialsPath} instead.`);
+    }
+    if (!envId && envSecret) {
+        return ('GOOGLE_CLIENT_SECRET is set but GOOGLE_CLIENT_ID is not, so OAuth cannot start. ' +
+            'Set GOOGLE_CLIENT_ID as well, or remove GOOGLE_CLIENT_SECRET and place a ' +
+            `credentials.json file at ${credentialsPath} instead.`);
+    }
+    return ('No OAuth credentials found. Either set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, ' +
+        `or download your OAuth client JSON from the Google Cloud Console and save it as ${credentialsPath}. ` +
+        'Then run `npx @a-bonus/google-docs-mcp auth` to authorize.');
+}
+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
+    let content;
+    try {
+        content = await fs.readFile(CREDENTIALS_PATH, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new Error(describeMissingCredentials(CREDENTIALS_PATH, envId, envSecret));
+        }
+        if (err.code === 'EACCES') {
+            throw new Error(`credentials.json exists at ${CREDENTIALS_PATH} but is not readable (EACCES). ` +
+                'Fix its permissions, or set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET instead.');
+        }
+        throw err;
+    }
+    let keys;
+    try {
+        keys = JSON.parse(content);
+    }
+    catch {
+        throw new Error(`${CREDENTIALS_PATH} is not valid JSON. Re-download the OAuth client JSON from the ` +
+            'Google Cloud Console (APIs & Services -> Credentials -> your OAuth client -> Download JSON) ' +
+            'and save it unmodified.');
+    }
+    return extractClientSecrets(keys, CREDENTIALS_PATH);
+}
+/**
+ * Validates the shape of a parsed credentials.json and returns the OAuth client
+ * pair, or throws an error that says what is wrong with the file.
+ *
+ * Kept separate from the filesystem so every branch is testable, and because the
+ * shape errors are what users actually hit: issue #57 reported the failure
+ * surfacing as "Cannot destructure property 'client_secret' of
+ * 'credentials.installed' as it is undefined", which names no file and suggests
+ * no fix.
+ */
+export function extractClientSecrets(keys, credentialsPath) {
+    const key = keys?.installed || keys?.web;
+    if (!key) {
+        // Usually a service-account key or an API key rather than an OAuth client.
+        const shape = Object.keys(keys ?? {})
+            .slice(0, 5)
+            .join(', ') || 'no top-level keys';
+        throw new Error(`${credentialsPath} has no "installed" or "web" section, so it is not an OAuth client ` +
+            `file (found: ${shape}). Download an OAuth 2.0 Client ID of type "Desktop app" or ` +
+            '"Web application" from the Google Cloud Console; a service-account key will not work.');
+    }
+    const missing = ['client_id', 'client_secret'].filter((field) => !key[field]);
+    if (missing.length > 0) {
+        throw new Error(`${credentialsPath} is missing ${missing.join(' and ')} inside its ` +
+            `"${keys.installed ? 'installed' : 'web'}" section. Re-download the OAuth client JSON ` +
+            'from the Google Cloud Console and save it unmodified.');
+    }
+    return { client_id: key.client_id, client_secret: key.client_secret };
+}
+// ---------------------------------------------------------------------------
+// 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 = sanitizeStoredTokenCredentials(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 configDir = getConfigDir();
+    await fs.mkdir(configDir, { recursive: true, mode: 0o700 });
+    const tokenPath = getTokenPath();
+    const payload = JSON.stringify(createStoredTokenPayload(client.credentials), null, 2);
+    await fs.writeFile(tokenPath, payload, { mode: 0o600 });
+    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 state = crypto.randomBytes(32).toString('hex');
+    // prompt: 'consent' is what makes re-authorization actually work. Google returns a refresh
+    // token only when it re-asks for consent; for an app the user already granted, an offline
+    // request without it yields an access token and no refresh token. Since only the refresh
+    // token is persisted, a re-auth would then save nothing and leave the old grant — and its
+    // old, narrower scope set — in place, while still reporting success. Adding a scope to
+    // SCOPES would appear to do nothing at all.
+    const authorizeUrl = oAuth2Client.generateAuthUrl({
+        access_type: 'offline',
+        prompt: 'consent',
+        scope: SCOPES.join(' '),
+        state,
+    });
+    logger.info('Authorize this app by visiting this url:', authorizeUrl);
+    const AUTH_TIMEOUT_MS = 5 * 60 * 1000;
+    const timeout = setTimeout(() => {
+        server.close();
+    }, AUTH_TIMEOUT_MS);
+    // 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}`));
+                clearTimeout(timeout);
+                server.close();
+                return;
+            }
+            const returnedState = url.searchParams.get('state');
+            if (returnedState !== state) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end('<h1>Invalid state parameter</h1><p>Possible CSRF attack. Please try again.</p>');
+                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);
+                clearTimeout(timeout);
+                server.close();
+            }
+        });
+    });
+    const { tokens } = await oAuth2Client.getToken(code);
+    oAuth2Client.setCredentials(tokens);
+    if (!tokens.refresh_token) {
+        // Nothing is persisted without a refresh token, so this run changed nothing on disk. Said
+        // as a warning it reads as a minor caveat under a success message, and the stale grant
+        // goes unnoticed until some tool fails for a reason that looks unrelated.
+        throw new Error('Google returned no refresh token, so nothing was saved and the previous authorization ' +
+            '(with whatever scopes it had) is still in force. Revoke this app at ' +
+            'https://myaccount.google.com/permissions and run the auth flow again.');
+    }
+    await saveCredentials(oAuth2Client);
+    logger.info(`Authentication successful! Granted scopes: ${tokens.scope ?? '(not reported)'}`);
+    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,180 @@
+// src/clients.ts
+import { google } from 'googleapis';
+import { UserError } from 'fastmcp';
+import { authorize } from './auth.js';
+import { logger } from './logger.js';
+import { requestClients } from './remoteWrapper.js';
+const isRemote = process.env.MCP_TRANSPORT === 'httpStream';
+let authClient = null;
+let googleDocs = null;
+let googleDrive = null;
+let googleSheets = null;
+let googleScript = null;
+let googleGmail = null;
+let googleCalendar = null;
+// --- Initialization ---
+export async function initializeGoogleClient() {
+    if (googleDocs && googleDrive && googleSheets)
+        return {
+            authClient,
+            googleDocs,
+            googleDrive,
+            googleSheets,
+            googleScript,
+            googleGmail,
+            googleCalendar,
+        };
+    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 });
+            googleGmail = google.gmail({ version: 'v1', auth: authClient });
+            googleCalendar = google.calendar({ version: 'v3', 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;
+            googleGmail = null;
+            googleCalendar = 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 (authClient && !googleGmail) {
+        googleGmail = google.gmail({ version: 'v1', auth: authClient });
+    }
+    if (authClient && !googleCalendar) {
+        googleCalendar = google.calendar({ version: 'v3', 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,
+        googleGmail,
+        googleCalendar,
+    };
+}
+// --- Helper to get Docs client within tools ---
+export async function getDocsClient() {
+    const remote = requestClients.getStore();
+    if (remote)
+        return remote.docs;
+    if (isRemote) {
+        throw new UserError('Request context missing. Tool must be called within an MCP request.');
+    }
+    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 remote = requestClients.getStore();
+    if (remote)
+        return remote.drive;
+    if (isRemote) {
+        throw new UserError('Request context missing. Tool must be called within an MCP request.');
+    }
+    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 remote = requestClients.getStore();
+    if (remote)
+        return remote.sheets;
+    if (isRemote) {
+        throw new UserError('Request context missing. Tool must be called within an MCP request.');
+    }
+    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 remote = requestClients.getStore();
+    if (remote)
+        return remote.auth;
+    if (isRemote) {
+        throw new UserError('Request context missing. Tool must be called within an MCP request.');
+    }
+    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 remote = requestClients.getStore();
+    if (remote)
+        return remote.script;
+    if (isRemote) {
+        throw new UserError('Request context missing. Tool must be called within an MCP request.');
+    }
+    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;
+}
+// --- Helper to get Gmail client within tools ---
+export async function getGmailClient() {
+    const remote = requestClients.getStore();
+    if (remote)
+        return remote.gmail;
+    if (isRemote) {
+        throw new UserError('Request context missing. Tool must be called within an MCP request.');
+    }
+    const { googleGmail: gmail } = await initializeGoogleClient();
+    if (!gmail) {
+        throw new UserError('Gmail client is not initialized. Authentication might have failed during startup or lost connection.');
+    }
+    return gmail;
+}
+// --- Helper to get Calendar client within tools ---
+export async function getCalendarClient() {
+    const remote = requestClients.getStore();
+    if (remote)
+        return remote.calendar;
+    if (isRemote) {
+        throw new UserError('Request context missing. Tool must be called within an MCP request.');
+    }
+    const { googleCalendar: calendar } = await initializeGoogleClient();
+    if (!calendar) {
+        throw new UserError('Google Calendar client is not initialized. Authentication might have failed during startup or lost connection.');
+    }
+    return calendar;
+}

package/dist/config.js

@@ -0,0 +1,9 @@
+/**
+ * Parses MCP_STATELESS env var. Stateless mode disables httpStream session
+ * tracking so the server survives serverless scale-to-zero without losing
+ * MCP sessions.
+ */
+export function parseStatelessFlag(value) {
+    const raw = (value ?? process.env.MCP_STATELESS ?? '').trim().toLowerCase();
+    return raw === 'true' || raw === '1';
+}

package/dist/downloadProxy.js

@@ -0,0 +1,82 @@
+import crypto from 'node:crypto';
+import { Readable } from 'node:stream';
+import { stream } from 'hono/streaming';
+import { google } from 'googleapis';
+import { OAuth2Client } from 'google-auth-library';
+// Per-process encryption key — never leaves memory, regenerated on restart.
+const ENCRYPTION_KEY = crypto.randomBytes(32);
+function encrypt(plaintext) {
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', ENCRYPTION_KEY, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    // iv (12) + tag (16) + ciphertext — all hex-encoded
+    return iv.toString('hex') + tag.toString('hex') + encrypted.toString('hex');
+}
+function decrypt(blob) {
+    const iv = Buffer.from(blob.slice(0, 24), 'hex');
+    const tag = Buffer.from(blob.slice(24, 56), 'hex');
+    const encrypted = Buffer.from(blob.slice(56), 'hex');
+    const decipher = crypto.createDecipheriv('aes-256-gcm', ENCRYPTION_KEY, iv);
+    decipher.setAuthTag(tag);
+    return decipher.update(encrypted) + decipher.final('utf8');
+}
+const pending = new Map();
+setInterval(() => {
+    const now = Date.now();
+    for (const [k, v] of pending)
+        if (v.expiresAt < now)
+            pending.delete(k);
+}, 60_000).unref();
+export function createDownloadToken(opts) {
+    const token = crypto.randomBytes(32).toString('hex');
+    pending.set(token, {
+        ...opts,
+        accessToken: encrypt(opts.accessToken),
+        expiresAt: Date.now() + 60 * 1000,
+    });
+    return token;
+}
+export function registerDownloadRoute(server) {
+    const app = server.getApp();
+    app.get('/download/:token', async (c) => {
+        const token = c.req.param('token');
+        const entry = pending.get(token);
+        if (!entry || entry.expiresAt < Date.now()) {
+            pending.delete(token);
+            return c.text('Download link expired or invalid.', 410);
+        }
+        pending.delete(token);
+        let accessToken;
+        try {
+            accessToken = decrypt(entry.accessToken);
+        }
+        catch {
+            return c.text('Download link expired or invalid.', 410);
+        }
+        const auth = new OAuth2Client();
+        auth.setCredentials({ access_token: accessToken });
+        const drive = google.drive({ version: 'v3', auth });
+        c.header('Content-Disposition', `attachment; filename="${entry.fileName.replace(/"/g, '\\"')}"`);
+        if (entry.isWorkspace && entry.exportMime) {
+            c.header('Content-Type', entry.exportMime);
+            const res = await drive.files.export({ fileId: entry.fileId, mimeType: entry.exportMime }, { responseType: 'stream' });
+            const webStream = Readable.toWeb(res.data);
+            return stream(c, async (s) => {
+                await s.pipe(webStream);
+            });
+        }
+        else {
+            c.header('Content-Type', entry.mimeType);
+            const res = await drive.files.get({ fileId: entry.fileId, alt: 'media', supportsAllDrives: true }, { responseType: 'stream' });
+            const webStream = Readable.toWeb(res.data);
+            return stream(c, async (s) => {
+                await s.pipe(webStream);
+            });
+        }
+    });
+}
+/** @internal Exposed only for tests — do not use in production code. */
+export function _testGetPending() {
+    return pending;
+}

package/dist/driveQueryUtils.js

@@ -0,0 +1,7 @@
+/**
+ * Escapes a string for safe interpolation into Google Drive API query strings.
+ * Backslashes must be escaped first, then single quotes (order matters).
+ */
+export function escapeDriveQuery(value) {
+    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}

package/dist/firestoreTokenStorage.js

@@ -0,0 +1,32 @@
+import { Firestore } from '@google-cloud/firestore';
+const COLLECTION = 'mcp-oauth-tokens';
+/**
+ * Firestore-backed TokenStorage for FastMCP's OAuth proxy.
+ * Tokens survive container restarts and redeployments.
+ * On Cloud Run, authentication is automatic via the service account.
+ */
+export class FirestoreTokenStorage {
+    db;
+    constructor(projectId) {
+        this.db = new Firestore({ projectId });
+    }
+    async save(key, value, _ttl) {
+        const doc = this.db.collection(COLLECTION).doc(encodeKey(key));
+        await doc.set({ value, createdAt: Date.now() });
+    }
+    async get(key) {
+        const doc = await this.db.collection(COLLECTION).doc(encodeKey(key)).get();
+        if (!doc.exists)
+            return null;
+        return doc.data().value;
+    }
+    async delete(key) {
+        await this.db.collection(COLLECTION).doc(encodeKey(key)).delete();
+    }
+    async cleanup() {
+        // FastMCP handles token expiry internally via delete() calls.
+    }
+}
+function encodeKey(key) {
+    return key.replace(/\//g, '__');
+}