mcp-google-api 0.22.1 → 0.25.0

package/CHANGELOG.md

@@ -1,7 +1,120 @@
 # Changelog
 
-## [0.22.1](https://github.com/Ogekuri/mcp-google-api/compare/v0.22.0..v0.22.1) - 2026-11-06
+## [0.25.0](https://github.com/Ogekuri/mcp-google-api/compare/v0.24.0..v0.25.0) - 2026-11-08
 ### 🐛  Bug Fixes
+- make doctor spawn tests hermetic with isolated home [useReq] *(cliSpawn)*
+  - Root cause of the CI-only failure: the doctor spawn test inherited the
+  - host HOME, so it read the developer machine's real
+  - ~/.config/mcp-google-api/config.json; locally the real API key made the
+  - REQ-070 api-key check pass (exit 0), while the clean CI runner had no
+  - settings file, so doctor correctly exited 1 and the gate failed.
+  - spawnCli now accepts an injectable HOME override; the doctor success
+  - test provisions an isolated home with the DES-018 settings fixture and
+  - a valid-format test key, so local runs reproduce the CI runner state
+  - exactly and the discrepancy can no longer hide before publication.
+  - Add a REQ-070 regression pin: doctor exits 1 on a clean isolated home
+  - without a configured API key (the exact CI failure state).
+  - Evidence: clean-HOME reproduction exited 1 with api-key fail before the
+  - fix; after the fix the suite passes 4/4 both with the real and a clean
+  - HOME; full suite 146/146; local pre-release gate green (exit 0).
+  - No source changes: doctor clean-env exit-1 behavior is REQ-070-correct.
+
+## [0.24.0](https://github.com/Ogekuri/mcp-google-api/compare/v0.23.0..v0.24.0) - 2026-11-08
+### ⛰️  Features
+- add pre-release-check.sh release gate [useReq] *(scripts)*
+  - Ship scripts/pre-release-check.sh running the release-gating stages
+  - in mandatory order: publish-version guard, typecheck, unit tests,
+  - production build, aborting at the first failed stage (PKG-058/059).
+  - The script exits 0 only when every stage passes, runs from any cwd
+  - by resolving the repository root, and never installs dependencies
+  - or publishes (PKG-060).
+  - Add tests/preReleaseCheck.unit.test.ts (TST-024): static contract on
+  - stage order, fail-fast wiring, repository-root cd, and no install/
+  - publish commands, plus a sandbox run proving fail-fast exit 1 on an
+  - injected failing stage.
+  - Runtime verification: full run green (guard 0.23.0 publishable,
+  - typecheck clean, 143/143 unit tests, build success, exit 0); real
+  - fail-fast observed on a missing-toolchain run (typecheck FAILED ->
+  - exit 1, later stages skipped).
+
+### 🐛  Bug Fixes
+- sync package-lock bin path with package.json launcher [useReq] *(packaging)*
+  - The committed package-lock.json root bin entry still recorded the
+  - superseded dist/cli.js launcher, so every standard bootstrap
+  - (npm install) rewrote the tracked lockfile and left a fresh clone dirty.
+  - Regenerate the lockfile bin entry to bin/mcp-google-api.mjs, matching
+  - the package.json launcher contract (PRJ-020).
+  - Add a level-0 regression guard test asserting lockfile/package.json
+  - bin-map identity to tests/npmPublishContract.unit.test.ts, closing
+  - the TST-021 coverage gap that let the drift go undetected.
+  - Evidence: reproducer red on the stale lockfile, green after the fix;
+  - full suite 138/138 pass, typecheck clean, static analysis clean.
+
+### 🚜  Changes
+- gate pipeline on pre-release test checks [useReq] *(release)*
+  - Add a Pre-release check step to .github/workflows/release-npm.yml
+  - running scripts/pre-release-check.sh after npm ci and before every
+  - build, pack, publish, and release-creation step, so versions whose
+  - tests fail produce no release artifact and are never published
+  - (PKG-063).
+  - The gate executes the PKG-058 stages (publish-version guard,
+  - typecheck, unit tests, build) in fail-fast order (PKG-059) and never
+  - installs dependencies or publishes (PKG-060).
+  - Update the workflow header and pack-step comments; the release
+  - pipeline defines no direct test commands - all test stages live in
+  - the gate script.
+  - SRS: add PKG-063 and extend TST-020 with the gate contract.
+  - Tests: ciContract asserts gate presence, placement, and absence of
+  - direct test commands; suite 6/6, full suite 145/145.
+- clean run-created artifacts in pre-release-check [useReq] *(scripts)*
+  - scripts/pre-release-check.sh now snapshots the repository state before
+  - the stages and removes on exit every artifact directory the run created
+  - (e.g. the tsup dist/ tree), on both success and fail-fast paths, so the
+  - repository is left as found (PKG-061).
+  - Pre-existing artifact directories are preserved untouched (PKG-062).
+  - SRS: add PKG-061/PKG-062 and extend TST-024 with the cleanup contract.
+  - Tests: shared sandbox helper plus two behavioral proofs - run-created
+  - dist removed on the fail-fast path, pre-existing dist sentinel intact.
+  - Verification: suite 7/7; full run 145/145 tests with dist removed after
+  - the run; pre-existing dist preserved in a second scenario; static
+  - analysis clean; git status clean after every run.
+
+## [0.23.0](https://github.com/Ogekuri/mcp-google-api/compare/v0.22.0..v0.23.0) - 2026-11-07
+### ⛰️  Features
+- add copilot CLI agent support (DES-017, REQ-110/112/113/117) [useReq] *(cli-targets)*
+  - Requirements: extend DES-017, REQ-110, REQ-112, REQ-113, REQ-117 with the copilot target
+  - Source: add COPILOT_TARGET adapter (~/.copilot/mcp.json JSON mcpServers + ~/.copilot/skills) to CLI_TARGETS registry in src/utils/cliTargets.ts
+  - Docs: README supported-agents list/table and WORKFLOW/REFERENCES runtime model updated
+  - Verification: eslint/tsc clean, npm test 132/132 pass, enable/show/install runtime smoke on isolated HOME
+
+### 🐛  Bug Fixes
+- build dist via prepare lifecycle for GitHub installs [useReq] *(packaging)*
+  - Develop-channel installs (npm install -g github:Ogekuri/mcp-google-api#<tag>,
+  - REQ-171) packed the fetched git tree without dist/: no build lifecycle ran, so
+  - every installed package hit the PRJ-021 remediation error and the post-upgrade
+  - install child failed (evidence: v0.22.4 pack listing had 0 dist entries).
+  - package.json: declare scripts.prepare = npm run build so npm git-dep
+  - preparation builds dist/ into the packed tarball (PRJ-020; verified by
+  - local git-sim packs: 8 dist entries incl. dist/cli.js).
+  - tests/npmPublishContract.unit.test.ts: add failing-first reproducer test
+  - pinning the prepare lifecycle contract (no chained installs, PKG-019) and
+  - restore deterministic pack listing via --ignore-scripts.
+  - usereq/docs/WORKFLOW.md: document the prepare build inside EDGE-09.
+- spawn package-manager child with neutral home cwd [useReq] *(upgrade)*
+  - Defect: --upgrade (npm and --dev|--develop channels) and --uninstall
+  - spawned npm from the caller's working directory. When invoked from the
+  - source checkout of the same package (scripts/mcp-google-api.sh cd's to
+  - the repo root), npm reconciled the git-ref global install against that
+  - same-name local project and corrupted reify: TAR_ENTRY_ERROR ENOENT
+  - floods on hono/@modelcontextprotocol/sdk/@grpc/grpc-js plus a fatal
+  - lifecycle 'spawn sh ENOENT' (protobufjs) against a cwd deleted
+  - mid-reify.
+  - Fix: runPackageManagerCommand spawns the child with cwd = os.homedir()
+  - (explicit neutral directory, env/prefix unchanged); stdio inheritance,
+  - exit propagation, and the REQ-128 manual-command hint are unchanged.
+  - Reproducer test (HDT Level 1) added to tests/upgradeManager.unit.test.ts:
+  - asserts the child cwd is the user home and never the caller cwd; suite
+  - went 11 pass / 1 fail before the fix to 136/136 after.
 - report skipped server-start dispatch with build remediation [useReq] *(cli)*
   - Root cause of the persistent pi 'MCP connection closed' after the 0.21.0 rename:
   - the REQ-114 launcher 'npx -y mcp-google-api start --stdio' resolves a same-name
@@ -16,6 +129,118 @@
   - Document the stale-artifact remediation in docs/CONFIGURATION.md; update
   - WORKFLOW.md TRACE-A/EDGE-06 and regenerate REFERENCES.md.
 
+### 🚜  Changes
+- make --upgrade update unconditionally [useReq] *(upgradeManager)*
+  - --upgrade now reinstalls mcp-google-api@latest in every invocation,
+  - without any pre-upgrade version comparison (REQ-146 rewrite).
+  - Removed the pre-upgrade registry necessity check and the
+  - already-latest skip path (REQ-144, REQ-145, REQ-147 deleted) and the
+  - pre-upgrade-latest summary shortcut (REQ-181 deleted); REQ-172
+  - reworded since the comparison no longer exists.
+  - The summary updated version now comes from the post-upgrade probe
+  - (REQ-134); unused isUpgradeNecessary removed.
+  - Requirements, workflow model, and references updated; typecheck and
+  - 136 unit tests pass.
+- self-heal npm reify ENOENT in --upgrade [useReq] *(upgradeManager)*
+  - --upgrade update children (npm and --develop/--dev channels) run with
+  - captured output echoed on stderr (REQ-125, REQ-171).
+  - A non-zero exit carrying an ENOENT reify diagnostic triggers one
+  - tolerated npm uninstall -g clean-slate child plus a single retry,
+  - repairing corrupted global trees whose dependency lifecycle spawns
+  - fail like the reported 'spawn sh ENOENT' (REQ-182, REQ-183).
+  - Requirements, workflow model, and references updated; typecheck and
+  - 136 unit tests pass.
+- resolve npmjs latest via packument manifest [useReq] *(upgradeManager)*
+  - --ver/--version now probe the npm packument manifest with the
+  - abbreviated Accept header and print dist-tags.latest (REQ-179, REQ-180).
+  - --upgrade reports the pre-upgrade npmjs latest as the summary updated
+  - version and skips the post-upgrade probe when resolved (REQ-181).
+  - REQUIREMENTS/WORKFLOW/REFERENCES updated; typecheck and 136 unit
+  - tests pass.
+- ship mcp-google-api launcher bin with remediation [useReq] *(bin)*
+  - PRJ-020: the installed mcp-google-api bin executes the packaged
+  - dist/cli.js Node entry forwarding every argument unchanged with no
+  - implicit install/build steps (analogous to scripts/mcp-google-api.sh).
+  - PRJ-021: new launcher bin/mcp-google-api.mjs (realpath-safe package-root
+  - resolution) prints JSON build-remediation guidance on stderr and exits
+  - non-zero when dist/cli.js is missing - impossible to deliver from the
+  - built artifact itself.
+  - package.json: bin repointed to bin/mcp-google-api.mjs; files allowlist
+  - ships bin/ (verified in npm pack --dry-run); .gitignore gains !bin/
+  - exceptions (CTN-010).
+  - PKG-038 publication fixture updated for the bin/ prefix; verified live:
+  - launcher forwards (--help, exit 0) and remediates (exit 1, JSON stderr);
+  - 136/136 tests, typecheck and eslint clean.
+- add develop-channel coverage for --upgrade --dev|--develop [useReq] *(test)*
+  - TST-023: new test requirement mapping REQ-170/171/172/173/177/178 to
+  - tests/upgradeManager.unit.test.ts.
+  - HDT Level 0: buildDevelopUpgradeCommand builds the raw tag install
+  - command npm install -g github:Ogekuri/mcp-google-api#<tag>.
+  - HDT Level 1: the develop channel probes only the GitHub releases
+  - endpoint bypassing the idle cache (REQ-177), spawns the tagged install
+  - with the raw tag_name (REQ-171), always proceeds even when the probed
+  - tag equals the installed version (REQ-172), reports the probed version
+  - in the summary (REQ-173), and fails fast on probe error without
+  - spawning any child process (REQ-178).
+  - No src/ changes: verification confirmed the implementation already
+  - satisfied the request; 135/135 tests, typecheck and eslint clean.
+- move publish guard to tools/ with gitignore exception [useReq] *(tools)*
+  - Move scripts/check-publish-version.mjs to tools/ (PKG-057 updated):
+  - the ../package.json resolution keeps working at the same directory
+  - depth; guard verified executable from the new path (exit 0).
+  - Wire package.json check:publish-version to the new path; the
+  - prepublishOnly chain (PKG-005, PKG-017) is unchanged.
+  - .gitignore: append !tools/ and !tools/**/* at the tail of the
+  - negated-inclusion included-paths section (CTN-009); git check-ignore
+  - confirms the guard is version-controlled.
+  - requirements: scripts/ tree entry reduced to the mcp-google-api.sh
+  - launcher; tools/ entry added for the publish guard.
+- BREAKING CHANGE: remove redundant shell helpers, document HTTP vs stdio [useReq] *(scripts)*
+  - Delete scripts/build.sh, start-http.sh, start-mcp.sh, test.sh: thin
+  - wrappers over npm run build/start/test/test:e2e; PKG-019 keeps the
+  - single npm run verify pipeline and REQ-094 forbids implicit builds.
+  - scripts/ now holds only mcp-google-api.sh (PRJ-018, PRJ-019) and the
+  - retained check-publish-version.mjs publish guard: required prepublishOnly
+  - stage, not an end-user accessory (PKG-057, PKG-005, PKG-017).
+  - README: new 'stdio vs Streamable HTTP' comparison section (PKG-054,
+  - PKG-055, PKG-056).
+  - Remove the obsolete start-mcp.sh remediation test whose subject was
+  - deleted; no src/ changes, WORKFLOW.md unaffected.
+- --dev|--develop installs the latest tagged GitHub release [useReq] *(upgrade)*
+  - REQ-170..173: --upgrade --develop|--dev now selects the latest tagged
+  - GitHub release regardless of the branch carrying the tag; REQ-177 adds
+  - the forced releases-API probe bypassing the idle cache gate; REQ-178
+  - fails fast with a stderr diagnostic and no child spawn on probe failure.
+  - upgradeManager: GITHUB_UPGRADE_REPOSITORY + buildDevelopUpgradeCommand(tag)
+  - replace PACKAGE_DEVELOP_UPGRADE_COMMAND; develop branch probes GitHub first,
+  - installs github:Ogekuri/mcp-google-api#<tag>, and reports the probed version.
+  - autoUpdate: GitHubLatestVersionProbe ok outcome now carries the raw tag_name.
+  - cli: help text and dispatch comments document the new channel semantics.
+- BREAKING CHANGE: remove legacy exec aliases, placeholder key, entry-gate fallback [useReq] *(cli)*
+  - BREAKING: exec accepts only canonical maps_ tool names (REQ-073); short/snake_case/batch-geocode-tool aliases removed from EXEC_TOOLS, execTool switch, help examples, and README.
+  - BREAKING: legacy INSTALL_API_KEY_PLACEHOLDER config value no longer loads as unset (DES-023, REQ-142); empty values still do.
+  - BREAKING: superseded isRunDirectly basename entry-gate removed; isEntryMainModule() alone decides dispatch.
+  - DOCTOR_PROBES use canonical tool names; tests canonicalized per user-requested legacy removal.
+  - Verified: typecheck, static-check clean, npm test 132/132; exec geocode now rejected as unknown tool.
+- make --help user-facing and document --develop/--dev [useReq] *(cli)*
+  - REQ-174: help descriptions limited to user-facing usage; removed internal details (persisted configuration, settings file, dispatch order, dist/cli.js path).
+  - REQ-175: --upgrade epilog documents the --develop | --dev GitHub develop-branch option.
+  - REQ-176: --ver described accurately as installed, npmjs-latest, and GitHub-latest versions.
+  - Verified facts kept: exec alias list (batch-geocode-tool) and search-nearby example params match the schema.
+  - Verified: static-check clean, npm test 132/132 (help contract REQ-129/130/131 intact).
+- add --develop/--dev GitHub develop-branch upgrade channel [useReq] *(upgrade-manager)*
+  - REQ-170..173: --upgrade accepts --develop with equivalent --dev alias selecting the GitHub develop branch.
+  - REQ-125/REQ-144 scoped to the default npm channel; develop channel skips the registry gate and already-latest path.
+  - upgradeManager: UpgradeChannel, PACKAGE_DEVELOP_UPGRADE_COMMAND (npm install -g github:Ogekuri/mcp-google-api#develop), parseUpgradeChannel; parseManagementCommand accepts the --upgrade + --develop/--dev pair.
+  - Develop-channel summary reports unknown as the updated version; default npm path unchanged.
+  - WORKFLOW.md TRACE-A/L and EDGE-07/09 updated; REFERENCES.md regenerated.
+  - Verified: typecheck, static-check clean, npm test 132/132.
+- encode README header block structure and centered quick index [useReq] *(readme)*
+  - Add requirements PKG-046..PKG-053: [!CAUTION] pre-header, exact title format, centered badge/description/quick-index/status blocks, fixed H1 section order, quick-start step order.
+  - Rebuild README header: centered description block (strong summary + br + detail), HTML quick-index anchors now including Requirements, single status+notice centered block.
+  - No source-code change; WORKFLOW.md runtime model unaffected; REFERENCES.md regenerated unchanged.
+  - Verified: static-check clean; npm test 132/132 pass.
+
 ## [0.22.0](https://github.com/Ogekuri/mcp-google-api/compare/v0.21.0..v0.22.0) - 2026-11-06
 ### 🐛  Bug Fixes
 - symlink-aware main-module gate restores CLI dispatch [useReq] *(cli)*
@@ -409,7 +634,9 @@
 - \[0.20.0\]: https://github.com/Ogekuri/mcp-google-api/releases/tag/v0.20.0
 - \[0.21.0\]: https://github.com/Ogekuri/mcp-google-api/releases/tag/v0.21.0
 - \[0.22.0\]: https://github.com/Ogekuri/mcp-google-api/releases/tag/v0.22.0
-- \[0.22.1\]: https://github.com/Ogekuri/mcp-google-api/releases/tag/v0.22.1
+- \[0.23.0\]: https://github.com/Ogekuri/mcp-google-api/releases/tag/v0.23.0
+- \[0.24.0\]: https://github.com/Ogekuri/mcp-google-api/releases/tag/v0.24.0
+- \[0.25.0\]: https://github.com/Ogekuri/mcp-google-api/releases/tag/v0.25.0
 
 [0.2.0]: https://github.com/Ogekuri/mcp-google-api/releases/tag/v0.2.0
 [0.3.0]: https://github.com/Ogekuri/mcp-google-api/compare/v0.2.0..v0.3.0
@@ -431,4 +658,6 @@
 [0.20.0]: https://github.com/Ogekuri/mcp-google-api/compare/v0.19.0..v0.20.0
 [0.21.0]: https://github.com/Ogekuri/mcp-google-api/compare/v0.20.0..v0.21.0
 [0.22.0]: https://github.com/Ogekuri/mcp-google-api/compare/v0.21.0..v0.22.0
-[0.22.1]: https://github.com/Ogekuri/mcp-google-api/compare/v0.22.0..v0.22.1
+[0.23.0]: https://github.com/Ogekuri/mcp-google-api/compare/v0.22.0..v0.23.0
+[0.24.0]: https://github.com/Ogekuri/mcp-google-api/compare/v0.23.0..v0.24.0
+[0.25.0]: https://github.com/Ogekuri/mcp-google-api/compare/v0.24.0..v0.25.0

package/README.md

@@ -10,7 +10,7 @@
 > * **No Support or Feature Requests:** please **do not** open issues, bug reports, or feature requests. They will not be addressed or accepted at this stage.
 > * **No Warranty:** this software is provided **"AS IS"**, without warranty of any kind, express or implied. Use it strictly for testing and evaluation purposes at your own sole risk.
 
-# mcp-google-api / MCP Google API server (0.22.1)
+# mcp-google-api / MCP Google API server (0.25.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/node-%3E%3D24-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js >= 24">
@@ -19,15 +19,25 @@
   <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-6A7EC2?style=flat-square&logo=terminal&logoColor=white" alt="Platforms">
 </p>
 
-**MCP Google API server** — Google APIs for AI agents over the [Model Context Protocol](https://modelcontextprotocol.io).
-
-The server exposes Google API families to AI agents over stdio or Streamable HTTP. The currently implemented family is **Google Maps**, providing 18 read-only tools: geocoding and reverse geocoding, Places API (New) text/nearby search with server-side filters (`priceLevels`, `minRating`, `strictTypeFiltering`), place details, directions, distance matrix, timezone, elevation, weather, air quality, static maps, batch geocode, and the composite tools explore-area, plan-route, compare-places, search-along-route, and local-rank-tracker. Tools are declared read-only, non-destructive, idempotent, and open-world via MCP annotations. The server ships the **eatspot-discovery** agent skill for budget-, quality-, category-, and schedule-validated venue search, and installs itself plus its skills into supported CLI agents (pi, OpenClaw, Codex, Antigravity, Claude) with one command.
-
-[Feature Highlights](#feature-highlights) | [Quick Start](#quick-start) | [User's Guide](#users-guide) | [Acknowledgments](#acknowledgments)
+<p align="center">
+  <strong>MCP Google API server — Google APIs for AI agents over the <a href="https://modelcontextprotocol.io">Model Context Protocol</a></strong>
+  <br>
+  The server exposes Google API families to AI agents over stdio or Streamable HTTP. The currently implemented family is <strong>Google Maps</strong>, providing 18 read-only tools: geocoding and reverse geocoding, Places API (New) text/nearby search with server-side filters (<code>priceLevels</code>, <code>minRating</code>, <code>strictTypeFiltering</code>), place details, directions, distance matrix, timezone, elevation, weather, air quality, static maps, batch geocode, and the composite tools explore-area, plan-route, compare-places, search-along-route, and local-rank-tracker. Tools are declared read-only, non-destructive, idempotent, and open-world via MCP annotations. The server ships the <strong>eatspot-discovery</strong> agent skill for budget-, quality-, category-, and schedule-validated venue search, and installs itself plus its skills into supported CLI agents (pi, OpenClaw, Codex, Antigravity, Claude) with one command.
+</p>
 
-🚧 **DRAFT:** Proof-of-Concept (PoC) Version 📝 — Work in Progress 🏗️ 🚧
+<p align="center">
+  <a href="#feature-highlights">Feature Highlights</a> |
+  <a href="#quick-start">Quick Start</a> |
+  <a href="#requirements">Requirements</a> |
+  <a href="#users-guide">User's Guide</a> |
+  <a href="#acknowledgments">Acknowledgments</a>
+</p>
 
-⚠️ **IMPORTANT NOTICE**: Created with [**PI-useReq/pi-usereq**](https://www.npmjs.com/package/pi-usereq) 🤖✨ ⚠️
+<p align="center">
+  🚧 <strong>STAGE:</strong> PRE-ALPHA 📝 — Proof-of-Concept (PoC), Work in Progress 🏗️ 🚧
+  <br>
+  ⚠️ <strong>IMPORTANT NOTICE</strong>: Created with <a href="https://www.npmjs.com/package/pi-usereq"><strong>PI-useReq/pi-usereq</strong></a> 🤖✨ ⚠️
+</p>
 
 # Feature Highlights
 
@@ -58,7 +68,7 @@ mcp-google-api api-key "AIza..."
 mcp-google-api doctor          # local self-check: Node, package, key, settings (no network)
 ```
 
-**3. Run** — register the server into your CLI agents (supported: `pi`, `openclaw`, `codex`, `antigravity`, `claude`), then start it:
+**3. Run** — register the server into your CLI agents (supported: `pi`, `openclaw`, `codex`, `antigravity`, `claude`, `copilot`), then start it:
 
 ```bash
 mcp-google-api enable pi
@@ -129,10 +139,11 @@ The `--host` and `--port` flags override the persisted settings for a single `st
 | codex | `~/.codex/config.toml` (`mcp_servers` table) | `~/.codex/skills` |
 | antigravity | `~/.gemini/settings.json` | `~/.gemini/config/skills` |
 | claude | `~/.claude.json` | `~/.claude/skills` |
+| copilot | `~/.copilot/mcp.json` | `~/.copilot/skills` |
 
 - **pi**: after installing, run `/reload` in the session if the configuration was changed externally; `/mcp` inspects status, tools, and connection errors.
 - **OpenClaw**: reload the gateway or restart the agent session so the new server gets connected.
-- `mcp-google-api show` prints the CLI Configuration table (all five agents) and the Installation Status table (server + each skill per enabled CLI with OK / MISSING / STALE).
+- `mcp-google-api show` prints the CLI Configuration table (all six agents) and the Installation Status table (server + each skill per enabled CLI with OK / MISSING / STALE).
 - `mcp-google-api install --debug-skills` additionally appends each skill's packaged debug overlay to the installed `SKILL.md`; plain installs and `api-key`/`--upgrade` refreshes never append it, and `show` reports OK in both modes.
 
 ## Running the server
@@ -149,6 +160,17 @@ mcp-google-api run                              # alias of start
 - stdio mode refuses to start without a configured key and exits 1 with a stderr error inviting `mcp-google-api api-key <key>`; HTTP mode starts anyway and logs a warning (per-request header keys remain usable).
 - The automatic update check runs at startup (default on): a newer npm version is reported on stderr only with an upgrade command; it never blocks startup.
 
+### stdio vs Streamable HTTP
+
+| | stdio | Streamable HTTP |
+|---|---|---|
+| Launch | `mcp-google-api start --stdio` (what `install` registers in MCP-client configs) | `mcp-google-api start` or `run`, with optional `--host`/`--port` |
+| Channel | JSON-RPC 2.0 frames over stdin/stdout; stdout carries only protocol traffic, diagnostics go to stderr | HTTP POST/GET/DELETE on `http://<host>:<port>/mcp`; GET upgrades to SSE for server-to-client notifications |
+| API key | resolved once at startup from the persisted `apiKey` setting; startup fails without one | per-request `X-Google-Maps-API-Key` or `Authorization: Bearer` header, then the session key, then the configured setting; startup only warns without one |
+| Typical use | locally registered MCP clients (pi, OpenClaw, Codex, Antigravity, Claude) launched by `install` | remote or multi-client access to one shared server, each client isolated by its `mcp-session-id` |
+
+Use **stdio** when a local MCP client launches the server from its own configuration; use **Streamable HTTP** when several clients, local or remote, share one server instance. Both transports expose the same 18 tools and the same per-session/per-request key isolation semantics.
+
 ## Per-request API keys
 
 On the HTTP transport each request may supply its own key with top priority: the `X-Google-Maps-API-Key` header, or an `Authorization: Bearer <key>` header. Each session (`mcp-session-id`) keeps its session key; the configured `apiKey` setting is the fallback. This lets concurrent clients use isolated credentials against one server.
@@ -167,7 +189,7 @@ mcp-google-api doctor --live --apikey "AIza..." # override the key for the probe
 ## One-shot CLI tools
 
 ```bash
-mcp-google-api exec geocode '{"address":"Tokyo Tower"}'        # run one tool; short/snake_case/maps_-prefixed names accepted
+mcp-google-api exec maps_geocode '{"address":"Tokyo Tower"}'    # run one tool by its canonical maps_ name
 mcp-google-api batch-geocode -i addresses.txt -o results.json # geocode one address per line
 cat addresses.txt | mcp-google-api batch-geocode -i -          # from stdin
 ```

package/bin/mcp-google-api.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * @file mcp-google-api.mjs
+ * @brief Installed distribution bin launcher executing the mcp-google-api Node.js CLI (PRJ-020).
+ * @details Mirrors `scripts/mcp-google-api.sh` for the installed package: resolves the
+ * real package root from this script's own location (realpath-safe against npm's
+ * symlinked global `bin/` links and renamed launchers), verifies the packaged
+ * `dist/cli.js` entry exists, and either forwards every argument unchanged to that
+ * Node.js entry with inherited stdio, propagating its exit code (PRJ-020, PRJ-019
+ * semantics), or prints exactly one JSON build-remediation diagnostic on stderr
+ * naming the package root and the build/refresh commands, exiting non-zero
+ * (PRJ-021; remediation guidance in the REQ-094 family). No implicit install or
+ * build steps are ever executed (PRJ-019). A plain Node.js ESM script is used
+ * instead of pointing the npm `bin` field directly at `dist/cli.js` because a built
+ * artifact cannot detect its own absence: the launcher must stay runnable on stale
+ * or unbuilt distributions to deliver the remediation path. On Windows, npm wraps
+ * this file in a `.cmd` shim that invokes `node`, so the shebang is informational.
+ * @satisfies PRJ-016, PRJ-020, PRJ-021
+ * @note stdout is reserved for the launched CLI; this launcher writes only to
+ * stderr, and only on the missing-artifact remediation path (PRJ-021).
+ * @warning The remediation diagnostic is emitted by this launcher, never by
+ * `dist/cli.js`: a missing artifact bypasses every CLI-side guard (REQ-094 covers
+ * dispatch from an existing artifact; PRJ-021 covers the artifact-missing case).
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const launcherPath = realpathSync(fileURLToPath(import.meta.url));
+const packageRoot = dirname(dirname(launcherPath));
+const cliEntry = join(packageRoot, "dist", "cli.js");
+
+if (!existsSync(cliEntry)) {
+  process.stderr.write(
+    JSON.stringify(
+      {
+        error: "dist/cli.js missing",
+        packageRoot,
+        remediation:
+          "build first: npm ci && npm run build (source checkout) or refresh the global install: npm install -g mcp-google-api@latest",
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+  process.exit(1);
+}
+
+const child = spawnSync(process.execPath, [cliEntry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+process.exit(child.status ?? 1);

package/dist/cli.d.ts

@@ -61,7 +61,7 @@ declare function startServer(port: number, apiKey?: string, host?: string): Prom
 type ShutdownExitHook = (code: number) => void;
 declare function createShutdownHandler(servers: readonly BaseMcpServer[], exitHook?: ShutdownExitHook): (signal: string) => Promise<void>;
 declare function installShutdownHandlers(servers: readonly BaseMcpServer[]): void;
-declare const EXEC_TOOLS: readonly ["geocode", "reverse-geocode", "search-nearby", "search-places", "place-details", "directions", "distance-matrix", "elevation", "timezone", "weather", "explore-area", "plan-route", "compare-places", "air-quality", "static-map", "batch-geocode-tool", "search-along-route", "local-rank-tracker"];
+declare const EXEC_TOOLS: readonly ["maps_geocode", "maps_reverse_geocode", "maps_search_nearby", "maps_search_places", "maps_place_details", "maps_directions", "maps_distance_matrix", "maps_elevation", "maps_timezone", "maps_weather", "maps_explore_area", "maps_plan_route", "maps_compare_places", "maps_air_quality", "maps_static_map", "maps_batch_geocode", "maps_search_along_route", "maps_local_rank_tracker"];
 interface ExecOutput {
     write(chunk: string): unknown;
 }