gogcli-mcp-contacts 4.6.3 → 4.7.1

package/dist/index.js

@@ -34537,11 +34537,19 @@ var DEFAULT_MAX_REQUEST_BODY_SIZE = 4 * 1024 * 1024;
 var McpToolError = class extends Error {
   /** Actionable remediation text, when one applies. */
   hint;
+  /** The upstream HTTP status this failure came from, when known. */
+  status;
+  /** What kind of failure this is, when the thrower knows. */
+  kind;
   constructor(message, opts) {
     super(message, opts?.cause !== void 0 ? { cause: opts.cause } : void 0);
     this.name = "McpToolError";
     if (opts?.hint !== void 0)
       this.hint = opts.hint;
+    if (opts?.status !== void 0)
+      this.status = opts.status;
+    if (opts?.kind !== void 0)
+      this.kind = opts.kind;
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
@@ -34566,7 +34574,7 @@ var API_KEY_RE = new RegExp([
   // webhook signing secret (Stripe-style)
 ].map((p) => `\\b${p}`).join("|"), "g");
 var GOOGLE_OAUTH_TOKEN_RE = /(?<![A-Za-z0-9+/])(?:ya29\.|1\/\/)[A-Za-z0-9._-]{8,}/g;
-var QUERY_SECRET_RE = new RegExp(`([?&](?:(?:access|refresh|id|auth|session|csrf|xsrf)[_-]?token|client[_-]?secret|api[_-]?secret|api[_-]?key|password|passwd|signature|token|key|sig|(?:php|j)?sess(?:ion)?[_-]?id|sid|x[-_]${HEADER_NAME_RUN}?(?:api[-_]?key|token|secret|auth)${HEADER_NAME_RUN})=)[^&#\\s"'<>\`]+`, "gi");
+var QUERY_SECRET_RE = new RegExp(`([?&](?:(?:access|refresh|id|auth|session|csrf|xsrf)[_-]?token|client[_-]?secret|api[_-]?secret|api[_-]?key|password|passwd|signature|token|key|sig|(?:code[_-]?)?verifier|(?:php|j)?sess(?:ion)?[_-]?id|sid|x[-_]${HEADER_NAME_RUN}?(?:api[-_]?key|token|secret|auth)${HEADER_NAME_RUN})=)[^&#\\s"'<>\`]+`, "gi");
 var OAUTH_CODE_RE = /([?&]code=)(?=[^&#\s"'<>`]{16,})[^&#\s"'<>`]+/gi;
 var FORM_PASSWORD_RE = /((?:^|[\s,;:"'(\[{])(?:password|passwd)=)[^&#\s"'<>`]+/gim;
 var HEADER_SECRET_RE = new RegExp(`(\\b(?:x[-_]${HEADER_NAME_RUN}?(?:api[-_]?key|token|secret|auth)${HEADER_NAME_RUN}|api[-_]?key)\\s*:\\s*)[^\\s,;"'<>\`]+`, "gi");
@@ -34577,6 +34585,8 @@ var JSON_SECRET_KEYS = [
   "api[_-]?secret",
   "(?:x[_-])?api[_-]?key",
   "private[_-]?key",
+  "code[_-]?verifier",
+  // PKCE; a bare `verifier` key is too generic for JSON
   `x[_-]${HEADER_NAME_RUN}?(?:api[_-]?key|token|secret|auth)${HEADER_NAME_RUN}`,
   // bounded like HEADER_SECRET_RE
   "(?:proxy-)?authorization",
@@ -34607,6 +34617,11 @@ function redactSecrets(text) {
   return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(GOOGLE_OAUTH_TOKEN_RE, "[REDACTED]").replace(HEADER_SECRET_RE, "$1[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(OAUTH_CODE_RE, "$1[REDACTED]").replace(FORM_PASSWORD_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_COOKIE_DQ_RE, redactJsonCookie('"')).replace(JSON_COOKIE_SQ_RE, redactJsonCookie("'")).replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_NUM_RE, "$1[REDACTED]").replace(JWT_RE, "[REDACTED]");
 }
 var ERROR_REDACTION_INPUT_MAX = 64 * 1024;
+function messageOf(err) {
+  if (err instanceof Error)
+    return err.message;
+  return String(err);
+}
 
 // ../../node_modules/@chrischall/mcp-utils/dist/response/view.js
 function minifiedResult(data) {
@@ -34731,6 +34746,7 @@ function escapeKey(key) {
 var DEFAULT_REQUEST_KEY = "confirmation";
 var DEFAULT_CONFIRMATION_LABEL = "Confirm this action should proceed.";
 var UNSUPPORTED_NOTE = "Nothing was done because this client cannot show a confirmation prompt (it declares no MCP elicitation capability), and this action is never taken without one";
+var DISABLED_NOTE = "Nothing was done because confirmation prompts are turned off for this server, and this action is never taken without one";
 var STATE_PREFIX = "mcpu.confirm.v1.";
 function bindingKey(binding) {
   if (binding.ttlSeconds !== void 0 && !(Number.isFinite(binding.ttlSeconds) && binding.ttlSeconds > 0)) {
@@ -34803,6 +34819,15 @@ ${JSON.stringify(preview, null, 2)}`,
   };
   const response = inputResponse(ctx.mcpReq.inputResponses, requestKey);
   const accepted = acceptedContent(ctx.mcpReq.inputResponses, requestKey, confirmationSchema);
+  if (options.elicitation === false) {
+    return textResult({
+      confirmed: false,
+      dispatched: false,
+      action: options.action,
+      reason: "confirmation-unsupported",
+      note: options.unsupportedNote ? `${DISABLED_NOTE}. ${options.unsupportedNote}` : `${DISABLED_NOTE}.`
+    });
+  }
   if (response.kind === "missing") {
     if (callerAcceptsFormElicitation(ctx) === false) {
       return textResult({
@@ -34997,7 +35022,7 @@ async function tokenConfirmation(action, fb) {
 }
 async function requireConfirmationWithFallback(ctx, options) {
   const { tokenFallback, ...confirmation } = options;
-  if (tokenFallback && callerAcceptsFormElicitation(ctx) === false) {
+  if (tokenFallback && (options.elicitation === false || callerAcceptsFormElicitation(ctx) === false)) {
     return tokenConfirmation(options.action, tokenFallback);
   }
   return requireConfirmation(ctx, confirmation);
@@ -35017,7 +35042,7 @@ function readEnvVar(key, opts = {}) {
   if (typeof raw === "string") {
     const trimmed = raw.trim();
     if (trimmed.length > 0 && trimmed !== "undefined" && trimmed !== "null" && !PLACEHOLDER_RE.test(trimmed)) {
-      return trimmed;
+      return opts.trim === false ? raw : trimmed;
     }
   }
   return opts.default;
@@ -35143,6 +35168,20 @@ function readConfirmMode(env = process.env) {
   }
   return "refuse";
 }
+function readConfirmElicitation(env = process.env) {
+  const raw = readEnvVar("MCP_CONFIRM_ELICITATION", { env })?.trim().toLowerCase();
+  if (!raw || raw === "on")
+    return "on";
+  if (raw === "off")
+    return "off";
+  const key = `elicitation:${raw}`;
+  if (!warned.has(key)) {
+    warned.add(key);
+    process.stderr.write(`MCP_CONFIRM_ELICITATION="${raw}" is not one of on, off; treating it as on.
+`);
+  }
+  return "on";
+}
 function readConfirmTtl(env) {
   const raw = readEnvVar("MCP_CONFIRM_TTL_SECONDS", { env })?.trim();
   if (!raw)
@@ -35187,6 +35226,7 @@ function spentTokenStoreFromEnv(env = process.env) {
 }
 var CONFIRM_TOKEN_AUTO_INSTRUCTION = "Nothing has been done yet. Review this preview; if it is what was intended, call again with the same arguments plus confirmToken. (This server runs with MCP_CONFIRM_MODE=auto, so the user's approval in chat is not required.)";
 var REFUSE_HINT = "Set MCP_CONFIRM_MODE=ask-user on the server to allow two-step confirmation instead.";
+var ELICITATION_OFF_HINT = "MCP_CONFIRM_ELICITATION=off on the server turns confirmation prompts off.";
 var BAD_TTL_HINT = "MCP_CONFIRM_TTL_SECONDS on the server is not a positive whole number of seconds; fix it to allow two-step confirmation.";
 function boundArgs(args) {
   if (args === null || typeof args !== "object" || Array.isArray(args) || !("confirmToken" in args))
@@ -35197,19 +35237,29 @@ function boundArgs(args) {
 }
 function confirmationFromEnv(options) {
   const { tool, account, confirmToken, subject, instruction, args, env = process.env, spent: callerSpent, ...rest } = options;
+  if (args === void 0 || args === null) {
+    throw new TypeError(`confirmationFromEnv: ${tool} passed no args; pass the tool's validated arguments ({} for a tool with none).`);
+  }
   const spent2 = callerSpent ?? spentTokenStoreFromEnv(env);
   const mode = readConfirmMode(env);
   const ttlSeconds = readConfirmTtl(env);
-  const bound = args === void 0 ? void 0 : boundArgs(args);
-  const confirmation = bound === void 0 || rest.binding ? rest : { ...rest, binding: { key: confirmKeyFromEnv(env), args: bound, ttlSeconds: ttlSeconds ?? DEFAULT_TTL_SECONDS2 } };
+  const elicitationOff = readConfirmElicitation(env) === "off";
+  const bound = boundArgs(args);
+  const elicitationBound = account === void 0 ? { args: bound } : { account, args: bound };
+  const bindingAdded = rest.binding ? rest : {
+    ...rest,
+    binding: { key: confirmKeyFromEnv(env), args: elicitationBound, ttlSeconds: ttlSeconds ?? DEFAULT_TTL_SECONDS2 }
+  };
+  const confirmation = elicitationOff ? { ...bindingAdded, elicitation: false } : bindingAdded;
   if (mode === "refuse" || ttlSeconds === void 0) {
-    const hint = mode === "refuse" ? REFUSE_HINT : BAD_TTL_HINT;
+    const reason = mode === "refuse" ? REFUSE_HINT : BAD_TTL_HINT;
+    const hint = elicitationOff ? `${ELICITATION_OFF_HINT} ${reason}` : reason;
     return {
       ...confirmation,
       unsupportedNote: confirmation.unsupportedNote ? `${confirmation.unsupportedNote} ${hint}` : hint
     };
   }
-  const boundSubject = bound === void 0 ? subject : async () => {
+  const boundSubject = async () => {
     const read = await subject();
     if ("content" in read)
       return read;
@@ -35236,12 +35286,14 @@ var SERVER_PROTOCOL_VERSIONS = Object.freeze([
   ...SUPPORTED_PROTOCOL_VERSIONS
 ]);
 function hintResultOrRethrow(err) {
+  if (err instanceof ProtocolError && err.code === ProtocolErrorCode.UrlElicitationRequired)
+    throw err;
   if (err instanceof McpToolError && err.hint) {
     return errorResult(`${err.message}
 
 Hint: ${err.hint}`);
   }
-  throw err;
+  return errorResult(messageOf(err));
 }
 function mcpRequestFrom(args) {
   const ctx = args.at(-1);
@@ -35475,7 +35527,7 @@ var PositiveInt = external_exports.number().int().positive();
 var NonNegInt = external_exports.number().int().nonnegative();
 var NonEmptyString = external_exports.string().min(1);
 var IsoDate = external_exports.iso.date();
-var IsoTime = external_exports.string().regex(/^([01]?\d|2[0-3]):[0-5]\d$/, "must be HH:MM (24h), e.g. 19:30");
+var IsoTime = external_exports.string().regex(/^([01]?\d|2[0-3]):[0-5]\d$/, "must be HH:MM (24h), e.g. 19:30").overwrite((v) => v.padStart(5, "0"));
 var NumericIdString = external_exports.string().regex(/^\d+$/, "must be a numeric id (digits only)").describe("A numeric id string (digits only), safe to interpolate into a URL path.");
 var SafePathSegment = external_exports.string().min(1).regex(/^[^/?#\s]+$/, 'must not contain "/", "?", "#", or whitespace').refine((v) => !v.includes(".."), 'must not contain ".."').describe('A single URL path segment, safe to interpolate: no "/", "..", "?", "#", or whitespace.');
 var schemaOrigin = external_exports.string().optional().describe("Portal origin (e.g. https://<vendor>.example.co) selecting which active session to use. Optional when only one session is active.");
@@ -36162,7 +36214,7 @@ function registerRunTool(server, options) {
   }
   server.registerTool(`gog_${service}_run`, {
     description,
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object(inputSchema)
   }, async (rawArgs) => {
     const { subcommand, args, account } = rawArgs;
@@ -36330,11 +36382,20 @@ async function requireDispatchConfirmation(ctx, options) {
     confirmationLabel: options.confirmationLabel,
     ...options.unsupportedNote ? { unsupportedNote: options.unsupportedNote } : {}
   };
-  if (!fallback) return requireConfirmationWithFallback(ctx, confirmation);
+  if (!fallback) {
+    if (readConfirmElicitation() !== "off") return requireConfirmationWithFallback(ctx, confirmation);
+    const offNote = "MCP_CONFIRM_ELICITATION=off on the server turns confirmation prompts off.";
+    return requireConfirmationWithFallback(ctx, {
+      ...confirmation,
+      elicitation: false,
+      unsupportedNote: confirmation.unsupportedNote ? `${offNote} ${confirmation.unsupportedNote}` : offNote
+    });
+  }
   return requireConfirmationWithFallback(ctx, confirmationFromEnv({
     ...confirmation,
     tool: fallback.tool,
     account: fallback.account ?? readEnvVar("GOG_ACCOUNT") ?? "",
+    args: fallback.args,
     confirmToken: fallback.confirmToken,
     subject: fallback.subject,
     instruction: fallback.instruction ?? CONFIRM_ACTION_INSTRUCTION,
@@ -36343,13 +36404,13 @@ async function requireDispatchConfirmation(ctx, options) {
 }
 
 // ../gogcli-mcp/src/tools/auth.ts
-var AUTH_RUN_SUBCOMMANDS = ["list", "status", "services", "remove", "alias"];
+var AUTH_RUN_SUBCOMMANDS = ["list", "status", "services", "alias"];
 function registerAuthToolsWith(server, defaultServices) {
   const servicesDescribe = `Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). Default: "${defaultServices}". Prefer the narrowest set you need \u2014 requesting a service whose Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request with invalid_scope.`;
   const extraScopesDescribe = "Additional raw OAuth scope URIs to request, comma-separated, on top of the ones `services` implies. Use for scopes no service covers \u2014 e.g. https://www.googleapis.com/auth/bigquery.readonly, required before gog_sheets_datasource_* can read BigQuery-backed Connected Sheets. Leave unset otherwise: an extra scope whose API is not enabled on the OAuth client project makes Google reject the WHOLE authorization with invalid_scope.";
   server.registerTool("gog_auth_list", {
     description: "List the Google accounts stored in gogcli, with their scopes. This reads local configuration only \u2014 it does not contact Google and does NOT tell you whether an account still works: a signed-out account whose refresh token expired or was revoked is listed here exactly like a healthy one, scopes and all. Use gog_auth_health to check whether an account can actually authenticate.",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: false },
     inputSchema: external_exports.object({})
   }, async () => {
     try {
@@ -36360,7 +36421,7 @@ function registerAuthToolsWith(server, defaultServices) {
   });
   server.registerTool("gog_auth_status", {
     description: "Show gogcli auth CONFIGURATION: keyring backend, credential files, and auth setup. Despite the name this is not a health check \u2014 it reads local setup and does not contact Google, so it says nothing about whether an account can still authenticate. Use gog_auth_health for that.",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: false },
     inputSchema: external_exports.object({})
   }, async () => {
     try {
@@ -36371,7 +36432,7 @@ function registerAuthToolsWith(server, defaultServices) {
   });
   server.registerTool("gog_auth_health", {
     description: `Check the LIVE health of each stored Google account. Unlike gog_auth_status (which only reports keyring/config setup), this performs a real token refresh against Google, so it detects expired or revoked (invalid_grant) refresh tokens \u2014 the account-wide sign-out that blocks every service. Reports per account: whether the token is currently valid, the mapped cause when it is not, how long ago it was authorized, and a warning as it approaches the 7-day refresh-token limit that applies to OAuth apps whose consent screen is still in "Testing" mode. Run it proactively to re-authorize on your own schedule instead of mid-task. On a hosted deployment this is the ONLY check that measures Google: a connector showing "connected" or "refreshed" has verified the client's connection to the MCP host, and nothing else \u2014 the Google credential lives in gog's keyring on that host and can be dead while the connection looks perfectly healthy.`,
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({})
   }, async () => {
     try {
@@ -36382,7 +36443,7 @@ function registerAuthToolsWith(server, defaultServices) {
   });
   server.registerTool("gog_auth_services", {
     description: "List all Google services supported by gogcli and the OAuth scopes each requires.",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: false },
     inputSchema: external_exports.object({})
   }, async () => {
     try {
@@ -36393,7 +36454,7 @@ function registerAuthToolsWith(server, defaultServices) {
   });
   server.registerTool("gog_auth_add", {
     description: "Authorize a Google account via browser-based OAuth. Opens a browser window where the user must sign in and grant access. Blocks for up to 5 minutes waiting for the user to complete authorization. If the browser does not open automatically, a fallback URL is included in the response. Use gog_auth_list to check which accounts are already configured.",
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       email: external_exports.string().describe("Google account email to authorize"),
       services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe),
@@ -36413,7 +36474,7 @@ function registerAuthToolsWith(server, defaultServices) {
   });
   server.registerTool("gog_auth_add_url", {
     description: "Begin REMOTE/headless Google authorization (step 1 of 2). Returns a sign-in URL to open in any browser \u2014 no local server or terminal on the gogcli host is needed, so this works on a hosted deployment where the interactive gog_auth_add cannot. Hand the URL to the user; after they sign in, the browser is redirected to a localhost URL that fails to load \u2014 that is expected. They copy that full redirected URL (from the address bar) and you pass it to gog_auth_add_complete. The link is valid for 10 minutes. If you pass a custom `services` here, pass the SAME value to gog_auth_add_complete or the second step will not match this one.",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: false },
     inputSchema: external_exports.object({
       email: external_exports.string().describe("Google account email to authorize"),
       services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe),
@@ -36430,7 +36491,7 @@ function registerAuthToolsWith(server, defaultServices) {
   });
   server.registerTool("gog_auth_add_complete", {
     description: "Complete REMOTE/headless Google authorization (step 2 of 2). Takes the full redirected localhost URL the user copied after finishing gog_auth_add_url, exchanges it for a refresh token, and stores it. Use the SAME `services` value you passed to gog_auth_add_url. Must run within 10 minutes of step 1 and against the same gogcli host.",
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       email: external_exports.string().describe("Google account email being authorized (same as step 1)"),
       redirectUrl: external_exports.string().describe(
@@ -36466,7 +36527,7 @@ function registerAuthToolsWith(server, defaultServices) {
   });
   registerRunTool(server, {
     service: "auth",
-    examples: '"remove", "alias", "list"',
+    examples: '"alias", "list", "status"',
     omitAccount: true,
     allowedSubcommands: AUTH_RUN_SUBCOMMANDS,
     note: "For browser-based authorization, use gog_auth_add instead."
@@ -36536,7 +36597,7 @@ function vetContactsRun(subcommand, args) {
 function registerContactsTools(server) {
   server.registerTool("gog_contacts_search", {
     description: "Search personal Google Contacts by name, email, or phone. For searching the Workspace directory (internal users not in your personal contacts), use gog_people_search from gogcli-mcp-contacts.",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       query: external_exports.string().describe("Search query (name, email, or phone)"),
       account: accountParam
@@ -36546,7 +36607,7 @@ function registerContactsTools(server) {
   });
   server.registerTool("gog_contacts_list", {
     description: "List all Google Contacts.",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       account: accountParam
     })
@@ -36555,7 +36616,7 @@ function registerContactsTools(server) {
   });
   server.registerTool("gog_contacts_get", {
     description: "Get a contact by resource name.",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       resourceName: external_exports.string().describe("Contact resource name (e.g. people/c12345)"),
       account: accountParam
@@ -36565,7 +36626,7 @@ function registerContactsTools(server) {
   });
   server.registerTool("gog_contacts_create", {
     description: "Create a new Google Contact.",
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       givenName: external_exports.string().describe("Given (first) name"),
       familyName: external_exports.string().optional().describe("Family (last) name"),
@@ -36620,7 +36681,7 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "4.6.3" : "0.0.0";
+var VERSION = true ? "4.7.1" : "0.0.0";
 
 // ../gogcli-mcp/src/bootstrap-auth.ts
 import { join as join7 } from "node:path";
@@ -36698,7 +36759,7 @@ var MAX_BLOB_UPLOAD_BYTES = 100 * 1024 * 1024;
 function registerExtraContactsTools(server) {
   server.registerTool("gog_people_me", {
     description: "Show your own People profile (people/me).",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       account: accountParam
     })
@@ -36707,7 +36768,7 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_people_get", {
     description: "Get a People profile by resource name.",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       userId: external_exports.string().describe("Person resource name (people/...) or email"),
       account: accountParam
@@ -36717,7 +36778,7 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_people_search", {
     description: "Search the Google Workspace directory (covers internal users, unlike contacts search which is limited to your personal contacts).",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       query: external_exports.string().describe("Search query (name, email, etc.)"),
       max: external_exports.number().optional().describe("Max results (default: 50)"),
@@ -36736,7 +36797,7 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_people_relations", {
     description: "Get relations (manager, reports, etc.) for a user. Defaults to self when userId is omitted.",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       userId: external_exports.string().optional().describe("Person resource name (defaults to self when omitted)"),
       type: external_exports.string().optional().describe('Filter to a specific relation type (e.g. "manager")'),
@@ -36750,7 +36811,7 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_contacts_update", {
     description: "Update an existing Google Contact. Empty string clears a field; repeatable fields (url/address/custom/relation) take comma/semicolon-separated lists.",
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       resourceName: external_exports.string().describe("Contact resource name (people/...)"),
       given: external_exports.string().optional().describe("Given (first) name"),
@@ -36783,7 +36844,7 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_contacts_delete", {
     description: "Delete a Google Contact by resource name.",
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       resourceName: external_exports.string().describe("Contact resource name (people/...)"),
       account: accountParam
@@ -36793,13 +36854,13 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_contacts_batch_get", {
     description: "Fetch exact Google Contacts by People resource name in native API batches (up to 200).",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({ resourceNames: external_exports.array(external_exports.string().min(1)).min(1).max(200).describe("Exact resource names such as people/c123; maximum 200"), account: accountParam })
   }, async ({ resourceNames, account }) => runOrDiagnose(["contacts", "batch", "get", ...resourceNames.map(pos)], { account }));
   server.registerTool("gog_contacts_batch_create", {
     description: "Create Google Contacts in native People API batches (up to 200). peopleJson is a JSON array of People API Person resources. The payload is materialized in a temporary file on the gog host.",
     // Same kind of write as gog_contacts_create, so the same annotation.
-    annotations: { readOnlyHint: false, destructiveHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({ peopleJson: external_exports.string().describe("JSON array of People API Person resources, up to 200 contacts"), account: accountParam })
   }, async ({ peopleJson, account }) => {
     let people;
@@ -36814,7 +36875,7 @@ function registerExtraContactsTools(server) {
   server.registerTool("gog_contacts_batch_update", {
     description: "Update Google Contacts in native People API batches. peopleByResourceName is a JSON object keyed by People resource name; each value must include the CONTACT source metadata and etag returned by a prior read. gog preserves those etag guards and reports partial progress.",
     // Overwrites fields like gog_contacts_update, so the same annotation.
-    annotations: { readOnlyHint: false, destructiveHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({ peopleByResourceName: external_exports.string().describe("JSON object keyed by people/... resource name, with Person resources including CONTACT source metadata and etag"), account: accountParam })
   }, async ({ peopleByResourceName, account }) => {
     let people;
@@ -36828,7 +36889,7 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_contacts_batch_delete", {
     description: "Permanently delete exact Google Contacts in native People API batches (up to 500). Requires explicit user confirmation; deleted contacts cannot be restored from Trash.",
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({ resourceNames: external_exports.array(external_exports.string().min(1)).min(1).max(500).describe("Exact People resource names; maximum 500"), account: accountParam, confirmToken: confirmTokenParam })
   }, async ({ resourceNames, account, confirmToken }, ctx) => {
     const confirmation = await requireDispatchConfirmation(ctx, {
@@ -36836,7 +36897,7 @@ function registerExtraContactsTools(server) {
       message: "Review and confirm permanent deletion of these Google Contacts:",
       confirmationLabel: "Confirm permanent deletion of the listed contacts.",
       details: { resourceNames },
-      fallback: { tool: "gog_contacts_batch_delete", account, confirmToken, subject: () => ({ target: "contacts", payload: { resourceNames }, preview: { resourceNames } }) }
+      fallback: { args: { resourceNames, account }, tool: "gog_contacts_batch_delete", account, confirmToken, subject: () => ({ target: "contacts", payload: { resourceNames }, preview: { resourceNames } }) }
     });
     if (confirmation) return confirmation;
     return runOrDiagnose(["contacts", "batch", "delete", ...resourceNames.map(pos), "--force"], { account });
@@ -36844,7 +36905,7 @@ function registerExtraContactsTools(server) {
   server.registerTool("gog_contacts_export", {
     description: "Export contacts as vCard (.vcf). Provide a selector (resource name, email, or name), or use query / all to export multiple.",
     // Writes a file on the gog host and can overwrite one: not read-only (audit SEC-4).
-    annotations: { readOnlyHint: false, destructiveHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       selector: external_exports.string().optional().describe("Contact resource name (people/...), email, or name"),
       query: external_exports.string().optional().describe("Search query to export (max 30 results)"),
@@ -36869,7 +36930,7 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_contacts_dedupe", {
     description: "Find likely duplicate personal contacts. Defaults to a read-only preview of the merge plan; set apply to actually merge each duplicate group and delete the redundant contacts (etag-checked, with ambiguous or unmergeable groups refused). Scope a risky apply with resource. Always preview first.",
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       match: external_exports.string().optional().describe("Match fields, comma-separated from email,phone,name (default: email,phone)"),
       max: external_exports.number().optional().describe("Max contacts to scan (0 = all). Mutually exclusive with resource \u2014 gog rejects passing both."),
@@ -36890,7 +36951,7 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_contacts_directory_list", {
     description: "List people from the Google Workspace directory (domain shared contacts).",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       max: external_exports.number().optional().describe("Max results (default: 50)"),
       pageToken: pageTokenParam,
@@ -36908,7 +36969,7 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_contacts_other_list", {
     description: 'List "other contacts" \u2014 auto-collected addresses (e.g. people you have emailed) that are not in your saved contacts.',
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       max: external_exports.number().optional().describe("Max results (default: 100)"),
       pageToken: pageTokenParam,
@@ -36926,7 +36987,7 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_contacts_other_search", {
     description: 'Search "other contacts" \u2014 auto-collected addresses not in your saved contacts.',
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       query: external_exports.string().describe("Search query"),
       max: external_exports.number().optional().describe("Max results (default: 50)"),
@@ -36939,7 +37000,7 @@ function registerExtraContactsTools(server) {
   });
   server.registerTool("gog_people_raw", {
     description: "Dump the raw People API response as JSON (lossless; for scripting and LLM consumption).",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       userId: external_exports.string().describe("Person resource name (people/...) or email"),
       personFields: external_exports.string().optional().describe("People API personFields mask (default: broad set)"),

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-contacts",
   "display_name": "gogcli (Contacts)",
-  "version": "4.6.3",
+  "version": "4.7.1",
   "description": "Extended Google Contacts for Claude via gogcli — auth + Contacts + Workspace directory (People API)",
   "author": {
     "name": "Chris Hall",
@@ -36,7 +36,10 @@
       "env": {
         "GOG_ACCOUNT": "${user_config.gog_account}",
         "GOG_PATH": "${user_config.gog_path}",
-        "GOG_FILE_ROOTS": "${user_config.gog_file_roots}"
+        "GOG_FILE_ROOTS": "${user_config.gog_file_roots}",
+        "DISPLAY_TZ": "${user_config.display_tz}",
+        "GOG_READONLY": "${user_config.gog_readonly}",
+        "GOG_TIMEZONE": "${user_config.gog_timezone}"
       }
     }
   },
@@ -58,6 +61,24 @@
       "title": "Allowed file directories",
       "description": "Directories tools may read files from (attachments, uploads) or write files to (exports, downloads), separated by ':' (';' on Windows). Optional — defaults to ~/gogcli-mcp-files",
       "required": false
+    },
+    "display_tz": {
+      "type": "string",
+      "title": "Display time zone",
+      "description": "zone for *Display fields and for interpreting naive gog values; defaults to America/New_York",
+      "required": false
+    },
+    "gog_readonly": {
+      "type": "string",
+      "title": "Read-only mode",
+      "description": "block all mutating gog API requests (injects gog's --readonly); set to 0/false/no/off (or unset) to allow writes",
+      "required": false
+    },
+    "gog_timezone": {
+      "type": "string",
+      "title": "gog time zone",
+      "description": "zone gog formats naive dates in; unset, runner.ts hands gog DISPLAY_TZ so the two cannot diverge",
+      "required": false
     }
   },
   "tools": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-contacts",
-  "version": "4.6.3",
+  "version": "4.7.1",
   "mcpName": "io.github.chrischall/gogcli-mcp-contacts",
   "description": "Extended Google Contacts + People MCP server via gogcli — auth + Contacts + Workspace directory (People API)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -24,7 +24,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.14.0",
+    "@chrischall/mcp-utils": "^3.0.0",
     "@modelcontextprotocol/server": "^2.3.0",
     "zod": "^4.6.1"
   },

package/src/tools/contacts-extra.ts

@@ -8,7 +8,7 @@ import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
 export function registerExtraContactsTools(server: McpServer): void {
   server.registerTool('gog_people_me', {
     description: 'Show your own People profile (people/me).',
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: z.object({
       account: accountParam,
     }),
@@ -18,7 +18,7 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_people_get', {
     description: 'Get a People profile by resource name.',
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: z.object({
       userId: z.string().describe('Person resource name (people/...) or email'),
       account: accountParam,
@@ -29,7 +29,7 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_people_search', {
     description: 'Search the Google Workspace directory (covers internal users, unlike contacts search which is limited to your personal contacts).',
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: z.object({
       query: z.string().describe('Search query (name, email, etc.)'),
       max: z.number().optional().describe('Max results (default: 50)'),
@@ -49,7 +49,7 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_people_relations', {
     description: 'Get relations (manager, reports, etc.) for a user. Defaults to self when userId is omitted.',
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: z.object({
       userId: z.string().optional().describe('Person resource name (defaults to self when omitted)'),
       type: z.string().optional().describe('Filter to a specific relation type (e.g. "manager")'),
@@ -64,7 +64,7 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_contacts_update', {
     description: 'Update an existing Google Contact. Empty string clears a field; repeatable fields (url/address/custom/relation) take comma/semicolon-separated lists.',
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: z.object({
       resourceName: z.string().describe('Contact resource name (people/...)'),
       given: z.string().optional().describe('Given (first) name'),
@@ -98,7 +98,7 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_contacts_delete', {
     description: 'Delete a Google Contact by resource name.',
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: z.object({
       resourceName: z.string().describe('Contact resource name (people/...)'),
       account: accountParam,
@@ -109,14 +109,14 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_contacts_batch_get', {
     description: 'Fetch exact Google Contacts by People resource name in native API batches (up to 200).',
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: z.object({ resourceNames: z.array(z.string().min(1)).min(1).max(200).describe('Exact resource names such as people/c123; maximum 200'), account: accountParam }),
   }, async ({ resourceNames, account }) => runOrDiagnose(['contacts', 'batch', 'get', ...resourceNames.map(pos)], { account }));
 
   server.registerTool('gog_contacts_batch_create', {
     description: 'Create Google Contacts in native People API batches (up to 200). peopleJson is a JSON array of People API Person resources. The payload is materialized in a temporary file on the gog host.',
     // Same kind of write as gog_contacts_create, so the same annotation.
-    annotations: { readOnlyHint: false, destructiveHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: z.object({ peopleJson: z.string().describe('JSON array of People API Person resources, up to 200 contacts'), account: accountParam }),
   }, async ({ peopleJson, account }) => {
     let people: unknown;
@@ -128,7 +128,7 @@ export function registerExtraContactsTools(server: McpServer): void {
   server.registerTool('gog_contacts_batch_update', {
     description: 'Update Google Contacts in native People API batches. peopleByResourceName is a JSON object keyed by People resource name; each value must include the CONTACT source metadata and etag returned by a prior read. gog preserves those etag guards and reports partial progress.',
     // Overwrites fields like gog_contacts_update, so the same annotation.
-    annotations: { readOnlyHint: false, destructiveHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: z.object({ peopleByResourceName: z.string().describe('JSON object keyed by people/... resource name, with Person resources including CONTACT source metadata and etag'), account: accountParam }),
   }, async ({ peopleByResourceName, account }) => {
     let people: unknown;
@@ -139,7 +139,7 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_contacts_batch_delete', {
     description: 'Permanently delete exact Google Contacts in native People API batches (up to 500). Requires explicit user confirmation; deleted contacts cannot be restored from Trash.',
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: z.object({ resourceNames: z.array(z.string().min(1)).min(1).max(500).describe('Exact People resource names; maximum 500'), account: accountParam, confirmToken: confirmTokenParam }),
   }, async ({ resourceNames, account, confirmToken }, ctx) => {
     const confirmation = await requireDispatchConfirmation(ctx, {
@@ -147,7 +147,7 @@ export function registerExtraContactsTools(server: McpServer): void {
       message: 'Review and confirm permanent deletion of these Google Contacts:',
       confirmationLabel: 'Confirm permanent deletion of the listed contacts.',
       details: { resourceNames },
-      fallback: { tool: 'gog_contacts_batch_delete', account, confirmToken, subject: () => ({ target: 'contacts', payload: { resourceNames }, preview: { resourceNames } }) },
+      fallback: { args: { resourceNames, account }, tool: 'gog_contacts_batch_delete', account, confirmToken, subject: () => ({ target: 'contacts', payload: { resourceNames }, preview: { resourceNames } }) },
     });
     if (confirmation) return confirmation;
     return runOrDiagnose(['contacts', 'batch', 'delete', ...resourceNames.map(pos), '--force'], { account });
@@ -156,7 +156,7 @@ export function registerExtraContactsTools(server: McpServer): void {
   server.registerTool('gog_contacts_export', {
     description: 'Export contacts as vCard (.vcf). Provide a selector (resource name, email, or name), or use query / all to export multiple.',
     // Writes a file on the gog host and can overwrite one: not read-only (audit SEC-4).
-    annotations: { readOnlyHint: false, destructiveHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: z.object({
       selector: z.string().optional().describe('Contact resource name (people/...), email, or name'),
       query: z.string().optional().describe('Search query to export (max 30 results)'),
@@ -182,7 +182,7 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_contacts_dedupe', {
     description: 'Find likely duplicate personal contacts. Defaults to a read-only preview of the merge plan; set apply to actually merge each duplicate group and delete the redundant contacts (etag-checked, with ambiguous or unmergeable groups refused). Scope a risky apply with resource. Always preview first.',
-    annotations: { destructiveHint: true },
+    annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: z.object({
       match: z.string().optional().describe('Match fields, comma-separated from email,phone,name (default: email,phone)'),
       max: z.number().optional().describe('Max contacts to scan (0 = all). Mutually exclusive with resource — gog rejects passing both.'),
@@ -204,7 +204,7 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_contacts_directory_list', {
     description: 'List people from the Google Workspace directory (domain shared contacts).',
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: z.object({
       max: z.number().optional().describe('Max results (default: 50)'),
       pageToken: pageTokenParam,
@@ -223,7 +223,7 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_contacts_other_list', {
     description: 'List "other contacts" — auto-collected addresses (e.g. people you have emailed) that are not in your saved contacts.',
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: z.object({
       max: z.number().optional().describe('Max results (default: 100)'),
       pageToken: pageTokenParam,
@@ -242,7 +242,7 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_contacts_other_search', {
     description: 'Search "other contacts" — auto-collected addresses not in your saved contacts.',
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: z.object({
       query: z.string().describe('Search query'),
       max: z.number().optional().describe('Max results (default: 50)'),
@@ -256,7 +256,7 @@ export function registerExtraContactsTools(server: McpServer): void {
 
   server.registerTool('gog_people_raw', {
     description: 'Dump the raw People API response as JSON (lossless; for scripting and LLM consumption).',
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: z.object({
       userId: z.string().describe('Person resource name (people/...) or email'),
       personFields: z.string().optional().describe('People API personFields mask (default: broad set)'),

package/tests/tool-annotations.test.ts

@@ -0,0 +1,10 @@
+import { authToolsFor, registerContactsTools } from '../../gogcli-mcp/src/lib.js';
+import { registerExtraContactsTools } from '../src/tools/contacts-extra.js';
+import { describeToolAnnotations, LOCAL_AUTH_TOOLS } from '../../gogcli-mcp/tests/support/tool-annotations.js';
+
+// The same registrar list src/index.ts hands to runMcp.
+describeToolAnnotations([authToolsFor('contacts'), registerContactsTools, registerExtraContactsTools] as never, {
+  tools: 29,
+  destructive: 12,
+  local: [...LOCAL_AUTH_TOOLS],
+});