mcp-google-map 0.6.0 → 0.7.0

package/README.md

@@ -1,4 +1,4 @@
-# mcp-google-map (0.6.0)
+# mcp-google-map (0.7.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/node-%3E%3D22-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js >= 22">
@@ -98,11 +98,11 @@ npm install -g mcp-google-map
 mcp-google-map setup --write-env   # scaffold .env in the current directory (never overwrites)
 $EDITOR .env                       # set GOOGLE_MAPS_API_KEY
 mcp-google-map doctor               # local self-check: Node, package, key, config (no network)
-mcp-google-map --stdio             # MCP server over stdio
-mcp-google-map                      # MCP server over Streamable HTTP at http://127.0.0.1:3000/mcp
+mcp-google-map start --stdio        # MCP server over stdio
+mcp-google-map start                # MCP server over Streamable HTTP at http://127.0.0.1:3000/mcp
 ```
 
-One-shot alternative without a global install: `npx -y mcp-google-map --stdio`.
+One-shot alternative without a global install: `npx -y mcp-google-map start --stdio`.
 
 ### From source (this repository) — cross-platform, no bash required
 
@@ -111,8 +111,8 @@ git clone https://github.com/Ogekuri/mcp-google-map.git
 cd mcp-google-map
 npm ci                             # install dependencies from the lockfile
 npm run build                       # tsup -> dist/ (ESM)
-node dist/cli.js --stdio            # MCP server over stdio
-node dist/cli.js --host 127.0.0.1 --port 3000   # Streamable HTTP at /mcp
+node dist/cli.js start --stdio            # MCP server over stdio
+node dist/cli.js start --host 127.0.0.1 --port 3000   # Streamable HTTP at /mcp
 ```
 
 On Linux/macOS the bash helpers in `scripts/` wrap the same commands (`scripts/setup.sh`, `scripts/build.sh`, `scripts/start-mcp.sh`, `scripts/start-http.sh`, `scripts/test.sh`); each helper fails with remediation guidance instead of chaining implicit installs or builds. On Windows use the `npm`/`node` commands above.
@@ -124,7 +124,7 @@ MCP client registration over stdio works cross-platform with plain `node`:
   "mcpServers": {
     "mcp-google-map": {
       "command": "node",
-      "args": ["/absolute/path/to/mcp-google-map/dist/cli.js", "--stdio"],
+      "args": ["/absolute/path/to/mcp-google-map/dist/cli.js", "start", "--stdio"],
       "env": { "GOOGLE_MAPS_API_KEY": "AIza..." }
     }
   }
@@ -155,8 +155,8 @@ mcp-google-map snippet --transport http --port 3100              # HTTP URL snip
 All commands work through the `mcp-google-map` binary (npm install) or `node dist/cli.js` (from source).
 
 ```bash
-mcp-google-map --stdio                                  # MCP server over stdio
-mcp-google-map --host 127.0.0.1 --port 3000             # MCP server over Streamable HTTP at /mcp (loopback default)
+mcp-google-map start --stdio                            # MCP server over stdio
+mcp-google-map start --host 127.0.0.1 --port 3000       # MCP server over Streamable HTTP at /mcp (loopback default)
 mcp-google-map setup --write-env                        # onboarding: readiness checks + .env scaffold (no network, no prompts)
 mcp-google-map doctor                                   # local self-check: Node, package, key, config, tool profiles (no network)
 mcp-google-map doctor --live --apikey "AIza..."         # also probes Geocoding, Places (New), Routes (billable calls)
@@ -178,7 +178,7 @@ mcp-google-map snippet --client cursor                  # print an MCP client re
 - `snippet` prints a valid `mcpServers` JSON registration to stdout (guidance notes on stderr) and never writes or edits configuration files; by default it embeds a literal placeholder, and `--env-key NAME` emits a `${NAME}` reference whose expansion is client-specific.
 - `--env-file <path>` loads exactly the given environment file for any command and exits 1 with a JSON error when the file is missing (no implicit `.env` fallback).
 - `enable <cli>` / `disable <cli>` manage the persisted enabled-CLI set at `~/.config/mcp-google-map/config.json`; accepted names (case-insensitive): `pi`, `openclaw`, `codex`, `antigravity`, `claude`; unsupported names exit 2 listing the supported ones.
-- `install` registers for every enabled CLI the stdio server entry `mcp-google-map` (`npx -y mcp-google-map --stdio`, embedding the resolved `GOOGLE_MAPS_API_KEY` when set) and installs every bundled skill; `uninstall` is the reciprocal removal. Per-CLI targets: pi `~/.pi/agent/mcp.json` + `~/.pi/agent/skills`, openclaw `~/.openclaw/openclaw.json` + `~/.openclaw/workspace/skills`, codex `~/.codex/config.toml` (`mcp_servers` table) + `~/.codex/skills`, antigravity `~/.gemini/settings.json` + `~/.gemini/config/skills`, claude `~/.claude.json` + `~/.claude/skills`. Existing unrelated configuration entries are always preserved.
+- `install` registers for every enabled CLI the stdio server entry `mcp-google-map` (`npx -y mcp-google-map start --stdio`, embedding the resolved `GOOGLE_MAPS_API_KEY` when set) and installs every bundled skill; `uninstall` is the reciprocal removal. Per-CLI targets: pi `~/.pi/agent/mcp.json` + `~/.pi/agent/skills`, openclaw `~/.openclaw/openclaw.json` + `~/.openclaw/workspace/skills`, codex `~/.codex/config.toml` (`mcp_servers` table) + `~/.codex/skills`, antigravity `~/.gemini/settings.json` + `~/.gemini/config/skills`, claude `~/.claude.json` + `~/.claude/skills`. Existing unrelated configuration entries are always preserved.
 - `show` prints two human-readable tables: CLI Configuration (CLI, Enabled, MCP Config Path, Skills Config Path for all five CLIs) and Installation Status (Type, Name, CLI, Enabled, Installed with OK/MISSING/STALE per enabled CLI).
 - HTTP mode starts even without an API key and logs a warning; stdio mode and the CLI commands require a key (`--apikey` or `GOOGLE_MAPS_API_KEY`). When no HTTP instance can start (invalid or taken port), the process exits non-zero.
 
@@ -220,14 +220,14 @@ pi reads MCP servers from `~/.pi/agent/mcp.json` (user) or `.pi/mcp.json` (proje
   "mcpServers": {
     "maps": {
       "command": "node",
-      "args": ["/absolute/path/to/mcp-google-map/dist/cli.js", "--stdio"],
+      "args": ["/absolute/path/to/mcp-google-map/dist/cli.js", "start", "--stdio"],
       "env": { "GOOGLE_MAPS_API_KEY": "${GOOGLE_MAPS_API_KEY}" }
     }
   }
 }
 ```
 
-- From a terminal: `pi mcp add maps -- node /absolute/path/to/mcp-google-map/dist/cli.js --stdio` (add `--env GOOGLE_MAPS_API_KEY=...` to pass the key).
+- From a terminal: `pi mcp add maps -- node /absolute/path/to/mcp-google-map/dist/cli.js start --stdio` (add `--env GOOGLE_MAPS_API_KEY=...` to pass the key).
 - `${GOOGLE_MAPS_API_KEY}` expands the environment variable on the fly: the key never stays hard-coded in the configuration file.
 - After editing `mcp.json` outside the session, run `/reload` in pi; `/mcp` inspects status, tools, and connection errors.
 - Tools appear with the `mcp__<server>__` prefix: `mcp__maps__maps_geocode`, `mcp__maps__maps_search_places`, ...
@@ -237,10 +237,10 @@ pi reads MCP servers from `~/.pi/agent/mcp.json` (user) or `.pi/mcp.json` (proje
 OpenClaw manages MCP servers in `~/.openclaw/openclaw.json` through its CLI (verified on OpenClaw 2026.4.21):
 
 ```bash
-openclaw mcp set maps '{"command":"node","args":["/absolute/path/to/mcp-google-map/dist/cli.js","--stdio"],"env":{"GOOGLE_MAPS_API_KEY":"AIza..."},"description":"Google Maps: Places API (New), geocoding, routes, weather"}'
+openclaw mcp set maps '{"command":"node","args":["/absolute/path/to/mcp-google-map/dist/cli.js","start","--stdio"],"env":{"GOOGLE_MAPS_API_KEY":"AIza..."},"description":"Google Maps: Places API (New), geocoding, routes, weather"}'
 ```
 
-- Without a local install: use `"command":"npx","args":["-y","mcp-google-map","--stdio"]` (runs the published npm package).
+- Without a local install: use `"command":"npx","args":["-y","mcp-google-map","start","--stdio"]` (runs the published npm package).
 - After the change, reload the gateway or restart the agent session so the new server gets connected.
 - Inspect and remove: `openclaw mcp list`, `openclaw mcp show maps`, `openclaw mcp unset maps`.
 - The OpenClaw agent can install and configure the server on its own (shell + `openclaw mcp set`); creating the API key in Google Cloud Console remains a human task.

package/dist/cli.js

@@ -1594,7 +1594,6 @@ async function checkVersionIdle(deps = {}) {
     case "current":
       lastSuccess = now();
       result.currentVersion = probe.currentVersion;
-      logger.error(red("Version check: no newer version available."));
       break;
     case "newer": {
       lastSuccess = now();
@@ -1788,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.");
     }
@@ -2068,7 +2067,7 @@ function buildServerRegistration(apiKey) {
   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");
@@ -2834,7 +2833,65 @@ if (isRunDirectly || isMainModule) {
       process.exitCode = 1;
     });
   } else {
-    yargs(hideBin(process.argv)).command(
+    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: "Hostname to bind the server to (default 127.0.0.1 loopback; 0.0.0.0 for all interfaces)",
+      default: process.env.MCP_SERVER_HOST || "127.0.0.1"
+    }).option("apikey", {
+      alias: "k",
+      type: "string",
+      description: "Google Maps API key",
+      default: process.env.GOOGLE_MAPS_API_KEY
+    }).option("stdio", {
+      type: "boolean",
+      description: "Use stdio transport instead of HTTP",
+      default: false
+    }).example([
+      ["$0 start", "Start HTTP server with default settings"],
+      ['$0 start --port 3000 --apikey "your_api_key"', "Start HTTP with custom port and API key"],
+      ["$0 start --host 0.0.0.0 --port 3000", "Start HTTP accessible from all interfaces"],
+      ["$0 start --stdio", "Start in stdio mode (for MCP clients)"],
+      ["$0 run --stdio", "Alias: run the server in stdio mode"]
+    ]);
+    const runServerCommand = async (argv) => {
+      if (argv.apikey) {
+        process.env.GOOGLE_MAPS_API_KEY = argv.apikey;
+      }
+      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", {
@@ -3164,67 +3221,34 @@ if (isRunDirectly || isMainModule) {
         process.exit(failed > 0 ? 1 : 0);
       }
     ).command(
-      "$0",
+      "start",
       "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 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);
-          });
-        }
+      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)"
-    }).help().parse();
+    }).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 {