mcp-google-map 0.5.0 → 0.7.0

package/dist/cli.js

@@ -19,6 +19,46 @@ 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());
@@ -40,54 +80,6 @@ function isNewerVersion(candidate, current) {
   }
   return false;
 }
-async function checkForUpdates(deps = {}) {
-  const logger = deps.logger ?? Logger;
-  const env = deps.env ?? process.env;
-  try {
-    if (isAutoUpdateDisabled(env)) {
-      return null;
-    }
-    const currentVersion = deps.currentVersion;
-    if (!currentVersion) {
-      logger.error(
-        `\u26A0\uFE0F  [${DEFAULT_PACKAGE_NAME}] Automatic update check skipped: running package version is unknown.`
-      );
-      return null;
-    }
-    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;
-    const response = await fetchImpl(`${registryBaseUrl}/${packageName}/latest`, {
-      headers: { accept: "application/vnd.npm.install-v1+json" },
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    if (!response.ok) {
-      logger.error(
-        `\u26A0\uFE0F  [${DEFAULT_PACKAGE_NAME}] Automatic update check failed: registry responded with HTTP ${response.status}.`
-      );
-      return null;
-    }
-    const payload = await response.json();
-    if (typeof payload?.version !== "string") {
-      logger.error(
-        `\u26A0\uFE0F  [${DEFAULT_PACKAGE_NAME}] Automatic update check failed: registry response has no version field.`
-      );
-      return null;
-    }
-    if (!isNewerVersion(payload.version, currentVersion)) {
-      return null;
-    }
-    logger.log(
-      `\u26A0\uFE0F  Update available: ${packageName} ${currentVersion} \u2192 ${payload.version}. Upgrade with: npm install -g ${packageName}@latest (or run npx -y ${packageName}@latest).`
-    );
-    return { currentVersion, latestVersion: payload.version };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    logger.error(`\u26A0\uFE0F  [${DEFAULT_PACKAGE_NAME}] Automatic update check failed: ${message}`);
-    return null;
-  }
-}
 
 // src/utils/configResolver.ts
 var NODE_ENGINE_FLOOR = 22;
@@ -1451,10 +1443,255 @@ var BaseMcpServer = class {
 
 // src/cli.ts
 import { fileURLToPath } from "url";
-import { dirname } from "path";
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync4 } from "fs";
+import { dirname as dirname2 } from "path";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync4, existsSync as existsSync4 } from "fs";
 import { createInterface } from "readline";
 
+// src/utils/upgradeManager.ts
+import { spawnSync } from "child_process";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir } from "os";
+import { dirname, join as join2 } from "path";
+
+// 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";
+function resolveCliSettingsPath(home) {
+  const root = home ?? (process.env.HOME ?? process.cwd());
+  return resolve(root, ...CLI_SETTINGS_RELATIVE);
+}
+function uniqueStrings(value) {
+  if (!Array.isArray(value)) return [];
+  const result = [];
+  for (const item of value) {
+    if (typeof item === "string" && item.length > 0 && !result.includes(item)) {
+      result.push(item);
+    }
+  }
+  return result;
+}
+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) };
+  } catch {
+    return { enabled: [] };
+  }
+}
+function saveCliSettings(settings, home) {
+  const path = resolveCliSettingsPath(home);
+  const temporary = `${path}.tmp`;
+  try {
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(temporary, JSON.stringify({ enabled: uniqueStrings(settings.enabled) }, null, 2) + "\n", "utf-8");
+    renameSync(temporary, path);
+  } catch (error) {
+    throw new Error(`settings write failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return path;
+}
+
+// src/utils/upgradeManager.ts
+var ANSI_GREEN = "\x1B[92m";
+var ANSI_RED = "\x1B[91m";
+var ANSI_RESET = "\x1B[0m";
+var green = (text) => `${ANSI_GREEN}${text}${ANSI_RESET}`;
+var red = (text) => `${ANSI_RED}${text}${ANSI_RESET}`;
+var IDLE_CACHE_DIR_NAME = "mcp-google-map";
+var IDLE_CACHE_FILE_NAME = "check_version_idle-time.json";
+var IDLE_WINDOW_NEWER_MS = 60 * 60 * 1e3;
+var IDLE_WINDOW_DEFAULT_MS = 24 * 60 * 60 * 1e3;
+var PACKAGE_UPGRADE_COMMAND = [
+  "npm",
+  "install",
+  "-g",
+  `${DEFAULT_PACKAGE_NAME}@latest`
+];
+var PACKAGE_UNINSTALL_COMMAND = [
+  "npm",
+  "uninstall",
+  "-g",
+  DEFAULT_PACKAGE_NAME
+];
+var POST_UPGRADE_INSTALL_COMMAND = [
+  "npx",
+  "-y",
+  DEFAULT_PACKAGE_NAME,
+  "install"
+];
+function resolveIdleCachePath(home) {
+  return join2(home ?? homedir(), ".cache", IDLE_CACHE_DIR_NAME, IDLE_CACHE_FILE_NAME);
+}
+function loadIdleCache(cachePath, fs = {}) {
+  try {
+    const readFile = fs.readFile ?? ((path) => readFileSync2(path, "utf-8"));
+    const raw = readFile(cachePath);
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) {
+      return {};
+    }
+    const record = parsed;
+    const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+    return {
+      last_success_epoch: isFiniteNumber(record.last_success_epoch) ? record.last_success_epoch : void 0,
+      last_success_human: typeof record.last_success_human === "string" ? record.last_success_human : void 0,
+      idle_time_epoch: isFiniteNumber(record.idle_time_epoch) ? record.idle_time_epoch : void 0,
+      idle_time_human: typeof record.idle_time_human === "string" ? record.idle_time_human : void 0
+    };
+  } catch {
+    return {};
+  }
+}
+function persistIdleCache(cachePath, lastSuccess, idleUntil, fs = {}, logger = Logger) {
+  const toIso = (epoch) => epoch === void 0 ? null : new Date(epoch).toISOString();
+  const data = {
+    last_success_epoch: lastSuccess ?? null,
+    last_success_human: toIso(lastSuccess),
+    idle_time_epoch: idleUntil,
+    idle_time_human: toIso(idleUntil)
+  };
+  try {
+    const mkdir = fs.mkdir ?? ((path) => mkdirSync2(path, { recursive: true }));
+    const writeFile = fs.writeFile ?? ((path, data2) => writeFileSync2(path, data2));
+    mkdir(dirname(cachePath));
+    writeFile(cachePath, JSON.stringify(data, null, 2) + "\n");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(red(`Version cache error: ${message}`));
+  }
+}
+async function checkVersionIdle(deps = {}) {
+  const logger = deps.logger ?? Logger;
+  const now = deps.now ?? (() => Date.now());
+  const cachePath = deps.cachePath ?? resolveIdleCachePath();
+  const cache = loadIdleCache(cachePath, deps.fs);
+  if (deps.force !== true) {
+    const idle = cache.idle_time_epoch;
+    if (typeof idle === "number" && idle > now()) {
+      return { checked: false, status: "idle" };
+    }
+  }
+  const probe = await probeLatestVersion(deps);
+  if (probe.status === "disabled") {
+    return { checked: false, status: "disabled" };
+  }
+  let delayMs = IDLE_WINDOW_DEFAULT_MS;
+  let lastSuccess = typeof cache.last_success_epoch === "number" ? cache.last_success_epoch : void 0;
+  const result = { checked: true, status: probe.status };
+  switch (probe.status) {
+    case "unknown-version":
+      logger.error(red("Version check error: running package version is unknown."));
+      break;
+    case "error":
+      logger.error(red(`Version check error: ${probe.message}`));
+      break;
+    case "current":
+      lastSuccess = now();
+      result.currentVersion = probe.currentVersion;
+      break;
+    case "newer": {
+      lastSuccess = now();
+      delayMs = IDLE_WINDOW_NEWER_MS;
+      result.currentVersion = probe.currentVersion;
+      result.latestVersion = probe.latestVersion;
+      logger.log(
+        green(
+          `Available Version: ${probe.latestVersion} | Installed Version: ${probe.currentVersion}`
+        )
+      );
+      logger.log(
+        green(
+          `Upgrade with: npm install -g ${DEFAULT_PACKAGE_NAME}@latest (or run: ${DEFAULT_PACKAGE_NAME} --upgrade)`
+        )
+      );
+      break;
+    }
+  }
+  const finishedAt = now();
+  const idleUntil = finishedAt + delayMs;
+  persistIdleCache(cachePath, lastSuccess, idleUntil, deps.fs, logger);
+  result.idleUntilEpoch = idleUntil;
+  result.lastSuccessEpoch = lastSuccess;
+  return result;
+}
+function parseManagementCommand(args) {
+  if (args.length !== 1) {
+    return void 0;
+  }
+  const arg = args[0];
+  if (arg === "--ver" || arg === "--version" || arg === "--upgrade" || arg === "--uninstall") {
+    return arg;
+  }
+  return void 0;
+}
+function runPackageManagerCommand(command, deps = {}) {
+  const logger = deps.logger ?? Logger;
+  const spawnImpl = deps.spawn ?? spawnSync;
+  const reportSpawnFailure = (message) => {
+    logger.error(`Error executing ${command[0]}: ${message}`);
+    logger.log(`Warning: run this command manually: ${command.join(" ")}`);
+    return 1;
+  };
+  try {
+    const result = spawnImpl(command[0], [...command.slice(1)], {
+      stdio: "inherit",
+      shell: process.platform === "win32"
+    });
+    if (result.error) {
+      return reportSpawnFailure(result.error.message);
+    }
+    return result.status ?? 1;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return reportSpawnFailure(message);
+  }
+}
+function runPostUpgradeSkillInstall(options, deps = {}) {
+  const enabled = loadCliSettings(options.home).enabled;
+  if (enabled.length === 0) {
+    return 0;
+  }
+  return runPackageManagerCommand(POST_UPGRADE_INSTALL_COMMAND, deps);
+}
+async function runVersionCommand(options, deps = {}) {
+  await checkVersionIdle({
+    ...deps.idleCheck,
+    force: true,
+    currentVersion: options.currentVersion
+  });
+  const stdout = deps.stdout ?? process.stdout;
+  stdout.write(`${options.currentVersion}
+`);
+  return 0;
+}
+function runUpgradeCommand(options, deps = {}) {
+  const upgraded = runPackageManagerCommand(PACKAGE_UPGRADE_COMMAND, deps);
+  if (upgraded !== 0) {
+    return upgraded;
+  }
+  return runPostUpgradeSkillInstall(options, deps);
+}
+function runUninstallCommand(deps = {}) {
+  return runPackageManagerCommand(PACKAGE_UNINSTALL_COMMAND, deps);
+}
+async function runManagementCommand(command, options, deps = {}) {
+  switch (command) {
+    case "--ver":
+    case "--version":
+      return runVersionCommand(options, deps);
+    case "--upgrade":
+      return runUpgradeCommand(options, deps);
+    case "--uninstall":
+      return runUninstallCommand(deps);
+  }
+}
+
 // src/utils/toolProfiles.ts
 var TOOL_API_PROFILES = {
   maps_geocode: { tool: "maps_geocode", apis: ["geocoding"], dependsOnTools: [] },
@@ -1550,14 +1787,14 @@ function renderClientSnippet(options = {}) {
     const host = options.host ?? SNIPPET_DEFAULT_HOST;
     const port = options.port ?? SNIPPET_DEFAULT_PORT;
     entry = { url: `http://${host}:${port}/mcp` };
-    notes.push(`Start the server first: mcp-google-map --host ${host} --port ${port}.`);
+    notes.push(`Start the server first: mcp-google-map start --host ${host} --port ${port}.`);
   } else {
     const launcher = options.launcher ?? "npx";
     if (launcher === "node" && !options.commandPath) {
       throw new Error("--launcher node requires --command <path> pointing at dist/cli.js");
     }
     const command = launcher === "npx" ? "npx" : launcher === "bin" ? "mcp-google-map" : "node";
-    const args = launcher === "npx" ? ["-y", "mcp-google-map", "--stdio"] : launcher === "bin" ? ["--stdio"] : [options.commandPath, "--stdio"];
+    const args = launcher === "npx" ? ["-y", "mcp-google-map", "start", "--stdio"] : launcher === "bin" ? ["start", "--stdio"] : [options.commandPath, "start", "--stdio"];
     if (launcher === "npx") {
       notes.push("The npx launcher runs the published package; npm must be available on PATH.");
     }
@@ -1575,95 +1812,51 @@ function renderClientSnippet(options = {}) {
   return { json, notes };
 }
 
-// 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";
-function resolveCliSettingsPath(home) {
-  const root = home ?? (process.env.HOME ?? process.cwd());
-  return resolve(root, ...CLI_SETTINGS_RELATIVE);
-}
-function uniqueStrings(value) {
-  if (!Array.isArray(value)) return [];
-  const result = [];
-  for (const item of value) {
-    if (typeof item === "string" && item.length > 0 && !result.includes(item)) {
-      result.push(item);
-    }
-  }
-  return result;
-}
-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) };
-  } catch {
-    return { enabled: [] };
-  }
-}
-function saveCliSettings(settings, home) {
-  const path = resolveCliSettingsPath(home);
-  const temporary = `${path}.tmp`;
-  try {
-    mkdirSync(join(path, ".."), { recursive: true });
-    writeFileSync(temporary, JSON.stringify({ enabled: uniqueStrings(settings.enabled) }, null, 2) + "\n", "utf-8");
-    renameSync(temporary, path);
-  } catch (error) {
-    throw new Error(`settings write failed: ${error instanceof Error ? error.message : String(error)}`);
-  }
-  return path;
-}
-
 // src/utils/cliTargets.ts
 import {
   cpSync,
   existsSync as existsSync2,
-  mkdirSync as mkdirSync2,
-  readFileSync as readFileSync2,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync3,
   readdirSync,
   renameSync as renameSync2,
   rmSync,
   statSync,
-  writeFileSync as writeFileSync2
+  writeFileSync as writeFileSync3
 } from "fs";
-import { join as join2, relative } from "path";
+import { join as join3, relative } from "path";
 function homeRoot(home) {
   return home ?? (process.env.HOME ?? process.cwd());
 }
 var PI_TARGET = {
   id: "pi",
   configFormat: "json",
-  mcpConfigPath: (home) => join2(homeRoot(home), ".pi", "agent", "mcp.json"),
-  skillsDir: (home) => join2(homeRoot(home), ".pi", "agent", "skills")
+  mcpConfigPath: (home) => join3(homeRoot(home), ".pi", "agent", "mcp.json"),
+  skillsDir: (home) => join3(homeRoot(home), ".pi", "agent", "skills")
 };
 var OPENCLAW_TARGET = {
   id: "openclaw",
   configFormat: "json",
-  mcpConfigPath: (home) => join2(homeRoot(home), ".openclaw", "openclaw.json"),
-  skillsDir: (home) => join2(homeRoot(home), ".openclaw", "workspace", "skills")
+  mcpConfigPath: (home) => join3(homeRoot(home), ".openclaw", "openclaw.json"),
+  skillsDir: (home) => join3(homeRoot(home), ".openclaw", "workspace", "skills")
 };
 var CODEX_TARGET = {
   id: "codex",
   configFormat: "toml",
-  mcpConfigPath: (home) => join2(homeRoot(home), ".codex", "config.toml"),
-  skillsDir: (home) => join2(homeRoot(home), ".codex", "skills")
+  mcpConfigPath: (home) => join3(homeRoot(home), ".codex", "config.toml"),
+  skillsDir: (home) => join3(homeRoot(home), ".codex", "skills")
 };
 var ANTIGRAVITY_TARGET = {
   id: "antigravity",
   configFormat: "json",
-  mcpConfigPath: (home) => join2(homeRoot(home), ".gemini", "settings.json"),
-  skillsDir: (home) => join2(homeRoot(home), ".gemini", "config", "skills")
+  mcpConfigPath: (home) => join3(homeRoot(home), ".gemini", "settings.json"),
+  skillsDir: (home) => join3(homeRoot(home), ".gemini", "config", "skills")
 };
 var CLAUDE_TARGET = {
   id: "claude",
   configFormat: "json",
-  mcpConfigPath: (home) => join2(homeRoot(home), ".claude.json"),
-  skillsDir: (home) => join2(homeRoot(home), ".claude", "skills")
+  mcpConfigPath: (home) => join3(homeRoot(home), ".claude.json"),
+  skillsDir: (home) => join3(homeRoot(home), ".claude", "skills")
 };
 var CLI_TARGETS = {
   pi: PI_TARGET,
@@ -1680,7 +1873,7 @@ function supportedCliNames() {
 }
 function readJsonConfig(configPath) {
   if (!existsSync2(configPath)) return {};
-  const parsed = JSON.parse(readFileSync2(configPath, "utf-8"));
+  const parsed = JSON.parse(readFileSync3(configPath, "utf-8"));
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(`configuration is not a JSON object: ${configPath}`);
   }
@@ -1688,8 +1881,8 @@ function readJsonConfig(configPath) {
 }
 function writeJsonConfig(configPath, value) {
   const temporary = `${configPath}.tmp`;
-  mkdirSync2(join2(configPath, ".."), { recursive: true });
-  writeFileSync2(temporary, JSON.stringify(value, null, 2) + "\n", "utf-8");
+  mkdirSync3(join3(configPath, ".."), { recursive: true });
+  writeFileSync3(temporary, JSON.stringify(value, null, 2) + "\n", "utf-8");
   renameSync2(temporary, configPath);
 }
 function writeJsonMcpServerEntry(configPath, serverName, entry) {
@@ -1776,35 +1969,35 @@ function registrationToTomlLines(entry) {
   return lines;
 }
 function writeTomlMcpServerSection(configPath, serverName, entry) {
-  const previous = existsSync2(configPath) ? readFileSync2(configPath, "utf-8") : "";
+  const previous = existsSync2(configPath) ? readFileSync3(configPath, "utf-8") : "";
   const base = removeTomlSection(previous, serverName);
   const table = [tomlSectionHeader(serverName), ...registrationToTomlLines(entry), ""].join("\n");
   const content = base.length > 0 ? base.replace(/\n*$/, "\n") + table : table;
   const temporary = `${configPath}.tmp`;
-  mkdirSync2(join2(configPath, ".."), { recursive: true });
-  writeFileSync2(temporary, content, "utf-8");
+  mkdirSync3(join3(configPath, ".."), { recursive: true });
+  writeFileSync3(temporary, content, "utf-8");
   renameSync2(temporary, configPath);
 }
 function removeTomlMcpServerSection(configPath, serverName) {
   if (!existsSync2(configPath)) return false;
-  const previous = readFileSync2(configPath, "utf-8");
+  const previous = readFileSync3(configPath, "utf-8");
   if (!hasTomlSection(previous, serverName)) return false;
   const content = removeTomlSection(previous, serverName);
   const temporary = `${configPath}.tmp`;
-  writeFileSync2(temporary, content, "utf-8");
+  writeFileSync3(temporary, content, "utf-8");
   renameSync2(temporary, configPath);
   return true;
 }
 function hasTomlMcpServerSection(configPath, serverName) {
   if (!existsSync2(configPath)) return false;
-  return hasTomlSection(readFileSync2(configPath, "utf-8"), serverName);
+  return hasTomlSection(readFileSync3(configPath, "utf-8"), serverName);
 }
 function listFilesRecursive(root) {
   if (!existsSync2(root)) return [];
   const files = [];
   const walk = (dir) => {
     for (const entry of readdirSync(dir)) {
-      const full = join2(dir, entry);
+      const full = join3(dir, entry);
       if (statSync(full).isDirectory()) {
         walk(full);
       } else {
@@ -1816,14 +2009,14 @@ function listFilesRecursive(root) {
   return files;
 }
 function syncSkillTree(source, destination) {
-  mkdirSync2(destination, { recursive: true });
+  mkdirSync3(destination, { recursive: true });
   cpSync(source, destination, { recursive: true, force: true });
   const expected = new Set(listFilesRecursive(source));
   const existing = listFilesRecursive(destination);
   existing.sort((a, b) => b.length - a.length);
   for (const rel of existing) {
     if (expected.has(rel)) continue;
-    rmSync(join2(destination, rel), { recursive: true, force: true });
+    rmSync(join3(destination, rel), { recursive: true, force: true });
   }
 }
 function removeSkillDir(skillDir) {
@@ -1834,9 +2027,9 @@ function compareSkillTree(source, destination) {
   if (packaged.length === 0) return "MISSING";
   if (!existsSync2(destination)) return "MISSING";
   for (const rel of packaged) {
-    const target = join2(destination, ...rel.split("/"));
+    const target = join3(destination, ...rel.split("/"));
     if (!existsSync2(target)) return "MISSING";
-    if (readFileSync2(target).toString("utf-8") !== readFileSync2(join2(source, ...rel.split("/"))).toString("utf-8")) {
+    if (readFileSync3(target).toString("utf-8") !== readFileSync3(join3(source, ...rel.split("/"))).toString("utf-8")) {
       return "STALE";
     }
   }
@@ -1867,14 +2060,14 @@ function applyServerRegistration(target, serverName, entry, home) {
 }
 
 // src/utils/cliInstaller.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
-import { join as join3, resolve as resolve3 } from "path";
+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, "--stdio"], env };
+  return { command: "npx", args: ["-y", MCP_SERVER_NAME, "start", "--stdio"], env };
 }
 function resolveSkillsResourcesRoot(packageRoot) {
   const candidate = resolve3(packageRoot, "src", "resources", "skills");
@@ -1884,13 +2077,13 @@ function resolveSkillsResourcesRoot(packageRoot) {
   return candidate;
 }
 function loadSkillsManifest(resourcesRoot) {
-  const manifestPath = join3(resourcesRoot, "manifest.json");
+  const manifestPath = join4(resourcesRoot, "manifest.json");
   if (!existsSync3(manifestPath)) {
     throw new Error(`skills manifest not found: ${manifestPath}`);
   }
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync3(manifestPath, "utf-8"));
+    parsed = JSON.parse(readFileSync4(manifestPath, "utf-8"));
   } catch (error) {
     throw new Error(`skills manifest is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
   }
@@ -1903,8 +2096,8 @@ 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(join3(resourcesRoot, skill.path))) {
-      throw new Error(`manifest skill file not found: ${join3(resourcesRoot, skill.path)}`);
+    if (!existsSync3(join4(resourcesRoot, skill.path))) {
+      throw new Error(`manifest skill file not found: ${join4(resourcesRoot, skill.path)}`);
     }
     return {
       id: skill.id,
@@ -1929,7 +2122,7 @@ function installEnabledCliResources(options) {
       applyServerRegistration(target, MCP_SERVER_NAME, entry, options.home);
       let skills = 0;
       for (const skill of manifest) {
-        syncSkillTree(join3(options.resourcesRoot, skill.id), join3(target.skillsDir(options.home), skill.id));
+        syncSkillTree(join4(options.resourcesRoot, skill.id), join4(target.skillsDir(options.home), skill.id));
         skills += 1;
       }
       result.summaries.push({ cli: target.id, server: 1, skills });
@@ -1952,7 +2145,7 @@ function uninstallEnabledCliResources(options) {
       applyServerRegistration(target, MCP_SERVER_NAME, void 0, options.home);
       let skills = 0;
       for (const skill of manifest) {
-        removeSkillDir(join3(target.skillsDir(options.home), skill.id));
+        removeSkillDir(join4(target.skillsDir(options.home), skill.id));
         skills += 1;
       }
       result.summaries.push({ cli: target.id, server: 0, skills });
@@ -1964,7 +2157,7 @@ function uninstallEnabledCliResources(options) {
 }
 
 // src/utils/cliShow.ts
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { relative as relative2, resolve as resolve4 } from "path";
 var MAX_CELL_WIDTH = 48;
 var STATUS_OK = "OK";
@@ -2051,7 +2244,7 @@ function buildInstallRows(home, resourcesRoot) {
         skill.id,
         target.id,
         "yes",
-        compareSkillTree(join4(resourcesRoot, skill.id), join4(target.skillsDir(home), skill.id))
+        compareSkillTree(join5(resourcesRoot, skill.id), join5(target.skillsDir(home), skill.id))
       ]);
     }
   }
@@ -2069,7 +2262,7 @@ function buildCliShowReport(options) {
 
 // src/cli.ts
 var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname(__filename);
+var __dirname = dirname2(__filename);
 function extractEnvFileOption(argv) {
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -2466,8 +2659,8 @@ async function runDoctor(packageVersion, apiKey, live = false, runner = execTool
 async function runSetup(options, deps = {}) {
   const fsImpl = deps.fs ?? {
     existsSync: (path) => existsSync4(path),
-    readFileSync: (path, encoding) => readFileSync4(path, encoding),
-    writeFileSync: (path, data, encoding) => writeFileSync3(path, data, encoding)
+    readFileSync: (path, encoding) => readFileSync5(path, encoding),
+    writeFileSync: (path, data, encoding) => writeFileSync4(path, data, encoding)
   };
   const nodeVersion = deps.nodeVersion ?? process.versions.node;
   const nodeMajor = Number.parseInt(nodeVersion.split(".")[0] ?? "0", 10);
@@ -2625,402 +2818,438 @@ if (isRunDirectly || isMainModule) {
   let packageVersion = "0.0.0";
   try {
     const packageJsonPath = resolve5(__dirname, "../package.json");
-    const packageJson = JSON.parse(readFileSync4(packageJsonPath, "utf-8"));
+    const packageJson = JSON.parse(readFileSync5(packageJsonPath, "utf-8"));
     packageVersion = packageJson.version;
   } catch (e) {
     packageVersion = "0.0.0";
   }
-  yargs(hideBin(process.argv)).command(
-    "doctor",
-    "Check standalone CLI readiness without starting an MCP server",
-    (yargs2) => yargs2.option("live", {
-      type: "boolean",
-      default: false,
-      description: "Make billable test requests to Geocoding, Places (New), and Routes APIs"
-    }).option("probes", {
+  const managementCommand = parseManagementCommand(hideBin(process.argv));
+  if (managementCommand !== void 0) {
+    void runManagementCommand(managementCommand, { currentVersion: packageVersion }).then((code) => {
+      process.exitCode = code;
+    }).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      process.stderr.write(JSON.stringify({ error: message }, null, 2) + "\n");
+      process.exitCode = 1;
+    });
+  } else {
+    const buildServerCommandOptions = (yargs2) => yargs2.option("port", {
+      alias: "p",
+      type: "number",
+      description: "Port to run the MCP server on",
+      default: process.env.MCP_SERVER_PORT ? parseInt(process.env.MCP_SERVER_PORT) : 3e3
+    }).option("host", {
       type: "string",
-      description: "Comma-separated subset of live probes: geocoding, places-new, routes (default: all three)"
+      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 (prefer GOOGLE_MAPS_API_KEY to avoid shell history exposure)",
+      description: "Google Maps API key",
       default: process.env.GOOGLE_MAPS_API_KEY
-    }).example([
-      ["$0 doctor", "Check local runtime and API key configuration without network calls"],
-      ["$0 doctor --live", "Also verify three Google Maps APIs with billable requests"],
-      ["$0 doctor --live --probes geocoding,routes", "Probe only the selected APIs"]
-    ]),
-    async (argv) => {
-      const parsedProbes = parseDoctorProbes(argv.probes);
-      if (parsedProbes.error) {
-        process.stderr.write(JSON.stringify({ error: parsedProbes.error }, null, 2) + "\n");
-        process.exitCode = 1;
-        return;
-      }
-      const report = await runDoctor(packageVersion, argv.apikey, argv.live, void 0, {
-        probes: parsedProbes.probes,
-        config: resolveRuntimeConfig(process.env, { envFile: extractEnvFileOption(process.argv) })
-      });
-      process.stdout.write(JSON.stringify(report, null, 2) + "\n");
-      process.exitCode = report.success ? 0 : 1;
-    }
-  ).command(
-    "setup",
-    "Non-interactive onboarding: verify local readiness, optionally scaffold .env",
-    (yargs2) => yargs2.option("write-env", {
+    }).option("stdio", {
       type: "boolean",
-      default: false,
-      description: "Create .env from .env.example in --env-dir when it does not exist (never overwrites)"
-    }).option("env-dir", {
-      type: "string",
-      default: process.cwd(),
-      description: "Directory where .env is looked up / created"
-    }).example([
-      ["$0 setup", "Check readiness without writing anything"],
-      ["$0 setup --write-env", "Also scaffold .env from the package template"]
-    ]),
-    async (argv) => {
-      const report = await runSetup({
-        packageDir: resolve5(__dirname, ".."),
-        targetDir: argv.envDir,
-        writeEnv: argv.writeEnv
-      });
-      process.stdout.write(JSON.stringify(report, null, 2) + "\n");
-      process.exitCode = report.success ? 0 : 1;
-    }
-  ).command(
-    "snippet",
-    "Print an MCP client registration snippet (JSON on stdout; never writes files)",
-    (yargs2) => yargs2.option("client", {
-      type: "string",
-      choices: ["generic", "claude", "cursor", "pi"],
-      default: "generic",
-      description: "Target client (selects the documented target file)"
-    }).option("transport", {
-      type: "string",
-      choices: ["stdio", "http"],
-      default: "stdio",
-      description: "MCP transport of the snippet"
-    }).option("launcher", {
-      type: "string",
-      choices: ["npx", "node", "bin"],
-      default: "npx",
-      description: "stdio launcher command"
-    }).option("command", {
-      type: "string",
-      description: "Absolute path to dist/cli.js (required for --launcher node)"
-    }).option("host", {
-      type: "string",
-      default: "127.0.0.1",
-      description: "Host used in the URL (transport http)"
-    }).option("port", {
-      type: "number",
-      default: 3e3,
-      description: "Port used in the URL (transport http)"
-    }).option("env-key", {
-      type: "string",
-      description: "Emit a ${NAME} variable reference instead of a literal placeholder (expansion is client-specific)"
-    }).option("name", {
-      type: "string",
-      default: "mcp-google-map",
-      description: "Server name inside mcpServers"
+      description: "Use stdio transport instead of HTTP",
+      default: false
     }).example([
-      ["$0 snippet --client claude", "stdio snippet using the npx launcher"],
-      ["$0 snippet --client pi --launcher node --command /abs/path/dist/cli.js", "stdio snippet with an explicit artifact"],
-      ["$0 snippet --transport http --port 3100", "HTTP URL snippet"]
-    ]),
-    (argv) => {
-      process.exitCode = runSnippetCommand({
-        client: argv.client,
-        transport: argv.transport,
-        launcher: argv.launcher,
-        commandPath: argv.command,
-        host: argv.host,
-        port: argv.port,
-        envKey: argv.envKey,
-        serverName: argv.name
-      });
-    }
-  ).command(
-    "enable <cli>",
-    "Enable MCP-server and skill installation for a supported CLI",
-    (yargs2) => yargs2.positional("cli", {
-      type: "string",
-      describe: `CLI name: ${supportedCliNames()}`
-    }).option("home", {
-      type: "string",
-      description: "Home-directory override for the settings file (default: user home)"
-    }).example([["$0 enable pi", "Enable pi for install/uninstall/show"]]),
-    (argv) => {
-      process.exitCode = runEnableDisableCliCommand(argv.cli, true, {
-        home: argv.home
-      });
-    }
-  ).command(
-    "disable <cli>",
-    "Disable MCP-server and skill installation for a supported CLI",
-    (yargs2) => yargs2.positional("cli", {
-      type: "string",
-      describe: `CLI name: ${supportedCliNames()}`
-    }).option("home", {
-      type: "string",
-      description: "Home-directory override for the settings file (default: user home)"
-    }).example([["$0 disable claude", "Disable claude for install/uninstall/show"]]),
-    (argv) => {
-      process.exitCode = runEnableDisableCliCommand(argv.cli, false, {
-        home: argv.home
-      });
-    }
-  ).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"]]),
-    (argv) => {
-      process.exitCode = runInstallUninstallCommand("install", {
-        home: argv.home,
-        apiKey: argv.apikey,
-        resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
-      });
-    }
-  ).command(
-    "uninstall",
-    "Remove the mcp-google-map server entry and managed skills from every enabled CLI",
-    (yargs2) => yargs2.option("home", {
-      type: "string",
-      description: "Home-directory override for CLI configuration paths (default: user home)"
-    }).example([["$0 uninstall", "Reciprocal removal of install for every enabled CLI"]]),
-    (argv) => {
-      process.exitCode = runInstallUninstallCommand("uninstall", {
-        home: argv.home,
-        resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
-      });
-    }
-  ).command(
-    "show",
-    "Show CLI configuration and installation status tables (human-readable)",
-    (yargs2) => yargs2.option("home", {
-      type: "string",
-      description: "Home-directory override for CLI configuration paths (default: user home)"
-    }).example([["$0 show", "Print CLI Configuration and Installation Status tables"]]),
-    (argv) => {
-      process.exitCode = runShowCommand({
-        home: argv.home,
-        resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
-      });
-    }
-  ).command(
-    "exec <tool> [params]",
-    "Execute a tool directly and output JSON",
-    (yargs2) => {
-      return yargs2.positional("tool", {
-        type: "string",
-        describe: `Tool name: ${EXEC_TOOLS.join(", ")}`
-      }).positional("params", {
+      ["$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;
+      }
+      void checkVersionIdle({ currentVersion: packageVersion }).catch(() => void 0);
+      const tools = filterTools(config_default[0].tools);
+      if (argv.stdio) {
+        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) {
+          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("");
+        }
+        startServer(argv.port, argv.apikey, argv.host).then((outcome) => {
+          if (outcome.started === 0) {
+            process.exit(1);
+          }
+        }).catch((error) => {
+          Logger.error("\u274C Failed to start server:", error);
+          process.exit(1);
+        });
+      }
+    };
+    const cli = yargs(hideBin(process.argv)).scriptName("mcp-google-map").usage(
+      `mcp-google-map v${packageVersion}
+
+Usage: mcp-google-map <command> [options]
+       mcp-google-map start|run [--stdio] [options]`
+    ).command(
+      "doctor",
+      "Check standalone CLI readiness without starting an MCP server",
+      (yargs2) => yargs2.option("live", {
+        type: "boolean",
+        default: false,
+        description: "Make billable test requests to Geocoding, Places (New), and Routes APIs"
+      }).option("probes", {
         type: "string",
-        describe: "JSON parameters string"
+        description: "Comma-separated subset of live probes: geocoding, places-new, routes (default: all three)"
       }).option("apikey", {
         alias: "k",
         type: "string",
-        description: "Google Maps API key",
+        description: "Google Maps API key (prefer GOOGLE_MAPS_API_KEY to avoid shell history exposure)",
         default: process.env.GOOGLE_MAPS_API_KEY
       }).example([
-        [`$0 exec geocode '{"address":"Tokyo Tower"}'`, "Geocode an address"],
-        [
-          `$0 exec search-nearby '{"center":{"value":"35.68,139.74","isCoordinates":true},"keyword":"restaurant"}'`,
-          "Search nearby"
-        ],
-        [`$0 exec search-places '{"query":"ramen in Tokyo"}'`, "Text search"]
-      ]);
-    },
-    async (argv) => {
-      if (!argv.apikey) {
-        process.stderr.write(
-          JSON.stringify(
-            {
-              error: "GOOGLE_MAPS_API_KEY not set. Use --apikey or set GOOGLE_MAPS_API_KEY environment variable."
-            },
-            null,
-            2
-          ) + "\n"
-        );
-        process.exitCode = 1;
-        return;
+        ["$0 doctor", "Check local runtime and API key configuration without network calls"],
+        ["$0 doctor --live", "Also verify three Google Maps APIs with billable requests"],
+        ["$0 doctor --live --probes geocoding,routes", "Probe only the selected APIs"]
+      ]),
+      async (argv) => {
+        const parsedProbes = parseDoctorProbes(argv.probes);
+        if (parsedProbes.error) {
+          process.stderr.write(JSON.stringify({ error: parsedProbes.error }, null, 2) + "\n");
+          process.exitCode = 1;
+          return;
+        }
+        const report = await runDoctor(packageVersion, argv.apikey, argv.live, void 0, {
+          probes: parsedProbes.probes,
+          config: resolveRuntimeConfig(process.env, { envFile: extractEnvFileOption(process.argv) })
+        });
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        process.exitCode = report.success ? 0 : 1;
       }
-      try {
-        const params = argv.params ? JSON.parse(argv.params) : {};
-        process.exitCode = await runExecCommand(argv.tool, params, argv.apikey);
-      } catch (error) {
-        process.stderr.write(JSON.stringify({ error: error.message }, null, 2) + "\n");
-        process.exitCode = 1;
+    ).command(
+      "setup",
+      "Non-interactive onboarding: verify local readiness, optionally scaffold .env",
+      (yargs2) => yargs2.option("write-env", {
+        type: "boolean",
+        default: false,
+        description: "Create .env from .env.example in --env-dir when it does not exist (never overwrites)"
+      }).option("env-dir", {
+        type: "string",
+        default: process.cwd(),
+        description: "Directory where .env is looked up / created"
+      }).example([
+        ["$0 setup", "Check readiness without writing anything"],
+        ["$0 setup --write-env", "Also scaffold .env from the package template"]
+      ]),
+      async (argv) => {
+        const report = await runSetup({
+          packageDir: resolve5(__dirname, ".."),
+          targetDir: argv.envDir,
+          writeEnv: argv.writeEnv
+        });
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        process.exitCode = report.success ? 0 : 1;
       }
-    }
-  ).command(
-    "batch-geocode",
-    "Geocode multiple addresses from a file (one address per line)",
-    (yargs2) => {
-      return yargs2.option("input", {
-        alias: "i",
+    ).command(
+      "snippet",
+      "Print an MCP client registration snippet (JSON on stdout; never writes files)",
+      (yargs2) => yargs2.option("client", {
+        type: "string",
+        choices: ["generic", "claude", "cursor", "pi"],
+        default: "generic",
+        description: "Target client (selects the documented target file)"
+      }).option("transport", {
+        type: "string",
+        choices: ["stdio", "http"],
+        default: "stdio",
+        description: "MCP transport of the snippet"
+      }).option("launcher", {
         type: "string",
-        describe: "Input file path (one address per line). Use - for stdin.",
-        demandOption: true
-      }).option("output", {
-        alias: "o",
+        choices: ["npx", "node", "bin"],
+        default: "npx",
+        description: "stdio launcher command"
+      }).option("command", {
         type: "string",
-        describe: "Output file path (JSON). Defaults to stdout."
-      }).option("concurrency", {
-        alias: "c",
+        description: "Absolute path to dist/cli.js (required for --launcher node)"
+      }).option("host", {
+        type: "string",
+        default: "127.0.0.1",
+        description: "Host used in the URL (transport http)"
+      }).option("port", {
         type: "number",
-        describe: "Max parallel requests",
-        default: 20
+        default: 3e3,
+        description: "Port used in the URL (transport http)"
+      }).option("env-key", {
+        type: "string",
+        description: "Emit a ${NAME} variable reference instead of a literal placeholder (expansion is client-specific)"
+      }).option("name", {
+        type: "string",
+        default: "mcp-google-map",
+        description: "Server name inside mcpServers"
+      }).example([
+        ["$0 snippet --client claude", "stdio snippet using the npx launcher"],
+        ["$0 snippet --client pi --launcher node --command /abs/path/dist/cli.js", "stdio snippet with an explicit artifact"],
+        ["$0 snippet --transport http --port 3100", "HTTP URL snippet"]
+      ]),
+      (argv) => {
+        process.exitCode = runSnippetCommand({
+          client: argv.client,
+          transport: argv.transport,
+          launcher: argv.launcher,
+          commandPath: argv.command,
+          host: argv.host,
+          port: argv.port,
+          envKey: argv.envKey,
+          serverName: argv.name
+        });
+      }
+    ).command(
+      "enable <cli>",
+      "Enable MCP-server and skill installation for a supported CLI",
+      (yargs2) => yargs2.positional("cli", {
+        type: "string",
+        describe: `CLI name: ${supportedCliNames()}`
+      }).option("home", {
+        type: "string",
+        description: "Home-directory override for the settings file (default: user home)"
+      }).example([["$0 enable pi", "Enable pi for install/uninstall/show"]]),
+      (argv) => {
+        process.exitCode = runEnableDisableCliCommand(argv.cli, true, {
+          home: argv.home
+        });
+      }
+    ).command(
+      "disable <cli>",
+      "Disable MCP-server and skill installation for a supported CLI",
+      (yargs2) => yargs2.positional("cli", {
+        type: "string",
+        describe: `CLI name: ${supportedCliNames()}`
+      }).option("home", {
+        type: "string",
+        description: "Home-directory override for the settings file (default: user home)"
+      }).example([["$0 disable claude", "Disable claude for install/uninstall/show"]]),
+      (argv) => {
+        process.exitCode = runEnableDisableCliCommand(argv.cli, false, {
+          home: argv.home
+        });
+      }
+    ).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",
-        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"],
-        ["cat addresses.txt | $0 batch-geocode -i -", "Geocode from stdin"]
-      ]);
-    },
-    async (argv) => {
-      if (!argv.apikey) {
-        console.error("Error: GOOGLE_MAPS_API_KEY not set. Use --apikey or set env var.");
-        process.exit(1);
+        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"]]),
+      (argv) => {
+        process.exitCode = runInstallUninstallCommand("install", {
+          home: argv.home,
+          apiKey: argv.apikey,
+          resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
+        });
       }
-      let lines;
-      if (argv.input === "-") {
-        const rl = createInterface({ input: process.stdin });
-        lines = [];
-        for await (const line of rl) {
-          const trimmed = line.trim();
-          if (trimmed) lines.push(trimmed);
-        }
-      } else {
-        if (!existsSync4(argv.input)) {
-          console.error(`Error: File not found: ${argv.input}`);
-          process.exit(1);
-        }
-        lines = readFileSync4(argv.input, "utf-8").split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+    ).command(
+      "uninstall",
+      "Remove the mcp-google-map server entry and managed skills from every enabled CLI",
+      (yargs2) => yargs2.option("home", {
+        type: "string",
+        description: "Home-directory override for CLI configuration paths (default: user home)"
+      }).example([["$0 uninstall", "Reciprocal removal of install for every enabled CLI"]]),
+      (argv) => {
+        process.exitCode = runInstallUninstallCommand("uninstall", {
+          home: argv.home,
+          resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
+        });
       }
-      if (lines.length === 0) {
-        console.error("Error: No addresses found in input.");
-        process.exit(1);
+    ).command(
+      "show",
+      "Show CLI configuration and installation status tables (human-readable)",
+      (yargs2) => yargs2.option("home", {
+        type: "string",
+        description: "Home-directory override for CLI configuration paths (default: user home)"
+      }).example([["$0 show", "Print CLI Configuration and Installation Status tables"]]),
+      (argv) => {
+        process.exitCode = runShowCommand({
+          home: argv.home,
+          resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
+        });
       }
-      const searcher = new PlacesSearcher(argv.apikey);
-      const concurrency = Math.min(Math.max(argv.concurrency, 1), 50);
-      const results = [];
-      let completed = 0;
-      const semaphore = async (tasks2, limit) => {
-        const executing = [];
-        for (const task of tasks2) {
-          const p = task().then(() => {
-            executing.splice(executing.indexOf(p), 1);
-          });
-          executing.push(p);
-          if (executing.length >= limit) {
-            await Promise.race(executing);
-          }
+    ).command(
+      "exec <tool> [params]",
+      "Execute a tool directly and output JSON",
+      (yargs2) => {
+        return yargs2.positional("tool", {
+          type: "string",
+          describe: `Tool name: ${EXEC_TOOLS.join(", ")}`
+        }).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"],
+          [
+            `$0 exec search-nearby '{"center":{"value":"35.68,139.74","isCoordinates":true},"keyword":"restaurant"}'`,
+            "Search nearby"
+          ],
+          [`$0 exec search-places '{"query":"ramen in Tokyo"}'`, "Text search"]
+        ]);
+      },
+      async (argv) => {
+        if (!argv.apikey) {
+          process.stderr.write(
+            JSON.stringify(
+              {
+                error: "GOOGLE_MAPS_API_KEY not set. Use --apikey or set GOOGLE_MAPS_API_KEY environment variable."
+              },
+              null,
+              2
+            ) + "\n"
+          );
+          process.exitCode = 1;
+          return;
         }
-        await Promise.all(executing);
-      };
-      const tasks = lines.map((address, index) => async () => {
         try {
-          const result = await searcher.geocode(address);
-          results[index] = { address, ...result };
+          const params = argv.params ? JSON.parse(argv.params) : {};
+          process.exitCode = await runExecCommand(argv.tool, params, argv.apikey);
         } catch (error) {
-          results[index] = { address, success: false, error: error.message };
+          process.stderr.write(JSON.stringify({ error: error.message }, null, 2) + "\n");
+          process.exitCode = 1;
         }
-        completed++;
-        if (!argv.output) return;
-        process.stderr.write(`\r  ${completed}/${lines.length} geocoded`);
-      });
-      await semaphore(tasks, concurrency);
-      if (argv.output) {
-        process.stderr.write("\n");
       }
-      const succeeded = results.filter((r) => r.success).length;
-      const failed = results.filter((r) => !r.success).length;
-      const summary = { total: lines.length, succeeded, failed, results };
-      const json = JSON.stringify(summary, null, 2);
-      if (argv.output) {
-        writeFileSync3(argv.output, json, "utf-8");
-        console.error(`Done: ${succeeded}/${lines.length} succeeded. Output: ${argv.output}`);
-      } else {
-        console.log(json);
-      }
-      process.exit(failed > 0 ? 1 : 0);
-    }
-  ).command(
-    "$0",
-    "Start the MCP server (HTTP by default, --stdio for stdio mode)",
-    (yargs2) => {
-      return yargs2.option("port", {
-        alias: "p",
-        type: "number",
-        description: "Port to run the MCP server on",
-        default: process.env.MCP_SERVER_PORT ? parseInt(process.env.MCP_SERVER_PORT) : 3e3
-      }).option("host", {
-        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 HTTP server with default settings"],
-        ['$0 --port 3000 --apikey "your_api_key"', "Start HTTP with custom port and API key"],
-        ["$0 --host 0.0.0.0 --port 3000", "Start HTTP accessible from all interfaces"],
-        ["$0 --stdio", "Start in stdio mode (for Claude Desktop, Cursor, etc.)"]
-      ]);
-    },
-    async (argv) => {
-      if (argv.apikey) {
-        process.env.GOOGLE_MAPS_API_KEY = argv.apikey;
-      }
-      void checkForUpdates({ currentVersion: packageVersion }).catch(() => void 0);
-      const tools = filterTools(config_default[0].tools);
-      if (argv.stdio) {
-        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("");
+    ).command(
+      "batch-geocode",
+      "Geocode multiple addresses from a file (one address per line)",
+      (yargs2) => {
+        return yargs2.option("input", {
+          alias: "i",
+          type: "string",
+          describe: "Input file path (one address per line). Use - for stdin.",
+          demandOption: true
+        }).option("output", {
+          alias: "o",
+          type: "string",
+          describe: "Output file path (JSON). Defaults to stdout."
+        }).option("concurrency", {
+          alias: "c",
+          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"],
+          ["cat addresses.txt | $0 batch-geocode -i -", "Geocode from stdin"]
+        ]);
+      },
+      async (argv) => {
         if (!argv.apikey) {
-          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("");
+          console.error("Error: GOOGLE_MAPS_API_KEY not set. Use --apikey or set env var.");
+          process.exit(1);
         }
-        startServer(argv.port, argv.apikey, argv.host).then((outcome) => {
-          if (outcome.started === 0) {
+        let lines;
+        if (argv.input === "-") {
+          const rl = createInterface({ input: process.stdin });
+          lines = [];
+          for await (const line of rl) {
+            const trimmed = line.trim();
+            if (trimmed) lines.push(trimmed);
+          }
+        } else {
+          if (!existsSync4(argv.input)) {
+            console.error(`Error: File not found: ${argv.input}`);
             process.exit(1);
           }
-        }).catch((error) => {
-          Logger.error("\u274C Failed to start server:", error);
+          lines = readFileSync5(argv.input, "utf-8").split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+        }
+        if (lines.length === 0) {
+          console.error("Error: No addresses found in input.");
           process.exit(1);
+        }
+        const searcher = new PlacesSearcher(argv.apikey);
+        const concurrency = Math.min(Math.max(argv.concurrency, 1), 50);
+        const results = [];
+        let completed = 0;
+        const semaphore = async (tasks2, limit) => {
+          const executing = [];
+          for (const task of tasks2) {
+            const p = task().then(() => {
+              executing.splice(executing.indexOf(p), 1);
+            });
+            executing.push(p);
+            if (executing.length >= limit) {
+              await Promise.race(executing);
+            }
+          }
+          await Promise.all(executing);
+        };
+        const tasks = lines.map((address, index) => async () => {
+          try {
+            const result = await searcher.geocode(address);
+            results[index] = { address, ...result };
+          } catch (error) {
+            results[index] = { address, success: false, error: error.message };
+          }
+          completed++;
+          if (!argv.output) return;
+          process.stderr.write(`\r  ${completed}/${lines.length} geocoded`);
         });
+        await semaphore(tasks, concurrency);
+        if (argv.output) {
+          process.stderr.write("\n");
+        }
+        const succeeded = results.filter((r) => r.success).length;
+        const failed = results.filter((r) => !r.success).length;
+        const summary = { total: lines.length, succeeded, failed, results };
+        const json = JSON.stringify(summary, null, 2);
+        if (argv.output) {
+          writeFileSync4(argv.output, json, "utf-8");
+          console.error(`Done: ${succeeded}/${lines.length} succeeded. Output: ${argv.output}`);
+        } else {
+          console.log(json);
+        }
+        process.exit(failed > 0 ? 1 : 0);
       }
-    }
-  ).version(packageVersion).alias("version", "v").option("env-file", {
-    type: "string",
-    global: true,
-    description: "Load environment variables from this exact file (error if missing; no implicit .env fallback)"
-  }).help().parse();
+    ).command(
+      "start",
+      "Start the MCP server (HTTP by default, --stdio for stdio mode)",
+      buildServerCommandOptions,
+      runServerCommand
+    ).command(
+      "run",
+      "Alias of start: run the MCP server (HTTP by default, --stdio for stdio mode)",
+      buildServerCommandOptions,
+      runServerCommand
+    ).command(
+      "$0",
+      "Print the help text (use start or run to launch the MCP server)",
+      (yargs2) => yargs2,
+      () => {
+        cli.showHelp("log");
+      }
+    ).version(packageVersion).alias("version", "v").option("env-file", {
+      type: "string",
+      global: true,
+      description: "Load environment variables from this exact file (error if missing; no implicit .env fallback)"
+    }).epilog(
+      `Management commands (single flags, dispatched before subcommands):
+  --ver         Print the installed version and force one update check
+  --version     Alias of --ver
+  --upgrade     Upgrade the global package to the latest version and refresh installed skills
+  --uninstall   Remove the globally installed mcp-google-map package`
+    ).help();
+    cli.parse();
+  }
 }
 export {
   DOCTOR_PROBES,