mcp-google-map 0.9.0 → 0.13.0

package/dist/cli.js

@@ -2,7 +2,7 @@
 import {
   Logger,
   PlacesSearcher
-} from "./chunk-OAML6T2D.js";
+} from "./chunk-VCFXCLJF.js";
 
 // src/cli.ts
 import { config as dotenvConfig2 } from "dotenv";
@@ -13,75 +13,6 @@ import { hideBin } from "yargs/helpers";
 // src/utils/configResolver.ts
 import { config as dotenvConfig } from "dotenv";
 import { existsSync } from "fs";
-
-// src/utils/autoUpdate.ts
-var AUTO_UPDATE_DISABLED_ENV = "MCP_AUTO_UPDATE_DISABLED";
-var DEFAULT_PACKAGE_NAME = "mcp-google-map";
-var DEFAULT_REGISTRY_BASE_URL = "https://registry.npmjs.org";
-var DEFAULT_UPDATE_CHECK_TIMEOUT_MS = 2e3;
-async function probeLatestVersion(deps = {}) {
-  const env = deps.env ?? process.env;
-  if (isAutoUpdateDisabled(env)) {
-    return { status: "disabled" };
-  }
-  const currentVersion = deps.currentVersion;
-  if (!currentVersion) {
-    return { status: "unknown-version" };
-  }
-  const packageName = deps.packageName ?? DEFAULT_PACKAGE_NAME;
-  const registryBaseUrl = deps.registryBaseUrl ?? DEFAULT_REGISTRY_BASE_URL;
-  const timeoutMs = deps.timeoutMs ?? DEFAULT_UPDATE_CHECK_TIMEOUT_MS;
-  const fetchImpl = deps.fetchImpl ?? fetch;
-  try {
-    const response = await fetchImpl(`${registryBaseUrl}/${packageName}/latest`, {
-      headers: { accept: "application/json" },
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    if (!response.ok) {
-      return {
-        status: "error",
-        message: `registry responded with HTTP ${response.status}.`
-      };
-    }
-    const payload = await response.json();
-    if (typeof payload?.version !== "string") {
-      return {
-        status: "error",
-        message: "registry response has no version field."
-      };
-    }
-    if (!isNewerVersion(payload.version, currentVersion)) {
-      return { status: "current", currentVersion };
-    }
-    return { status: "newer", currentVersion, latestVersion: payload.version };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { status: "error", message };
-  }
-}
-function isAutoUpdateDisabled(env = process.env) {
-  const raw = env[AUTO_UPDATE_DISABLED_ENV];
-  return typeof raw === "string" && /^(1|true|yes)$/i.test(raw.trim());
-}
-function isNewerVersion(candidate, current) {
-  const toSegments = (version) => version.trim().split(".").map((segment) => /^\d+$/.test(segment) ? Number(segment) : Number.NaN);
-  const candidateSegments = toSegments(candidate);
-  const currentSegments = toSegments(current);
-  if (candidateSegments.some((segment) => !Number.isInteger(segment)) || currentSegments.some((segment) => !Number.isInteger(segment))) {
-    return false;
-  }
-  const length = Math.max(candidateSegments.length, currentSegments.length);
-  for (let index = 0; index < length; index += 1) {
-    const candidatePart = candidateSegments[index] ?? 0;
-    const currentPart = currentSegments[index] ?? 0;
-    if (candidatePart !== currentPart) {
-      return candidatePart > currentPart;
-    }
-  }
-  return false;
-}
-
-// src/utils/configResolver.ts
 var NODE_ENGINE_FLOOR = 22;
 var DEFAULT_HTTP_HOST = "127.0.0.1";
 var DEFAULT_HTTP_PORT = 3e3;
@@ -116,7 +47,7 @@ function resolveRuntimeConfig(env = process.env, overrides = {}) {
     portSource,
     enabledToolsRaw,
     enabledToolsSource: enabledToolsRaw ? "environment" : "default",
-    autoUpdateDisabled: isAutoUpdateDisabled(env),
+    autoUpdateDisabled: overrides.autoUpdateDisabled === true,
     envFile: overrides.envFile
   };
 }
@@ -178,10 +109,92 @@ import { z } from "zod";
 
 // src/utils/requestContext.ts
 import { AsyncLocalStorage } from "async_hooks";
+
+// src/utils/apiKeyManager.ts
+var ApiKeyManager = class _ApiKeyManager {
+  constructor() {
+    this.defaultApiKey = void 0;
+  }
+  /**
+   * @brief Returns the process-wide singleton instance.
+   * @details Lazily constructs the manager; the default key starts unset and
+   * MUST be injected by the server-start path before serving requests.
+   * Complexity O(1).
+   * @return {ApiKeyManager} The singleton instance.
+   */
+  static getInstance() {
+    if (!_ApiKeyManager.instance) {
+      _ApiKeyManager.instance = new _ApiKeyManager();
+    }
+    return _ApiKeyManager.instance;
+  }
+  /**
+   * @brief Injects the startup default API key.
+   * @details Called by the server-start command with the key resolved from
+   * the persisted settings (REQ-142); undefined clears the default so
+   * requests without header/session keys resolve no key (REQ-018, DES-006).
+   * Pure in-memory mutation; no environment writes.
+   * @param key {string | undefined} Default key from the persisted settings; undefined clears it.
+   * @return {void}
+   * @satisfies DES-006, REQ-142
+   */
+  setDefaultApiKey(key) {
+    this.defaultApiKey = key;
+  }
+  /**
+   * @brief Resolves the effective API key for one request.
+   * @details Priority: `X-Google-Maps-API-Key` header, then `Authorization:
+   * Bearer` token, then the session key, then the injected default key
+   * (DES-005, REQ-016, REQ-017, REQ-018). Complexity O(1).
+   * @param req {Request | undefined} Incoming HTTP request; undefined skips header resolution.
+   * @param sessionApiKey {string | undefined} Session-scoped key; consulted before the default.
+   * @return {string | undefined} Effective key; undefined when nothing resolves.
+   * @satisfies DES-005, REQ-016, REQ-017, REQ-018
+   */
+  getApiKey(req, sessionApiKey) {
+    if (req) {
+      const headerApiKey = req.headers["x-google-maps-api-key"];
+      if (headerApiKey) {
+        return headerApiKey;
+      }
+      const authHeader = req.headers["authorization"];
+      if (authHeader && authHeader.startsWith("Bearer ")) {
+        return authHeader.substring(7);
+      }
+    }
+    if (sessionApiKey) {
+      return sessionApiKey;
+    }
+    return this.defaultApiKey;
+  }
+  /**
+   * @brief Reports whether any API key is resolvable for a request.
+   * @details Delegates to `getApiKey` truthiness. Complexity O(1).
+   * @param req {Request | undefined} Incoming HTTP request.
+   * @param sessionApiKey {string | undefined} Session-scoped key.
+   * @return {boolean} True when a key resolves.
+   */
+  hasApiKey(req, sessionApiKey) {
+    return !!this.getApiKey(req, sessionApiKey);
+  }
+  /**
+   * @brief Validates the API key format.
+   * @details Accepts 20-50 characters of `[A-Za-z0-9_-]` (REQ-020). Pure;
+   * complexity O(n) in key length.
+   * @param key {string} Candidate key.
+   * @return {boolean} True when the format is valid.
+   * @satisfies REQ-020
+   */
+  isValidApiKeyFormat(key) {
+    return /^[A-Za-z0-9_-]{20,50}$/.test(key);
+  }
+};
+
+// src/utils/requestContext.ts
 var requestContextStorage = new AsyncLocalStorage();
 function getCurrentApiKey() {
   const context = requestContextStorage.getStore();
-  return context?.apiKey || process.env.GOOGLE_MAPS_API_KEY;
+  return context?.apiKey || ApiKeyManager.getInstance().getApiKey();
 }
 function runWithContext(context, fn) {
   return requestContextStorage.run(context, fn);
@@ -1210,62 +1223,6 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import express from "express";
 import { randomUUID } from "crypto";
 import { z as z19 } from "zod";
-
-// src/utils/apiKeyManager.ts
-var ApiKeyManager = class _ApiKeyManager {
-  constructor() {
-    this.defaultApiKey = process.env.GOOGLE_MAPS_API_KEY;
-  }
-  static getInstance() {
-    if (!_ApiKeyManager.instance) {
-      _ApiKeyManager.instance = new _ApiKeyManager();
-    }
-    return _ApiKeyManager.instance;
-  }
-  /**
-   * Set the default API key (from command line or environment)
-   */
-  setDefaultApiKey(key) {
-    this.defaultApiKey = key;
-    process.env.GOOGLE_MAPS_API_KEY = key;
-  }
-  /**
-   * Get API key with priority:
-   * 1. HTTP Header (X-Google-Maps-API-Key or Authorization: Bearer)
-   * 2. Session-specific API key
-   * 3. Default API key (command line or environment)
-   */
-  getApiKey(req, sessionApiKey) {
-    if (req) {
-      const headerApiKey = req.headers["x-google-maps-api-key"];
-      if (headerApiKey) {
-        return headerApiKey;
-      }
-      const authHeader = req.headers["authorization"];
-      if (authHeader && authHeader.startsWith("Bearer ")) {
-        return authHeader.substring(7);
-      }
-    }
-    if (sessionApiKey) {
-      return sessionApiKey;
-    }
-    return this.defaultApiKey;
-  }
-  /**
-   * Check if any API key is available
-   */
-  hasApiKey(req, sessionApiKey) {
-    return !!this.getApiKey(req, sessionApiKey);
-  }
-  /**
-   * Validate API key format (basic validation)
-   */
-  isValidApiKeyFormat(key) {
-    return /^[A-Za-z0-9_-]{20,50}$/.test(key);
-  }
-};
-
-// src/core/BaseMcpServer.ts
 var VERSION = "0.0.1";
 var BaseMcpServer = class {
   constructor(name, tools) {
@@ -1443,7 +1400,7 @@ var BaseMcpServer = class {
 
 // src/cli.ts
 import { fileURLToPath } from "url";
-import { dirname as dirname2 } from "path";
+import { dirname as dirname3 } from "path";
 import { readFileSync as readFileSync5, writeFileSync as writeFileSync4, existsSync as existsSync4 } from "fs";
 import { createInterface } from "readline";
 
@@ -1453,12 +1410,80 @@ import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync a
 import { homedir } from "os";
 import { dirname, join as join2 } from "path";
 
+// src/utils/autoUpdate.ts
+var AUTO_UPDATE_DISABLED_ENV = "MCP_AUTO_UPDATE_DISABLED";
+var DEFAULT_PACKAGE_NAME = "mcp-google-map";
+var DEFAULT_REGISTRY_BASE_URL = "https://registry.npmjs.org";
+var DEFAULT_UPDATE_CHECK_TIMEOUT_MS = 2e3;
+async function probeLatestVersion(deps = {}) {
+  const env = deps.env;
+  if (env !== void 0 && isAutoUpdateDisabled(env)) {
+    return { status: "disabled" };
+  }
+  const currentVersion = deps.currentVersion;
+  if (!currentVersion) {
+    return { status: "unknown-version" };
+  }
+  const packageName = deps.packageName ?? DEFAULT_PACKAGE_NAME;
+  const registryBaseUrl = deps.registryBaseUrl ?? DEFAULT_REGISTRY_BASE_URL;
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_UPDATE_CHECK_TIMEOUT_MS;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  try {
+    const response = await fetchImpl(`${registryBaseUrl}/${packageName}/latest`, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!response.ok) {
+      return {
+        status: "error",
+        message: `registry responded with HTTP ${response.status}.`
+      };
+    }
+    const payload = await response.json();
+    if (typeof payload?.version !== "string") {
+      return {
+        status: "error",
+        message: "registry response has no version field."
+      };
+    }
+    if (!isNewerVersion(payload.version, currentVersion)) {
+      return { status: "current", currentVersion };
+    }
+    return { status: "newer", currentVersion, latestVersion: payload.version };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { status: "error", message };
+  }
+}
+function isAutoUpdateDisabled(env = process.env) {
+  const raw = env[AUTO_UPDATE_DISABLED_ENV];
+  return typeof raw === "string" && /^(1|true|yes)$/i.test(raw.trim());
+}
+function isNewerVersion(candidate, current) {
+  const toSegments = (version) => version.trim().split(".").map((segment) => /^\d+$/.test(segment) ? Number(segment) : Number.NaN);
+  const candidateSegments = toSegments(candidate);
+  const currentSegments = toSegments(current);
+  if (candidateSegments.some((segment) => !Number.isInteger(segment)) || currentSegments.some((segment) => !Number.isInteger(segment))) {
+    return false;
+  }
+  const length = Math.max(candidateSegments.length, currentSegments.length);
+  for (let index = 0; index < length; index += 1) {
+    const candidatePart = candidateSegments[index] ?? 0;
+    const currentPart = currentSegments[index] ?? 0;
+    if (candidatePart !== currentPart) {
+      return candidatePart > currentPart;
+    }
+  }
+  return false;
+}
+
 // src/utils/cliSettings.ts
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
 import { join, resolve } from "path";
 var SETTINGS_PROGRAM_NAME = "mcp-google-map";
 var CLI_SETTINGS_RELATIVE = [".config", SETTINGS_PROGRAM_NAME, "config.json"];
 var MCP_SERVER_NAME = "mcp-google-map";
+var INSTALL_API_KEY_PLACEHOLDER = "__RUN_mcp-google-map_api-key_TO_CONFIGURE_YOUR_API_KEY__";
 function resolveCliSettingsPath(home) {
   const root = home ?? (process.env.HOME ?? process.cwd());
   return resolve(root, ...CLI_SETTINGS_RELATIVE);
@@ -1473,23 +1498,40 @@ function uniqueStrings(value) {
   }
   return result;
 }
+function isUnsetApiKey(value) {
+  return value === void 0 || value === null || value.trim().length === 0 || value === INSTALL_API_KEY_PLACEHOLDER;
+}
 function loadCliSettings(home) {
   try {
     const raw = JSON.parse(readFileSync(resolveCliSettingsPath(home), "utf-8"));
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-      return { enabled: [] };
+      return { enabled: [], apiKey: "", autoUpdate: true };
     }
-    return { enabled: uniqueStrings(raw.enabled) };
+    const record = raw;
+    return {
+      enabled: uniqueStrings(record.enabled),
+      apiKey: typeof record.apiKey === "string" ? record.apiKey : "",
+      autoUpdate: typeof record.autoUpdate === "boolean" ? record.autoUpdate : true
+    };
   } catch {
-    return { enabled: [] };
+    return { enabled: [], apiKey: "", autoUpdate: true };
   }
 }
+function loadConfiguredApiKey(home) {
+  const apiKey = loadCliSettings(home).apiKey;
+  return isUnsetApiKey(apiKey) ? void 0 : apiKey;
+}
 function saveCliSettings(settings, home) {
   const path = resolveCliSettingsPath(home);
   const temporary = `${path}.tmp`;
+  const payload = {
+    enabled: uniqueStrings(settings.enabled),
+    apiKey: typeof settings.apiKey === "string" ? settings.apiKey : "",
+    autoUpdate: settings.autoUpdate === true
+  };
   try {
     mkdirSync(join(path, ".."), { recursive: true });
-    writeFileSync(temporary, JSON.stringify({ enabled: uniqueStrings(settings.enabled) }, null, 2) + "\n", "utf-8");
+    writeFileSync(temporary, JSON.stringify(payload, null, 2) + "\n", "utf-8");
     renameSync(temporary, path);
   } catch (error) {
     throw new Error(`settings write failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -1772,7 +1814,22 @@ async function runVersionCommand(options, deps = {}) {
 `);
   return 0;
 }
+function isUpgradeNecessary(status) {
+  return status !== "current";
+}
 async function runUpgradeCommand(options, deps = {}) {
+  const precheck = await probeLatestVersion({
+    ...deps.idleCheck,
+    currentVersion: options.currentVersion
+  });
+  if (!isUpgradeNecessary(precheck.status)) {
+    const stdout2 = deps.stdout ?? process.stdout;
+    stdout2.write(
+      `${DEFAULT_PACKAGE_NAME} ${options.currentVersion} is already the latest available version.
+`
+    );
+    return 0;
+  }
   const upgraded = runPackageManagerCommand(PACKAGE_UPGRADE_COMMAND, deps);
   if (upgraded !== 0) {
     return upgraded;
@@ -1920,6 +1977,7 @@ function renderClientSnippet(options = {}) {
 
 // src/utils/cliTargets.ts
 import {
+  appendFileSync,
   cpSync,
   existsSync as existsSync2,
   mkdirSync as mkdirSync3,
@@ -2114,30 +2172,46 @@ function listFilesRecursive(root) {
   walk(root);
   return files;
 }
-function syncSkillTree(source, destination) {
+var SKILL_DOCUMENT_FILE = "SKILL.md";
+function syncSkillTree(source, destination, layout = {}) {
   mkdirSync3(destination, { recursive: true });
-  cpSync(source, destination, { recursive: true, force: true });
-  const expected = new Set(listFilesRecursive(source));
+  cpSync(source, destination, {
+    recursive: true,
+    force: true,
+    filter: (entry) => layout.debugPath === void 0 || relative(source, entry).split("\\").join("/") !== layout.debugPath
+  });
+  const expected = new Set(listFilesRecursive(source).filter((rel) => rel !== layout.debugPath));
   const existing = listFilesRecursive(destination);
   existing.sort((a, b) => b.length - a.length);
   for (const rel of existing) {
     if (expected.has(rel)) continue;
     rmSync(join3(destination, rel), { recursive: true, force: true });
   }
+  if (layout.includeDebug === true && layout.debugPath !== void 0) {
+    appendFileSync(
+      join3(destination, ...SKILL_DOCUMENT_FILE.split("/")),
+      readFileSync3(join3(source, ...layout.debugPath.split("/")))
+    );
+  }
 }
 function removeSkillDir(skillDir) {
   rmSync(skillDir, { recursive: true, force: true });
 }
-function compareSkillTree(source, destination) {
-  const packaged = listFilesRecursive(source);
+function compareSkillTree(source, destination, layout = {}) {
+  const packaged = listFilesRecursive(source).filter((rel) => rel !== layout.debugPath);
   if (packaged.length === 0) return "MISSING";
   if (!existsSync2(destination)) return "MISSING";
   for (const rel of packaged) {
     const target = join3(destination, ...rel.split("/"));
     if (!existsSync2(target)) return "MISSING";
-    if (readFileSync3(target).toString("utf-8") !== readFileSync3(join3(source, ...rel.split("/"))).toString("utf-8")) {
-      return "STALE";
+    const packagedText = readFileSync3(join3(source, ...rel.split("/"))).toString("utf-8");
+    const installedText = readFileSync3(target).toString("utf-8");
+    if (installedText === packagedText) continue;
+    if (rel === SKILL_DOCUMENT_FILE && layout.debugPath !== void 0) {
+      const overlayText = readFileSync3(join3(source, ...layout.debugPath.split("/"))).toString("utf-8");
+      if (installedText === packagedText + overlayText) continue;
     }
+    return "STALE";
   }
   return "OK";
 }
@@ -2167,13 +2241,9 @@ function applyServerRegistration(target, serverName, entry, home) {
 
 // src/utils/cliInstaller.ts
 import { existsSync as existsSync3, readFileSync as readFileSync4 } from "fs";
-import { join as join4, resolve as resolve3 } from "path";
-function buildServerRegistration(apiKey) {
-  const env = {};
-  if (apiKey !== void 0 && apiKey.length > 0) {
-    env.GOOGLE_MAPS_API_KEY = apiKey;
-  }
-  return { command: "npx", args: ["-y", MCP_SERVER_NAME, "start", "--stdio"], env };
+import { dirname as dirname2, join as join4, resolve as resolve3 } from "path";
+function buildServerRegistration() {
+  return { command: "npx", args: ["-y", MCP_SERVER_NAME, "start", "--stdio"] };
 }
 function resolveSkillsResourcesRoot(packageRoot) {
   const candidate = resolve3(packageRoot, "src", "resources", "skills");
@@ -2202,21 +2272,36 @@ function loadSkillsManifest(resourcesRoot) {
     if (typeof skill.id !== "string" || typeof skill.path !== "string") {
       throw new Error(`skills manifest entry is missing id or path: ${manifestPath}`);
     }
-    if (!existsSync3(join4(resourcesRoot, skill.path))) {
-      throw new Error(`manifest skill file not found: ${join4(resourcesRoot, skill.path)}`);
+    const skillFile = join4(resourcesRoot, skill.path);
+    if (!existsSync3(skillFile)) {
+      throw new Error(`manifest skill file not found: ${skillFile}`);
+    }
+    if (skill.debug !== void 0 && (typeof skill.debug !== "string" || skill.debug.trim() === "")) {
+      throw new Error(`manifest skill debug path is invalid: ${manifestPath}`);
+    }
+    const debugPath = typeof skill.debug === "string" ? skill.debug : void 0;
+    if (debugPath !== void 0 && !existsSync3(join4(dirname2(resolve3(skillFile)), debugPath))) {
+      throw new Error(`manifest skill debug file not found: ${join4(dirname2(resolve3(skillFile)), debugPath)}`);
     }
     return {
       id: skill.id,
       name: skill.name ?? skill.id,
       version: skill.version ?? "",
       path: skill.path,
-      description: skill.description ?? ""
+      description: skill.description ?? "",
+      ...debugPath === void 0 ? {} : { debugPath }
     };
   });
 }
+function resolveSkillContentLayout(skill, includeDebug) {
+  return {
+    ...skill.debugPath === void 0 ? {} : { debugPath: skill.debugPath },
+    includeDebug: includeDebug && skill.debugPath !== void 0
+  };
+}
 function installEnabledCliResources(options) {
   const manifest = loadSkillsManifest(options.resourcesRoot);
-  const entry = buildServerRegistration(options.apiKey);
+  const entry = buildServerRegistration();
   const result = { summaries: [], errors: [] };
   for (const cli of loadCliSettings(options.home).enabled) {
     const target = CLI_TARGETS[cli];
@@ -2228,7 +2313,11 @@ function installEnabledCliResources(options) {
       applyServerRegistration(target, MCP_SERVER_NAME, entry, options.home);
       let skills = 0;
       for (const skill of manifest) {
-        syncSkillTree(join4(options.resourcesRoot, skill.id), join4(target.skillsDir(options.home), skill.id));
+        syncSkillTree(
+          join4(options.resourcesRoot, skill.id),
+          join4(target.skillsDir(options.home), skill.id),
+          resolveSkillContentLayout(skill, options.includeDebugSkills === true)
+        );
         skills += 1;
       }
       result.summaries.push({ cli: target.id, server: 1, skills });
@@ -2350,7 +2439,9 @@ function buildInstallRows(home, resourcesRoot) {
         skill.id,
         target.id,
         "yes",
-        compareSkillTree(join5(resourcesRoot, skill.id), join5(target.skillsDir(home), skill.id))
+        compareSkillTree(join5(resourcesRoot, skill.id), join5(target.skillsDir(home), skill.id), {
+          ...skill.debugPath === void 0 ? {} : { debugPath: skill.debugPath }
+        })
       ]);
     }
   }
@@ -2368,7 +2459,7 @@ function buildCliShowReport(options) {
 
 // src/cli.ts
 var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname2(__filename);
+var __dirname = dirname3(__filename);
 function extractEnvFileOption(argv) {
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -2397,9 +2488,7 @@ async function startServer(port, apiKey, host) {
   if (port) {
     process.env.MCP_SERVER_PORT = port.toString();
   }
-  if (apiKey) {
-    process.env.GOOGLE_MAPS_API_KEY = apiKey;
-  }
+  ApiKeyManager.getInstance().setDefaultApiKey(apiKey);
   if (host) {
     process.env.MCP_SERVER_HOST = host;
   }
@@ -2874,6 +2963,80 @@ function runEnableDisableCliCommand(name, enable, options = {}) {
   );
   return 0;
 }
+function runApiKeyCommand(key, options) {
+  const streams = options.streams ?? { stdout: process.stdout, stderr: process.stderr };
+  const trimmed = (key ?? "").trim();
+  if (!ApiKeyManager.getInstance().isValidApiKeyFormat(trimmed)) {
+    streams.stderr.write(
+      "api-key: invalid Google Maps API key. Expected 20-50 characters of letters, digits, hyphens, or underscores.\nUsage: mcp-google-map api-key <your-api-key>\n"
+    );
+    return 1;
+  }
+  try {
+    const settings = loadCliSettings(options.home);
+    settings.apiKey = trimmed;
+    saveCliSettings(settings, options.home);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    streams.stderr.write(`api-key: failed to persist the API key: ${message}
+`);
+    return 1;
+  }
+  streams.stdout.write(`API key configured (${maskSecret(trimmed)}).
+`);
+  let install;
+  try {
+    install = installEnabledCliResources({ home: options.home, resourcesRoot: options.resourcesRoot });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    streams.stderr.write(`api-key: install failed: ${message}
+`);
+    return 1;
+  }
+  if (install.summaries.length === 0 && install.errors.length === 0) {
+    streams.stdout.write("No CLI agent enabled. Run 'mcp-google-map enable <cli name>' first.\n");
+    return 0;
+  }
+  for (const summary of install.summaries) {
+    streams.stdout.write(
+      `${summary.cli}: MCP connector installed (server entries: ${summary.server}, skills: ${summary.skills}).
+`
+    );
+  }
+  for (const error of install.errors) {
+    streams.stdout.write(`${error}
+`);
+  }
+  return install.errors.length > 0 ? 1 : 0;
+}
+function runAutoUpdateCommand(rawState, options = {}) {
+  const streams = options.streams ?? { stdout: process.stdout, stderr: process.stderr };
+  const normalized = (rawState ?? "").trim().toLowerCase();
+  let enabled;
+  if (normalized === "enable" || normalized === "1") {
+    enabled = true;
+  } else if (normalized === "disable" || normalized === "0") {
+    enabled = false;
+  } else {
+    streams.stderr.write(
+      `auto-update: invalid value "${rawState ?? ""}". Accepted values: enable, disable, 1, 0.
+`
+    );
+    return 1;
+  }
+  try {
+    const settings = loadCliSettings(options.home);
+    settings.autoUpdate = enabled;
+    saveCliSettings(settings, options.home);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    streams.stderr.write(`auto-update: failed to persist the setting: ${message}
+`);
+    return 1;
+  }
+  streams.stdout.write(enabled ? "Auto-update check enabled.\n" : "Auto-update check disabled.\n");
+  return 0;
+}
 function runInstallUninstallCommand(operation, options) {
   const streams = options.streams ?? { stdout: process.stdout, stderr: process.stderr };
   if (loadCliSettings(options.home).enabled.length === 0) {
@@ -2893,7 +3056,11 @@ function runInstallUninstallCommand(operation, options) {
   }
   let result;
   try {
-    result = operation === "install" ? installEnabledCliResources({ home: options.home, apiKey: options.apiKey, resourcesRoot: options.resourcesRoot }) : uninstallEnabledCliResources({ home: options.home, resourcesRoot: options.resourcesRoot });
+    result = operation === "install" ? installEnabledCliResources({
+      home: options.home,
+      resourcesRoot: options.resourcesRoot,
+      includeDebugSkills: options.includeDebugSkills === true
+    }) : uninstallEnabledCliResources({ home: options.home, resourcesRoot: options.resourcesRoot });
   } catch (error) {
     streams.stderr.write(
       JSON.stringify({ success: false, errors: [error instanceof Error ? error.message : String(error)] }, null, 2) + "\n"
@@ -2948,41 +3115,49 @@ if (isRunDirectly || isMainModule) {
       type: "string",
       description: "Hostname to bind the server to (default 127.0.0.1 loopback; 0.0.0.0 for all interfaces)",
       default: process.env.MCP_SERVER_HOST || "127.0.0.1"
-    }).option("apikey", {
-      alias: "k",
-      type: "string",
-      description: "Google Maps API key",
-      default: process.env.GOOGLE_MAPS_API_KEY
     }).option("stdio", {
       type: "boolean",
       description: "Use stdio transport instead of HTTP",
       default: false
     }).example([
       ["$0 start", "Start HTTP server with default settings"],
-      ['$0 start --port 3000 --apikey "your_api_key"', "Start HTTP with custom port and API key"],
       ["$0 start --host 0.0.0.0 --port 3000", "Start HTTP accessible from all interfaces"],
       ["$0 start --stdio", "Start in stdio mode (for MCP clients)"],
       ["$0 run --stdio", "Alias: run the server in stdio mode"]
     ]);
     const runServerCommand = async (argv) => {
-      if (argv.apikey) {
-        process.env.GOOGLE_MAPS_API_KEY = argv.apikey;
+      const effectiveApiKey = loadConfiguredApiKey();
+      ApiKeyManager.getInstance().setDefaultApiKey(effectiveApiKey);
+      if (loadCliSettings().autoUpdate) {
+        void checkVersionIdle({ currentVersion: packageVersion }).catch(() => void 0);
       }
-      void checkVersionIdle({ currentVersion: packageVersion }).catch(() => void 0);
       const tools = filterTools(config_default[0].tools);
       if (argv.stdio) {
+        if (effectiveApiKey === void 0) {
+          process.stderr.write(
+            JSON.stringify(
+              {
+                error: "Google Maps API key is not configured. Run 'mcp-google-map api-key <your-api-key>' to configure it."
+              },
+              null,
+              2
+            ) + "\n"
+          );
+          process.exitCode = 1;
+          return;
+        }
         const server = new BaseMcpServer(config_default[0].name, tools);
         await server.startStdio();
       } else {
         Logger.log("\u{1F5FA}\uFE0F  Google Maps MCP Server");
         Logger.log("   A Model Context Protocol server for Google Maps services");
         Logger.log("");
-        if (!argv.apikey) {
+        if (effectiveApiKey === void 0) {
           Logger.log("\u26A0\uFE0F  Google Maps API Key not found!");
-          Logger.log("   Please provide --apikey parameter or set GOOGLE_MAPS_API_KEY in your .env file");
+          Logger.log("   Run 'mcp-google-map api-key <your-api-key>' to configure it.");
           Logger.log("");
         }
-        startServer(argv.port, argv.apikey, argv.host).then((outcome) => {
+        startServer(argv.port, effectiveApiKey, argv.host).then((outcome) => {
           if (outcome.started === 0) {
             process.exit(1);
           }
@@ -3138,23 +3313,59 @@ Usage: mcp-google-map <command> [options]
           home: argv.home
         });
       }
+    ).command(
+      "auto-update <state>",
+      "Enable or disable the automatic update check in the persisted configuration",
+      (yargs2) => yargs2.positional("state", {
+        type: "string",
+        describe: "New state: enable or disable (1 and 0 accepted)"
+      }).option("home", {
+        type: "string",
+        description: "Home-directory override for the settings file (default: user home)"
+      }).example([[
+        "$0 auto-update disable",
+        "Disable the automatic update check in the persisted configuration"
+      ]]),
+      (argv) => {
+        process.exitCode = runAutoUpdateCommand(argv.state, {
+          home: argv.home
+        });
+      }
+    ).command(
+      "api-key <key>",
+      "Save the Google Maps API key in the user settings and refresh every enabled CLI registration",
+      (yargs2) => yargs2.positional("key", {
+        type: "string",
+        describe: "Google Maps API key (20-50 characters: letters, digits, hyphens, underscores)"
+      }).option("home", {
+        type: "string",
+        description: "Home-directory override for CLI configuration paths (default: user home)"
+      }).example([["$0 api-key AIzaSy...", "Save the key and reinstall every enabled CLI"]]),
+      (argv) => {
+        process.exitCode = runApiKeyCommand(argv.key, {
+          home: argv.home,
+          resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
+        });
+      }
     ).command(
       "install",
       "Register the mcp-google-map stdio server and install packaged skills for every enabled CLI",
       (yargs2) => yargs2.option("home", {
         type: "string",
         description: "Home-directory override for CLI configuration paths (default: user home)"
-      }).option("apikey", {
-        alias: "k",
-        type: "string",
-        description: "Google Maps API key embedded in the registered entry (prefer GOOGLE_MAPS_API_KEY)",
-        default: resolveRuntimeConfig(process.env, { envFile: extractEnvFileOption(process.argv) }).apiKey
-      }).example([["$0 install", "Register the server and skills in every enabled CLI"]]),
+      }).option("debug-skills", {
+        type: "boolean",
+        description: "Append each skill's packaged debug overlay to the installed SKILL.md",
+        default: false
+      }).example([
+        ["$0 install", "Register the server and skills in every enabled CLI"],
+        ["$0 install --debug-skills", "Also append the packaged debug overlay to every installed skill"]
+      ]),
       (argv) => {
         process.exitCode = runInstallUninstallCommand("install", {
           home: argv.home,
-          apiKey: argv.apikey,
-          resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
+          resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, "..")),
+          includeDebugSkills: argv.debugSkills === true
         });
       }
     ).command(
@@ -3193,11 +3404,6 @@ Usage: mcp-google-map <command> [options]
         }).positional("params", {
           type: "string",
           describe: "JSON parameters string"
-        }).option("apikey", {
-          alias: "k",
-          type: "string",
-          description: "Google Maps API key",
-          default: process.env.GOOGLE_MAPS_API_KEY
         }).example([
           [`$0 exec geocode '{"address":"Tokyo Tower"}'`, "Geocode an address"],
           [
@@ -3208,11 +3414,12 @@ Usage: mcp-google-map <command> [options]
         ]);
       },
       async (argv) => {
-        if (!argv.apikey) {
+        const apiKey = loadConfiguredApiKey();
+        if (!apiKey) {
           process.stderr.write(
             JSON.stringify(
               {
-                error: "GOOGLE_MAPS_API_KEY not set. Use --apikey or set GOOGLE_MAPS_API_KEY environment variable."
+                error: "Google Maps API key is not configured. Run 'mcp-google-map api-key <your-api-key>' to configure it."
               },
               null,
               2
@@ -3223,7 +3430,7 @@ Usage: mcp-google-map <command> [options]
         }
         try {
           const params = argv.params ? JSON.parse(argv.params) : {};
-          process.exitCode = await runExecCommand(argv.tool, params, argv.apikey);
+          process.exitCode = await runExecCommand(argv.tool, params, apiKey);
         } catch (error) {
           process.stderr.write(JSON.stringify({ error: error.message }, null, 2) + "\n");
           process.exitCode = 1;
@@ -3247,11 +3454,6 @@ Usage: mcp-google-map <command> [options]
           type: "number",
           describe: "Max parallel requests",
           default: 20
-        }).option("apikey", {
-          alias: "k",
-          type: "string",
-          description: "Google Maps API key",
-          default: process.env.GOOGLE_MAPS_API_KEY
         }).example([
           ["$0 batch-geocode -i addresses.txt", "Geocode to stdout"],
           ["$0 batch-geocode -i addresses.txt -o results.json", "Geocode to file"],
@@ -3259,8 +3461,9 @@ Usage: mcp-google-map <command> [options]
         ]);
       },
       async (argv) => {
-        if (!argv.apikey) {
-          console.error("Error: GOOGLE_MAPS_API_KEY not set. Use --apikey or set env var.");
+        const apiKey = loadConfiguredApiKey();
+        if (!apiKey) {
+          console.error("Error: Google Maps API key is not configured. Run 'mcp-google-map api-key <your-api-key>'.");
           process.exit(1);
         }
         let lines;
@@ -3282,7 +3485,7 @@ Usage: mcp-google-map <command> [options]
           console.error("Error: No addresses found in input.");
           process.exit(1);
         }
-        const searcher = new PlacesSearcher(argv.apikey);
+        const searcher = new PlacesSearcher(apiKey);
         const concurrency = Math.min(Math.max(argv.concurrency, 1), 50);
         const results = [];
         let completed = 0;
@@ -3365,6 +3568,8 @@ export {
   extractEnvFileOption,
   installShutdownHandlers,
   parseDoctorProbes,
+  runApiKeyCommand,
+  runAutoUpdateCommand,
   runDoctor,
   runEnableDisableCliCommand,
   runExecCommand,