google-tools-mcp 1.2.11 → 2.0.0

package/dist/readTracker.js

@@ -7,23 +7,57 @@ import { UserError } from 'fastmcp';
 import { createPatch } from 'diff';
 import { getDriveClient } from './clients.js';
 import { logger } from './logger.js';
+import { currentSessionKey } from './sessionContext.js';
 
-// Map of fileId → { readAt: Date, modifiedTime: string|null, content: string|null }
-// content is only populated for file types that opt in (currently Google Docs).
-// Sheets and raw Drive files still track read/modifiedTime only.
-const readLog = new Map();
+// Per-session read logs.
+//
+// Each session has its own Map of fileId → { readAt, modifiedTime, content }.
+// content is only populated for file types that opt in (currently Google Docs);
+// Sheets and raw Drive files track read/modifiedTime only.
+//
+// Namespacing by session is what makes shared HTTP mode safe: two clients
+// reading or mutating the same file no longer clobber each other's tracked
+// content, modifiedTime, and revision guard (PR #36 review). In stdio mode the
+// ambient session key is null, so there is a single namespace and behavior is
+// identical to the original single-Map implementation.
+const sessions = new Map(); // sessionKey (string|null) → Map<fileId, entry>
+
+// Sentinel for the stdio / no-request namespace (Map keys can't be null-safe
+// across distinct absent values, so normalize null → this string).
+const DEFAULT_SESSION = '\0default';
+
+function logForCurrentSession() {
+    const key = currentSessionKey() ?? DEFAULT_SESSION;
+    let log = sessions.get(key);
+    if (!log) {
+        log = new Map();
+        sessions.set(key, log);
+    }
+    return log;
+}
+
+/**
+ * Drop all tracked state for a session. Called when an HTTP session disconnects
+ * so a long-lived shared server doesn't accumulate tracker entries forever.
+ * @param {string|null|undefined} sessionKey
+ */
+export function clearSession(sessionKey) {
+    sessions.delete(sessionKey ?? DEFAULT_SESSION);
+}
 
 /**
  * Record that a file was read. Call from all read tools.
  * @param fileId
  * @param modifiedTime Drive API modifiedTime (ISO string) at read time, or null
  * @param content Optional content snapshot (e.g. markdown for docs) used for diffs
+ * @param revisionId Optional Google Docs revision ID used for optimistic concurrency
  */
-export function trackRead(fileId, modifiedTime, content) {
-    readLog.set(fileId, {
+export function trackRead(fileId, modifiedTime, content, revisionId) {
+    logForCurrentSession().set(fileId, {
         readAt: new Date(),
         modifiedTime: modifiedTime || null,
         content: typeof content === 'string' ? content : null,
+        revisionId: typeof revisionId === 'string' ? revisionId : null,
     });
 }
 
@@ -33,12 +67,19 @@ export function trackRead(fileId, modifiedTime, content) {
  *
  * @param fileId - The file/document/spreadsheet ID
  * @param opts.skipExternalCheck - If true, skip the Drive API modifiedTime check (for performance)
- * @param opts.contentFetcher - Optional async () => string. If provided and an
- *   external-change conflict is detected, the fetcher is used to grab current
- *   content and the UserError message will include a unified diff plus rebase
- *   instructions rather than a plain error.
+ * @param opts.contentFetcher - Optional async () => (string | { content: string, revisionId?: string|null }).
+ *   If provided and an external-change conflict is detected, the fetcher is used to grab current
+ *   content (and, for Google Docs, the revision that content came from) and the UserError message
+ *   will include a unified diff plus rebase instructions rather than a plain error. When the fetcher
+ *   returns an object with `revisionId`, that revision is stored as the new baseline atomically with
+ *   the content/modifiedTime refresh below, so a subsequent rebased write is guarded against the
+ *   version the diff was actually taken from rather than the pre-external-edit revision. When the
+ *   fetcher returns a bare string (or omits revisionId), the revision can't be known to be current,
+ *   so it is cleared instead of left stale — the next write then goes out unguarded rather than with
+ *   a guaranteed-stale requiredRevisionId.
  */
 export async function guardMutation(fileId, opts) {
+    const readLog = logForCurrentSession();
     const entry = readLog.get(fileId);
     if (!entry) {
         throw new UserError(
@@ -48,6 +89,19 @@ export async function guardMutation(fileId, opts) {
         );
     }
 
+    // A previous write left the document in a state we can't describe: no
+    // revision to guard against and no content snapshot to diff. Refuse rather
+    // than let this write go out against a stale baseline. The modifiedTime
+    // check below cannot cover this, because it is skipped when modifiedTime
+    // is null and would just re-baseline on the post-write value.
+    if (entry.requiresReread) {
+        throw new UserError(
+            `This file (${fileId}) must be read again before it can be edited: ${entry.requiresReread} ` +
+            'Read it again (readDocument, readSpreadsheet, readFile, or readDriveFile) and rebase your edit ' +
+            'on the current content.'
+        );
+    }
+
     // Optionally check if file was modified externally since last read
     if (!opts?.skipExternalCheck) {
         try {
@@ -65,8 +119,22 @@ export async function guardMutation(fileId, opts) {
                 // model can rebase its edit on top of the new version.
                 if (entry.content && typeof opts?.contentFetcher === 'function') {
                     let currentContent;
+                    let currentRevisionId;
                     try {
-                        currentContent = await opts.contentFetcher();
+                        const fetched = await opts.contentFetcher();
+                        if (fetched && typeof fetched === 'object') {
+                            currentContent = fetched.content;
+                            currentRevisionId = typeof fetched.revisionId === 'string' ? fetched.revisionId : null;
+                        } else {
+                            currentContent = fetched;
+                            // A bare-string fetcher can't tell us the revision the
+                            // content came from. Clear rather than keep the
+                            // pre-external-edit revisionId around: a cleared
+                            // revision sends the next write out unguarded, which
+                            // is safe; a stale one sends it out with a
+                            // requiredRevisionId that is guaranteed to conflict.
+                            currentRevisionId = null;
+                        }
                     } catch (fetchError) {
                         logger.warn(`contentFetcher failed for ${fileId}: ${fetchError.message}`);
                     }
@@ -79,10 +147,16 @@ export async function guardMutation(fileId, opts) {
                             'current',
                             { context: 3 }
                         );
-                        // Refresh the snapshot so a subsequent read/mutation
-                        // works against the new baseline.
+                        // Refresh content, modifiedTime, AND revisionId together
+                        // (atomically, in the same tick) so a subsequent rebased
+                        // write is guarded against the version this diff was
+                        // actually taken from — not the pre-external-edit
+                        // revision, which would otherwise cause a second,
+                        // confusing conflict even when the caller correctly
+                        // rebuilt its edit from the diff above.
                         entry.content = currentContent;
                         entry.modifiedTime = currentModifiedTime;
+                        entry.revisionId = currentRevisionId;
                         throw new UserError(
                             `This file was modified externally since you last read it ` +
                             `(last read: ${readAt}, last modified: ${currentModifiedTime}).\n\n` +
@@ -115,9 +189,22 @@ export async function guardMutation(fileId, opts) {
 /**
  * Update the read tracker after a successful mutation (so subsequent mutations
  * don't fail the external-change check against our own changes).
+ *
+ * @param fileId
+ * @param newRevisionId Optional Google Docs revision ID produced by the write
+ *   that just succeeded (the API's batchUpdate response echoes this back as
+ *   `writeControl.requiredRevisionId` — "the updated write control after
+ *   applying the request"). When provided, the WriteControl guard is
+ *   re-armed against this fresh revision instead of being disabled, so a
+ *   second write to the same document later in the same session (with no
+ *   re-read in between) is still guarded against a genuine concurrent edit —
+ *   rather than either (a) silently going out unguarded, or (b) reusing the
+ *   now-stale pre-mutation revision and spuriously conflicting with our own
+ *   prior write. When omitted, the revision is cleared (legacy/unknown
+ *   behavior, same as before).
  */
-export function trackMutation(fileId) {
-    const entry = readLog.get(fileId);
+export function trackMutation(fileId, newRevisionId) {
+    const entry = logForCurrentSession().get(fileId);
     if (entry) {
         entry.readAt = new Date();
         // Clear modifiedTime — it will be stale after our mutation.
@@ -126,6 +213,33 @@ export function trackMutation(fileId) {
         // Content is also stale after our mutation; clear so a future diff
         // doesn't show our own edits as "external" changes.
         entry.content = null;
+        entry.revisionId = typeof newRevisionId === 'string' ? newRevisionId : null;
+    }
+}
+
+/**
+ * Mark a file as needing a fresh read before any further mutation.
+ *
+ * Use this instead of trackMutation after a write whose resulting revision we
+ * cannot learn (an Apps Script call that edits the document outside our
+ * batchUpdate visibility, for example). trackMutation on its own clears the
+ * revision and the modifiedTime, which leaves the next write with nothing to
+ * guard against: it sends no writeControl and the external-change check is
+ * skipped because modifiedTime is null. That write would then be based on a
+ * pre-mutation read without anyone noticing. Blocking it and asking for a
+ * re-read is the only safe option when the post-write revision is unknown.
+ *
+ * @param fileId
+ * @param reason Sentence fragment explaining what happened, shown to the caller.
+ */
+export function requireRereadBeforeMutation(fileId, reason) {
+    const entry = logForCurrentSession().get(fileId);
+    if (entry) {
+        entry.readAt = new Date();
+        entry.modifiedTime = null;
+        entry.content = null;
+        entry.revisionId = null;
+        entry.requiresReread = reason || 'a previous write changed it in a way we could not track.';
     }
 }
 
@@ -133,13 +247,18 @@ export function trackMutation(fileId) {
  * Check if a file has been read (without throwing).
  */
 export function hasBeenRead(fileId) {
-    return readLog.has(fileId);
+    return logForCurrentSession().has(fileId);
 }
 
 /**
  * Return the content snapshot from the last read, or null if none stored.
  */
 export function getLastReadContent(fileId) {
-    const entry = readLog.get(fileId);
+    const entry = logForCurrentSession().get(fileId);
     return entry?.content ?? null;
 }
+
+/** Return the Google Docs revision ID from the last read, or null. */
+export function getLastReadRevisionId(fileId) {
+    return logForCurrentSession().get(fileId)?.revisionId ?? null;
+}

package/dist/sessionContext.js

@@ -0,0 +1,37 @@
+// Per-request session scoping.
+//
+// In stdio mode there is exactly one client per process, so module-global state
+// (e.g. the read-before-edit tracker in readTracker.js) is implicitly
+// per-client. In shared HTTP mode a single process serves many clients, so that
+// same global state would leak across clients — one client's "I read this doc"
+// would satisfy another client's mutation guard, and their content snapshots
+// would clobber each other (see PR #36 review).
+//
+// This module carries the current request's session key ambiently via
+// AsyncLocalStorage so stateful helpers can namespace their data per session
+// without every tool having to thread a session id through its call sites.
+// Outside a request (stdio, startup) the key is null, which maps to a single
+// default namespace — preserving the original single-client behavior exactly.
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const sessionStore = new AsyncLocalStorage();
+
+/**
+ * Run `fn` with `sessionKey` bound as the ambient session for the duration of
+ * the (possibly async) call. Returns whatever `fn` returns.
+ * @param {string|null|undefined} sessionKey
+ * @param {() => any} fn
+ */
+export function runWithSession(sessionKey, fn) {
+    return sessionStore.run(sessionKey ?? null, fn);
+}
+
+/**
+ * The current ambient session key, or null when running outside a request
+ * (stdio transport, server startup). null is a valid namespace key.
+ * @returns {string|null}
+ */
+export function currentSessionKey() {
+    const key = sessionStore.getStore();
+    return key === undefined ? null : key;
+}

package/dist/setup.js

@@ -6,6 +6,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
 import { exec, execSync } from 'child_process';
+import { fileURLToPath } from 'url';
 import { google } from 'googleapis';
 
 // ---------------------------------------------------------------------------
@@ -35,6 +36,15 @@ const CONSENT_SCREEN_URL =
 const AUDIENCE_URL =
     'https://console.cloud.google.com/auth/audience';
 
+// The command a global-install user needs to run to pick up a new release.
+// Unlike `npx -y google-tools-mcp`, a direct `node <global-path>` launch
+// command (see the fast-launch block below) never re-resolves to the latest
+// version on its own, so we surface this explicitly wherever we point a
+// client at a fixed path. Exported so the regression test can assert the
+// wizard actually tells the user about it instead of just asserting a
+// hardcoded string.
+export const UPDATE_COMMAND = 'npm install -g google-tools-mcp@latest';
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -82,6 +92,115 @@ function cancelled() {
     process.exit(0);
 }
 
+// ---------------------------------------------------------------------------
+// Fast-launch install
+// ---------------------------------------------------------------------------
+// `npx -y google-tools-mcp` re-resolves and verifies the whole dependency
+// tree on every single launch. On some machines (observed on Windows, likely
+// antivirus scanning of npm's file I/O during install/verify — this package
+// pulls in fastmcp + the full googleapis client library tree) that takes
+// 30+ seconds, even when the exact version is already cached. Claude Code's
+// stdio MCP connection timeout is a fixed 30s, so that's enough to lose the
+// race and surface as "the server won't connect" with no visible cause.
+// See https://github.com/karthikcsq/google-tools-mcp/issues/46
+//
+// To avoid paying npx's per-launch cost on every server start, we install
+// the package globally once here and point the MCP client directly at the
+// resolved dist/index.js via `node`, skipping npx entirely afterward.
+
+// Pure helper: where npm puts an installed package's files under a given
+// global node_modules root. Exported for testing.
+export function resolveGlobalIndexPath(globalRoot) {
+    return path.join(globalRoot, 'google-tools-mcp', 'dist', 'index.js');
+}
+
+// Installs google-tools-mcp globally and resolves the absolute path to its
+// dist/index.js so callers can launch it directly with `node`, bypassing
+// npx. `run`/`access`/`hasNpm` are injectable for testing; they default to
+// the real shell/filesystem/CLI-detection implementations.
+export async function installGlobalFastLaunch({
+    run = runCommand,
+    access = fs.access,
+    hasNpm = () => hasCli('npm'),
+} = {}) {
+    if (!hasNpm()) {
+        return { ok: false, npmMissing: true, reason: 'npm was not found on PATH, so nothing can be installed globally.' };
+    }
+
+    try {
+        await run('npm install -g google-tools-mcp@latest');
+    } catch (err) {
+        return { ok: false, reason: `npm install -g google-tools-mcp failed: ${err.message}` };
+    }
+
+    let globalRoot;
+    try {
+        globalRoot = (await run('npm root -g')).trim();
+    } catch (err) {
+        return { ok: false, reason: `could not resolve the npm global root: ${err.message}` };
+    }
+
+    const indexPath = resolveGlobalIndexPath(globalRoot);
+    try {
+        await access(indexPath);
+    } catch {
+        return { ok: false, reason: `installed globally, but dist/index.js was not found at ${indexPath}` };
+    }
+
+    return { ok: true, indexPath };
+}
+
+// Absolute path to the dist/index.js sitting next to this file, i.e. the copy
+// of the package that is running setup right now. Used as the last fallback:
+// wherever this wizard was launched from, that entry point demonstrably exists.
+// Returns null if the URL can't be turned into a path, so a surprise here
+// degrades to "no last-resort fallback" instead of crashing the wizard.
+export function resolveRunningIndexPath(moduleUrl = import.meta.url) {
+    try {
+        return path.join(path.dirname(fileURLToPath(moduleUrl)), 'index.js');
+    } catch {
+        return null;
+    }
+}
+
+// Builds the { command, args, shellDisplay, source } to launch the server with,
+// given the result of installGlobalFastLaunch().
+//
+// Falling back to `npx` unconditionally would be wrong: on a standard Node
+// installation npm and npx ship together, so "npm is not on PATH" almost always
+// means npx is not either, and the wizard would finish happily after writing a
+// launch command that cannot run. So the order is: the global install if it
+// worked, then npx if npx actually exists, then the copy of the package running
+// this wizard. Returns null when none of those is available, which the caller
+// must report rather than write a broken config.
+export function buildLaunchCommand(fastLaunch, {
+    execPath = process.execPath,
+    runningIndexPath = null,
+    hasNpx = () => hasCli('npx'),
+} = {}) {
+    const direct = (indexPath, source) => ({
+        command: execPath,
+        args: [indexPath],
+        shellDisplay: `"${execPath}" "${indexPath}"`,
+        source,
+    });
+
+    if (fastLaunch?.ok) return direct(fastLaunch.indexPath, 'global');
+
+    if (hasNpx()) {
+        return {
+            command: 'npx',
+            args: ['-y', 'google-tools-mcp'],
+            shellDisplay: 'npx -y google-tools-mcp',
+            source: 'npx',
+        };
+    }
+
+    if (runningIndexPath) return direct(runningIndexPath, 'running-copy');
+
+    return null;
+}
+
 // Pull the GCP project number out of an OAuth client ID.
 // Format: <project_number>-<hash>.apps.googleusercontent.com
 function extractProjectNumberFromClientId(clientId) {
@@ -381,6 +500,60 @@ export async function runSetup() {
 
     // ── Step 5: Install ──────────────────────────────────────────────────
     p.log.step(chalk.cyan.bold('Step 5') + chalk.dim(' · ') + 'Install MCP server');
+    p.log.message(chalk.dim(
+        'Installing globally so your MCP client launches google-tools-mcp directly ' +
+        'instead of through npx — npx re-resolves the whole dependency tree on every ' +
+        'launch, which can take 30+ seconds on some machines and lose the race against ' +
+        "Claude Code's 30s connection timeout (github.com/karthikcsq/google-tools-mcp/issues/46)."
+    ));
+
+    const installSpinner = p.spinner();
+    installSpinner.start('Installing google-tools-mcp globally...');
+    const fastLaunch = await installGlobalFastLaunch();
+
+    // Last-resort launch target: the copy of the package running this wizard.
+    // Only offered if it is really there, so we never write a path we haven't
+    // confirmed.
+    let runningIndexPath = resolveRunningIndexPath();
+    try {
+        await fs.access(runningIndexPath);
+    } catch {
+        runningIndexPath = null;
+    }
+
+    const launch = buildLaunchCommand(fastLaunch, { runningIndexPath });
+
+    if (fastLaunch.ok) {
+        installSpinner.stop(chalk.green('Installed globally — MCP clients will launch it directly via node.'));
+        p.log.message(chalk.dim(
+            'Note: unlike npx, this direct launch path does not auto-update. The server checks for new ' +
+            'releases at startup and will log a line if one is available, without slowing down connection. ' +
+            `To update whenever you like, run: `
+        ) + chalk.cyan(UPDATE_COMMAND));
+    } else if (!launch) {
+        installSpinner.stop(chalk.red('Could not work out any way to launch the server on this machine.'));
+        p.log.warn(fastLaunch.reason);
+        p.log.error(
+            'No global install, no npx on PATH, and no readable entry point next to this wizard. ' +
+            'Install Node.js with npm from nodejs.org, or install this package yourself with ' +
+            '`npm install -g google-tools-mcp`, then run setup again. Nothing was written to your MCP client config.'
+        );
+        process.exit(1);
+    } else if (launch.source === 'npx') {
+        installSpinner.stop(chalk.yellow('Global install failed — falling back to npx (slower; can hit connection timeouts).'));
+        p.log.warn(fastLaunch.reason);
+        p.log.message(chalk.dim('See the README troubleshooting section if the MCP server fails to connect.'));
+    } else {
+        installSpinner.stop(chalk.yellow('Global install failed and npx is not on PATH — pointing at this copy of the package instead.'));
+        p.log.warn(fastLaunch.reason);
+        p.log.message(chalk.dim(
+            `Your MCP client will launch ${runningIndexPath} directly. That works as long as this copy stays ` +
+            'where it is; if it was run from a temporary npx cache, install the package properly and run setup again.'
+        ));
+        p.log.message(chalk.dim(
+            'This path does not auto-update either. Once npm is available, run: '
+        ) + chalk.cyan(UPDATE_COMMAND) + chalk.dim(' to update, or re-run this wizard.'));
+    }
 
     const hasCodex = hasCli('codex');
     const hasClaude = hasCli('claude');
@@ -393,19 +566,20 @@ export async function runSetup() {
         });
         if (p.isCancel(install)) cancelled();
 
+        const codexAddCmd = `codex mcp add google -- ${launch.shellDisplay}`;
         if (install) {
             const s = p.spinner();
             s.start('Adding to Codex...');
             try {
-                await runCommand('codex mcp add google -- npx -y google-tools-mcp');
+                await runCommand(codexAddCmd);
                 s.stop('Added to Codex!');
             } catch (err) {
                 s.stop('Failed to add automatically');
                 p.log.warn(`Error: ${err.message}`);
-                p.log.message(`Run manually:\n${chalk.cyan('codex mcp add google -- npx -y google-tools-mcp')}`);
+                p.log.message(`Run manually:\n${chalk.cyan(codexAddCmd)}`);
             }
         } else {
-            p.log.message(`To add later:\n${chalk.cyan('codex mcp add google -- npx -y google-tools-mcp')}`);
+            p.log.message(`To add later:\n${chalk.cyan(codexAddCmd)}`);
         }
     }
 
@@ -418,34 +592,38 @@ export async function runSetup() {
         });
         if (p.isCancel(install)) cancelled();
 
+        const claudeAddCmd = `claude mcp add -s user google -- ${launch.shellDisplay}`;
         if (install) {
             const s = p.spinner();
             s.start('Adding to Claude Code...');
             try {
-                await runCommand('claude mcp add -s user google -- npx -y google-tools-mcp');
+                await runCommand(claudeAddCmd);
                 s.stop('Added to Claude Code!');
             } catch (err) {
                 s.stop('Failed to add automatically');
                 p.log.warn(`Error: ${err.message}`);
-                p.log.message(`Run manually:\n${chalk.cyan('claude mcp add -s user google -- npx -y google-tools-mcp')}`);
+                p.log.message(`Run manually:\n${chalk.cyan(claudeAddCmd)}`);
             }
         } else {
-            p.log.message(`To add later:\n${chalk.cyan('claude mcp add -s user google -- npx -y google-tools-mcp')}`);
+            p.log.message(`To add later:\n${chalk.cyan(claudeAddCmd)}`);
         }
     }
 
     if (!hasCodex && !hasClaude) {
+        const jsonSnippet = JSON.stringify({
+            mcpServers: { google: { command: launch.command, args: launch.args } },
+        });
         p.log.message([
             'Add to your MCP client:',
             '',
             chalk.dim('Codex:'),
-            chalk.cyan('  codex mcp add google -- npx -y google-tools-mcp'),
+            chalk.cyan(`  codex mcp add google -- ${launch.shellDisplay}`),
             '',
             chalk.dim('Claude Code:'),
-            chalk.cyan('  claude mcp add -s user google -- npx -y google-tools-mcp'),
+            chalk.cyan(`  claude mcp add -s user google -- ${launch.shellDisplay}`),
             '',
             chalk.dim('Other clients') + chalk.dim(' (.mcp.json):'),
-            chalk.cyan('  { "mcpServers": { "google": { "command": "npx", "args": ["-y", "google-tools-mcp"] } } }'),
+            chalk.cyan(`  ${jsonSnippet}`),
         ].join('\n'));
     }
 

package/dist/tools/calendar/getBusy.js

@@ -1,64 +1,64 @@
-import { UserError } from 'fastmcp';
-import { z } from 'zod';
-import { getCalendarClient } from '../../clients.js';
-
-export function register(server) {
-    server.addTool({
-        name: 'get_busy',
-        description:
-            'Returns busy time blocks for one or more people in a given time range. ' +
-            'Works across your Google Workspace org without needing calendar sharing — you see when people are busy but not event details. ' +
-            'Pass email addresses as calendar_ids to check other people.',
-        parameters: z.object({
-            time_min: z
-                .string()
-                .describe('Start of query range in RFC3339 format (e.g. "2025-03-15T00:00:00Z").'),
-            time_max: z
-                .string()
-                .describe('End of query range in RFC3339 format (e.g. "2025-03-16T23:59:59Z").'),
-            calendar_ids: z
-                .array(z.string())
-                .optional()
-                .default(['primary'])
-                .describe('Calendar IDs or email addresses to check. Defaults to ["primary"].'),
-        }),
-        execute: async (args, { log }) => {
-            const calendar = await getCalendarClient();
-            log.info(`Checking busy times for ${args.calendar_ids.join(', ')}`);
-
-            try {
-                const response = await calendar.freebusy.query({
-                    requestBody: {
-                        timeMin: args.time_min,
-                        timeMax: args.time_max,
-                        items: args.calendar_ids.map((id) => ({ id })),
-                    },
-                });
-
-                const calendars = response.data.calendars || {};
-                const results = {};
-
-                for (const [calId, data] of Object.entries(calendars)) {
-                    if (data.errors?.length) {
-                        results[calId] = {
-                            error: data.errors[0].reason,
-                            busy: [],
-                        };
-                    } else {
-                        results[calId] = {
-                            busy: (data.busy || []).map((block) => ({
-                                start: block.start,
-                                end: block.end,
-                            })),
-                        };
-                    }
-                }
-
-                return JSON.stringify(results, null, 2);
-            } catch (error) {
-                log.error(`Error querying freebusy: ${error.message || error}`);
-                throw new UserError(`Failed to query busy times: ${error.message || 'Unknown error'}`);
-            }
-        },
-    });
-}
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getCalendarClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'getBusy',
+        description:
+            'Returns busy time blocks for one or more people in a given time range. ' +
+            'Works across your Google Workspace org without needing calendar sharing — you see when people are busy but not event details. ' +
+            'Pass email addresses as calendar_ids to check other people.',
+        parameters: z.object({
+            time_min: z
+                .string()
+                .describe('Start of query range in RFC3339 format (e.g. "2025-03-15T00:00:00Z").'),
+            time_max: z
+                .string()
+                .describe('End of query range in RFC3339 format (e.g. "2025-03-16T23:59:59Z").'),
+            calendar_ids: z
+                .array(z.string())
+                .optional()
+                .default(['primary'])
+                .describe('Calendar IDs or email addresses to check. Defaults to ["primary"].'),
+        }),
+        execute: async (args, { log }) => {
+            const calendar = await getCalendarClient();
+            log.info(`Checking busy times for ${args.calendar_ids.join(', ')}`);
+
+            try {
+                const response = await calendar.freebusy.query({
+                    requestBody: {
+                        timeMin: args.time_min,
+                        timeMax: args.time_max,
+                        items: args.calendar_ids.map((id) => ({ id })),
+                    },
+                });
+
+                const calendars = response.data.calendars || {};
+                const results = {};
+
+                for (const [calId, data] of Object.entries(calendars)) {
+                    if (data.errors?.length) {
+                        results[calId] = {
+                            error: data.errors[0].reason,
+                            busy: [],
+                        };
+                    } else {
+                        results[calId] = {
+                            busy: (data.busy || []).map((block) => ({
+                                start: block.start,
+                                end: block.end,
+                            })),
+                        };
+                    }
+                }
+
+                return JSON.stringify(results, null, 2);
+            } catch (error) {
+                log.error(`Error querying freebusy: ${error.message || error}`);
+                throw new UserError(`Failed to query busy times: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}