mcp-google-map 0.9.0 → 0.10.0

package/README.md

@@ -1,4 +1,4 @@
-# mcp-google-map (0.9.0)
+# mcp-google-map (0.10.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/node-%3E%3D22-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js >= 22">
@@ -164,6 +164,7 @@ mcp-google-map doctor --live --probes geocoding,routes  # probe only the selecte
 mcp-google-map exec geocode '{"address":"Tokyo Tower"}' # one tool call from the terminal
 mcp-google-map batch-geocode -i addresses.txt -o results.json
 mcp-google-map enable pi claude                  # enable MCP registration + skills for specific CLIs
+mcp-google-map api-key "AIza..."                # save the API key in the user settings and refresh every enabled CLI registration
 mcp-google-map install                           # register the stdio server and install skills in every enabled CLI
 mcp-google-map uninstall                         # reciprocal removal of install in every enabled CLI
 mcp-google-map show                              # CLI Configuration and Installation Status tables
@@ -178,9 +179,10 @@ mcp-google-map snippet --client cursor                  # print an MCP client re
 - `snippet` prints a valid `mcpServers` JSON registration to stdout (guidance notes on stderr) and never writes or edits configuration files; by default it embeds a literal placeholder, and `--env-key NAME` emits a `${NAME}` reference whose expansion is client-specific.
 - `--env-file <path>` loads exactly the given environment file for any command and exits 1 with a JSON error when the file is missing (no implicit `.env` fallback).
 - `enable <cli>` / `disable <cli>` manage the persisted enabled-CLI set at `~/.config/mcp-google-map/config.json`; accepted names (case-insensitive): `pi`, `openclaw`, `codex`, `antigravity`, `claude`; unsupported names exit 2 listing the supported ones.
-- `install` registers for every enabled CLI the stdio server entry `mcp-google-map` (`npx -y mcp-google-map start --stdio`, embedding the resolved `GOOGLE_MAPS_API_KEY` when set) and installs every bundled skill; `uninstall` is the reciprocal removal. Per-CLI targets: pi `~/.pi/agent/mcp.json` + `~/.pi/agent/skills`, openclaw `~/.openclaw/openclaw.json` + `~/.openclaw/workspace/skills`, codex `~/.codex/config.toml` (`mcp_servers` table) + `~/.codex/skills`, antigravity `~/.gemini/settings.json` + `~/.gemini/config/skills`, claude `~/.claude.json` + `~/.claude/skills`. Existing unrelated configuration entries are always preserved.
+- `api-key <key>` validates the key (20-50 characters of letters, digits, hyphens, underscores), saves it as `apiKey` in the persisted settings at `~/.config/mcp-google-map/config.json` (masked in the JSON output), and immediately re-runs `install` for every enabled CLI; invalid keys fail with a JSON error and persist nothing.
+- `install` registers for every enabled CLI the stdio server entry `mcp-google-map` (`npx -y mcp-google-map start --stdio`) and installs every bundled skill; the embedded `GOOGLE_MAPS_API_KEY` is resolved with priority `--apikey`, the persisted `api-key` settings, then the `GOOGLE_MAPS_API_KEY` environment — when none resolves, a literal placeholder that names the `api-key` command is embedded instead; `uninstall` is the reciprocal removal. Per-CLI targets: pi `~/.pi/agent/mcp.json` + `~/.pi/agent/skills`, openclaw `~/.openclaw/openclaw.json` + `~/.openclaw/workspace/skills`, codex `~/.codex/config.toml` (`mcp_servers` table) + `~/.codex/skills`, antigravity `~/.gemini/settings.json` + `~/.gemini/config/skills`, claude `~/.claude.json` + `~/.claude/skills`. Existing unrelated configuration entries are always preserved.
 - `show` prints two human-readable tables: CLI Configuration (CLI, Enabled, MCP Config Path, Skills Config Path for all five CLIs) and Installation Status (Type, Name, CLI, Enabled, Installed with OK/MISSING/STALE per enabled CLI).
-- HTTP mode starts even without an API key and logs a warning; stdio mode and the CLI commands require a key (`--apikey` or `GOOGLE_MAPS_API_KEY`). When no HTTP instance can start (invalid or taken port), the process exits non-zero.
+- HTTP mode starts even without an API key and logs a warning (per-request header keys remain supported); stdio mode resolves the effective key with priority `--apikey`, `GOOGLE_MAPS_API_KEY`, then the persisted `api-key` settings, and exits 1 with a JSON error on stderr inviting `mcp-google-map api-key <key>` when no key resolves; the CLI commands require a key (`--apikey` or `GOOGLE_MAPS_API_KEY`). When no HTTP instance can start (invalid or taken port), the process exits non-zero.
 
 ## Registering in an MCP client
 

package/dist/cli.d.ts

@@ -138,6 +138,11 @@ declare function runEnableDisableCliCommand(name: string, enable: boolean, optio
     home?: string;
     streams?: ExecStreams;
 }): number;
+declare function runApiKeyCommand(key: string | undefined, options: {
+    home?: string;
+    resourcesRoot: string;
+    streams?: ExecStreams;
+}): number;
 declare function runInstallUninstallCommand(operation: "install" | "uninstall", options: {
     home?: string;
     apiKey?: string;
@@ -150,4 +155,4 @@ declare function runShowCommand(options: {
     streams?: ExecStreams;
 }): number;
 
-export { DOCTOR_PROBES, type DoctorCheck, type DoctorLiveProbe, type DoctorOptions, type DoctorProbeId, type DoctorProbesParseResult, type DoctorReport, EXEC_TOOLS, type ServerStartupOutcome, type SetupCheck, type SetupDeps, type SetupFs, type SetupOptions, type SetupReport, type ShutdownExitHook, createShutdownHandler, execTool, extractEnvFileOption, installShutdownHandlers, parseDoctorProbes, runDoctor, runEnableDisableCliCommand, runExecCommand, runInstallUninstallCommand, runSetup, runShowCommand, runSnippetCommand, startServer };
+export { DOCTOR_PROBES, type DoctorCheck, type DoctorLiveProbe, type DoctorOptions, type DoctorProbeId, type DoctorProbesParseResult, type DoctorReport, EXEC_TOOLS, type ServerStartupOutcome, type SetupCheck, type SetupDeps, type SetupFs, type SetupOptions, type SetupReport, type ShutdownExitHook, createShutdownHandler, execTool, extractEnvFileOption, installShutdownHandlers, parseDoctorProbes, runApiKeyCommand, runDoctor, runEnableDisableCliCommand, runExecCommand, runInstallUninstallCommand, runSetup, runShowCommand, runSnippetCommand, startServer };

package/dist/cli.js

@@ -1459,6 +1459,7 @@ 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 +1474,39 @@ 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: uniqueStrings(raw.enabled) };
+    const record = raw;
+    const settings = { enabled: uniqueStrings(record.enabled) };
+    if (typeof record.apiKey === "string" && record.apiKey.length > 0) {
+      settings.apiKey = record.apiKey;
+    }
+    return settings;
   } catch {
     return { enabled: [] };
   }
 }
+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) };
+  if (typeof settings.apiKey === "string" && settings.apiKey.length > 0) {
+    payload.apiKey = settings.apiKey;
+  }
   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)}`);
@@ -2169,12 +2186,21 @@ function applyServerRegistration(target, serverName, entry, home) {
 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;
-  }
+  const env = {
+    GOOGLE_MAPS_API_KEY: isUnsetApiKey(apiKey) ? INSTALL_API_KEY_PLACEHOLDER : apiKey
+  };
   return { command: "npx", args: ["-y", MCP_SERVER_NAME, "start", "--stdio"], env };
 }
+function resolveInstallApiKey(options) {
+  if (!isUnsetApiKey(options.flagKey)) {
+    return options.flagKey;
+  }
+  const persisted = loadConfiguredApiKey(options.home);
+  if (persisted !== void 0) {
+    return persisted;
+  }
+  return isUnsetApiKey(options.envKey) ? void 0 : options.envKey;
+}
 function resolveSkillsResourcesRoot(packageRoot) {
   const candidate = resolve3(packageRoot, "src", "resources", "skills");
   if (!existsSync3(candidate)) {
@@ -2874,6 +2900,68 @@ 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(
+      JSON.stringify(
+        {
+          success: false,
+          error: "Invalid Google Maps API key. Expected 20-50 characters of letters, digits, hyphens, or underscores. Usage: mcp-google-map api-key <your-api-key>"
+        },
+        null,
+        2
+      ) + "\n"
+    );
+    return 1;
+  }
+  let settingsPath;
+  try {
+    const settings = loadCliSettings(options.home);
+    settings.apiKey = trimmed;
+    settingsPath = saveCliSettings(settings, options.home);
+  } catch (error) {
+    streams.stderr.write(
+      JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }, null, 2) + "\n"
+    );
+    return 1;
+  }
+  let install;
+  try {
+    install = installEnabledCliResources({ home: options.home, apiKey: trimmed, resourcesRoot: options.resourcesRoot });
+  } catch (error) {
+    streams.stderr.write(
+      JSON.stringify(
+        {
+          success: false,
+          apiKey: maskSecret(trimmed),
+          settingsPath,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        null,
+        2
+      ) + "\n"
+    );
+    return 1;
+  }
+  const zeroEnabled = install.summaries.length === 0 && install.errors.length === 0;
+  streams.stdout.write(
+    JSON.stringify(
+      {
+        success: install.errors.length === 0,
+        command: "api-key",
+        apiKey: maskSecret(trimmed),
+        settingsPath,
+        ...zeroEnabled ? { message: "API key saved. No CLI enabled. Use 'mcp-google-map enable <cli name>' first." } : {},
+        install: { operation: "install", summaries: install.summaries, errors: install.errors }
+      },
+      null,
+      2
+    ) + "\n"
+  );
+  return install.errors.length > 0 ? 1 : 0;
+}
 function runInstallUninstallCommand(operation, options) {
   const streams = options.streams ?? { stdout: process.stdout, stderr: process.stderr };
   if (loadCliSettings(options.home).enabled.length === 0) {
@@ -2968,21 +3056,42 @@ if (isRunDirectly || isMainModule) {
       if (argv.apikey) {
         process.env.GOOGLE_MAPS_API_KEY = argv.apikey;
       }
+      let effectiveApiKey = isUnsetApiKey(process.env.GOOGLE_MAPS_API_KEY) ? void 0 : process.env.GOOGLE_MAPS_API_KEY;
+      if (effectiveApiKey === void 0) {
+        const persistedApiKey = loadConfiguredApiKey();
+        if (persistedApiKey !== void 0) {
+          process.env.GOOGLE_MAPS_API_KEY = persistedApiKey;
+          effectiveApiKey = persistedApiKey;
+        }
+      }
       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, or pass --apikey / set GOOGLE_MAPS_API_KEY."
+              },
+              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, or set GOOGLE_MAPS_API_KEY / pass --apikey");
           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,6 +3247,22 @@ Usage: mcp-google-map <command> [options]
           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",
@@ -3147,13 +3272,17 @@ Usage: mcp-google-map <command> [options]
       }).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
+        description: "Google Maps API key embedded in the registered entry (priority: this flag, persisted api-key settings, GOOGLE_MAPS_API_KEY)"
       }).example([["$0 install", "Register the server and skills in every enabled CLI"]]),
       (argv) => {
+        const config = resolveRuntimeConfig(process.env, { envFile: extractEnvFileOption(process.argv) });
         process.exitCode = runInstallUninstallCommand("install", {
           home: argv.home,
-          apiKey: argv.apikey,
+          apiKey: resolveInstallApiKey({
+            flagKey: argv.apikey,
+            envKey: config.apiKey,
+            home: argv.home
+          }),
           resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
         });
       }
@@ -3365,6 +3494,7 @@ export {
   extractEnvFileOption,
   installShutdownHandlers,
   parseDoctorProbes,
+  runApiKeyCommand,
   runDoctor,
   runEnableDisableCliCommand,
   runExecCommand,