mcp-google-multi 4.2.0

package/dist/auth.js

@@ -0,0 +1,178 @@
+import { google } from 'googleapis';
+import http from 'node:http';
+import { URL } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import open from 'open';
+import destroyer from 'server-destroy';
+import { ACCOUNTS, ACCOUNT_CONFIG } from './accounts.js';
+// ─── Scope tiers ────────────────────────────────────────────────────────
+//
+// BASE: always granted. Existing v3 surface + Tasks + Meet (added in v4.0.0).
+// OPTIONAL: per-account opt-in via env GOOGLE_OPTIONAL_SCOPES="forms,chat".
+// ADMIN: per-account opt-in via env GOOGLE_ADMIN_ACCOUNTS="alias1,alias2".
+//
+// Personal Gmail accounts will 403 on admin scopes — never grant by default.
+// ────────────────────────────────────────────────────────────────────────
+export const BASE_SCOPES = [
+    'https://www.googleapis.com/auth/gmail.modify',
+    'https://www.googleapis.com/auth/gmail.send',
+    'https://www.googleapis.com/auth/drive',
+    'https://www.googleapis.com/auth/calendar',
+    'https://www.googleapis.com/auth/spreadsheets',
+    'https://www.googleapis.com/auth/documents',
+    'https://www.googleapis.com/auth/contacts',
+    'https://www.googleapis.com/auth/webmasters',
+    'https://www.googleapis.com/auth/tasks',
+    'https://www.googleapis.com/auth/meetings.space.readonly',
+];
+export const OPTIONAL_SCOPE_BUNDLES = {
+    forms: [
+        'https://www.googleapis.com/auth/forms.body',
+        'https://www.googleapis.com/auth/forms.responses.readonly',
+    ],
+    chat: [
+        'https://www.googleapis.com/auth/chat.spaces',
+        'https://www.googleapis.com/auth/chat.messages',
+        'https://www.googleapis.com/auth/chat.messages.create',
+    ],
+    // Alert Center's apps.alerts scope is NOT grantable through the interactive
+    // user-consent flow this server uses — it requires a service account with
+    // domain-wide delegation. It lives in its own opt-in bundle so it never
+    // blocks the working Admin SDK admin scopes. See README "Alert Center".
+    alertcenter: [
+        'https://www.googleapis.com/auth/apps.alerts',
+    ],
+};
+export const ADMIN_SCOPES = [
+    'https://www.googleapis.com/auth/admin.reports.audit.readonly',
+    'https://www.googleapis.com/auth/admin.directory.user',
+    'https://www.googleapis.com/auth/admin.directory.group.readonly',
+    'https://www.googleapis.com/auth/admin.directory.group.member.readonly',
+];
+/** Parse comma-separated env value into a deduplicated string array. */
+function parseCsvEnv(name) {
+    return (process.env[name]?.trim() ?? '')
+        .split(',')
+        .map(s => s.trim())
+        .filter(Boolean);
+}
+/** Bundle keys enabled via GOOGLE_OPTIONAL_SCOPES (e.g. ["forms","chat"]). */
+export function getOptionalBundles() {
+    return parseCsvEnv('GOOGLE_OPTIONAL_SCOPES').filter(b => b in OPTIONAL_SCOPE_BUNDLES);
+}
+/** Account aliases granted ADMIN_SCOPES via GOOGLE_ADMIN_ACCOUNTS. */
+export function getAdminAccounts() {
+    return parseCsvEnv('GOOGLE_ADMIN_ACCOUNTS');
+}
+/**
+ * Compose the scope list for a single account at consent time.
+ * Resolves env flags: GOOGLE_OPTIONAL_SCOPES (global) and GOOGLE_ADMIN_ACCOUNTS (per-account allowlist).
+ */
+export function resolveScopesForAccount(alias) {
+    const scopes = [...BASE_SCOPES];
+    for (const bundle of getOptionalBundles()) {
+        scopes.push(...OPTIONAL_SCOPE_BUNDLES[bundle]);
+    }
+    if (getAdminAccounts().includes(alias)) {
+        scopes.push(...ADMIN_SCOPES);
+    }
+    return Array.from(new Set(scopes));
+}
+/** True if admin writes are explicitly enabled. Default refuses to prevent accidents on small orgs. */
+export function adminWritesEnabled() {
+    return process.env.GOOGLE_ALLOW_ADMIN_WRITES === 'true';
+}
+export async function runAuthFlow(args) {
+    const accountIdx = args.indexOf('--account');
+    if (accountIdx === -1 || !args[accountIdx + 1]) {
+        console.error('Usage: node dist/index.js auth --account <alias>');
+        console.error(`Valid aliases: ${ACCOUNTS.join(', ')}`);
+        process.exit(1);
+    }
+    const alias = args[accountIdx + 1];
+    if (!ACCOUNTS.includes(alias)) {
+        console.error(`Unknown account "${alias}". Valid aliases: ${ACCOUNTS.join(', ')}`);
+        process.exit(1);
+    }
+    const config = ACCOUNT_CONFIG[alias];
+    const scopes = resolveScopesForAccount(alias);
+    const oauth2Client = new google.auth.OAuth2(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
+    // CSRF protection for the OAuth callback (RFC 6749 §10.12).
+    const expectedState = randomBytes(32).toString('hex');
+    const authorizeUrl = oauth2Client.generateAuthUrl({
+        access_type: 'offline',
+        prompt: 'consent',
+        scope: scopes,
+        login_hint: config.email,
+        state: expectedState,
+    });
+    console.log(`Authenticating account "${alias}" (${config.email})...`);
+    console.log(`Requesting ${scopes.length} scopes.`);
+    if (getAdminAccounts().includes(alias)) {
+        console.log('  ⚠ Admin scopes included — this account will be granted Workspace admin access.');
+    }
+    console.log(`Opening browser for authorization...`);
+    return new Promise((resolve, reject) => {
+        const server = http
+            .createServer(async (req, res) => {
+            try {
+                if (req.url && req.url.startsWith('/oauth2callback')) {
+                    const qs = new URL(req.url, 'http://localhost:4242').searchParams;
+                    const error = qs.get('error');
+                    if (error) {
+                        res.writeHead(400, { 'Content-Type': 'text/plain' });
+                        res.end(`Authorization denied: ${error}`);
+                        server.destroy();
+                        reject(new Error(`Authorization denied: ${error}`));
+                        return;
+                    }
+                    const code = qs.get('code');
+                    if (!code) {
+                        res.writeHead(400, { 'Content-Type': 'text/plain' });
+                        res.end('No authorization code received.');
+                        server.destroy();
+                        reject(new Error('No authorization code received'));
+                        return;
+                    }
+                    const returnedState = qs.get('state');
+                    if (returnedState !== expectedState) {
+                        res.writeHead(400, { 'Content-Type': 'text/plain' });
+                        res.end('State mismatch — possible CSRF attempt. Aborting.');
+                        server.destroy();
+                        reject(new Error('OAuth state token mismatch'));
+                        return;
+                    }
+                    const { tokens } = await oauth2Client.getToken(code);
+                    await fs.mkdir(path.dirname(config.tokenPath), { recursive: true });
+                    // 0o600: tokens grant full account access; keep them user-only.
+                    await fs.writeFile(config.tokenPath, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end('<h2>Authentication successful!</h2><p>You can close this tab.</p>');
+                    server.destroy();
+                    console.log(`Token saved to ${config.tokenPath}`);
+                    resolve();
+                }
+            }
+            catch (e) {
+                res.writeHead(500, { 'Content-Type': 'text/plain' });
+                res.end('Internal error during authentication.');
+                server.destroy();
+                reject(e);
+            }
+        })
+            // Bind to loopback only — never expose the OAuth callback to the local network.
+            .listen(4242, '127.0.0.1', () => {
+            open(authorizeUrl, { wait: false }).then((cp) => cp.unref());
+        });
+        destroyer(server);
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                console.error('Port 4242 is already in use. Close the process using it and retry.');
+                process.exit(1);
+            }
+            reject(err);
+        });
+    });
+}

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+import type { Account } from './accounts.js';
+export declare function getClient(account: Account): Promise<import("google-auth-library").OAuth2Client>;

package/dist/client.js

@@ -0,0 +1,33 @@
+import { google } from 'googleapis';
+import fs from 'node:fs/promises';
+import { ACCOUNT_CONFIG } from './accounts.js';
+export async function getClient(account) {
+    const config = ACCOUNT_CONFIG[account];
+    if (!process.env.GOOGLE_CLIENT_ID || !process.env.GOOGLE_CLIENT_SECRET) {
+        throw new Error('GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must be set. ' +
+            'Check that .env exists in the project root or pass them as env vars.');
+    }
+    const oauth2Client = new google.auth.OAuth2(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
+    let tokenData;
+    try {
+        const raw = await fs.readFile(config.tokenPath, 'utf-8');
+        tokenData = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`No token file found for account "${account}" at ${config.tokenPath}. ` +
+            `Run: node dist/index.js auth --account ${account}`);
+    }
+    oauth2Client.setCredentials(tokenData);
+    // 0o600: tokens grant full account access; keep them user-only.
+    oauth2Client.on('tokens', async (tokens) => {
+        try {
+            const existing = JSON.parse(await fs.readFile(config.tokenPath, 'utf-8'));
+            const merged = { ...existing, ...tokens };
+            await fs.writeFile(config.tokenPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
+        }
+        catch {
+            await fs.writeFile(config.tokenPath, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+        }
+    });
+    return oauth2Client;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './accounts.js';

package/dist/index.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import './accounts.js';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerGmailTools } from './tools/gmail.js';
+import { registerDriveTools } from './tools/drive.js';
+import { registerCalendarTools } from './tools/calendar.js';
+import { registerSheetsTools } from './tools/sheets.js';
+import { registerDocsTools } from './tools/docs.js';
+import { registerContactsTools } from './tools/contacts.js';
+import { registerSearchConsoleTools } from './tools/searchconsole.js';
+import { registerTasksTools } from './tools/tasks.js';
+import { registerMeetTools } from './tools/meet.js';
+import { registerFormsTools } from './tools/forms.js';
+import { registerChatTools } from './tools/chat.js';
+import { registerAdminTools, registerAlertCenterTools } from './tools/admin.js';
+import { getOptionalBundles, getAdminAccounts } from './auth.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
+async function main() {
+    if (process.argv.includes('auth')) {
+        const { runAuthFlow } = await import('./auth.js');
+        await runAuthFlow(process.argv);
+        return;
+    }
+    // MCP server mode — no console.log (stdio is the MCP channel)
+    const server = new McpServer({
+        name: 'mcp-google-multi',
+        version: pkg.version,
+    });
+    registerGmailTools(server);
+    registerDriveTools(server);
+    registerCalendarTools(server);
+    registerSheetsTools(server);
+    registerDocsTools(server);
+    registerContactsTools(server);
+    registerSearchConsoleTools(server);
+    registerTasksTools(server);
+    registerMeetTools(server);
+    const optional = new Set(getOptionalBundles());
+    if (optional.has('forms'))
+        registerFormsTools(server);
+    if (optional.has('chat'))
+        registerChatTools(server);
+    if (optional.has('alertcenter'))
+        registerAlertCenterTools(server);
+    if (getAdminAccounts().length > 0)
+        registerAdminTools(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err.message}\n`);
+    process.exit(1);
+});

package/dist/tools/_errors.d.ts

@@ -0,0 +1,9 @@
+import type { Account } from '../accounts.js';
+/** Maps googleapis errors to MCP tool responses. 401 → re-auth instruction; 403 + hint → structured hint payload; 429 → retry-after; else → {error, code}. */
+export declare function handleGoogleApiError(error: any, account: Account, forbiddenHint?: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/tools/_errors.js

@@ -0,0 +1,42 @@
+/** Maps googleapis errors to MCP tool responses. 401 → re-auth instruction; 403 + hint → structured hint payload; 429 → retry-after; else → {error, code}. */
+export function handleGoogleApiError(error, account, forbiddenHint) {
+    if (error.code === 401) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Authentication error for account "${account}". Run: node dist/index.js auth --account ${account}`,
+                }],
+            isError: true,
+        };
+    }
+    if (error.code === 403 && forbiddenHint) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: 'forbidden',
+                        hint: forbiddenHint,
+                        original: error.message ?? String(error),
+                    }),
+                }],
+            isError: true,
+        };
+    }
+    if (error.code === 429) {
+        const retryAfter = error.response?.headers?.['retry-after'] ?? 'unknown';
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ error: 'rate_limited', retryAfter }),
+                }],
+            isError: true,
+        };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ error: error.message ?? String(error), code: error.code }),
+            }],
+        isError: true,
+    };
+}

package/dist/tools/admin.d.ts

@@ -0,0 +1,17 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Admin SDK tools require Workspace super-admin (or delegated admin) privileges on the target account.
+ * Personal `@gmail.com` accounts will 403 on every endpoint.
+ *
+ * Writes are gated behind GOOGLE_ALLOW_ADMIN_WRITES=true to prevent accidents on small orgs
+ * (a stray users.update on a 3-person Workspace is a bad day).
+ */
+export declare function registerAdminTools(server: McpServer): void;
+/**
+ * Alert Center tools. Gated behind the `alertcenter` optional bundle, NOT the
+ * admin bundle: the apps.alerts scope cannot be granted via this server's
+ * interactive user-consent OAuth flow — it requires a service account with
+ * domain-wide delegation. Registered separately so a missing/ungrantable
+ * apps.alerts scope never blocks the working Admin SDK admin tools.
+ */
+export declare function registerAlertCenterTools(server: McpServer): void;

package/dist/tools/admin.js

@@ -0,0 +1,307 @@
+import { z } from 'zod';
+import { google } from 'googleapis';
+import { ACCOUNTS } from '../accounts.js';
+import { getClient } from '../client.js';
+import { handleGoogleApiError } from './_errors.js';
+import { adminWritesEnabled } from '../auth.js';
+const accountEnum = z.enum(ACCOUNTS);
+/**
+ * Admin SDK tools require Workspace super-admin (or delegated admin) privileges on the target account.
+ * Personal `@gmail.com` accounts will 403 on every endpoint.
+ *
+ * Writes are gated behind GOOGLE_ALLOW_ADMIN_WRITES=true to prevent accidents on small orgs
+ * (a stray users.update on a 3-person Workspace is a bad day).
+ */
+export function registerAdminTools(server) {
+    // ─── Reports / audit log ───────────────────────────────────────────────
+    server.registerTool('reports_activities_list', {
+        description: 'List Admin Activity audit log entries. Filter by application (login, drive, gmail, admin, token, etc.), user, date range, event. The single most useful admin endpoint for SMB visibility.',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
+            applicationName: z.enum([
+                'access_transparency', 'admin', 'calendar', 'chat', 'drive', 'gcp', 'gmail',
+                'gplus', 'groups', 'groups_enterprise', 'jamboard', 'login', 'meet', 'mobile',
+                'rules', 'saml', 'token', 'user_accounts', 'context_aware_access', 'chrome',
+                'data_studio', 'keep', 'vault', 'classroom', 'assignments', 'cloud_search',
+                'tasks', 'data_migration', 'meet_hardware', 'directory_sync', 'ldap',
+                'profile', 'contacts', 'takeout',
+            ]).describe('Which application\'s activity to query'),
+            userKey: z.string().default('all').optional().describe('User profile ID, email, or "all" (default)'),
+            startTime: z.string().optional().describe('RFC 3339 lower bound'),
+            endTime: z.string().optional().describe('RFC 3339 upper bound'),
+            eventName: z.string().optional().describe('Specific event name to filter'),
+            actorIpAddress: z.string().optional(),
+            filters: z.string().optional().describe('Comma-separated event-parameter filters with relational operators'),
+            orgUnitID: z.string().optional(),
+            groupIdFilter: z.string().optional(),
+            customerId: z.string().optional(),
+            maxResults: z.number().min(1).max(1000).optional(),
+            pageToken: z.string().optional(),
+        },
+    }, async ({ account, applicationName, userKey, startTime, endTime, eventName, actorIpAddress, filters, orgUnitID, groupIdFilter, customerId, maxResults, pageToken }) => {
+        try {
+            const auth = await getClient(account);
+            const reports = google.admin({ version: 'reports_v1', auth });
+            const res = await reports.activities.list({
+                applicationName,
+                userKey: userKey ?? 'all',
+                startTime,
+                endTime,
+                eventName,
+                actorIpAddress,
+                filters,
+                orgUnitID,
+                groupIdFilter,
+                customerId,
+                maxResults: maxResults ?? 100,
+                pageToken,
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAdminError(error, account);
+        }
+    });
+    // ─── Directory: users ─────────────────────────────────────────────────
+    server.registerTool('admin_users_list', {
+        description: 'List users in the Workspace customer. Filter by domain or customer=my_customer.',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
+            customer: z.string().default('my_customer').optional(),
+            domain: z.string().optional(),
+            query: z.string().optional().describe('Search query, e.g. "name:John"'),
+            maxResults: z.number().min(1).max(500).optional(),
+            pageToken: z.string().optional(),
+            orderBy: z.enum(['email', 'familyName', 'givenName']).optional(),
+            showDeleted: z.boolean().optional(),
+            projection: z.enum(['basic', 'custom', 'full']).optional(),
+        },
+    }, async ({ account, customer, domain, query, maxResults, pageToken, orderBy, showDeleted, projection }) => {
+        try {
+            const auth = await getClient(account);
+            const directory = google.admin({ version: 'directory_v1', auth });
+            const res = await directory.users.list({
+                customer: customer ?? 'my_customer',
+                domain,
+                query,
+                maxResults: maxResults ?? 100,
+                pageToken,
+                orderBy,
+                showDeleted: showDeleted !== undefined ? (showDeleted ? 'true' : 'false') : undefined,
+                projection: projection ?? 'basic',
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAdminError(error, account);
+        }
+    });
+    server.registerTool('admin_users_get', {
+        description: 'Get a single Workspace user by email or user ID',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
+            userKey: z.string().describe('User email or ID'),
+            projection: z.enum(['basic', 'custom', 'full']).optional(),
+        },
+    }, async ({ account, userKey, projection }) => {
+        try {
+            const auth = await getClient(account);
+            const directory = google.admin({ version: 'directory_v1', auth });
+            const res = await directory.users.get({
+                userKey,
+                projection: projection ?? 'basic',
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAdminError(error, account);
+        }
+    });
+    server.registerTool('admin_users_update', {
+        description: 'Update a Workspace user (PATCH semantics). GATED: requires GOOGLE_ALLOW_ADMIN_WRITES=true to prevent accidental destructive ops on small orgs.',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
+            userKey: z.string().describe('User email or ID'),
+            givenName: z.string().optional(),
+            familyName: z.string().optional(),
+            suspended: z.boolean().optional(),
+            password: z.string().optional(),
+            changePasswordAtNextLogin: z.boolean().optional(),
+            orgUnitPath: z.string().optional(),
+        },
+    }, async ({ account, userKey, givenName, familyName, suspended, password, changePasswordAtNextLogin, orgUnitPath }) => {
+        try {
+            if (!adminWritesEnabled()) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: 'admin_writes_disabled',
+                                hint: 'Admin write operations are disabled by default. Set GOOGLE_ALLOW_ADMIN_WRITES=true in .env and restart to enable.',
+                            }),
+                        }],
+                    isError: true,
+                };
+            }
+            const auth = await getClient(account);
+            const directory = google.admin({ version: 'directory_v1', auth });
+            const requestBody = {};
+            if (givenName !== undefined || familyName !== undefined) {
+                requestBody.name = {};
+                if (givenName !== undefined)
+                    requestBody.name.givenName = givenName;
+                if (familyName !== undefined)
+                    requestBody.name.familyName = familyName;
+            }
+            if (suspended !== undefined)
+                requestBody.suspended = suspended;
+            if (password !== undefined)
+                requestBody.password = password;
+            if (changePasswordAtNextLogin !== undefined)
+                requestBody.changePasswordAtNextLogin = changePasswordAtNextLogin;
+            if (orgUnitPath !== undefined)
+                requestBody.orgUnitPath = orgUnitPath;
+            if (Object.keys(requestBody).length === 0) {
+                return { content: [{ type: 'text', text: JSON.stringify({ error: 'No fields to update' }) }], isError: true };
+            }
+            const res = await directory.users.patch({ userKey, requestBody });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAdminError(error, account);
+        }
+    });
+    // ─── Directory: groups ────────────────────────────────────────────────
+    server.registerTool('admin_groups_list', {
+        description: 'List groups in the Workspace customer',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
+            customer: z.string().default('my_customer').optional(),
+            domain: z.string().optional(),
+            userKey: z.string().optional().describe('Only return groups containing this user'),
+            query: z.string().optional(),
+            maxResults: z.number().min(1).max(200).optional(),
+            pageToken: z.string().optional(),
+        },
+    }, async ({ account, customer, domain, userKey, query, maxResults, pageToken }) => {
+        try {
+            const auth = await getClient(account);
+            const directory = google.admin({ version: 'directory_v1', auth });
+            const res = await directory.groups.list({
+                customer: customer ?? 'my_customer',
+                domain,
+                userKey,
+                query,
+                maxResults: maxResults ?? 100,
+                pageToken,
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAdminError(error, account);
+        }
+    });
+    server.registerTool('admin_group_members_list', {
+        description: 'List members of a Workspace group',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
+            groupKey: z.string().describe('Group email or ID'),
+            roles: z.string().optional().describe('Comma-separated roles to include (OWNER, MANAGER, MEMBER)'),
+            includeDerivedMembership: z.boolean().optional(),
+            maxResults: z.number().min(1).max(200).optional(),
+            pageToken: z.string().optional(),
+        },
+    }, async ({ account, groupKey, roles, includeDerivedMembership, maxResults, pageToken }) => {
+        try {
+            const auth = await getClient(account);
+            const directory = google.admin({ version: 'directory_v1', auth });
+            const res = await directory.members.list({
+                groupKey,
+                roles,
+                includeDerivedMembership,
+                maxResults: maxResults ?? 100,
+                pageToken,
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAdminError(error, account);
+        }
+    });
+}
+/**
+ * Alert Center tools. Gated behind the `alertcenter` optional bundle, NOT the
+ * admin bundle: the apps.alerts scope cannot be granted via this server's
+ * interactive user-consent OAuth flow — it requires a service account with
+ * domain-wide delegation. Registered separately so a missing/ungrantable
+ * apps.alerts scope never blocks the working Admin SDK admin tools.
+ */
+export function registerAlertCenterTools(server) {
+    server.registerTool('alertcenter_alerts_list', {
+        description: 'List Workspace security alerts (suspicious login, phishing, leaked password, Drive exfil, etc.). Requires the alertcenter bundle + service-account domain-wide delegation.',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
+            pageSize: z.number().min(1).max(1000).optional(),
+            pageToken: z.string().optional(),
+            filter: z.string().optional().describe('Filter expression, e.g. "type = \\"Suspicious login\\""'),
+            orderBy: z.string().optional(),
+            customerId: z.string().optional(),
+        },
+    }, async ({ account, pageSize, pageToken, filter, orderBy, customerId }) => {
+        try {
+            const auth = await getClient(account);
+            const alertcenter = google.alertcenter({ version: 'v1beta1', auth });
+            const res = await alertcenter.alerts.list({
+                pageSize: pageSize ?? 50,
+                pageToken,
+                filter,
+                orderBy,
+                customerId,
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAlertCenterError(error, account);
+        }
+    });
+    server.registerTool('alertcenter_alert_get', {
+        description: 'Get a single alert by ID. Requires the alertcenter bundle + service-account domain-wide delegation.',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
+            alertId: z.string().describe('Alert ID'),
+            customerId: z.string().optional(),
+        },
+    }, async ({ account, alertId, customerId }) => {
+        try {
+            const auth = await getClient(account);
+            const alertcenter = google.alertcenter({ version: 'v1beta1', auth });
+            const res = await alertcenter.alerts.get({ alertId, customerId });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAlertCenterError(error, account);
+        }
+    });
+}
+function handleAdminError(error, account) {
+    return handleGoogleApiError(error, account, "Admin tools require Workspace super-admin privileges AND the account must be listed in GOOGLE_ADMIN_ACCOUNTS (then re-authenticated). Personal Gmail accounts cannot use these endpoints.");
+}
+function handleAlertCenterError(error, account) {
+    return handleGoogleApiError(error, account, "Alert Center (apps.alerts) is not grantable via this server's user-consent OAuth flow — it requires a service account with domain-wide delegation. Enabling GOOGLE_OPTIONAL_SCOPES=alertcenter only declares the scope; the API will reject user-OAuth tokens. See README \"Alert Center\".");
+}

package/dist/tools/calendar.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCalendarTools(server: McpServer): void;