@cablate/mcp-google-map 0.0.63 → 0.0.65

package/skills/_shared/setup-and-diagnostics.md

@@ -0,0 +1,59 @@
+# Setup and diagnostics
+
+Use this procedure before the first Google Maps CLI call in a session and when a call fails. Do not start an MCP server: these Skills use the standalone CLI.
+
+## Local preflight
+
+Run the local doctor first. It makes no Google API requests and does not print the key:
+
+```bash
+npx -y @cablate/mcp-google-map doctor
+```
+
+Interpret its JSON checks:
+
+- `node`: Node.js 18 or newer is required.
+- `package`: the npm package and CLI entrypoint were resolved.
+- `api-key`: `GOOGLE_MAPS_API_KEY` is visible to the agent process; the value stays hidden.
+- `live-api: skip`: expected during local-only diagnosis and not a failure.
+
+If the key is missing, ask the user to set `GOOGLE_MAPS_API_KEY` in the environment used to launch the agent and start a new session. Prefer the environment variable to `--apikey`; command-line keys may appear in shell history or process listings.
+
+## Google Cloud prerequisites
+
+The key must belong to a Google Cloud project with billing enabled and restrictions compatible with the environment. Enable only the APIs needed by the requested tools:
+
+| Capability | Google Maps Platform API |
+|---|---|
+| Address geocoding and reverse geocoding | Geocoding API |
+| Text search, nearby search, place details, along-route place search, comparisons, local rank tracking | Places API (New) |
+| Directions, distance matrix, waypoint optimization, along-route routing | Routes API |
+| Elevation | Elevation API |
+| Timezone | Time Zone API |
+| Weather | Weather API |
+| Air quality | Air Quality API |
+| Static maps | Maps Static API |
+
+## Optional live diagnosis
+
+Only run this after telling the user that it makes billable test requests:
+
+```bash
+npx -y @cablate/mcp-google-map doctor --live
+```
+
+It independently tests Geocoding API, Places API (New), and Routes API so one disabled capability does not hide the others. It does not validate every optional API in the table. Test an optional capability with the smallest relevant tool call only when the user's task needs it.
+
+## Failure classification
+
+| Symptom | Likely cause | Next action |
+|---|---|---|
+| Package or command cannot be found | Node.js/npm unavailable, registry blocked, or package resolution failed | Repair Node/npm or registry access, then rerun local doctor |
+| API key missing | Environment variable was not passed to the agent process | Set the variable and start a new session |
+| `REQUEST_DENIED`, permission, or API-disabled error | API disabled, billing unavailable, or key restriction mismatch | Use the failed check name to review that API and the key restrictions in Google Cloud Console |
+| `OVER_QUERY_LIMIT`, quota, or rate-limit error | Project quota or billing limit | Stop retries and ask the user to review quota/billing |
+| Invalid request | Wrong parameters or unsupported mode | Read the selected tool's parameter reference and correct the request |
+| Network or timeout error | Connectivity, proxy, DNS, or transient service issue | Report the observed failure; retry only when reasonable and requested |
+| One live check fails while others pass | Capability-specific API configuration | Fix only the named API; do not claim the entire key is invalid |
+
+Never include the API key in diagnostic output, copied commands, bug reports, or final answers.

package/skills/google-maps/SKILL.md

@@ -1,84 +1,43 @@
 ---
 name: google-maps
-description: Use Google Maps-backed geocoding, place search, routing, and geographic analysis through the standalone @cablate/mcp-google-map CLI when a user asks about real-world locations. No MCP connection is required.
+description: Search places, resolve addresses, compare routes, inspect neighborhoods, and retrieve geographic or environmental facts through the standalone @cablate/mcp-google-map CLI. Use for concrete location questions; use the travel-planning or local-seo Skill for those specialized outcomes.
 license: MIT
 ---
 
-# Google Maps - Geospatial Query Capabilities
+# Google Maps
 
-## Overview
+Answer real-world location questions with the package's standalone `exec` CLI. Do not start or configure an MCP server for this workflow.
 
-Use the package's `exec` CLI to answer location questions without starting an MCP server. The Skill supplies tool-selection and chaining guidance; the npm package makes the API calls. The user must provide their own Google Maps Platform API key.
+## Before calling the CLI
 
----
-
-## Core Principles
-
-| Principle | Explanation |
-|-----------|-------------|
-| Chain over single-shot | Most geo questions require 2-5 tool calls chained together. See Scenario Recipes in references/tools-api.md for the full patterns. |
-| Match recipe to intent | Map the user's question to a recipe (Trip Planning, Local Discovery, Route Comparison, Neighborhood Analysis, Multi-Stop, Place Comparison, Along the Route) before calling any tool. |
-| Precise input saves trouble | Use coordinates over address strings when available. Use place_id over name search. More precise input = more reliable output. |
-| Output is structured | Every tool returns JSON. Use it directly for downstream computation or comparison — no extra parsing needed. |
-| Present results clearly | Summarize comparisons in a table when it helps; do not pass raw JSON through as the final answer. |
-| Preserve source context | Google Maps content has display, attribution, and retention conditions. Read `references/content-attribution.md` before presenting place reviews, photos, or AI summaries. |
-
----
+- On the first call in a session, or after an execution failure, read `../_shared/setup-and-diagnostics.md` and run the non-billable local preflight.
+- The user must supply `GOOGLE_MAPS_API_KEY`. Never print it or place it in a command unless the user explicitly accepts shell-history and process-list exposure.
+- Before presenting Places reviews, photos, or AI summaries, read `../_shared/content-attribution.md`.
 
-## Tool Map
+## Workflow
 
-18 tools in five categories — pick by scenario:
+1. Identify the concrete location outcome and missing inputs. Do not request details that can be resolved by geocoding or place search.
+2. Read `references/tools-api.md` when exact parameters, response fields, or a multi-tool recipe are needed.
+3. Prefer coordinates over ambiguous addresses and `place_id` over repeated name searches.
+4. Chain only the calls needed for the outcome. Reuse returned identifiers and coordinates.
+5. Treat nonzero exit status or `{ "success": false }` as a failure, not as geographic data.
+6. Summarize the useful result rather than returning raw JSON. Preserve source and attribution metadata where required.
 
-### Place Discovery
-| Tool | When to use | Example |
-|------|-------------|---------|
-| `maps_geocode` | Have an address/landmark, need coordinates | "What are the coordinates of Tokyo Tower?" |
-| `maps_reverse_geocode` | Have coordinates, need an address | "What's at 35.65, 139.74?" |
-| `maps_search_nearby` | Know a location, find nearby places by type | "Coffee shops near my hotel" |
-| `maps_search_places` | Natural language place search | "Best ramen in Tokyo" |
-| `maps_place_details` | Have a place_id, need full info (+ optional photo URLs via `maxPhotos`) | "Opening hours and reviews for this restaurant?" |
-| `maps_batch_geocode` | Geocode multiple addresses at once (max 50) | "Get coordinates for all these offices" |
+## Tool selection
 
-### Routing & Distance
-| Tool | When to use | Example |
-|------|-------------|---------|
-| `maps_directions` | How to get from A to B, including drive-only avoid-tolls/highways controls | "Route from Taipei Main Station to airport avoiding tolls" |
-| `maps_distance_matrix` | Compare distances across multiple points, including drive-only avoid-tolls/highways controls | "Which of these 3 hotels is closest to airport without highways?" |
-| `maps_search_along_route` | Find places along a route (meals, stops) ranked by detour time | "Restaurants between Fushimi Inari and Kiyomizu-dera" |
-
-### Environment
-| Tool | When to use | Example |
-|------|-------------|---------|
-| `maps_elevation` | Query altitude | "Elevation profile along this hiking trail" |
-| `maps_timezone` | Need local time at a destination | "What time is it in Tokyo?" |
-| `maps_weather` | Weather at a location (current or forecast) | "What's the weather in Paris?" |
-| `maps_air_quality` | AQI, pollutants, health recommendations | "Is the air safe for jogging?" |
-
-### Visualization
-| Tool | When to use | Example |
-|------|-------------|---------|
-| `maps_static_map` | Show locations/routes on a map image | "Show me these places on a map" |
-
-### Composite (one-call shortcuts)
-| Tool | When to use | Example |
-|------|-------------|---------|
-| `maps_explore_area` | Overview of a neighborhood | "What's around Tokyo Tower?" |
-| `maps_plan_route` | Multi-stop optimized itinerary (Routes API waypoint optimization, up to 25 stops) with drive-only avoid-tolls/highways controls | "Visit these 5 places efficiently without tolls" |
-| `maps_compare_places` | Side-by-side comparison | "Which ramen shop near Shibuya?" |
-| `maps_local_rank_tracker` | Local SEO grid rank tracking | "How does this dentist rank across the area?" |
-
----
-
-## Known API Limitations
-
-| Tool | Limitation | Workaround |
-|------|-----------|------------|
-| `maps_weather` | Unsupported regions: Japan, China, South Korea, Cuba, Iran, North Korea, Syria | Use web search for weather in these regions |
-| `maps_distance_matrix` | Transit mode may return null in some regions | Fall back to `driving` or `walking` mode, or use `maps_directions` for transit |
-| `maps_plan_route` | Transit mode does not support waypoint optimization | Set `optimize: false` for transit mode |
-| `maps_air_quality` | Works globally including Japan (unlike weather) | — |
-
----
+| Outcome | Preferred tools |
+|---|---|
+| Address or landmark to coordinates | `maps_geocode` |
+| Coordinates to address | `maps_reverse_geocode` |
+| Nearby discovery | `maps_search_nearby`, then `maps_place_details` |
+| Natural-language place search | `maps_search_places`, then `maps_place_details` |
+| Compare candidate places | `maps_compare_places` or search → details → distance matrix |
+| Route or travel-mode comparison | `maps_directions`, `maps_distance_matrix` |
+| Multi-stop route without a broader itinerary | `maps_plan_route` |
+| Things along a route | `maps_search_along_route` |
+| Neighborhood facts | `maps_explore_area` plus targeted nearby searches |
+| Elevation, timezone, weather, or air quality | corresponding environment tool; geocode first when needed |
+| Visual map | `maps_static_map` after locations or a route are known |
 
 ## Invocation
 
@@ -86,30 +45,18 @@ Use the package's `exec` CLI to answer location questions without starting an MC
 npx -y @cablate/mcp-google-map exec <tool> '<json_params>'
 ```
 
-- **API Key**: Set `GOOGLE_MAPS_API_KEY` in the environment. The `-k` flag also works, but may expose the key in shell history or process listings. If no key is available, ask the user to configure one; do not invent results.
-- **Output**: Successful calls return JSON on stdout. A failed call exits nonzero with error details on stderr; report the failure rather than treating it as map data.
-- **Stateless**: each call is independent
-- **Tool names**: CLI accepts both `maps_geocode` and `geocode` short forms
+The CLI accepts both MCP-style names such as `maps_geocode` and short names such as `geocode`. Each call is stateless and returns JSON on stdout.
 
----
-
-## When to Update This Skill
-
-| Trigger | What to update |
-|---------|----------------|
-| New tool added to the package | Tool Map table + references/tools-api.md |
-| Tool parameters changed | references/tools-api.md |
-| New chaining pattern discovered in practice | references/tools-api.md chaining section |
-
----
+## Boundaries
 
-## Reference
+- For a multi-day itinerary, trip schedule, or travel-day optimization, use `google-maps-travel-planning` instead.
+- For Google Business Profile visibility, grid ranking, keyword coverage, or competitor audits, use `google-maps-local-seo` instead.
+- `maps_weather` is unavailable in Japan, China, South Korea, Cuba, Iran, North Korea, and Syria; use a current web source there.
+- Transit waypoint optimization is unsupported; use `optimize: false` for transit routes.
+- Geographic proximity and elevation alone do not establish safety, accessibility, flood risk, or suitability. State those limitations when relevant.
 
-| File | Content | When to read |
-|------|---------|--------------|
-| `references/tools-api.md` | Full parameter specs, response formats, 7 scenario recipes, and decision guide | When you need exact parameters, response shapes, or multi-tool workflow patterns |
-| `references/travel-planning.md` | Travel planning methodology — 6-layer model, Search Along Route, anti-patterns | When planning multi-day trips — **read before Recipe 1** |
-| `references/local-seo.md` | Local SEO / Google Business Profile ranking analysis — competitor audit, keyword landscape, gap analysis | When analyzing business rankings, comparing competitors, or scouting locations |
-| `references/content-attribution.md` | Google Maps content attribution, source links, AI disclosure, and storage limits | Before presenting reviews, photos, or AI summaries from Places |
+## References
 
-> For **project development** knowledge (architecture, API guide, GIS domain, design decisions), see `skills/project-docs/SKILL.md`.
+- `references/tools-api.md`: read for exact parameters, response shapes, and generic chaining recipes.
+- `../_shared/setup-and-diagnostics.md`: read for first-run checks and error classification.
+- `../_shared/content-attribution.md`: read before displaying regulated Google Maps content.

package/skills/google-maps/references/tools-api.md

@@ -156,7 +156,7 @@ Response includes (when available from Google):
 | `reviews[].author_uri`, `author_photo_uri`, `google_maps_uri` | string | Author profile/avatar and individual review source |
 | `photos[].author_attributions`, `google_maps_uri` | object[], string | Photo credits and individual photo source, returned with `maxPhotos > 0` |
 
-Before showing reviews, photos, or AI summaries to end users, read [`content-attribution.md`](./content-attribution.md). The old legacy-review merge was removed because it could not supply a per-review Google Maps source link; reviews now come from Places API (New) only.
+Before showing reviews, photos, or AI summaries to end users, read [`content-attribution.md`](../../_shared/content-attribution.md). The old legacy-review merge was removed because it could not supply a per-review Google Maps source link; reviews now come from Places API (New) only.
 
 ---
 
@@ -494,7 +494,7 @@ Use these recipes when the user's question maps to a multi-step workflow. Think
 
 This is the most common complex scenario. The goal is a time-ordered itinerary with routes between stops.
 
-> **Read `references/travel-planning.md` first** — it contains the full methodology, anti-patterns, and time budget guidelines.
+> This workflow belongs to the `google-maps-travel-planning` Skill. Read its `references/travel-planning.md` before planning an itinerary.
 
 **Steps:**
 1. `maps_search_places` — Search "top attractions in {city}" → geographically diverse **anchor points**

package/skills/google-maps-local-seo/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: google-maps-local-seo
+description: Analyze Google Business Profile visibility, geographic grid rankings, local search keywords, and nearby competitors through the standalone Google Maps CLI. Use for local SEO or location-strategy decisions, not ordinary place recommendations.
+license: MIT
+---
+
+# Google Maps Local SEO
+
+Produce a reproducible local-search visibility analysis grounded in Google Maps results. Use the standalone CLI; no MCP connection is required.
+
+## Before calling the CLI
+
+- On the first call in a session, or after an execution failure, read `../_shared/setup-and-diagnostics.md` and run the non-billable local preflight.
+- The user must supply `GOOGLE_MAPS_API_KEY`. Never expose its value.
+- Read `../_shared/content-attribution.md` before presenting reviews, photos, or Google-generated summaries.
+
+## Workflow
+
+1. Confirm the target business or `place_id`, service area, relevant keywords, grid size, and decision the user needs to make.
+2. Read `references/local-seo.md` before running an audit.
+3. Resolve the target with `maps_search_places` and `maps_place_details`; do not assume businesses with similar names are identical.
+4. Use `maps_local_rank_tracker` for geographic rankings. Keep the keyword, center, spacing, and grid size with every reported result.
+5. Use place search, comparison, and area exploration to identify competitors and evidence for gaps.
+6. Separate observed API results from recommendations. Explain ARP, ATRP, SoLV, unfound grid points, and sample limitations.
+7. Present prioritized actions tied to the observed evidence; do not promise ranking improvements.
+
+## CLI
+
+```bash
+npx -y @cablate/mcp-google-map exec <tool> '<json_params>'
+```
+
+For exact parameters, read the relevant sections of `../google-maps/references/tools-api.md`.
+
+## Boundaries
+
+- Ordinary nearby-place discovery and place comparison belong to `google-maps`.
+- Consumer travel itineraries belong to `google-maps-travel-planning`.
+- Grid results are a sampled snapshot, not an exhaustive or stable representation of Google ranking.
+- Do not recommend deceptive reviews, keyword stuffing, impersonation, or other policy-violating tactics.
+
+## References
+
+- `references/local-seo.md`: required audit method, competitor analysis, metrics, and reporting structure.
+- `../google-maps/references/tools-api.md`: selected tool parameters and response shapes.
+- `../_shared/setup-and-diagnostics.md`: first-run and failure recovery.
+- `../_shared/content-attribution.md`: Places presentation requirements.

package/skills/google-maps-travel-planning/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: google-maps-travel-planning
+description: Build evidence-backed day trips, multi-day itineraries, and efficient stop sequences with Google Maps data through the standalone CLI. Use when the desired output is a practical travel plan, not merely a route or list of places.
+license: MIT
+---
+
+# Google Maps Travel Planning
+
+Build a time-ordered itinerary whose geography, travel times, opening constraints, and along-route stops have been checked. Use the standalone CLI; no MCP connection is required.
+
+## Before calling the CLI
+
+- On the first call in a session, or after an execution failure, read `../_shared/setup-and-diagnostics.md` and run the non-billable local preflight.
+- The user must supply `GOOGLE_MAPS_API_KEY`. Never expose its value.
+- Read `../_shared/content-attribution.md` before presenting reviews, photos, or Google-generated summaries.
+
+## Workflow
+
+1. Establish destination, dates or duration, fixed anchors, mobility constraints, pace, and relevant preferences. Ask only for omissions that materially change the itinerary.
+2. Read `references/travel-planning.md` before designing the itinerary.
+3. Use `maps_search_places` to find candidate anchors, then group nearby anchors into one-direction daily arcs.
+4. Use `maps_search_along_route` for meals and breaks between anchors. Use `maps_place_details` for hours, ratings, and source metadata.
+5. Validate every day with `maps_plan_route` or `maps_directions`. Do not present estimated timing as validated timing.
+6. Check weather and air quality when they affect the plan. Respect regional weather limitations described in the reference.
+7. When useful, produce a numbered static map after the stop order is final.
+8. Present a day-by-day schedule with travel time, visit duration, reservations or opening-hour caveats, and clearly marked fallbacks.
+
+## CLI
+
+```bash
+npx -y @cablate/mcp-google-map exec <tool> '<json_params>'
+```
+
+For exact tool parameters, read `../google-maps/references/tools-api.md` only for the tools selected by the plan.
+
+## Boundaries
+
+- A request for only A-to-B directions or a simple multi-stop ordering belongs to `google-maps`.
+- A request to assess business visibility or local search rankings belongs to `google-maps-local-seo`.
+- Do not infer that a venue is accessible, open, safe, or suitable when the API response does not establish it.
+- Do not silently substitute web estimates for unavailable Google Maps results; identify the alternate source.
+
+## References
+
+- `references/travel-planning.md`: required methodology, timing budgets, geographic arcs, and anti-patterns.
+- `../google-maps/references/tools-api.md`: exact parameters and response shapes for selected tools.
+- `../_shared/setup-and-diagnostics.md`: first-run and failure recovery.
+- `../_shared/content-attribution.md`: Places presentation requirements.

package/skills/project-docs/SKILL.md

@@ -1,66 +0,0 @@
----
-name: mcp-google-map-project
-description: Project knowledge for developing and maintaining @cablate/mcp-google-map. Architecture, Google Maps API guide, GIS domain knowledge, and design decisions. Read this skill to onboard onto the project or make informed development decisions.
-version: 0.0.1
-compatibility:
-  - claude-code
-  - cursor
-  - vscode-copilot
----
-
-# mcp-google-map — Project Knowledge
-
-## Overview
-
-This skill contains everything needed to develop, maintain, and extend the `@cablate/mcp-google-map` MCP server. Reading these files gives you full context on architecture, API specifics, domain knowledge, and the reasoning behind design decisions.
-
-For the **agent skill** (how to USE the tools), see `skills/google-maps/SKILL.md`.
-
----
-
-## Quick Orientation
-
-| Aspect | Summary |
-|--------|---------|
-| **What** | MCP server providing Google Maps tools for AI agents |
-| **Stack** | TypeScript, Node.js, Express, MCP SDK, Zod |
-| **Tools** | 18 tools (14 atomic + 4 composite) |
-| **Transports** | stdio, Streamable HTTP, standalone exec CLI |
-| **APIs** | Places API (New), Directions, Geocoding, Elevation, Timezone, Weather, Air Quality, Static Maps, Search Along Route |
-
----
-
-## Reference Files
-
-| File | Content | When to read |
-|------|---------|--------------|
-| `references/architecture.md` | System architecture, 3-layer design, transport modes, tool registration flow, 9-file checklist, code map | **Start here** when onboarding. Also read when adding new tools. |
-| `references/google-maps-api-guide.md` | All Google Maps API endpoints used, pricing, coverage limits, rate limits, common gotchas, Places New vs Legacy | When debugging API errors, evaluating new APIs, or checking costs |
-| `references/geo-domain-knowledge.md` | GIS fundamentals — coordinates, distance, geocoding, place types, spatial search, map projection, Japan-specific knowledge | When making tool design decisions that involve geographic concepts |
-| `references/decisions.md` | 10 Architecture Decision Records (ADR) with context and rationale | When asking "why was X built this way?" or considering changes to existing design |
-
----
-
-## How to Add a New Tool
-
-See `references/architecture.md` § "9-File Tool Change Checklist" for the complete procedure. Summary:
-
-1. Create `src/tools/maps/<toolName>.ts` (NAME, DESCRIPTION, SCHEMA, ACTION)
-2. Register in `src/config.ts`
-3. Add exec case in `src/cli.ts`
-4. Add to `tests/smoke.test.ts` (expectedTools + API call test)
-5. Update `README.md` (count + table + exec list + project structure)
-6. Update `skills/google-maps/SKILL.md` (Tool Map)
-7. Update `skills/google-maps/references/tools-api.md` (params + chaining)
-8. Check `server.json` and `package.json` descriptions
-
----
-
-## When to Update This Skill
-
-| Trigger | What to update |
-|---------|----------------|
-| Architecture change | `references/architecture.md` |
-| New Google Maps API integrated | `references/google-maps-api-guide.md` |
-| New design decision made | `references/decisions.md` (add ADR) |
-| New GIS concept relevant to tools | `references/geo-domain-knowledge.md` |

package/skills/project-docs/references/architecture.md

@@ -1,137 +0,0 @@
-# Architecture Reference
-
-## System Architecture Overview
-
-Three-layer architecture with a shared entry point:
-
-```
-CLI / HTTP / stdio
-       |
-  BaseMcpServer          <- MCP protocol layer (tool registration, transport)
-       |
-  Tool ACTION()          <- thin dispatch, calls PlacesSearcher
-       |
-  PlacesSearcher         <- service facade (composition, filtering, response shaping)
-      /|\
-GoogleMapsTools  RoutesService    NewPlacesService
-(geocode/tz/elev) (Routes API REST) (Places API New)
-```
-
-| Layer | Files | Responsibility |
-|---|---|---|
-| Entry | `src/cli.ts` | Parse CLI args, select transport mode, instantiate server |
-| Protocol | `src/core/BaseMcpServer.ts` | Register tools, handle MCP sessions, route HTTP/stdio |
-| Tool | `src/tools/maps/*.ts` | Declare NAME, DESCRIPTION, SCHEMA, ACTION |
-| Config | `src/config.ts` | Assemble ToolConfig[], attach MAPS_TOOL_ANNOTATIONS |
-| Facade | `src/services/PlacesSearcher.ts` | Orchestrate multi-step / composite tools |
-| API client (routes) | `src/services/RoutesService.ts` | Routes API REST client (directions, distance matrix, waypoint optimization) |
-| API client (legacy) | `src/services/toolclass.ts` | Wrap `@googlemaps/google-maps-services-js` SDK (geocode, timezone, elevation) |
-| API client (places) | `src/services/NewPlacesService.ts` | Wrap `@googlemaps/places` gRPC client |
-| Auth | `src/utils/apiKeyManager.ts` | API key priority resolution |
-| Context | `src/utils/requestContext.ts` | Per-request AsyncLocalStorage propagation |
-
----
-
-## Transport Modes
-
-| Mode | Entry | How to activate | Notes |
-|---|---|---|---|
-| **HTTP (Streamable)** | `cli.ts` → `BaseMcpServer.startHttpServer()` | default, or `--port` | Listens on `/mcp` (POST/GET/DELETE); sessions tracked by UUID header `mcp-session-id` |
-| **stdio** | `cli.ts` → `BaseMcpServer.startStdio()` | `--stdio` flag | Used by Claude Desktop, Cursor; stdout reserved for JSON-RPC, all logs go to stderr |
-| **exec CLI** | `cli.ts` → `execTool()` | `mcp-google-map exec <tool> '<json>'` | No MCP protocol; directly calls `PlacesSearcher` method and prints JSON to stdout; used for scripting/piping |
-
-### HTTP Session Lifecycle
-
-```
-POST /mcp (no session-id, isInitializeRequest)
-  -> create StreamableHTTPServerTransport
-  -> create new McpServer, connect transport
-  -> store in sessions[uuid]
-
-POST /mcp (mcp-session-id header)
-  -> reuse existing session context
-  -> update apiKey if header present
-
-DELETE /mcp (mcp-session-id header)
-  -> terminate session, clean up transport
-```
-
----
-
-## Tool Registration Flow
-
-```
-src/tools/maps/weather.ts          exports Weather.{NAME, DESCRIPTION, SCHEMA, ACTION}
-          |
-src/config.ts                      builds ToolConfig[] array, attaches MAPS_TOOL_ANNOTATIONS
-          |
-src/cli.ts                         passes config.tools[] to new BaseMcpServer(name, tools)
-          |
-BaseMcpServer.createMcpServer()    calls server.registerTool(name, {description, inputSchema, annotations}, action)
-          |
-@modelcontextprotocol/sdk          exposes tool to MCP client
-```
-
-`MAPS_TOOL_ANNOTATIONS` applied to all tools:
-
-```ts
-{ readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
-```
-
----
-
-## API Key Management
-
-Priority order (highest to lowest):
-
-| Priority | Source | Header / Variable |
-|---|---|---|
-| 1 | HTTP request header | `X-Google-Maps-API-Key` |
-| 2 | HTTP Authorization header | `Authorization: Bearer <key>` |
-| 3 | Session-specific key | stored per `mcp-session-id` |
-| 4 | CLI argument | `--apikey` / `-k` |
-| 5 | Environment variable | `GOOGLE_MAPS_API_KEY` |
-| 6 | `.env` file | loaded by `dotenv` at startup from `cwd` or package dir |
-
-**Flow in HTTP mode**: `ApiKeyManager.getApiKey(req)` resolves key → stored in `SessionContext.apiKey` → propagated via `runWithContext()` (AsyncLocalStorage) → tool action reads from context or `process.env`.
-
-**Flow in exec mode**: `--apikey` arg → directly passed to `new PlacesSearcher(apiKey)` constructor.
-
----
-
-## Adding a New Tool — 9-File Checklist
-
-From `CLAUDE.md`:
-
-| # | File | What to update |
-|---|---|---|
-| 1 | `src/tools/maps/<toolName>.ts` | Define NAME, DESCRIPTION, SCHEMA, ACTION |
-| 2 | `src/config.ts` | Add to `tools[]` array with annotations |
-| 3 | `src/cli.ts` | Add to `EXEC_TOOLS` const + `switch` case in `execTool()` |
-| 4 | `tests/smoke.test.ts` | Add to `expectedTools` array + update tool count assertions |
-| 5 | `README.md` | Update tool count (header, comparison table, Server Info, exec mode) + Available Tools table + Project Structure |
-| 6 | `skills/google-maps/SKILL.md` | Add row to Tool Map table |
-| 7 | `skills/google-maps/references/tools-api.md` | Add parameter docs + chaining patterns |
-| 8 | `server.json` | Update description if it mentions tool count |
-| 9 | `package.json` | Update description if it mentions tool count |
-
-Missing any file causes doc/behavior mismatch. Verify all before opening a PR.
-
----
-
-## Code Map
-
-| File | Purpose |
-|---|---|
-| `src/cli.ts` | CLI entry point — parses args, selects transport, dispatches exec mode |
-| `src/config.ts` | Assembles ToolConfig[] array from all tool modules |
-| `src/core/BaseMcpServer.ts` | MCP server core — tool registration, HTTP session management, stdio transport |
-| `src/index.ts` | Package entry — exports Logger and re-exports public API |
-| `src/services/PlacesSearcher.ts` | Service facade — orchestrates multi-step composite tools (planRoute, exploreArea, comparePlaces, searchAlongRoute) |
-| `src/services/RoutesService.ts` | Routes API REST client — computeRoutes (directions), computeRouteMatrix (distance matrix), waypoint optimization |
-| `src/services/toolclass.ts` | Google Maps SDK wrapper — geocode, elevation, timezone, weather, airQuality, staticMap, searchAlongRoute |
-| `src/services/NewPlacesService.ts` | Places API (New) client — searchNearby, searchText, getPlaceDetails via gRPC |
-| `src/tools/maps/*.ts` | Individual tool definitions (17 files) — each exports NAME, DESCRIPTION, SCHEMA, ACTION |
-| `src/utils/apiKeyManager.ts` | Singleton — resolves API key priority from headers / session / env |
-| `src/utils/requestContext.ts` | AsyncLocalStorage — propagates API key within a single request lifecycle |
-| `tests/smoke.test.ts` | Integration smoke tests — validates tool list, basic API calls |