mcp-google-map 0.3.0 → 0.5.0

package/dist/cli.js

@@ -2,14 +2,185 @@
 import {
   Logger,
   PlacesSearcher
-} from "./chunk-K27FX5QH.js";
+} from "./chunk-NAUIQEK4.js";
 
 // src/cli.ts
-import { config as dotenvConfig } from "dotenv";
-import { resolve } from "path";
+import { config as dotenvConfig2 } from "dotenv";
+import { resolve as resolve5 } from "path";
 import yargs from "yargs";
 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;
+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;
+}
+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;
+var DEFAULT_HTTP_HOST = "127.0.0.1";
+var DEFAULT_HTTP_PORT = 3e3;
+function resolveRuntimeConfig(env = process.env, overrides = {}) {
+  const envPort = env.MCP_SERVER_PORT?.trim() || void 0;
+  let port;
+  let portRaw;
+  let portSource;
+  if (overrides.port !== void 0) {
+    port = overrides.port;
+    portRaw = String(overrides.port);
+    portSource = "flag";
+  } else if (envPort !== void 0) {
+    const parsed = Number(envPort);
+    port = Number.isFinite(parsed) ? parsed : void 0;
+    portRaw = envPort;
+    portSource = "environment";
+  } else {
+    port = DEFAULT_HTTP_PORT;
+    portRaw = void 0;
+    portSource = "default";
+  }
+  const apiKey = overrides.apiKey ?? env.GOOGLE_MAPS_API_KEY;
+  const enabledToolsRaw = env.GOOGLE_MAPS_ENABLED_TOOLS?.trim() || void 0;
+  return {
+    apiKey,
+    apiKeySource: overrides.apiKey !== void 0 ? "flag" : apiKey ? "environment" : "none",
+    host: overrides.host ?? env.MCP_SERVER_HOST ?? DEFAULT_HTTP_HOST,
+    hostSource: overrides.host !== void 0 ? "flag" : env.MCP_SERVER_HOST ? "environment" : "default",
+    port,
+    portRaw,
+    portSource,
+    enabledToolsRaw,
+    enabledToolsSource: enabledToolsRaw ? "environment" : "default",
+    autoUpdateDisabled: isAutoUpdateDisabled(env),
+    envFile: overrides.envFile
+  };
+}
+function maskSecret(value) {
+  if (!value) {
+    return "unset";
+  }
+  if (value.length <= 8) {
+    return "****";
+  }
+  return `${value.slice(0, 4)}****${value.slice(-4)}`;
+}
+function describeRuntimeConfig(config) {
+  return {
+    apiKey: { value: maskSecret(config.apiKey), source: config.apiKeySource },
+    httpHost: { value: config.host, source: config.hostSource },
+    httpPort: {
+      value: config.port ?? null,
+      raw: config.portRaw ?? null,
+      source: config.portSource
+    },
+    enabledTools: { value: config.enabledToolsRaw ?? "*", source: config.enabledToolsSource },
+    autoUpdateCheck: { enabled: !config.autoUpdateDisabled },
+    envFile: { value: config.envFile ?? null }
+  };
+}
+function formatConfigDiagnostics(diagnostics) {
+  return [
+    `host=${diagnostics.httpHost.value} (${diagnostics.httpHost.source})`,
+    `port=${diagnostics.httpPort.value ?? "invalid"} (raw: ${diagnostics.httpPort.raw ?? "n/a"}, ${diagnostics.httpPort.source})`,
+    `apiKey=${diagnostics.apiKey.value} (${diagnostics.apiKey.source})`,
+    `enabledTools=${diagnostics.enabledTools.value} (${diagnostics.enabledTools.source})`,
+    `updateCheck=${diagnostics.autoUpdateCheck.enabled ? "enabled" : "disabled"}`
+  ].join("; ");
+}
+function applyExplicitEnvFile(path) {
+  if (!existsSync(path)) {
+    return { ok: false, error: `env file not found: ${path}` };
+  }
+  dotenvConfig({ path });
+  return { ok: true };
+}
+function resolveEnabledToolNames(allToolNames, raw) {
+  const trimmed = raw?.trim();
+  if (!trimmed || trimmed === "*") {
+    return { names: [...allToolNames], matched: allToolNames.length, fallback: false, requested: [] };
+  }
+  const requested = trimmed.split(",").map((item) => item.trim()).filter(Boolean);
+  const enabled = new Set(requested);
+  const names = allToolNames.filter((name) => enabled.has(name));
+  if (names.length === 0) {
+    return { names: [...allToolNames], matched: 0, fallback: true, requested };
+  }
+  return { names, matched: names.length, fallback: false, requested };
+}
+
 // src/tools/maps/searchNearby.ts
 import { z } from "zod";
 
@@ -1023,18 +1194,19 @@ var serverConfigs = [
   }
 ];
 function filterTools(tools) {
-  const raw = process.env.GOOGLE_MAPS_ENABLED_TOOLS?.trim();
-  if (!raw || raw === "*") return tools;
-  const enabled = new Set(
-    raw.split(",").map((s) => s.trim()).filter(Boolean)
+  const resolution = resolveEnabledToolNames(
+    tools.map((tool) => tool.name),
+    process.env.GOOGLE_MAPS_ENABLED_TOOLS
   );
-  const filtered = tools.filter((t) => enabled.has(t.name));
-  if (filtered.length === 0) {
+  if (resolution.fallback) {
     Logger.error(`GOOGLE_MAPS_ENABLED_TOOLS matched 0 tools. Available: ${tools.map((t) => t.name).join(", ")}`);
     return tools;
   }
-  Logger.log(`GOOGLE_MAPS_ENABLED_TOOLS: ${filtered.length}/${tools.length} tools active`);
-  return filtered;
+  if (resolution.matched !== tools.length) {
+    Logger.log(`GOOGLE_MAPS_ENABLED_TOOLS: ${resolution.matched}/${tools.length} tools active`);
+  }
+  const enabled = new Set(resolution.names);
+  return tools.filter((tool) => enabled.has(tool.name));
 }
 var config_default = serverConfigs;
 
@@ -1140,7 +1312,20 @@ var BaseMcpServer = class {
     };
     Logger.log(`${this.serverName} connected and ready to process requests`);
   }
-  async startHttpServer(port, host = "0.0.0.0") {
+  /**
+   * @brief Starts the Streamable HTTP listener and resolves once it is accepting connections.
+   * @details Builds the Express app with the `/mcp` POST/GET/DELETE handlers,
+   * then wraps `app.listen` in a Promise that resolves from the listen callback
+   * and rejects on the server `error` event (e.g. EADDRINUSE), so callers get
+   * a reliable startup outcome instead of an unhandled error. Default host is
+   * loopback `127.0.0.1` (REQ-008); pass `0.0.0.0` to bind all interfaces.
+   * @param port {number} TCP port to listen on (1-65535).
+   * @param host {string} Bind address; defaults to `127.0.0.1`.
+   * @return {Promise<void>} Resolves when listening; rejects with the listen error.
+   * @throws {Error} Rejects when the HTTP listener emits an error (port in use, permission denied).
+   * @satisfies REQ-008, REQ-095
+   */
+  async startHttpServer(port, host = "127.0.0.1") {
     const app = express();
     app.use(express.json());
     app.post("/mcp", async (req, res) => {
@@ -1212,42 +1397,53 @@ var BaseMcpServer = class {
     app.get("/mcp", handleSessionRequest);
     app.delete("/mcp", handleSessionRequest);
     const displayHost = host === "0.0.0.0" ? "localhost" : host;
-    this.httpServer = app.listen(port, host, () => {
-      Logger.log(`[${this.serverName}] HTTP server listening on ${host}:${port}`);
-      Logger.log(`[${this.serverName}] MCP endpoint available at http://${displayHost}:${port}/mcp`);
+    await new Promise((resolve6, reject) => {
+      this.httpServer = app.listen(port, host, () => {
+        Logger.log(`[${this.serverName}] HTTP server listening on ${host}:${port}`);
+        Logger.log(`[${this.serverName}] MCP endpoint available at http://${displayHost}:${port}/mcp`);
+        resolve6();
+      });
+      this.httpServer.on("error", (error) => reject(error));
     });
   }
   async startStdio() {
     const transport = new StdioServerTransport();
     await this.connect(transport);
   }
+  /**
+   * @brief Stops the HTTP listener and closes every session transport in order.
+   * @details Idempotent: when no listener exists it logs and resolves. Otherwise
+   * it detaches the server reference, clears the session map, awaits
+   * `transport.close()` for every session (errors tolerated via allSettled),
+   * calls `closeAllConnections` when available, and finally closes the socket.
+   * Wired to SIGINT/SIGTERM through `installShutdownHandlers` (REQ-096).
+   * @return {Promise<void>} Resolves after the socket closes; rejects when `server.close` errors.
+   * @throws {Error} Rejects with the `server.close` error.
+   * @satisfies REQ-096
+   */
   async stopHttpServer() {
-    if (!this.httpServer) {
+    const server = this.httpServer;
+    if (!server) {
       Logger.error(`[${this.serverName}] HTTP server is not running or already stopped.`);
       return;
     }
-    return new Promise((resolve2, reject) => {
-      this.httpServer.close((err) => {
+    this.httpServer = null;
+    const closingSessions = Object.values(this.sessions);
+    this.sessions = {};
+    await Promise.allSettled(closingSessions.map((context) => context.transport.close()));
+    if (closingSessions.length > 0) {
+      Logger.log(`[${this.serverName}] All transports closed.`);
+    }
+    return new Promise((resolve6, reject) => {
+      server.closeAllConnections?.();
+      server.close((err) => {
         if (err) {
           Logger.error(`[${this.serverName}] Error stopping HTTP server:`, err);
           reject(err);
           return;
         }
         Logger.log(`[${this.serverName}] HTTP server stopped.`);
-        this.httpServer = null;
-        const closingSessions = Object.values(this.sessions).map((context) => {
-          if (context.transport.sessionId) {
-            delete this.sessions[context.transport.sessionId];
-          }
-          return Promise.resolve();
-        });
-        Promise.all(closingSessions).then(() => {
-          Logger.log(`[${this.serverName}] All transports closed.`);
-          resolve2();
-        }).catch((transportCloseErr) => {
-          Logger.error(`[${this.serverName}] Error during bulk transport closing:`, transportCloseErr);
-          reject(transportCloseErr);
-        });
+        resolve6();
       });
     });
   }
@@ -1256,12 +1452,648 @@ var BaseMcpServer = class {
 // src/cli.ts
 import { fileURLToPath } from "url";
 import { dirname } from "path";
-import { readFileSync, writeFileSync, existsSync } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync4 } from "fs";
 import { createInterface } from "readline";
+
+// src/utils/toolProfiles.ts
+var TOOL_API_PROFILES = {
+  maps_geocode: { tool: "maps_geocode", apis: ["geocoding"], dependsOnTools: [] },
+  maps_reverse_geocode: { tool: "maps_reverse_geocode", apis: ["geocoding"], dependsOnTools: [] },
+  maps_batch_geocode: { tool: "maps_batch_geocode", apis: ["geocoding"], dependsOnTools: ["maps_geocode"] },
+  maps_search_nearby: {
+    tool: "maps_search_nearby",
+    apis: ["places-new", "geocoding"],
+    dependsOnTools: ["maps_geocode"]
+  },
+  maps_search_places: { tool: "maps_search_places", apis: ["places-new"], dependsOnTools: [] },
+  maps_place_details: { tool: "maps_place_details", apis: ["places-new"], dependsOnTools: [] },
+  maps_directions: { tool: "maps_directions", apis: ["routes"], dependsOnTools: [] },
+  maps_distance_matrix: { tool: "maps_distance_matrix", apis: ["routes"], dependsOnTools: [] },
+  maps_elevation: { tool: "maps_elevation", apis: ["elevation"], dependsOnTools: [] },
+  maps_timezone: { tool: "maps_timezone", apis: ["timezone"], dependsOnTools: [] },
+  maps_weather: { tool: "maps_weather", apis: ["weather"], dependsOnTools: [] },
+  maps_air_quality: { tool: "maps_air_quality", apis: ["air-quality"], dependsOnTools: [] },
+  maps_static_map: { tool: "maps_static_map", apis: ["static-maps"], dependsOnTools: [] },
+  maps_explore_area: {
+    tool: "maps_explore_area",
+    apis: ["places-new", "geocoding"],
+    dependsOnTools: ["maps_geocode", "maps_search_nearby", "maps_place_details"]
+  },
+  maps_plan_route: {
+    tool: "maps_plan_route",
+    apis: ["routes", "geocoding", "places-new"],
+    dependsOnTools: ["maps_geocode", "maps_search_places", "maps_directions"]
+  },
+  maps_compare_places: {
+    tool: "maps_compare_places",
+    apis: ["places-new", "routes"],
+    dependsOnTools: ["maps_search_places", "maps_place_details", "maps_distance_matrix"]
+  },
+  maps_search_along_route: {
+    tool: "maps_search_along_route",
+    apis: ["routes", "places-new"],
+    dependsOnTools: ["maps_directions", "maps_search_places"]
+  },
+  maps_local_rank_tracker: {
+    tool: "maps_local_rank_tracker",
+    apis: ["places-new"],
+    dependsOnTools: ["maps_place_details", "maps_search_places"]
+  }
+};
+function describeToolsProfile(toolNames) {
+  const tools = [];
+  const apiOrder = [];
+  const seenApis = /* @__PURE__ */ new Set();
+  const seenTools = /* @__PURE__ */ new Set();
+  for (const name of toolNames) {
+    if (seenTools.has(name)) {
+      continue;
+    }
+    const profile = TOOL_API_PROFILES[name];
+    if (!profile) {
+      continue;
+    }
+    seenTools.add(name);
+    tools.push({
+      tool: profile.tool,
+      apis: [...profile.apis],
+      dependsOnTools: [...profile.dependsOnTools]
+    });
+    for (const api of profile.apis) {
+      if (!seenApis.has(api)) {
+        seenApis.add(api);
+        apiOrder.push(api);
+      }
+    }
+  }
+  return { toolCount: tools.length, apis: apiOrder, tools };
+}
+
+// src/utils/clientSnippets.ts
+var API_KEY_PLACEHOLDER = "<your-google-maps-api-key>";
+var SNIPPET_DEFAULT_HOST = "127.0.0.1";
+var SNIPPET_DEFAULT_PORT = 3e3;
+var SNIPPET_CLIENT_TARGETS = {
+  generic: "your MCP client configuration file",
+  claude: "Claude Desktop: claude_desktop_config.json",
+  cursor: "Cursor: .cursor/mcp.json",
+  pi: "pi CLI: ~/.pi/agent/mcp.json (user) or .pi/mcp.json (project)"
+};
+function renderClientSnippet(options = {}) {
+  const client = options.client ?? "generic";
+  const transport = options.transport ?? "stdio";
+  const serverName = options.serverName ?? "mcp-google-map";
+  const notes = [`Paste this snippet into ${SNIPPET_CLIENT_TARGETS[client]}.`];
+  notes.push("This command prints the snippet only; it never writes or edits configuration files.");
+  let entry;
+  if (transport === "http") {
+    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}.`);
+  } 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"];
+    if (launcher === "npx") {
+      notes.push("The npx launcher runs the published package; npm must be available on PATH.");
+    }
+    const apiKeyValue = options.envKey ? `\${${options.envKey}}` : API_KEY_PLACEHOLDER;
+    entry = { command, args, env: { GOOGLE_MAPS_API_KEY: apiKeyValue } };
+    if (options.envKey) {
+      notes.push(
+        `Variable references (\${${options.envKey}}) are client-specific: confirm your client expands environment variables before relying on them.`
+      );
+    } else {
+      notes.push(`Replace ${API_KEY_PLACEHOLDER} with your Google Maps API key.`);
+    }
+  }
+  const json = JSON.stringify({ mcpServers: { [serverName]: entry } }, null, 2);
+  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,
+  readdirSync,
+  renameSync as renameSync2,
+  rmSync,
+  statSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { join as join2, 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")
+};
+var OPENCLAW_TARGET = {
+  id: "openclaw",
+  configFormat: "json",
+  mcpConfigPath: (home) => join2(homeRoot(home), ".openclaw", "openclaw.json"),
+  skillsDir: (home) => join2(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")
+};
+var ANTIGRAVITY_TARGET = {
+  id: "antigravity",
+  configFormat: "json",
+  mcpConfigPath: (home) => join2(homeRoot(home), ".gemini", "settings.json"),
+  skillsDir: (home) => join2(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")
+};
+var CLI_TARGETS = {
+  pi: PI_TARGET,
+  openclaw: OPENCLAW_TARGET,
+  codex: CODEX_TARGET,
+  antigravity: ANTIGRAVITY_TARGET,
+  claude: CLAUDE_TARGET
+};
+function resolveCliTarget(name) {
+  return CLI_TARGETS[name.trim().toLowerCase()];
+}
+function supportedCliNames() {
+  return Object.keys(CLI_TARGETS).join(", ");
+}
+function readJsonConfig(configPath) {
+  if (!existsSync2(configPath)) return {};
+  const parsed = JSON.parse(readFileSync2(configPath, "utf-8"));
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`configuration is not a JSON object: ${configPath}`);
+  }
+  return parsed;
+}
+function writeJsonConfig(configPath, value) {
+  const temporary = `${configPath}.tmp`;
+  mkdirSync2(join2(configPath, ".."), { recursive: true });
+  writeFileSync2(temporary, JSON.stringify(value, null, 2) + "\n", "utf-8");
+  renameSync2(temporary, configPath);
+}
+function writeJsonMcpServerEntry(configPath, serverName, entry) {
+  const config = readJsonConfig(configPath);
+  const mcpServers = config.mcpServers ?? {};
+  if (mcpServers === null || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+    throw new Error(`mcpServers is not an object: ${configPath}`);
+  }
+  mcpServers[serverName] = entry;
+  config.mcpServers = mcpServers;
+  writeJsonConfig(configPath, config);
+}
+function removeJsonMcpServerEntry(configPath, serverName) {
+  if (!existsSync2(configPath)) return false;
+  const config = readJsonConfig(configPath);
+  const mcpServers = config.mcpServers;
+  if (mcpServers === void 0) return false;
+  if (mcpServers === null || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+    throw new Error(`mcpServers is not an object: ${configPath}`);
+  }
+  const map = mcpServers;
+  if (!(serverName in map)) return false;
+  delete map[serverName];
+  config.mcpServers = map;
+  writeJsonConfig(configPath, config);
+  return true;
+}
+function readJsonMcpServerEntry(configPath, serverName) {
+  try {
+    const config = readJsonConfig(configPath);
+    const mcpServers = config.mcpServers;
+    if (mcpServers === null || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+      return void 0;
+    }
+    return mcpServers[serverName];
+  } catch {
+    return void 0;
+  }
+}
+function tomlString(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function tomlSectionHeader(serverName) {
+  return `[mcp_servers.${serverName}]`;
+}
+function removeTomlSection(content, serverName) {
+  const lines = content.split("\n");
+  const header = tomlSectionHeader(serverName);
+  const kept = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (skipping) {
+      if (line.trimStart().startsWith("[")) {
+        skipping = false;
+      } else {
+        continue;
+      }
+    } else if (line.trim() === header) {
+      skipping = true;
+      while (kept.length > 0 && kept[kept.length - 1].trim() === "") {
+        kept.pop();
+      }
+      continue;
+    }
+    kept.push(line);
+  }
+  while (kept.length > 0 && kept[kept.length - 1].trim() === "") {
+    kept.pop();
+  }
+  return kept.length > 0 ? kept.join("\n") + "\n" : "";
+}
+function hasTomlSection(content, serverName) {
+  return content.split("\n").some((line) => line.trim() === tomlSectionHeader(serverName));
+}
+function registrationToTomlLines(entry) {
+  const lines = [`command = ${tomlString(entry.command)}`];
+  if (entry.args !== void 0) {
+    lines.push(`args = [${entry.args.map((arg) => tomlString(arg)).join(", ")}]`);
+  }
+  if (entry.env !== void 0) {
+    const pairs = Object.entries(entry.env).map(([key, value]) => `${tomlString(key)} = ${tomlString(value)}`);
+    if (pairs.length > 0) lines.push(`env = { ${pairs.join(", ")} }`);
+  }
+  return lines;
+}
+function writeTomlMcpServerSection(configPath, serverName, entry) {
+  const previous = existsSync2(configPath) ? readFileSync2(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");
+  renameSync2(temporary, configPath);
+}
+function removeTomlMcpServerSection(configPath, serverName) {
+  if (!existsSync2(configPath)) return false;
+  const previous = readFileSync2(configPath, "utf-8");
+  if (!hasTomlSection(previous, serverName)) return false;
+  const content = removeTomlSection(previous, serverName);
+  const temporary = `${configPath}.tmp`;
+  writeFileSync2(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);
+}
+function listFilesRecursive(root) {
+  if (!existsSync2(root)) return [];
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join2(dir, entry);
+      if (statSync(full).isDirectory()) {
+        walk(full);
+      } else {
+        files.push(relative(root, full).split("\\").join("/"));
+      }
+    }
+  };
+  walk(root);
+  return files;
+}
+function syncSkillTree(source, destination) {
+  mkdirSync2(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 });
+  }
+}
+function removeSkillDir(skillDir) {
+  rmSync(skillDir, { recursive: true, force: true });
+}
+function compareSkillTree(source, destination) {
+  const packaged = listFilesRecursive(source);
+  if (packaged.length === 0) return "MISSING";
+  if (!existsSync2(destination)) return "MISSING";
+  for (const rel of packaged) {
+    const target = join2(destination, ...rel.split("/"));
+    if (!existsSync2(target)) return "MISSING";
+    if (readFileSync2(target).toString("utf-8") !== readFileSync2(join2(source, ...rel.split("/"))).toString("utf-8")) {
+      return "STALE";
+    }
+  }
+  return "OK";
+}
+function isServerRegistered(target, serverName, home) {
+  const configPath = target.mcpConfigPath(home);
+  if (target.configFormat === "toml") {
+    return hasTomlMcpServerSection(configPath, serverName);
+  }
+  return readJsonMcpServerEntry(configPath, serverName) !== void 0;
+}
+function applyServerRegistration(target, serverName, entry, home) {
+  const configPath = target.mcpConfigPath(home);
+  if (target.configFormat === "toml") {
+    if (entry === void 0) {
+      removeTomlMcpServerSection(configPath, serverName);
+    } else {
+      writeTomlMcpServerSection(configPath, serverName, entry);
+    }
+    return;
+  }
+  if (entry === void 0) {
+    removeJsonMcpServerEntry(configPath, serverName);
+  } else {
+    writeJsonMcpServerEntry(configPath, serverName, entry);
+  }
+}
+
+// src/utils/cliInstaller.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { join as join3, 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 };
+}
+function resolveSkillsResourcesRoot(packageRoot) {
+  const candidate = resolve3(packageRoot, "src", "resources", "skills");
+  if (!existsSync3(candidate)) {
+    throw new Error(`skills resources root not found: ${candidate}`);
+  }
+  return candidate;
+}
+function loadSkillsManifest(resourcesRoot) {
+  const manifestPath = join3(resourcesRoot, "manifest.json");
+  if (!existsSync3(manifestPath)) {
+    throw new Error(`skills manifest not found: ${manifestPath}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync3(manifestPath, "utf-8"));
+  } catch (error) {
+    throw new Error(`skills manifest is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const skills = parsed?.skills;
+  if (!Array.isArray(skills)) {
+    throw new Error(`skills manifest has no skills array: ${manifestPath}`);
+  }
+  return skills.map((entry) => {
+    const skill = entry;
+    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)}`);
+    }
+    return {
+      id: skill.id,
+      name: skill.name ?? skill.id,
+      version: skill.version ?? "",
+      path: skill.path,
+      description: skill.description ?? ""
+    };
+  });
+}
+function installEnabledCliResources(options) {
+  const manifest = loadSkillsManifest(options.resourcesRoot);
+  const entry = buildServerRegistration(options.apiKey);
+  const result = { summaries: [], errors: [] };
+  for (const cli of loadCliSettings(options.home).enabled) {
+    const target = CLI_TARGETS[cli];
+    if (target === void 0) {
+      result.errors.push(`Unsupported CLI: ${cli}`);
+      continue;
+    }
+    try {
+      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));
+        skills += 1;
+      }
+      result.summaries.push({ cli: target.id, server: 1, skills });
+    } catch (error) {
+      result.errors.push(`${target.id}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return result;
+}
+function uninstallEnabledCliResources(options) {
+  const manifest = loadSkillsManifest(options.resourcesRoot);
+  const result = { summaries: [], errors: [] };
+  for (const cli of loadCliSettings(options.home).enabled) {
+    const target = CLI_TARGETS[cli];
+    if (target === void 0) {
+      result.errors.push(`Unsupported CLI: ${cli}`);
+      continue;
+    }
+    try {
+      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));
+        skills += 1;
+      }
+      result.summaries.push({ cli: target.id, server: 0, skills });
+    } catch (error) {
+      result.errors.push(`${target.id}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return result;
+}
+
+// src/utils/cliShow.ts
+import { join as join4 } from "path";
+import { relative as relative2, resolve as resolve4 } from "path";
+var MAX_CELL_WIDTH = 48;
+var STATUS_OK = "OK";
+var STATUS_MISSING = "MISSING";
+function wrapCell(text, width) {
+  const normalized = String(text).split(/\s+/).filter((word) => word.length > 0);
+  if (normalized.length === 0) return [""];
+  const lines = [];
+  let current = "";
+  for (let word of normalized) {
+    while (word.length > width) {
+      if (current.length > 0) {
+        lines.push(current);
+        current = "";
+      }
+      lines.push(word.slice(0, width));
+      word = word.slice(width);
+    }
+    if (current.length === 0) {
+      current = word;
+    } else if (current.length + 1 + word.length <= width) {
+      current = `${current} ${word}`;
+    } else {
+      lines.push(current);
+      current = word;
+    }
+  }
+  if (current.length > 0) lines.push(current);
+  return lines.length > 0 ? lines : [""];
+}
+function renderAsciiTable(headers, rows, maxWidth = MAX_CELL_WIDTH) {
+  const widths = headers.map((header, index) => {
+    const lengths = [header.length, ...rows.map((row) => (row[index] ?? "").length)];
+    return Math.max(1, Math.min(Math.max(...lengths), Math.max(1, maxWidth)));
+  });
+  const border = "+" + widths.map((width) => "-".repeat(width + 2)).join("+") + "+";
+  const renderRow = (cells) => {
+    const wrapped = cells.map((cell, index) => wrapCell(cell ?? "", widths[index]));
+    const height = Math.max(...wrapped.map((part) => part.length));
+    const lines = [];
+    for (let line = 0; line < height; line += 1) {
+      const parts = wrapped.map((part, index) => (part[line] ?? "").padEnd(widths[index]));
+      lines.push("| " + parts.join(" | ") + " |");
+    }
+    return lines;
+  };
+  const output = [border, ...renderRow(headers), border];
+  for (const row of rows) {
+    output.push(...renderRow(row));
+    output.push(border);
+  }
+  return output.join("\n");
+}
+function buildCliRows(home) {
+  const root = home ?? (process.env.HOME ?? process.cwd());
+  const enabled = new Set(loadCliSettings(home).enabled);
+  return Object.keys(CLI_TARGETS).map((id) => {
+    const target = CLI_TARGETS[id];
+    return [
+      target.id,
+      enabled.has(id) ? "yes" : "no",
+      relative2(resolve4(root), resolve4(target.mcpConfigPath(home))).split("\\").join("/"),
+      relative2(resolve4(root), resolve4(target.skillsDir(home))).split("\\").join("/")
+    ];
+  });
+}
+function buildInstallRows(home, resourcesRoot) {
+  const enabled = loadCliSettings(home).enabled;
+  const manifest = loadSkillsManifest(resourcesRoot);
+  const rows = [];
+  for (const cli of enabled) {
+    const target = CLI_TARGETS[cli];
+    if (target === void 0) continue;
+    rows.push([
+      "Server",
+      MCP_SERVER_NAME,
+      target.id,
+      "yes",
+      isServerRegistered(target, MCP_SERVER_NAME, home) ? STATUS_OK : STATUS_MISSING
+    ]);
+    for (const skill of manifest) {
+      rows.push([
+        "Skill",
+        skill.id,
+        target.id,
+        "yes",
+        compareSkillTree(join4(resourcesRoot, skill.id), join4(target.skillsDir(home), skill.id))
+      ]);
+    }
+  }
+  return rows;
+}
+function buildCliShowReport(options) {
+  return [
+    "CLI Configuration",
+    renderAsciiTable(["CLI", "Enabled", "MCP Config Path", "Skills Config Path"], buildCliRows(options.home)),
+    "",
+    "Installation Status",
+    renderAsciiTable(["Type", "Name", "CLI", "Enabled", "Installed"], buildInstallRows(options.home, options.resourcesRoot))
+  ].join("\n");
+}
+
+// src/cli.ts
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname(__filename);
-dotenvConfig({ path: resolve(process.cwd(), ".env") });
-dotenvConfig({ path: resolve(__dirname, "../.env") });
+function extractEnvFileOption(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--env-file" && i + 1 < argv.length) {
+      return argv[i + 1];
+    }
+    if (arg.startsWith("--env-file=")) {
+      return arg.slice("--env-file=".length);
+    }
+  }
+  return void 0;
+}
+function loadEnvironment(envFile) {
+  if (envFile !== void 0) {
+    const result = applyExplicitEnvFile(envFile);
+    if (!result.ok) {
+      process.stderr.write(JSON.stringify({ error: result.error }, null, 2) + "\n");
+      process.exit(1);
+    }
+    return;
+  }
+  dotenvConfig2({ path: resolve5(process.cwd(), ".env") });
+  dotenvConfig2({ path: resolve5(__dirname, "../.env") });
+}
 async function startServer(port, apiKey, host) {
   if (port) {
     process.env.MCP_SERVER_PORT = port.toString();
@@ -1278,36 +2110,69 @@ async function startServer(port, apiKey, host) {
     "\u2139\uFE0F  Reminder: enable Places API (New) in https://console.cloud.google.com before using the new Place features."
   );
   Logger.log("");
-  const startPromises = config_default.map(async (config) => {
-    const portString = process.env[config.portEnvVar];
-    if (!portString) {
-      Logger.error(`\u26A0\uFE0F  [${config.name}] Port environment variable ${config.portEnvVar} not set.`);
-      Logger.log(`\u{1F4A1} Please set ${config.portEnvVar} in your .env file or use --port parameter.`);
-      Logger.log(`   Example: ${config.portEnvVar}=3000 or --port 3000`);
-      return;
-    }
-    const serverPort = Number(portString);
-    if (isNaN(serverPort) || serverPort <= 0) {
-      Logger.error(`\u274C [${config.name}] Invalid port number "${portString}" defined in ${config.portEnvVar}.`);
-      return;
-    }
-    try {
-      const server = new BaseMcpServer(config.name, filterTools(config.tools));
-      const serverHost = process.env.MCP_SERVER_HOST || "0.0.0.0";
-      Logger.log(`\u{1F527} [${config.name}] Initializing MCP Server in HTTP mode on ${serverHost}:${serverPort}...`);
-      await server.startHttpServer(serverPort, serverHost);
-      const displayHost = serverHost === "0.0.0.0" ? "localhost" : serverHost;
-      Logger.log(`\u2705 [${config.name}] MCP Server started successfully!`);
-      Logger.log(`   \u{1F310} Endpoint: http://${displayHost}:${serverPort}/mcp`);
-      Logger.log(`   \u{1F4DA} Tools: ${config.tools.length} available`);
-    } catch (error) {
-      Logger.error(`\u274C [${config.name}] Failed to start MCP Server on port ${serverPort}:`, error);
-    }
-  });
-  await Promise.allSettled(startPromises);
+  const servers = [];
+  let started = 0;
+  let failed = 0;
+  await Promise.all(
+    config_default.map(async (config) => {
+      const portString = process.env[config.portEnvVar];
+      if (!portString) {
+        Logger.error(`\u26A0\uFE0F  [${config.name}] Port environment variable ${config.portEnvVar} not set.`);
+        Logger.log(`\u{1F4A1} Please set ${config.portEnvVar} in your .env file or use --port parameter.`);
+        Logger.log(`   Example: ${config.portEnvVar}=3000 or --port 3000`);
+        failed++;
+        return;
+      }
+      const serverPort = Number(portString);
+      if (!Number.isInteger(serverPort) || serverPort < 1 || serverPort > 65535) {
+        Logger.error(
+          `\u274C [${config.name}] Invalid port number "${portString}" defined in ${config.portEnvVar} (expected integer 1-65535).`
+        );
+        failed++;
+        return;
+      }
+      try {
+        const activeTools = filterTools(config.tools);
+        const server = new BaseMcpServer(config.name, activeTools);
+        const serverHost = process.env.MCP_SERVER_HOST || "127.0.0.1";
+        Logger.log(`\u{1F527} [${config.name}] Initializing MCP Server in HTTP mode on ${serverHost}:${serverPort}...`);
+        await server.startHttpServer(serverPort, serverHost);
+        servers.push(server);
+        started++;
+        const displayHost = serverHost === "0.0.0.0" ? "localhost" : serverHost;
+        Logger.log(`\u2705 [${config.name}] MCP Server started successfully!`);
+        Logger.log(`   \u{1F310} Endpoint: http://${displayHost}:${serverPort}/mcp`);
+        Logger.log(`   \u{1F4DA} Tools: ${activeTools.length} available`);
+      } catch (error) {
+        Logger.error(`\u274C [${config.name}] Failed to start MCP Server on port ${serverPort}:`, error);
+        failed++;
+      }
+    })
+  );
+  if (started > 0) {
+    installShutdownHandlers(servers);
+  }
   Logger.log("");
-  Logger.log("\u{1F389} Server initialization completed!");
+  Logger.log(started > 0 ? "\u{1F389} Server initialization completed!" : "\u274C No MCP server instance started.");
   Logger.log("\u{1F4A1} Need help? Check the README.md for configuration details.");
+  return { started, failed, servers };
+}
+function createShutdownHandler(servers, exitHook = (code) => process.exit(code)) {
+  let invoked = false;
+  return async (signal) => {
+    if (invoked) {
+      return;
+    }
+    invoked = true;
+    Logger.log(`\u{1F4F6} Received ${signal}; shutting down MCP HTTP server...`);
+    await Promise.allSettled(servers.map((server) => server.stopHttpServer()));
+    exitHook(0);
+  };
+}
+function installShutdownHandlers(servers) {
+  const handler = createShutdownHandler(servers);
+  process.on("SIGINT", () => void handler("SIGINT"));
+  process.on("SIGTERM", () => void handler("SIGTERM"));
 }
 var EXEC_TOOLS = [
   "geocode",
@@ -1473,13 +2338,58 @@ async function runExecCommand(toolName, params, apiKey, runner = execTool, strea
     return 1;
   }
 }
-async function runDoctor(packageVersion, apiKey, live = false, runner = execTool) {
-  const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+var DOCTOR_PROBES = [
+  { id: "geocoding", name: "geocoding-api", tool: "geocode", params: { address: "Tokyo Tower" } },
+  { id: "places-new", name: "places-api-new", tool: "search-places", params: { query: "Tokyo Tower" } },
+  {
+    id: "routes",
+    name: "routes-api",
+    tool: "directions",
+    params: { origin: "Tokyo Tower", destination: "Tokyo Station", mode: "walking" }
+  }
+];
+var DOCTOR_PROBE_ALIASES = {
+  geocoding: "geocoding",
+  "geocoding-api": "geocoding",
+  "places-new": "places-new",
+  places: "places-new",
+  "places-api-new": "places-new",
+  routes: "routes",
+  "routes-api": "routes"
+};
+function parseDoctorProbes(raw) {
+  if (raw === void 0) {
+    return { probes: void 0 };
+  }
+  const items = raw.split(",").map((item) => item.trim().toLowerCase()).filter(Boolean);
+  if (items.length === 0) {
+    return { probes: void 0, error: "--probes received no probe names (expected: geocoding, places-new, routes)" };
+  }
+  const probes = [];
+  for (const item of items) {
+    const id = DOCTOR_PROBE_ALIASES[item];
+    if (!id) {
+      return { probes: [], error: `unknown probe "${item}" (expected: geocoding, places-new, routes)` };
+    }
+    if (!probes.includes(id)) {
+      probes.push(id);
+    }
+  }
+  return { probes };
+}
+async function runDoctor(packageVersion, apiKey, live = false, runner = execTool, options = {}) {
+  const nodeVersion = options.nodeVersion ?? process.versions.node;
+  const nodeMajor = Number.parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+  const config = options.config ?? resolveRuntimeConfig(process.env);
+  const allToolNames = options.allToolNames ?? config_default[0].tools.map((tool) => tool.name);
+  const toolsResolution = resolveEnabledToolNames(allToolNames, config.enabledToolsRaw);
+  const diagnostics = describeRuntimeConfig(config);
+  const toolsProfile = describeToolsProfile(toolsResolution.names);
   const checks = [
     {
       name: "node",
-      status: nodeMajor >= 18 ? "pass" : "fail",
-      detail: `Node.js ${process.versions.node} detected; version 18 or newer is required.`
+      status: nodeMajor >= NODE_ENGINE_FLOOR ? "pass" : "fail",
+      detail: `Node.js ${nodeVersion} detected; version ${NODE_ENGINE_FLOOR} or newer is required (package.json engines).`
     },
     {
       name: "package",
@@ -1490,6 +2400,21 @@ async function runDoctor(packageVersion, apiKey, live = false, runner = execTool
       name: "api-key",
       status: apiKey ? "pass" : "fail",
       detail: apiKey ? "GOOGLE_MAPS_API_KEY is configured (value hidden)." : "GOOGLE_MAPS_API_KEY is not configured. Set it in the environment before making API calls."
+    },
+    {
+      name: "config",
+      status: toolsResolution.fallback ? "fail" : "pass",
+      detail: toolsResolution.fallback ? `GOOGLE_MAPS_ENABLED_TOOLS matched 0 tools; the server falls back to all ${allToolNames.length} tools. Effective configuration: ${formatConfigDiagnostics(diagnostics)}` : `Effective configuration: ${formatConfigDiagnostics(diagnostics)}`
+    },
+    {
+      name: "env-file",
+      status: "pass",
+      detail: config.envFile ? `Explicit environment file loaded: ${config.envFile}` : "No explicit --env-file requested; implicit .env discovery (current directory, then package directory) applies."
+    },
+    {
+      name: "tools",
+      status: "pass",
+      detail: `${toolsProfile.toolCount} tool(s) enabled; Google APIs: ${toolsProfile.apis.join(", ") || "none"}; per-tool: ${toolsProfile.tools.map((tool) => `${tool.tool}[${tool.apis.join("+")}]`).join(", ")}`
     }
   ];
   if (!live) {
@@ -1505,16 +2430,8 @@ async function runDoctor(packageVersion, apiKey, live = false, runner = execTool
       detail: "Live API checks require GOOGLE_MAPS_API_KEY."
     });
   } else {
-    const liveChecks = [
-      { name: "geocoding-api", tool: "geocode", params: { address: "Tokyo Tower" } },
-      { name: "places-api-new", tool: "search-places", params: { query: "Tokyo Tower" } },
-      {
-        name: "routes-api",
-        tool: "directions",
-        params: { origin: "Tokyo Tower", destination: "Tokyo Station", mode: "walking" }
-      }
-    ];
-    for (const check of liveChecks) {
+    const selected = options.probes ? DOCTOR_PROBES.filter((probe) => options.probes.includes(probe.id)) : DOCTOR_PROBES;
+    for (const check of selected) {
       try {
         const result = await runner(check.tool, check.params, apiKey);
         if (isExecFailureResponse(result)) {
@@ -1546,13 +2463,169 @@ async function runDoctor(packageVersion, apiKey, live = false, runner = execTool
     checks
   };
 }
+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)
+  };
+  const nodeVersion = deps.nodeVersion ?? process.versions.node;
+  const nodeMajor = Number.parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+  const config = deps.config ?? resolveRuntimeConfig(process.env);
+  const examplePath = resolve5(options.packageDir, ".env.example");
+  const envPath = resolve5(options.targetDir, ".env");
+  const checks = [
+    {
+      name: "node",
+      status: nodeMajor >= NODE_ENGINE_FLOOR ? "pass" : "fail",
+      detail: `Node.js ${nodeVersion} detected; version ${NODE_ENGINE_FLOOR} or newer is required (package.json engines).`
+    },
+    {
+      name: "env-template",
+      status: fsImpl.existsSync(examplePath) ? "pass" : "fail",
+      detail: fsImpl.existsSync(examplePath) ? `Template found: ${examplePath}` : `Template missing: ${examplePath} (expected next to the installed package).`
+    }
+  ];
+  let created = false;
+  if (options.writeEnv) {
+    if (fsImpl.existsSync(envPath)) {
+      checks.push({
+        name: "env-file",
+        status: "pass",
+        detail: `${envPath} already exists; left untouched (no overwrite).`
+      });
+    } else if (!fsImpl.existsSync(examplePath)) {
+      checks.push({
+        name: "env-file",
+        status: "fail",
+        detail: `Cannot create ${envPath}: template ${examplePath} is missing.`
+      });
+    } else {
+      try {
+        fsImpl.writeFileSync(envPath, fsImpl.readFileSync(examplePath, "utf-8"), "utf-8");
+        created = true;
+        checks.push({
+          name: "env-file",
+          status: "pass",
+          detail: `Created ${envPath} from template; edit it and set GOOGLE_MAPS_API_KEY.`
+        });
+      } catch (error) {
+        checks.push({
+          name: "env-file",
+          status: "fail",
+          detail: `Failed to create ${envPath}: ${error instanceof Error ? error.message : String(error)}`
+        });
+      }
+    }
+  } else {
+    checks.push({
+      name: "env-file",
+      status: fsImpl.existsSync(envPath) ? "pass" : "skip",
+      detail: fsImpl.existsSync(envPath) ? `${envPath} found.` : `${envPath} not found; rerun with --write-env to create it from the template.`
+    });
+  }
+  checks.push({
+    name: "api-key",
+    status: config.apiKey ? "pass" : "fail",
+    detail: config.apiKey ? `GOOGLE_MAPS_API_KEY is configured (source: ${config.apiKeySource}, value hidden).` : "GOOGLE_MAPS_API_KEY is not configured. Set it in the environment or in .env after scaffolding."
+  });
+  return {
+    success: checks.every((check) => check.status !== "fail"),
+    created,
+    checks
+  };
+}
+function runSnippetCommand(options, streams = { stdout: process.stdout, stderr: process.stderr }) {
+  try {
+    const snippet = renderClientSnippet(options);
+    streams.stdout.write(snippet.json + "\n");
+    for (const note of snippet.notes) {
+      streams.stderr.write(`[snippet] ${note}
+`);
+    }
+    return 0;
+  } catch (error) {
+    streams.stderr.write(
+      JSON.stringify({ error: error instanceof Error ? error.message : String(error) }, null, 2) + "\n"
+    );
+    return 1;
+  }
+}
+function runEnableDisableCliCommand(name, enable, options = {}) {
+  const streams = options.streams ?? { stdout: process.stdout, stderr: process.stderr };
+  const target = resolveCliTarget(name);
+  if (target === void 0) {
+    streams.stderr.write(
+      JSON.stringify({ error: `Unsupported CLI: ${name}. Supported: ${supportedCliNames()}.` }, null, 2) + "\n"
+    );
+    return 2;
+  }
+  const settings = loadCliSettings(options.home);
+  const already = settings.enabled.includes(target.id);
+  if (enable === already) {
+    streams.stdout.write(
+      JSON.stringify({ cli: target.id, enabled: enable, message: `${target.id} is already ${enable ? "enabled" : "disabled"}.` }, null, 2) + "\n"
+    );
+    return 0;
+  }
+  settings.enabled = enable ? [...settings.enabled, target.id] : settings.enabled.filter((item) => item !== target.id);
+  saveCliSettings(settings, options.home);
+  streams.stdout.write(
+    JSON.stringify({ cli: target.id, enabled: enable, message: `${enable ? "Enabled" : "Disabled"} ${target.id}.` }, null, 2) + "\n"
+  );
+  return 0;
+}
+function runInstallUninstallCommand(operation, options) {
+  const streams = options.streams ?? { stdout: process.stdout, stderr: process.stderr };
+  if (loadCliSettings(options.home).enabled.length === 0) {
+    streams.stdout.write(
+      JSON.stringify(
+        {
+          success: true,
+          message: "No CLI enabled. Use 'mcp-google-map enable <cli name>' first.",
+          summaries: [],
+          errors: []
+        },
+        null,
+        2
+      ) + "\n"
+    );
+    return 0;
+  }
+  let result;
+  try {
+    result = operation === "install" ? installEnabledCliResources({ home: options.home, apiKey: options.apiKey, resourcesRoot: options.resourcesRoot }) : 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"
+    );
+    return 1;
+  }
+  streams.stdout.write(
+    JSON.stringify({ success: result.errors.length === 0, operation, summaries: result.summaries, errors: result.errors }, null, 2) + "\n"
+  );
+  return result.errors.length > 0 ? 1 : 0;
+}
+function runShowCommand(options) {
+  const streams = options.streams ?? { stdout: process.stdout, stderr: process.stderr };
+  try {
+    streams.stdout.write(buildCliShowReport(options) + "\n");
+    return 0;
+  } catch (error) {
+    streams.stderr.write(
+      JSON.stringify({ error: error instanceof Error ? error.message : String(error) }, null, 2) + "\n"
+    );
+    return 1;
+  }
+}
 var isRunDirectly = process.argv[1] && (process.argv[1].endsWith("cli.ts") || process.argv[1].endsWith("cli.js") || process.argv[1].endsWith("mcp-google-map") || process.argv[1].includes("mcp-google-map"));
 var isMainModule = import.meta.url === `file://${process.argv[1]}`;
 if (isRunDirectly || isMainModule) {
+  loadEnvironment(extractEnvFileOption(process.argv));
   let packageVersion = "0.0.0";
   try {
-    const packageJsonPath = resolve(__dirname, "../package.json");
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    const packageJsonPath = resolve5(__dirname, "../package.json");
+    const packageJson = JSON.parse(readFileSync4(packageJsonPath, "utf-8"));
     packageVersion = packageJson.version;
   } catch (e) {
     packageVersion = "0.0.0";
@@ -1564,6 +2637,9 @@ if (isRunDirectly || isMainModule) {
       type: "boolean",
       default: false,
       description: "Make billable test requests to Geocoding, Places (New), and Routes APIs"
+    }).option("probes", {
+      type: "string",
+      description: "Comma-separated subset of live probes: geocoding, places-new, routes (default: all three)"
     }).option("apikey", {
       alias: "k",
       type: "string",
@@ -1571,13 +2647,175 @@ if (isRunDirectly || isMainModule) {
       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", "Also verify three Google Maps APIs with billable requests"],
+      ["$0 doctor --live --probes geocoding,routes", "Probe only the selected APIs"]
     ]),
     async (argv) => {
-      const report = await runDoctor(packageVersion, argv.apikey, argv.live);
+      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", {
+      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"
+    }).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",
@@ -1667,11 +2905,11 @@ if (isRunDirectly || isMainModule) {
           if (trimmed) lines.push(trimmed);
         }
       } else {
-        if (!existsSync(argv.input)) {
+        if (!existsSync4(argv.input)) {
           console.error(`Error: File not found: ${argv.input}`);
           process.exit(1);
         }
-        lines = readFileSync(argv.input, "utf-8").split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+        lines = readFileSync4(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.");
@@ -1714,7 +2952,7 @@ if (isRunDirectly || isMainModule) {
       const summary = { total: lines.length, succeeded, failed, results };
       const json = JSON.stringify(summary, null, 2);
       if (argv.output) {
-        writeFileSync(argv.output, json, "utf-8");
+        writeFileSync3(argv.output, json, "utf-8");
         console.error(`Done: ${succeeded}/${lines.length} succeeded. Output: ${argv.output}`);
       } else {
         console.log(json);
@@ -1732,8 +2970,8 @@ if (isRunDirectly || isMainModule) {
         default: process.env.MCP_SERVER_PORT ? parseInt(process.env.MCP_SERVER_PORT) : 3e3
       }).option("host", {
         type: "string",
-        description: "Hostname to bind the server to (e.g. 0.0.0.0 for all interfaces)",
-        default: process.env.MCP_SERVER_HOST || "0.0.0.0"
+        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",
@@ -1754,6 +2992,7 @@ if (isRunDirectly || isMainModule) {
       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);
@@ -1767,19 +3006,37 @@ if (isRunDirectly || isMainModule) {
           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).catch((error) => {
+        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);
         });
       }
     }
-  ).version(packageVersion).alias("version", "v").help().parse();
+  ).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();
 }
 export {
+  DOCTOR_PROBES,
   EXEC_TOOLS,
+  createShutdownHandler,
   execTool,
+  extractEnvFileOption,
+  installShutdownHandlers,
+  parseDoctorProbes,
   runDoctor,
+  runEnableDisableCliCommand,
   runExecCommand,
+  runInstallUninstallCommand,
+  runSetup,
+  runShowCommand,
+  runSnippetCommand,
   startServer
 };
 //# sourceMappingURL=cli.js.map