mcp-google-multi 5.0.0-beta.1 → 5.1.0-alpha.1

package/README.md

@@ -69,10 +69,17 @@ Now the only thing on disk is the **encrypted** token store. Pass the token via
 | `GOOGLE_WRITE_ALLOW` / `GOOGLE_WRITE_DENY` | — | glob overrides, e.g. `calendar:*`, `*:delete*` |
 | `GOOGLE_OPTIONAL_SCOPES` | — | extra bundles: `forms`, `chat` |
 | `GOOGLE_ADMIN_ACCOUNTS` | — | aliases granted Workspace-admin scopes (the account's own super-admin OAuth) |
+| `GOOGLE_TOOLSETS` | — | `all` (default) or a CSV filter of: `gmail`, `drive`, `calendar`, `sheets`, `docs`, `contacts`, `searchconsole`, `tasks`, `meet`, `forms`, `chat`, `admin` |
 | `TOKEN_STORE_PATH` | — | override the encrypted token dir (default: `~/.config/mcp-google-multi/tokens`) |
 
 Inspect the resolved setup any time: `mcp-google-multi config check`.
 
+## Discover-first tools (tiny idle context)
+
+The server does **not** dump ~170 tool schemas into your model's context. At boot, `tools/list` exposes only one small `{service}_discover` tool per service (plus nothing else). Calling e.g. `drive_discover` returns that service's operation catalog (name, one-line summary, arguments, read/write class), reveals the operational tools, and emits `notifications/tools/list_changed` so the client re-fetches the list. An optional `query` argument filters the catalog.
+
+Hidden is a listing concept, not a security boundary: operational tools stay callable at all times (existing prompts that call tools directly keep working), and write-control + OAuth scopes remain the real enforcement. Use `GOOGLE_TOOLSETS` to switch entire services off — it is a filter only: listing `forms`/`chat`/`admin` does not enable them without their `GOOGLE_OPTIONAL_SCOPES` / `GOOGLE_ADMIN_ACCOUNTS` gates.
+
 ## Write-control (deny-by-default)
 
 Reads are never gated. **Every create/update/delete is off until you opt in** — pick a profile:
@@ -112,7 +119,7 @@ Your OAuth, your machine. Refresh tokens are **AES-256-GCM encrypted at rest** (
 
 ## Roadmap
 
-Maintainer-led. Direction is tracked publicly as **[GitHub Milestones](https://github.com/bakissation/mcp-google-multi/milestones)** (discover-first tooling → exhaustive API coverage → service accounts + hosting in v6). Not accepting unsolicited feature PRs; bug reports are welcome.
+Maintainer-led. Direction is tracked publicly as **[GitHub Milestones](https://github.com/bakissation/mcp-google-multi/milestones)** (exhaustive API coverage → service accounts + hosting in v6). Not accepting unsolicited feature PRs; bug reports are welcome.
 
 ## Contributing
 

package/dist/discover.d.ts

@@ -0,0 +1,3 @@
+import type { ToolRegistry } from './registry.js';
+import { type Policy } from './write-control.js';
+export declare function registerDiscoverTools(registry: ToolRegistry, policy: Policy): void;

package/dist/discover.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { describePolicy } from './write-control.js';
+function opVocabulary(registry, service) {
+    const ops = registry.catalog(service).map((o) => o.tool.startsWith(`${service}_`) ? o.tool.slice(service.length + 1) : o.tool);
+    return [...new Set(ops)].join(', ');
+}
+export function registerDiscoverTools(registry, policy) {
+    for (const service of registry.services()) {
+        registry.registerMeta(`${service}_discover`, {
+            description: `List the available ${service} operations. Operational ${service} tools are hidden ` +
+                `until discovered — call this first, then call the tool you need by name. ` +
+                `Operations: ${opVocabulary(registry, service)}.`,
+            inputSchema: {
+                query: z.string().optional().describe('Keyword to filter the returned operations'),
+            },
+        }, async ({ query }) => {
+            const operations = registry.catalog(service, query);
+            registry.reveal(service);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            service,
+                            operations,
+                            writeControl: describePolicy(policy),
+                            next: operations.length > 0
+                                ? 'Call the chosen tool by name; it is now listed and callable.'
+                                : `No ${service} operation matches "${query}". Call again without query for the full catalog.`,
+                        }),
+                    },
+                ],
+            };
+        });
+    }
+}

package/dist/index.js

@@ -19,27 +19,54 @@ import { registerChatTools } from './tools/chat.js';
 import { registerAdminTools } from './tools/admin.js';
 import { getOptionalBundles, getAdminAccounts } from './auth.js';
 import { ToolRegistry } from './registry.js';
+import { registerDiscoverTools } from './discover.js';
+import { getToolsets, toolsetEnabled } from './toolsets.js';
 import { resolvePolicy, isAllowed, describePolicy } from './write-control.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
+const SERVICES = [
+    { name: 'gmail', register: registerGmailTools },
+    { name: 'drive', register: registerDriveTools },
+    { name: 'calendar', register: registerCalendarTools },
+    { name: 'sheets', register: registerSheetsTools },
+    { name: 'docs', register: registerDocsTools },
+    { name: 'contacts', register: registerContactsTools },
+    { name: 'searchconsole', register: registerSearchConsoleTools },
+    { name: 'tasks', register: registerTasksTools },
+    { name: 'meet', register: registerMeetTools },
+    { name: 'forms', register: registerFormsTools, enabled: () => new Set(getOptionalBundles()).has('forms') },
+    { name: 'chat', register: registerChatTools, enabled: () => new Set(getOptionalBundles()).has('chat') },
+    { name: 'admin', register: registerAdminTools, enabled: () => getAdminAccounts().length > 0 },
+];
 function buildRegistry(server, policy) {
     const registry = new ToolRegistry(server, policy);
-    registerGmailTools(registry);
-    registerDriveTools(registry);
-    registerCalendarTools(registry);
-    registerSheetsTools(registry);
-    registerDocsTools(registry);
-    registerContactsTools(registry);
-    registerSearchConsoleTools(registry);
-    registerTasksTools(registry);
-    registerMeetTools(registry);
-    const optional = new Set(getOptionalBundles());
-    if (optional.has('forms'))
-        registerFormsTools(registry);
-    if (optional.has('chat'))
-        registerChatTools(registry);
-    if (getAdminAccounts().length > 0)
-        registerAdminTools(registry);
+    const toolsets = getToolsets();
+    if (toolsets !== 'all') {
+        const known = new Set(SERVICES.map((s) => s.name));
+        for (const requested of toolsets) {
+            if (!known.has(requested)) {
+                process.stderr.write(`GOOGLE_TOOLSETS: unknown service "${requested}" ignored\n`);
+            }
+        }
+    }
+    for (const svc of SERVICES) {
+        if (!toolsetEnabled(toolsets, svc.name))
+            continue;
+        if (svc.enabled && !svc.enabled()) {
+            if (toolsets !== 'all') {
+                const hint = svc.name === 'admin' ? 'set GOOGLE_ADMIN_ACCOUNTS' : `add "${svc.name}" to GOOGLE_OPTIONAL_SCOPES`;
+                process.stderr.write(`GOOGLE_TOOLSETS: "${svc.name}" requested but not enabled — ${hint}\n`);
+            }
+            continue;
+        }
+        svc.register(registry);
+    }
+    registerDiscoverTools(registry, policy);
+    if (registry.tools.length === 0) {
+        throw new Error(`GOOGLE_TOOLSETS="${process.env.GOOGLE_TOOLSETS ?? ''}" selected no enabled services. ` +
+            `Known services: ${SERVICES.map((s) => s.name).join(', ')}. ` +
+            `Note: forms/chat require GOOGLE_OPTIONAL_SCOPES, admin requires GOOGLE_ADMIN_ACCOUNTS.`);
+    }
     return registry;
 }
 async function main() {
@@ -58,9 +85,12 @@ async function main() {
         const registry = buildRegistry(new McpServer({ name: 'mcp-google-multi', version: pkg.version }), policy);
         const cud = registry.tools.filter((t) => t.cud !== 'read');
         const disabled = cud.filter((t) => !isAllowed(t, policy));
+        const counts = registry.visibleCount();
         console.log(`Write-control: ${describePolicy(policy)}`);
         console.log(`CUD tools enabled: ${cud.length - disabled.length}/${cud.length}`);
         console.log(`Disabled: ${disabled.map((t) => t.name).join(', ') || '(none)'}`);
+        console.log(`Services: ${registry.services().join(', ')}`);
+        console.log(`Tool surface: ${counts.eager} eager (discover), ${counts.hidden} deferred until discovery`);
         return;
     }
     const policy = resolvePolicy();
@@ -68,7 +98,8 @@ async function main() {
         name: 'mcp-google-multi',
         version: pkg.version,
     });
-    buildRegistry(server, policy);
+    const registry = buildRegistry(server, policy);
+    registry.installListHandler();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/registry.d.ts

@@ -1,14 +1,41 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
 import { type Policy } from './write-control.js';
 export type Cud = 'read' | 'create' | 'update' | 'delete';
 export interface ToolEntry {
     name: string;
     service: string;
     cud: Cud;
+    description: string;
+    inputShape: z.ZodRawShape;
+    annotations: Record<string, unknown>;
+    meta: boolean;
+}
+export interface CatalogOperation {
+    tool: string;
+    summary: string;
+    args: string[];
+    cud: Cud;
 }
 export declare function inferCud(name: string): Cud;
 export declare class ToolRegistry {
+    private readonly server;
     readonly tools: ToolEntry[];
     readonly registerTool: McpServer['registerTool'];
+    private readonly revealed;
+    private readonly jsonSchemaCache;
+    private registeringMeta;
     constructor(server: McpServer, policy: Policy);
+    registerMeta: McpServer['registerTool'];
+    services(): string[];
+    catalog(service: string, query?: string): CatalogOperation[];
+    reveal(service: string): boolean;
+    isVisible(tool: ToolEntry): boolean;
+    visibleCount(): {
+        eager: number;
+        revealed: number;
+        hidden: number;
+    };
+    installListHandler(): void;
+    private toToolJson;
 }

package/dist/registry.js

@@ -1,7 +1,12 @@
+import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
 import { isAllowed, writeDisabledResult } from './write-control.js';
 const CUD_OVERRIDES = {
     drive_untrash: 'update',
 };
+const SERVICE_OVERRIDES = {
+    reports_activities_list: 'admin',
+};
 const DELETE_VERB = /(^|_)(delete|remove|trash|clear|empty)(_|$)/;
 const CREATE_VERB = /(^|_)(create|add|insert|send|upload|copy|import|append|submit|duplicate|share|quick)(_|$)/;
 const UPDATE_VERB = /(^|_)(update|patch|modify|set|move|write|format|merge|unmerge|sort|replace|resize|publish|resolve)(_|$)/;
@@ -18,19 +23,100 @@ export function inferCud(name) {
     return 'read';
 }
 export class ToolRegistry {
+    server;
     tools = [];
     registerTool;
+    revealed = new Set();
+    jsonSchemaCache = new Map();
+    registeringMeta = false;
     constructor(server, policy) {
+        this.server = server;
         this.registerTool = ((name, config, handler) => {
-            const service = name.includes('_') ? name.slice(0, name.indexOf('_')) : name;
+            const service = SERVICE_OVERRIDES[name] ?? (name.includes('_') ? name.slice(0, name.indexOf('_')) : name);
             const cud = inferCud(name);
-            this.tools.push({ name, service, cud });
+            // destructiveHint=false claims "additive only" (MCP spec) — updates overwrite, so they stay true.
+            const annotations = {
+                readOnlyHint: cud === 'read',
+                destructiveHint: cud === 'delete' || cud === 'update',
+                ...config.annotations,
+            };
+            this.tools.push({
+                name,
+                service,
+                cud,
+                description: config.description ?? '',
+                inputShape: config.inputSchema ?? {},
+                annotations,
+                meta: this.registeringMeta,
+            });
             const guarded = cud === 'read'
                 ? handler
                 : (...args) => isAllowed({ name, service, cud }, policy)
                     ? handler(...args)
                     : writeDisabledResult({ name, service, cud }, policy);
-            return server.registerTool(name, config, guarded);
+            return server.registerTool(name, { ...config, annotations }, guarded);
         });
     }
+    registerMeta = ((name, config, handler) => {
+        this.registeringMeta = true;
+        try {
+            return this.registerTool(name, config, handler);
+        }
+        finally {
+            this.registeringMeta = false;
+        }
+    });
+    services() {
+        return [...new Set(this.tools.filter((t) => !t.meta).map((t) => t.service))];
+    }
+    catalog(service, query) {
+        const q = query?.trim().toLowerCase();
+        return this.tools
+            .filter((t) => !t.meta && t.service === service)
+            .filter((t) => !q || t.name.toLowerCase().includes(q) || t.description.toLowerCase().includes(q))
+            .map((t) => ({
+            tool: t.name,
+            summary: t.description,
+            args: Object.keys(t.inputShape),
+            cud: t.cud,
+        }));
+    }
+    reveal(service) {
+        if (this.revealed.has(service))
+            return false;
+        this.revealed.add(service);
+        this.server.sendToolListChanged();
+        return true;
+    }
+    isVisible(tool) {
+        return tool.meta || this.revealed.has(tool.service);
+    }
+    visibleCount() {
+        const meta = this.tools.filter((t) => t.meta).length;
+        const visible = this.tools.filter((t) => !t.meta && this.isVisible(t)).length;
+        return { eager: meta, revealed: visible, hidden: this.tools.length - meta - visible };
+    }
+    // Replaces the SDK list handler so hidden tools stay registered (and callable —
+    // graceful dispatch) while tools/list only advertises the visible set.
+    installListHandler() {
+        if (this.tools.length === 0) {
+            throw new Error('installListHandler() requires at least one registered tool');
+        }
+        this.server.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: this.tools.filter((t) => this.isVisible(t)).map((t) => this.toToolJson(t)),
+        }));
+    }
+    toToolJson(tool) {
+        let inputSchema = this.jsonSchemaCache.get(tool.name);
+        if (!inputSchema) {
+            inputSchema = z.toJSONSchema(z.object(tool.inputShape), { target: 'draft-7', io: 'input' });
+            this.jsonSchemaCache.set(tool.name, inputSchema);
+        }
+        return {
+            name: tool.name,
+            description: tool.description,
+            inputSchema,
+            annotations: tool.annotations,
+        };
+    }
 }

package/dist/toolsets.d.ts

@@ -0,0 +1,3 @@
+export type Toolsets = 'all' | Set<string>;
+export declare function getToolsets(env?: NodeJS.ProcessEnv): Toolsets;
+export declare function toolsetEnabled(toolsets: Toolsets, service: string): boolean;

package/dist/toolsets.js

@@ -0,0 +1,12 @@
+export function getToolsets(env = process.env) {
+    const parts = (env.GOOGLE_TOOLSETS ?? '')
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    if (parts.length === 0 || parts.includes('all'))
+        return 'all';
+    return new Set(parts);
+}
+export function toolsetEnabled(toolsets, service) {
+    return toolsets === 'all' || toolsets.has(service);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "5.0.0-beta.1",
+  "version": "5.1.0-alpha.1",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",
   "license": "MIT",
@@ -74,6 +74,6 @@
     "semantic-release": "^25.0.3",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.1",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.6"
   }
 }