mcp-google-multi 6.0.0-alpha.34 → 6.0.0-alpha.36

package/dist/registry.js

@@ -168,9 +168,9 @@ export class ToolRegistry {
             });
             const guarded = cud === 'read'
                 ? baseHandler
-                : (...args) => isAllowed({ name, service, cud }, policy)
+                : (...args) => isAllowed({ name, service, cud, scopes: config.requiredScopes }, policy)
                     ? baseHandler(...args)
-                    : writeDisabledResult({ name, service, cud }, policy, 
+                    : writeDisabledResult({ name, service, cud, scopes: config.requiredScopes }, policy, 
                     // Concrete by here: default-account injection wraps this.
                     args[0]?.account);
             // A2: the ONE default-account injection site — outside the CUD gate and

package/dist/tools/account-wizard.js

@@ -14,7 +14,7 @@ import { detectClients, buildServerEntry, renderInstruction, applyFileEntry, res
 // running server can add an account without the deployer editing env + running
 // a CLI. Google consent reuses the loopback flow (leg C); the HTTP-transport
 // consent path (${BASE}/authorize) is owned by the OAuth AS and lands with that
-// cluster — account_add over http is gated behind it.
+// cluster. account_add over http is gated behind it.
 const ALIAS_RE = /^[a-zA-Z0-9_-]+$/;
 // The common optional bundles get their own checkbox (MCP elicitation has no
 // multi-select, so a boolean per bundle IS the checklist); the long tail stays
@@ -214,7 +214,7 @@ async function runConsent(server, alias) {
 function s4Text(alias, missing) {
     const outcome = missing.length === 0
         ? `✔ "${alias}" authenticated; all requested scopes granted. It is now usable without a restart.`
-        : `⚠ "${alias}" authenticated, but ${missing.length} requested scope(s) were NOT granted (E_SCOPE_NOT_GRANTED) — you may have unchecked some on the consent screen. Re-run account_reauth to grant them. The account is usable for the granted scopes.`;
+        : `⚠ "${alias}" authenticated, but ${missing.length} requested scope(s) were NOT granted (E_SCOPE_NOT_GRANTED). You may have unchecked some on the consent screen. Re-run account_reauth to grant them. The account is usable for the granted scopes.`;
     return `${outcome}\n${TESTING_MODE_WARNING}`;
 }
 const REQUIRES_INTERACTION = { 'anthropic/requiresUserInteraction': true };
@@ -226,7 +226,7 @@ export function registerAccountWizardTools(registry, server) {
     registerMeta('account_add', {
         _meta: REQUIRES_INTERACTION,
         annotations: { openWorldHint: true },
-        description: 'Add a new Google account: pass alias + email directly (plus optional bundles/allBundles/admin), or pass nothing for an interactive form where the client supports elicitation. Writes the registry and runs Google consent in the browser — no file editing or restart needed. Requires GOOGLE_CLIENT_ID/SECRET (run the `setup` prompt first if missing).',
+        description: 'Add a new Google account: pass alias + email directly (plus optional bundles/allBundles/admin), or pass nothing for an interactive form where the client supports elicitation. Writes the registry and runs Google consent in the browser. No file editing or restart needed. Requires GOOGLE_CLIENT_ID/SECRET (run the `setup` prompt first if missing).',
         inputSchema: {
             alias: z.string().optional().describe('Account alias (letters, digits, _ or -). Pass with email to add directly, skipping the form.'),
             account: z.string().optional().describe('Alias for the new account (same as `alias`; every other tool spells it `account`)'),
@@ -358,16 +358,16 @@ export function registerAccountWizardTools(registry, server) {
             for (const client of targets) {
                 const instr = renderInstruction(client, name, entry);
                 if (client.managed === 'cli') {
-                    blocks.push(`${client.label} — run:\n  ${instr.text}`);
+                    blocks.push(`${client.label}: run\n  ${instr.text}`);
                 }
                 else if (a.write) {
                     const res = applyFileEntry(client, name, entry);
                     blocks.push(res.ok
-                        ? `${client.label} — ${res.action} "${name}" in ${res.path}${res.backup ? ` (backup ${res.backup})` : ''}`
-                        : `${client.label} — ${res.message}\n${res.snippet ?? ''}`);
+                        ? `${client.label}: ${res.action} "${name}" in ${res.path}${res.backup ? ` (backup ${res.backup})` : ''}`
+                        : `${client.label}: ${res.message}\n${res.snippet ?? ''}`);
                 }
                 else {
-                    blocks.push(`${client.label} — add to ${instr.path}:\n${instr.text}`);
+                    blocks.push(`${client.label}: add to ${instr.path}\n${instr.text}`);
                 }
             }
             if (targets.length === 0) {

package/dist/tools/drive.js

@@ -255,6 +255,7 @@ export function registerDriveTools(server) {
                                 webViewLink,
                             }, null, 2),
                         }],
+                    isError: true,
                 };
             }
             const fileSize = parseInt(size ?? '0', 10);
@@ -274,6 +275,7 @@ export function registerDriveTools(server) {
                                 webViewLink,
                             }, null, 2),
                         }],
+                    isError: true,
                 };
             }
             if (mimeType && isTextualMime(mimeType)) {
@@ -295,6 +297,7 @@ export function registerDriveTools(server) {
                             webViewLink,
                         }, null, 2),
                     }],
+                isError: true,
             };
         }
         catch (error) {

package/dist/tools/google-api.js

@@ -191,7 +191,10 @@ export function registerEscapeTools(registry, policy, deps = {}) {
         const cud = cudFromMethod(method);
         const policyService = serviceForAlias(apiKey);
         const lastSegment = method.id.split('.').pop() ?? method.id;
-        const toolRef = { name: `${policyService}_${lastSegment}`, service: policyService, cud };
+        // The escape hatch self-gates, so it needs the same scope signal the
+        // registry wrapper gets; without it a privileged method would slip past
+        // safe-writes here while its generated twin is refused.
+        const toolRef = { name: `${policyService}_${lastSegment}`, service: policyService, cud, scopes: method.scopes };
         if (cud !== 'read' && !isAllowed(toolRef, policy)) {
             return writeDisabledResult(toolRef, policy, account);
         }

package/dist/write-control.d.ts

@@ -22,6 +22,10 @@ interface ToolRef {
     name: string;
     service: string;
     cud: Cud;
+    /** The method's required OAuth scopes, when the caller knows them. Absent
+     * means "unknown", which is treated as not privileged: a missing scope list
+     * must not silently widen the gate OR silently break an ordinary write. */
+    scopes?: readonly string[];
 }
 /** The irreversible set (frozen, cc-write-control): real sends leave the
  * user's (or org's) identity unrecallably; permanent deletes bypass Trash.
@@ -35,7 +39,29 @@ export declare const IRREVERSIBLE_TOOLS: Set<string>;
 export declare function resolvePolicy(env?: NodeJS.ProcessEnv, opts?: {
     transport?: Transport;
 }): Policy;
+export type PrivilegeKind = 'push_registration' | 'privileged_scope';
+/** Why this write counts as privileged, or undefined if it does not.
+ * Derived, not a hand-kept name list: the tool surface is regenerated from
+ * Discovery, and a list of names would drift out of date silently. */
+export declare function privilegeOf(tool: ToolRef): PrivilegeKind | undefined;
 export declare function isAllowed(tool: ToolRef, policy: Policy): boolean;
+export type DenyReason = {
+    rule: 'read_only';
+} | {
+    rule: 'deny_glob';
+    pattern: string;
+} | {
+    rule: 'privileged';
+    profile: Profile;
+    kind: PrivilegeKind;
+} | {
+    rule: 'profile';
+    profile: Profile;
+};
+/** WHICH rule refused the call. `isAllowed` has a precedence order, so exactly
+ * one rule decides; naming the others sends the caller to a setting that
+ * cannot change the outcome. */
+export declare function denyReason(tool: ToolRef, policy: Policy): DenyReason | undefined;
 export declare function writeDisabledResult(tool: ToolRef, policy: Policy, account?: string): {
     content: {
         type: "text";

package/dist/write-control.js

@@ -45,24 +45,51 @@ function globToRegExp(glob) {
     const escaped = glob.trim().replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
     return new RegExp(`^${escaped}$`);
 }
+function opOf(tool) {
+    return tool.name.includes('_') ? tool.name.slice(tool.name.indexOf('_') + 1) : tool.name;
+}
 function candidates(tool) {
-    const op = tool.name.includes('_') ? tool.name.slice(tool.name.indexOf('_') + 1) : tool.name;
-    return [`${tool.service}:${tool.cud}`, `${tool.service}:${op}`];
+    return [`${tool.service}:${tool.cud}`, `${tool.service}:${opOf(tool)}`];
 }
-function matchesAny(tool, globs) {
+function firstMatch(tool, globs) {
     if (globs.length === 0)
-        return false;
+        return undefined;
     const cands = candidates(tool);
-    return globs.some((g) => {
+    return globs.find((g) => {
         const re = globToRegExp(g);
         return cands.some((c) => re.test(c));
     });
 }
-function profileAllows(profile, cud) {
+function matchesAny(tool, globs) {
+    return firstMatch(tool, globs) !== undefined;
+}
+/** Scopes that authorize acting on the whole organization, on legal holds, on
+ * billing, or on deployed code. A write behind one of these is not a "safe"
+ * write in any useful sense of the word, whatever its HTTP verb. */
+const PRIVILEGED_SCOPE_RE = /\/auth\/(admin\.directory|admin\.datatransfer|cloud-identity|apps\.licensing|apps\.order|apps\.groups\.settings|apps\.groups\.migration|ediscovery|script\.projects|script\.deployments)/;
+/** Registering a push channel hands this account's activity to an external URL.
+ * It is shaped like a create and behaves like an export, so the verb hides it. */
+const PUSH_REGISTRATION_RE = /(_watch|_subscriptions_create|_subscriptions_reactivate)$/;
+/** Why this write counts as privileged, or undefined if it does not.
+ * Derived, not a hand-kept name list: the tool surface is regenerated from
+ * Discovery, and a list of names would drift out of date silently. */
+export function privilegeOf(tool) {
+    if (PUSH_REGISTRATION_RE.test(tool.name))
+        return 'push_registration';
+    // `some`, not `every`: the scope list is an any-of, so a tool that CAN be
+    // authorized by a privileged scope is treated as privileged.
+    if (tool.scopes?.some((sc) => PRIVILEGED_SCOPE_RE.test(sc)))
+        return 'privileged_scope';
+    return undefined;
+}
+function profileAllows(profile, tool) {
     if (profile === 'full-writes')
         return true;
-    if (profile === 'safe-writes')
-        return cud === 'create' || cud === 'update';
+    if (profile === 'safe-writes') {
+        if (privilegeOf(tool) !== undefined)
+            return false;
+        return tool.cud === 'create' || tool.cud === 'update';
+    }
     return false;
 }
 export function isAllowed(tool, policy) {
@@ -74,13 +101,64 @@ export function isAllowed(tool, policy) {
         return false;
     if (matchesAny(tool, policy.allow))
         return true;
-    return profileAllows(policy.profile, tool.cud);
+    return profileAllows(policy.profile, tool);
+}
+/** Which profiles would permit this tool at all. */
+function profilesAllowing(tool) {
+    return PROFILES.filter((p) => profileAllows(p, tool));
+}
+/** WHICH rule refused the call. `isAllowed` has a precedence order, so exactly
+ * one rule decides; naming the others sends the caller to a setting that
+ * cannot change the outcome. */
+export function denyReason(tool, policy) {
+    if (tool.cud === 'read')
+        return undefined;
+    if (policy.readOnly)
+        return { rule: 'read_only' };
+    const pattern = firstMatch(tool, policy.deny);
+    if (pattern !== undefined)
+        return { rule: 'deny_glob', pattern };
+    if (matchesAny(tool, policy.allow))
+        return undefined;
+    if (profileAllows(policy.profile, tool))
+        return undefined;
+    const kind = privilegeOf(tool);
+    // Distinguished from a plain profile refusal: "delete is not a safe write"
+    // and "this is an org-wide operation" need different answers.
+    if (kind !== undefined && policy.profile === 'safe-writes') {
+        return { rule: 'privileged', profile: policy.profile, kind };
+    }
+    return { rule: 'profile', profile: policy.profile };
+}
+function denyHint(tool, reason) {
+    if (reason.rule === 'read_only') {
+        return 'GOOGLE_READ_ONLY=true refuses every write, ahead of the profile and the allow-list, so neither of those can enable this. Unset GOOGLE_READ_ONLY to allow writes.';
+    }
+    if (reason.rule === 'deny_glob') {
+        return `GOOGLE_WRITE_DENY pattern "${reason.pattern}" matches this tool, and deny is checked before the allow-list and the profile, so neither can override it. Remove or narrow that pattern.`;
+    }
+    if (reason.rule === 'privileged') {
+        const what = reason.kind === 'push_registration'
+            ? 'registers a push channel, which sends this account\'s activity to an external URL'
+            : 'needs a scope that acts on the whole organization, on legal holds, on billing, or on deployed code';
+        return `"${tool.name}" ${what}, so "${reason.profile}" refuses it whatever its verb. Use GOOGLE_PROFILE=full-writes, or allow just this one with GOOGLE_WRITE_ALLOW="${tool.service}:${opOf(tool)}".`;
+    }
+    const usable = profilesAllowing(tool).filter((p) => p !== reason.profile);
+    const profiles = usable.length > 0
+        ? `Use GOOGLE_PROFILE=${usable.join(' or ')}`
+        : 'No profile permits this operation';
+    // The allow-list vocabulary is service:cud or service:op, never the tool
+    // name, so suggesting the name would hand back a pattern that never matches.
+    return `Profile "${reason.profile}" does not permit ${tool.cud}. ${profiles}, or allow just this one with GOOGLE_WRITE_ALLOW="${tool.service}:${opOf(tool)}".`;
 }
 export function writeDisabledResult(tool, policy, account) {
+    // Recomputed rather than passed in: every call site has already run
+    // isAllowed, and a hint that disagrees with the verdict is worse than none.
+    const reason = denyReason(tool, policy) ?? { rule: 'profile', profile: policy.profile };
     const envelope = {
         error: 'write_disabled',
         message: `"${tool.name}" (${tool.cud}) is disabled by the current write-control policy (profile: ${policy.profile}${policy.readOnly ? ', GOOGLE_READ_ONLY=true' : ''}).`,
-        hint: `Enable via GOOGLE_PROFILE=safe-writes|full-writes, or GOOGLE_WRITE_ALLOW="${tool.service}:*".`,
+        hint: denyHint(tool, reason),
         retriable: false,
         ...(account ? { account } : {}),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.34",
+  "version": "6.0.0-alpha.36",
   "mcpName": "io.github.bakissation/mcp-google-multi",
   "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",