@cablate/mcp-google-map 0.0.63 → 0.0.64

package/.codex-plugin/plugin.json

@@ -0,0 +1,37 @@
+{
+  "name": "mcp-google-map",
+  "version": "0.0.64",
+  "description": "Use Google Maps-backed place search, routing, geocoding, weather, air quality, and geographic analysis through a standalone CLI.",
+  "author": {
+    "name": "CabLate",
+    "url": "https://github.com/cablate"
+  },
+  "homepage": "https://github.com/cablate/mcp-google-map",
+  "repository": "https://github.com/cablate/mcp-google-map",
+  "license": "MIT",
+  "keywords": [
+    "google-maps",
+    "places",
+    "routing",
+    "geocoding",
+    "travel",
+    "agent-skill"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Google Maps CLI",
+    "shortDescription": "Geospatial research and planning through a standalone CLI.",
+    "longDescription": "Guide an AI agent to use the @cablate/mcp-google-map exec CLI for place discovery, routing, geocoding, travel planning, local SEO, weather, air quality, and other geographic workflows. No MCP connection is required.",
+    "developerName": "CabLate",
+    "category": "Productivity",
+    "capabilities": [
+      "Read"
+    ],
+    "websiteURL": "https://github.com/cablate/mcp-google-map",
+    "defaultPrompt": [
+      "Find and compare places for my trip.",
+      "Plan an efficient route between these stops.",
+      "Research what is near this location."
+    ]
+  }
+}

package/README.md

@@ -89,6 +89,17 @@ All tools are annotated with `readOnlyHint: true` and `destructiveHint: false`
 
 ## Installation
 
+### Codex Plugin (Agent Skill, no MCP required)
+
+Install the CabLate marketplace, then install the Skill-only plugin:
+
+```bash
+codex plugin marketplace add cablate/mcp-google-map --ref main
+codex plugin add mcp-google-map@cablate
+```
+
+Set `GOOGLE_MAPS_API_KEY` in the environment available to Codex, make sure Node.js 18+ and `npx` are installed, then start a new conversation. The plugin teaches the agent to run `npx -y @cablate/mcp-google-map exec ...` directly. It does not register or start an MCP server; the MCP setup below remains an independent option.
+
 ### Method 1: stdio (Recommended for most clients)
 
 Works with Claude Desktop, Cursor, VS Code, and any MCP client that supports stdio:
@@ -290,20 +301,18 @@ src/
 tests/
 └── smoke.test.ts                 # Smoke + E2E test suite
 skills/
-├── google-maps/                  # Agent Skill — how to USE the tools
+└── google-maps/                  # Public Agent Skill — standalone CLI workflows
 │   ├── SKILL.md                  # Tool map, recipes, invocation
 │   ├── SKILL.skill               # Importable archive of this Skill
 │   └── references/
 │       ├── tools-api.md          # Tool parameters + scenario recipes
 │       ├── travel-planning.md    # Travel planning methodology
 │       └── local-seo.md          # Local SEO / Google Business Profile ranking analysis
-└── project-docs/                 # Project Skill — how to DEVELOP/MAINTAIN
-    ├── SKILL.md                  # Architecture overview + onboarding
-    └── references/
-        ├── architecture.md       # System design, code map, 9-file checklist
-        ├── google-maps-api-guide.md  # API endpoints, pricing, gotchas
-        ├── geo-domain-knowledge.md   # GIS fundamentals, Japan context
-        └── decisions.md          # 10 ADRs (design decisions + rationale)
+.agents/
+├── plugins/marketplace.json      # CabLate marketplace catalog
+└── skills/project-docs/          # Maintainer-only development Skill
+.codex-plugin/plugin.json         # Codex compatibility manifest
+plugin.json                       # Portable Agent Plugin manifest
 ```
 
 ## Tech Stack

package/README.zh-TW.md

@@ -89,6 +89,17 @@ npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
 
 ## 安裝
 
+### Codex Plugin（Agent Skill，不需要 MCP）
+
+先加入 CabLate marketplace，再安裝只包含 Skill 的 plugin：
+
+```bash
+codex plugin marketplace add cablate/mcp-google-map --ref main
+codex plugin add mcp-google-map@cablate
+```
+
+請在 Codex 可讀取的環境中設定 `GOOGLE_MAPS_API_KEY`，並確認已安裝 Node.js 18+ 與 `npx`，然後開啟新對話。Plugin 會教代理直接執行 `npx -y @cablate/mcp-google-map exec ...`；它不會註冊或啟動 MCP server。下方的 MCP 設定仍是另一種獨立使用方式。
+
 ### 方法一：stdio（大多數客戶端推薦）
 
 適用於 Claude Desktop、Cursor、VS Code 及任何支援 stdio 的 MCP 客戶端：
@@ -287,20 +298,18 @@ src/
 tests/
 └── smoke.test.ts                 # Smoke + E2E 測試套件
 skills/
-├── google-maps/                  # Agent Skill — 如何使用工具
+└── google-maps/                  # 公開 Agent Skill — 獨立 CLI 工作流程
 │   ├── SKILL.md                  # 工具對照表、場景食譜、呼叫方式
 │   ├── SKILL.skill               # 可匯入的 Skill 封裝檔
 │   └── references/
 │       ├── tools-api.md          # 工具參數 + 場景食譜
 │       ├── travel-planning.md    # 旅行規劃方法論
 │       └── local-seo.md          # Local SEO / Google 商家排名分析
-└── project-docs/                 # Project Skill — 如何開發/維護
-    ├── SKILL.md                  # 架構概覽 + 入門指南
-    └── references/
-        ├── architecture.md       # 系統設計、code map、9 檔案 checklist
-        ├── google-maps-api-guide.md  # API 端點、定價、注意事項
-        ├── geo-domain-knowledge.md   # GIS 基礎、日本場景
-        └── decisions.md          # 10 個 ADR（設計決策 + 理由）
+.agents/
+├── plugins/marketplace.json      # CabLate marketplace 目錄
+└── skills/project-docs/          # 僅供維護者使用的開發 Skill
+.codex-plugin/plugin.json         # Codex 相容 manifest
+plugin.json                       # 可攜式 Agent Plugin manifest
 ```
 
 ## 技術棧

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cablate/mcp-google-map",
-  "version": "0.0.63",
+  "version": "0.0.64",
   "mcpName": "io.github.cablate/google-map",
   "description": "18 Google Maps tools for AI agents — geocode, search, directions, weather, air quality, local rank tracking, map images via MCP server or standalone CLI",
   "type": "module",
@@ -12,6 +12,8 @@
     "dist",
     "dist/**/*.map",
     "README.md",
+    "plugin.json",
+    ".codex-plugin",
     "skills",
     "examples"
   ],

package/plugin.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "mcp-google-map",
+  "version": "0.0.64",
+  "description": "Use Google Maps-backed place search, routing, geocoding, weather, air quality, and geographic analysis through a standalone CLI.",
+  "author": {
+    "name": "CabLate",
+    "url": "https://github.com/cablate"
+  },
+  "homepage": "https://github.com/cablate/mcp-google-map",
+  "repository": "https://github.com/cablate/mcp-google-map",
+  "license": "MIT",
+  "keywords": [
+    "google-maps",
+    "places",
+    "routing",
+    "geocoding",
+    "travel",
+    "agent-skill"
+  ]
+}

package/skills/google-maps/SKILL.md

@@ -111,5 +111,3 @@ npx -y @cablate/mcp-google-map exec <tool> '<json_params>'
 | `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 |
-
-> For **project development** knowledge (architecture, API guide, GIS domain, design decisions), see `skills/project-docs/SKILL.md`.

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 |

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

@@ -1,149 +0,0 @@
-# Architecture Decision Records — mcp-google-map
-
-> Format: Decision / Context / Rationale
-> Sources: dev-roadmap-spec.md, CLAUDE.md, project history
-
----
-
-## ADR-001: Unified `maps_` Prefix for All Tool Names
-
-**Decision**: All tools are named with the `maps_` prefix (e.g., `maps_geocode`, `maps_search_nearby`). This was applied as a breaking change when the namespace was standardized.
-
-**Context**: Early tool names were inconsistent — some had prefixes, some did not. As the tool count grew and the server was listed on MCP registries, namespace collisions with other MCP servers became a concern. Claude's tool selection also benefits from a clear namespace signal.
-
-**Rationale**:
-- Consistent namespace prevents collision when multiple MCP servers are active simultaneously.
-- The `maps_` prefix gives Claude a strong disambiguation signal — it knows these tools are geospatial without reading descriptions.
-- Breaking change was accepted early (pre-stable) to avoid accumulating technical debt. All 9 files in the Tool Change Checklist must be updated together on any rename.
-
----
-
-## ADR-002: `compare_places` Retained as a Composite Tool
-
-**Decision**: `maps_compare_places` is a single tool that internally fetches details for multiple places and returns a structured comparison. It is not decomposed into atomic `place_details` calls that the AI chains together.
-
-**Context**: An alternative design would have the AI call `maps_place_details` N times and synthesize the comparison itself. During testing, this produced inconsistent output quality and required users to explicitly orchestrate the chain.
-
-**Rationale**:
-- Users ask "compare these restaurants" and expect a comparison table, not raw data to synthesize.
-- Composite tools reduce chaining overhead and produce deterministic, structured output.
-- The Geo-Reasoning Benchmark (GRB) validates this: Composite Efficiency Score (CES) rewards using 1 call instead of N calls. `compare_places` is the reference case for this metric.
-- User preference confirmed: users do not want to manually chain atomic calls for comparison tasks.
-
----
-
-## ADR-003: `maps_weather` and `maps_air_quality` as Separate Tools
-
-**Decision**: Weather and air quality are exposed as two independent tools, not combined into a single `maps_environment` tool.
-
-**Context**: A natural grouping might combine weather and air quality into one "environmental conditions" call. Both return ambient data about a location.
-
-**Rationale**:
-- **Different APIs**: Weather uses one endpoint; Air Quality uses `POST https://airquality.googleapis.com/v1/currentConditions:lookup` — a completely separate Google service requiring separate API enablement.
-- **Different geographic coverage**: Weather API does not support Japan. Air Quality API fully supports Japan (including AEROS local index). Combining them would require complex conditional logic and mislead users about availability.
-- **Different data structures and use cases**: Weather is for planning (will it rain?). Air quality is for health decisions (should I wear a mask? can elderly parents go outside?). The 7-demographic health recommendation field in air quality has no analogue in weather.
-- **Independent billing**: Separate pricing makes cost attribution cleaner.
-
----
-
-## ADR-004: `maps_isochrone` Not Built
-
-**Decision**: Isochrone generation (travel-time polygons) is excluded from the roadmap, marked as "Skip for now."
-
-**Context**: Isochrones are a commonly requested GIS feature — "show me everywhere I can reach in 30 minutes." They are valuable for real estate analysis, event planning, and accessibility research.
-
-**Rationale**:
-- **Google has no native isochrone API.** All alternative implementations have disqualifying problems:
-  - Mapbox Isochrone API: mature, but introduces a second vendor (Mapbox key) alongside Google — breaks the single-provider positioning.
-  - OpenRouteService: free but rate-limited and stability uncertain for production use.
-  - Distance Matrix grid approximation: 24+ API calls per isochrone at ~$0.12/request; prohibitively expensive and low-accuracy.
-- **Core value is visual**: An isochrone polygon is only meaningful when rendered on a map. Without `maps_static_map` to display it, returning raw GeoJSON coordinates is not useful to AI or users. The feature was deprioritized until static map rendering was in place.
-- **Revisit path**: If built later, the best approach is Distance Matrix 8-direction probing + `maps_static_map` to render an approximated polygon. Estimated effort: 8 hours.
-
----
-
-## ADR-005: `maps_validate_address` Not Built
-
-**Decision**: Address validation (checking if a postal address is deliverable) is excluded from the tool set.
-
-**Context**: Google's Address Validation API provides USPS CASS-certified validation, deliverability flags, and address correction. It could theoretically be useful for any tool that takes address inputs.
-
-**Rationale**:
-- **Cost**: $17 per 1,000 requests — 3.4× the cost of standard geocoding. This is prohibitive for conversational AI use where users make casual address queries.
-- **Wrong use case**: Address validation is designed for backend pipelines (e-commerce checkout, CRM deduplication, bulk mailing). It requires structured postal input and returns structured postal corrections — not a natural fit for natural-language AI conversations.
-- **Coverage gap**: Only 38 countries supported; excludes most of Asia and Africa. A tool that silently fails for Tokyo or Mumbai addresses would create confusing UX.
-- **Existing alternative**: `maps_geocode` already handles 60% of "is this address valid?" scenarios by returning whether a geocode succeeded and providing the `formatted_address` canonical form.
-
----
-
-## ADR-006: Spatial Context / Session Memory Not Built
-
-**Decision**: There is no persistent spatial context or session memory layer in the MCP server. The server does not remember previously queried locations or build a "current location" state across calls.
-
-**Context**: A proposed feature was to maintain implicit state — if a user asks "find coffee shops" after previously mentioning "I'm in Shinjuku," the server would remember Shinjuku and use it as the implicit location for the next search.
-
-**Rationale**:
-- **Claude's conversation history already solves this.** Claude reads its own prior messages and can extract previously mentioned locations. A server-side memory layer would duplicate capability that already exists in the LLM.
-- **Composite tools reduce chaining need.** Tools like `maps_explore_area` and `maps_plan_route` accept multi-intent inputs that would otherwise require chaining with location state.
-- **Implementation risks outweigh benefits**:
-  - Implicit state leakage: state from one user's session could bleed into another in concurrent scenarios.
-  - Debugging opacity: errors become harder to trace when the server has hidden state.
-  - stdio transport has no session concept — each stdio connection is stateless by design.
-- **User value assessed at 3/10.** In testing, users could not perceive a meaningful difference. The friction of unexpected state (wrong implicit location) outweighed the convenience.
-
----
-
-## ADR-007: stdio as Primary Transport
-
-**Decision**: The MCP server uses stdio (standard input/output) as its primary transport mechanism. HTTP/SSE is secondary.
-
-**Context**: MCP servers can expose transport via stdio (subprocess model) or HTTP+SSE (network server model). Both are valid per the MCP specification.
-
-**Rationale**:
-- **MCP Registry requirement**: The official MCP registry and most client integrations (Claude Desktop, Claude Code, Cursor) prefer or require stdio-based servers for local installation.
-- **Security model**: stdio servers run as a subprocess of the client, inheriting the client's trust context. No network port exposure, no authentication complexity.
-- **Deployment simplicity**: `npx mcp-google-map` works out of the box without configuring ports, firewalls, or SSL.
-- **Statelessness aligns with stdio**: Each stdio connection represents one session. This reinforces ADR-006 (no spatial context) — the transport model naturally discourages stateful designs.
-
----
-
-## ADR-008: Search Along Route Uses Direct REST Calls
-
-**Decision**: The "search along route" capability calls the Google Maps REST API directly rather than using the official `@googlemaps/google-maps-services-js` client library.
-
-**Context**: Most tools in this project use the official client library for consistency and type safety. The route-based search requires fetching a polyline and then querying points along it — a pattern not natively supported by the client library.
-
-**Rationale**:
-- **Client library may not expose the required parameters or patterns** for buffered route searches. The REST API is always the source of truth; the client library is a convenience wrapper.
-- **Direct REST calls are straightforward**: for GET requests with query parameters, `axios` or `fetch` is sufficient and keeps the implementation explicit.
-- **Type safety can be maintained** by defining TypeScript interfaces for the REST response shapes — same outcome as using the library, without library constraints.
-- This is an exception to the general project preference for the client library, justified by the specific technical requirement.
-
----
-
-## ADR-009: MCP Prompt Templates Removed
-
-**Decision**: MCP Prompt Templates (slash commands like `/travel-planner`) were evaluated and ultimately not shipped as a feature.
-
-**Context**: The roadmap spec (P1-1) proposed implementing MCP's `prompts` primitive to expose slash commands in clients like Claude Desktop. The intended value was giving non-technical users a one-click entry into geo agent mode.
-
-**Rationale**:
-- **Client support is low and inconsistent.** As of evaluation, most MCP clients either do not render prompt templates as slash commands or render them inconsistently. The feature would benefit a small fraction of users.
-- **SKILL.md already covers the use case** for Claude Code users — the skill system provides rich scenario guidance, chaining patterns, and example recipes that go beyond what prompt templates support.
-- **Maintenance cost**: Prompt template content would need to stay in sync with tool capabilities, adding to the already-significant 9-file update checklist (CLAUDE.md ADR).
-- **Revisit condition**: If MCP client support for prompts reaches broad adoption (Claude Desktop, VS Code extension, Cursor all render them consistently), this should be reconsidered. The 6-hour implementation estimate is low.
-
----
-
-## ADR-010: Travel Planning Uses "Tool-Driven Diffusion," Not AI Prior Knowledge
-
-**Decision**: Travel planning workflows are designed so the AI discovers ground truth by calling tools, not by relying on training-data knowledge of specific places, hours, or transit schedules.
-
-**Context**: An AI could answer "what time does Kinkaku-ji open?" from training data. It could suggest a Tokyo itinerary without any tool calls based on memorized "best of Tokyo" patterns. This is faster but fragile.
-
-**Rationale**:
-- **Training data goes stale.** Business hours change, places close, new venues open. A tool call to `maps_place_details` returns current data; training knowledge reflects a past snapshot.
-- **Specificity requires data.** A user asking for restaurants near their hotel requires the actual hotel coordinates, not generic neighborhood knowledge. The tool call chain (geocode hotel → search nearby → get details) produces a personalized result that training data cannot replicate.
-- **Verifiability and trust.** When the AI cites data from a tool response (e.g., "Fushimi Inari opens at 6 AM according to Google Maps"), users can verify the source. When it speaks from training data, there is no audit trail.
-- **The SKILL.md geo-domain knowledge** (temple hours, transit rules, energy curves) is intentionally at the *pattern* level — it tells the AI *how* to plan, not *what* specific facts are. The facts come from tools. This separation is the core design principle.
-- Practical implementation: always geocode place names (don't assume coordinates), always fetch operating hours from `maps_place_details` (don't assume 9–5), always calculate transit time with `maps_directions` (don't estimate from distance).

package/skills/project-docs/references/geo-domain-knowledge.md

@@ -1,286 +0,0 @@
-# Geo Domain Knowledge for AI Map Tool Operators
-
-> Purpose: Give an AI agent without GIS background the domain knowledge needed to use map tools correctly and confidently.
-
----
-
-## 1. Coordinate Systems
-
-**WGS84** is the universal standard. Every latitude/longitude pair you encounter in Google Maps APIs uses WGS84. No conversion needed.
-
-**Order convention — lat comes first:**
-- Correct: `(35.6762, 139.6503)` — Tokyo
-- Wrong: `(139.6503, 35.6762)` — inverted, puts you in the ocean
-- Google Maps API parameters are always `latitude`, `longitude` in that order.
-
-**Precision and real-world accuracy:**
-
-| Decimal places | Precision | Notes |
-|----------------|-----------|-------|
-| 0 (e.g., 35°) | ~111 km | Country-level |
-| 1 (35.6°) | ~11 km | City-level |
-| 2 (35.67°) | ~1.1 km | District-level |
-| 3 (35.676°) | ~111 m | Street-level |
-| 4 (35.6762°) | ~11 m | Building-level |
-| 5 (35.67620°) | ~1.1 m | Door-level |
-| 6+ | <1 m | Survey-grade, rarely needed |
-
-For navigation and place lookup, 4–5 decimal places is sufficient. Do not truncate coordinates returned by the API — pass them as-is to downstream tools.
-
----
-
-## 2. Distance Concepts
-
-**Latitude degree is nearly constant worldwide:**
-- 1° latitude ≈ 111 km everywhere
-
-**Longitude degree varies with latitude:**
-- At equator (0°): 1° longitude ≈ 111 km
-- At 35°N (Tokyo/Seoul/Beijing): 1° longitude ≈ 91 km
-- At 45°N (Paris/Milan): 1° longitude ≈ 78 km
-- At 60°N (Oslo/Helsinki): 1° longitude ≈ 55 km
-
-**Quick mental math:** At Tokyo's latitude, a 0.01° difference is roughly 1 km.
-
-**Speed references for time estimation:**
-
-| Mode | Typical speed | Notes |
-|------|--------------|-------|
-| Walking | ~5 km/h | 1 km = ~12 min |
-| Cycling | ~15 km/h | varies by terrain |
-| Urban driving | ~30–40 km/h | traffic included |
-| Highway driving | ~80–100 km/h | intercity |
-| Transit (urban) | ~20–30 km/h door-to-door | includes wait time |
-| Shinkansen | ~250–300 km/h | between major cities |
-
-These are rule-of-thumb values. Always use `maps_directions` or `maps_distance_matrix` for real travel time — actual conditions (traffic, transit schedules) differ significantly.
-
----
-
-## 3. Geocoding Concepts
-
-**Forward geocoding**: address/name → lat/lng
-- Input: "Shibuya Station, Tokyo"
-- Output: `{ lat: 35.6580, lng: 139.7016, place_id: "ChIJ...", formatted_address: "..." }`
-
-**Reverse geocoding**: lat/lng → address
-- Input: `(35.6580, 139.7016)`
-- Output: formatted address + place types for that location
-- Use case: "What is at these coordinates?"
-
-**place_id** — the stable identifier for a place in Google's database:
-- Format: `ChIJN1t_tDeuEmsRUsoyG83frY4` (opaque string)
-- Stable across time (unlike coordinates, which can shift if a business moves)
-- Preferred input for `maps_place_details` — faster and more precise than re-searching by name
-- Always cache `place_id` when you receive it; reuse in subsequent calls
-
-**formatted_address vs raw input:**
-- `formatted_address` is Google's canonical form: `"2 Chome-21-1 Asakusa, Taito City, Tokyo 111-0032, Japan"`
-- Use it for display and for chaining into other tools that accept address strings
-- Do not invent or modify addresses — only pass what Google returned
-
----
-
-## 4. Place Types
-
-Google's place type system is hierarchical. A place can have multiple types (e.g., a convenience store is both `convenience_store` and `store`).
-
-**Common type categories:**
-
-| Category | Examples |
-|----------|---------|
-| Food & drink | `restaurant`, `cafe`, `bar`, `bakery`, `meal_takeaway`, `food` |
-| Lodging | `lodging`, `hotel`, `hostel`, `guest_house` |
-| Transport | `train_station`, `subway_station`, `bus_station`, `airport`, `transit_station` |
-| Culture | `museum`, `art_gallery`, `library`, `church`, `temple`, `shrine` |
-| Nature | `park`, `natural_feature`, `campground`, `amusement_park` |
-| Health | `hospital`, `pharmacy`, `doctor`, `dentist` |
-| Shopping | `shopping_mall`, `supermarket`, `convenience_store`, `clothing_store` |
-| Finance | `bank`, `atm` |
-| Education | `school`, `university` |
-| Government | `local_government_office`, `post_office`, `police` |
-
-**How to pick the right type for search:**
-- Be specific for precision: `ramen_restaurant` > `restaurant` when you know what you want
-- Use broader types for exploration: `food` catches everything edible
-- Some types are not searchable (too broad) — prefer specific leaf-level types
-- Compound queries work: pass `keyword="ramen"` with `type="restaurant"` for best results
-
----
-
-## 5. Routing and Navigation
-
-**Travel modes:**
-
-| Mode | Parameter | Notes |
-|------|-----------|-------|
-| Driving | `DRIVE` | Default, uses current traffic |
-| Walking | `WALK` | No highways, includes pedestrian paths |
-| Cycling | `BICYCLE` | Not available in all regions |
-| Transit | `TRANSIT` | Requires `departure_time` for accurate results |
-
-**Key rule for transit**: Always provide `departure_time` (Unix timestamp). Without it, Google may use default schedules that don't reflect actual service patterns. For planning tools, use a future timestamp on a weekday.
-
-**Overview polyline:**
-- A compressed string encoding the entire route path (e.g., `_p~iF~ps|U_ulLnnqC_mqNvxq`@`)
-- Encoded in Google's Polyline Algorithm (each character represents coordinate delta)
-- Use it when you need to pass the route to `maps_static_map` for visualization
-- Do not try to decode it manually — pass it as-is to display tools
-
-**Waypoints and stops:**
-- Routes can include intermediate waypoints
-- Optimize waypoint order with `optimize=true` for multi-stop itineraries
-- For Tokyo sightseeing: always think about natural geographic flow (e.g., north→south or circular) to minimize backtracking
-
----
-
-## 6. Map Projections
-
-**Mercator projection** is what Google Maps (and virtually all web maps) uses.
-
-Key distortion property: **area is not preserved, shape is**. The further from the equator, the larger things appear relative to their true size.
-
-| Location | Apparent size on map vs reality |
-|----------|--------------------------------|
-| Africa vs Greenland | Africa is 14x larger in reality, but they look similar on Mercator |
-| Japan (~35°N) | Moderate distortion, cities appear roughly accurate |
-| Scandinavia (~60°N) | Significantly overstated on map |
-
-**Why this matters for `maps_static_map`:**
-- At the same zoom level, a 600x400 tile covers more actual ground at higher latitudes
-- Zoom 12 in Tokyo covers ~10 km across; zoom 12 in Tokyo's northern suburbs covers slightly more
-- Zoom guidelines for `maps_static_map`:
-
-| Zoom | Coverage |
-|------|---------|
-| 1 | World |
-| 5 | Continent/large country |
-| 10 | City |
-| 12 | District |
-| 14 | Neighborhood |
-| 16 | Streets |
-| 18 | Building-level |
-| 20 | Room-level (where available) |
-
----
-
-## 7. Spatial Search Types
-
-**Circular search (radius-based):**
-- Definition: find places within N meters of a center point
-- API: `maps_search_nearby` with `radius` parameter
-- Best for: "coffee shops near me," "ATM within 500m"
-- Limitation: covers uniform area regardless of walkability — a 500m radius includes both sides of a river
-
-**Search along route:**
-- Definition: find places near any point on a route path
-- Requires: route polyline from `maps_directions`
-- Best for: "rest stops between Tokyo and Osaka," "gas stations on the way"
-- Implementation: buffer the polyline, search at interval waypoints
-
-**Bounding box search:**
-- Definition: find everything within a lat/lng rectangle
-- Best for: "all museums in Kyoto" (known geographic area)
-- Less precise than radius — corners are farther from center than edge midpoints
-
-**Choosing the right approach:**
-
-| Scenario | Use |
-|----------|-----|
-| Near a specific point | Circular (radius) |
-| Along a travel path | Route-based |
-| Within a city/district | Bounding box or large radius from city center |
-| "Best of" in an area | Keyword search + type filter |
-
----
-
-## 8. Travel Planning Domain Knowledge
-
-**Time-of-day sensitivity:**
-- Early morning (6–9 AM): temples/shrines are quieter, markets open
-- Midday (11 AM–2 PM): lunch crowds at restaurants; museums uncrowded
-- Late afternoon (3–5 PM): good for viewpoints and gardens (golden hour light)
-- Evening (5–8 PM): best for dining, night markets, illuminated landmarks
-- Night (8 PM+): limited temple access, izakayas peak, Tokyo Skytree views
-
-**Arc routing principle:**
-- Design routes that move in one general direction, then return — avoid ping-pong backtracking
-- Example: Asakusa → Ueno → Akihabara (east→center→east) is efficient; Shinjuku → Asakusa → Shinjuku is not
-
-**Energy curve (fatigue model):**
-- Morning: high energy → schedule physically demanding activities (hills, many stairs)
-- Midday: lunch + rest → schedule museum interiors, air-conditioned venues
-- Afternoon: moderate energy → walking tours, shopping
-- Evening: low energy → seated dining, short walks only
-
-**Meal timing:**
-- Breakfast: 7–9 AM
-- Lunch: 11:30 AM–1:30 PM (plan to arrive before 12 to avoid queues)
-- Dinner: 6–8 PM (popular spots fill by 6:30)
-- Always build 15–20 min buffer for transit between meals and activities
-
-**Group size adjustments:**
-- Solo/couple: access anywhere, no reservation usually needed
-- Group (4–8): book restaurants ahead, check venue capacity
-- Large group (8+): many historic sites have capacity limits (e.g., Fushimi Inari paths are narrow)
-
----
-
-## 9. Japan-Specific Knowledge
-
-### Kyoto Area Structure
-
-Kyoto's main sightseeing zones:
-
-| Zone | Key sites | Character |
-|------|----------|-----------|
-| Arashiyama (west) | Bamboo Grove, Tenryu-ji | Nature, bamboo, riverside |
-| Higashiyama (east) | Kiyomizu-dera, Gion, Ninen-zaka | Traditional streets, temples |
-| Fushimi (south) | Fushimi Inari | Torii gates, accessible by JR |
-| Downtown (center) | Nijo Castle, Nishiki Market | Mix of modern and historical |
-| Nishijin (north-center) | Kinkaku-ji, Ryoan-ji | Famous temples, crowded |
-
-**Rule**: Arashiyama and Higashiyama are on opposite sides of the city (~1 hr by bus). Do not combine them in a half-day plan.
-
-### Train Network
-
-| Network | Type | Use case |
-|---------|------|---------|
-| Shinkansen (bullet train) | Inter-city | Tokyo↔Kyoto (2h15m), Tokyo↔Osaka (2h30m) |
-| JR lines | Regional/urban | JR Pass compatible, connects major stations |
-| Hankyu/Keihan/Kintetsu | Private railways | Osaka↔Kyoto alternatives, often cheaper |
-| Tokyo Metro / Toei | Urban subway | Dense Tokyo inner-city coverage |
-| Kyoto Bus | Urban bus | Essential for Kyoto (no subway to Arashiyama/Fushimi) |
-
-**Practical notes:**
-- IC cards (Suica, Pasmo, ICOCA) work on almost all trains and buses in Japan — recommend for all visitors
-- JR Pass only covers JR-operated lines, not private railways or subways
-- In Kyoto, bus day pass (¥700) is cost-effective for 3+ bus rides
-
-### Temple and Shrine Access Times
-
-| Category | Typical hours | Notes |
-|----------|--------------|-------|
-| Major temples (paid) | 8:30 AM – 5:00 PM | Last entry 30 min before close |
-| Fushimi Inari | 24 hours | Lower section always open |
-| Buddhist temple grounds | 6:00 AM – dusk | Gates/halls may have separate hours |
-| Shrine precincts | Usually always open | Inner buildings have set hours |
-
-**Key rule**: Always plan temple visits for morning to avoid afternoon crowds and ensure all halls are open. Schedule Fushimi Inari early morning (6–8 AM) to avoid tour groups.
-
-### Japanese Address System
-
-Addresses in Japan follow a reverse order from Western convention:
-- Prefecture → City → Ward → Chome (district) → Block → Building
-- Example: `東京都渋谷区道玄坂1丁目2-3` = Tokyo-to, Shibuya-ku, Dogenzaka 1-chome, block 2, building 3
-- Always geocode Japanese addresses using `maps_geocode` — do not attempt to calculate coordinates from address text.
-
-### Useful Distance References (Japan)
-
-| Route | Distance | Transport | Time |
-|-------|----------|-----------|------|
-| Tokyo → Kyoto | 450 km | Nozomi Shinkansen | 2h15m |
-| Tokyo → Osaka | 520 km | Nozomi Shinkansen | 2h30m |
-| Kyoto → Nara | 35 km | JR Nara Line | 45m |
-| Kyoto → Osaka | 75 km | JR/Hankyu | 15–28m |
-| Shinjuku → Asakusa (Tokyo) | 10 km | Metro | 30m |

package/skills/project-docs/references/google-maps-api-guide.md

@@ -1,139 +0,0 @@
-# Google Maps API Guide
-
-## APIs in Use
-
-| API | Endpoint | Tool(s) | GCP Service to Enable |
-|---|---|---|---|
-| Geocoding API | via `@googlemaps/google-maps-services-js` SDK | `maps_geocode`, `maps_reverse_geocode`, `maps_batch_geocode` | Geocoding API |
-| Routes API (computeRoutes) | `https://routes.googleapis.com/directions/v2:computeRoutes` (REST fetch) | `maps_directions`, `maps_plan_route` (legs + waypoint optimization), `maps_search_along_route` (polyline) | Routes API |
-| Routes API (computeRouteMatrix) | `https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix` (REST fetch) | `maps_distance_matrix` | Routes API |
-| Elevation API | via SDK | `maps_elevation` | Elevation API |
-| Time Zone API | via SDK | `maps_timezone` | Time Zone API |
-| Places API (New) — Nearby Search | `https://places.googleapis.com/v1/places:searchNearby` (gRPC via `@googlemaps/places`) | `maps_search_nearby` | Places API (New) |
-| Places API (New) — Text Search | `https://places.googleapis.com/v1/places:searchText` (gRPC + REST) | `maps_search_places`, `maps_compare_places`, `maps_explore_area`, `maps_search_along_route` (step 2) | Places API (New) |
-| Places API (New) — Place Details | `https://places.googleapis.com/v1/places/{placeId}` (gRPC) | `maps_place_details` | Places API (New) |
-| Weather API | `https://weather.googleapis.com/v1/currentConditions:lookup` | `maps_weather` (type=current) | Google Weather API |
-| Weather API — Daily Forecast | `https://weather.googleapis.com/v1/forecast/days:lookup` | `maps_weather` (type=forecast_daily, max 10 days) | Google Weather API |
-| Weather API — Hourly Forecast | `https://weather.googleapis.com/v1/forecast/hours:lookup` | `maps_weather` (type=forecast_hourly, max 240 hours) | Google Weather API |
-| Air Quality API | `https://airquality.googleapis.com/v1/currentConditions:lookup` | `maps_air_quality` | Air Quality API |
-| Maps Static API | `https://maps.googleapis.com/maps/api/staticmap` | `maps_static_map` | Maps Static API |
-
----
-
-## API Coverage Limitations
-
-### Weather API
-
-- **Not supported**: China, Japan, South Korea, Cuba, Iran, North Korea, Syria
-- Best coverage: North America, Europe, Oceania
-- Error message when unsupported: `"not supported for this location"` — the code catches this and returns a user-readable message including the list of unsupported regions
-- Forecast limits: daily max 10 days, hourly max 240 hours (enforced with `Math.min/Math.max`)
-
-### Air Quality API
-
-- Global coverage (no known hard exclusions)
-- Returns multiple indexes: universal AQI + local country-specific index where available
-- `extraComputations` options: `HEALTH_RECOMMENDATIONS`, `POLLUTANT_CONCENTRATION`
-
-### Places API (New)
-
-- `maxResultCount` hard cap: 20 (enforced in `NewPlacesService`)
-- `searchNearby` uses `includedTypes` (type-based), not free-text keyword
-- Photos: returns `photo.name` (resource reference), not a direct image URL
-
-### Directions API
-
-- `transit` mode requires `departure_time` for accurate transit schedule results (without it Google may return estimated or no results)
-- `plan_route` optimization uses `driving` mode for distance matrix even when the final leg mode is `transit`, to avoid matrix returning null entries
-
-### Static Maps API
-
-- URL length limit: 16,384 characters (enforced before fetch)
-- Returns binary PNG, converted to base64 by the server for MCP response
-- `maptype` options: `roadmap`, `satellite`, `terrain`, `hybrid`
-
----
-
-## Common Pitfalls
-
-| Scenario | Problem | Fix |
-|---|---|---|
-| `transit` directions with no `departure_time` | Google may return `ZERO_RESULTS` or incorrect duration | Always pass `departure_time` (Unix timestamp or `"now"`) when using transit mode |
-| `plan-route` with `formatted_address` from geocode | Directions API may return `ZERO_RESULTS` on complex formatted addresses | `plan-route` passes the original user-provided stop name to Directions, not `formatted_address` from geocode step |
-| `searchNearby` with free-text keyword | `includedTypes` expects a Place type string (e.g. `"restaurant"`), not a general query | Use `search_places` for free-text; use `search_nearby` for type-constrained radius search |
-| Weather for Japan/China | Returns HTTP error with "not supported for this location" | Catch and re-throw with explicit unsupported country list (already implemented) |
-| Air Quality `includePollutants: false` | Default is `true` for `includeHealthRecommendations`, `false` for pollutants | Be explicit — omitting `includePollutants` defaults to `false` |
-| Static map URL over 16,384 chars | Google rejects the request | Reduce number of markers or path waypoints |
-| Place Details with Places API (New) | Resource name format is `places/<id>` not raw `placeId` | `NewPlacesService.getPlaceDetails()` prepends `places/` automatically |
-| Batch geocode concurrency | Default concurrency is 20, max enforced at 50 | Use `--concurrency` flag in CLI batch-geocode command; tool-mode uses `Promise.all` |
-
----
-
-## Rate Limits and Batch Strategy
-
-| API | QPS Limit (default) | Notes |
-|---|---|---|
-| Geocoding API | 50 QPS | `maps_batch_geocode` uses `Promise.all` in tool mode; CLI uses semaphore with configurable concurrency (default 20, max 50) |
-| Places API (New) | 100 QPS | Result count capped at 20 per request |
-| Directions API | 50 QPS | `plan_route` makes N-1 serial Directions calls after parallel geocoding |
-| Distance Matrix API | 100 elements/request, 100 QPS | `plan_route` optimization: N×N matrix for ≤ ~10 stops is safe |
-| Weather / Air Quality | Per project quota | No internal retry logic; HTTP 429 surfaces as `"API quota exceeded"` message |
-| Static Maps API | 500 QPS | Single image fetch; no batch |
-
-**HTTP 403** → API key invalid or the required GCP API not enabled.
-**HTTP 429 / `OVER_QUERY_LIMIT`** → Quota exceeded; wait and retry or upgrade billing plan.
-
----
-
-## Search Along Route
-
-`maps_search_along_route` is a two-step composite:
-
-**Step 1** — Get route polyline via Directions API:
-```
-GoogleMapsTools.getDirections(origin, destination, mode)
-  -> routes[0].overview_polyline.points  (encoded polyline)
-```
-
-**Step 2** — Places Text Search with `searchAlongRouteParameters`:
-```
-POST https://places.googleapis.com/v1/places:searchText
-Headers:
-  X-Goog-Api-Key: <key>
-  X-Goog-FieldMask: places.displayName,places.id,places.formattedAddress,
-                    places.location,places.rating,places.userRatingCount,
-                    places.currentOpeningHours.openNow
-Body:
-{
-  "textQuery": "<query>",
-  "searchAlongRouteParameters": {
-    "polyline": { "encodedPolyline": "<encoded>" }
-  },
-  "maxResultCount": <1-20>
-}
-```
-
-**Limitations**:
-- Requires Places API (New) to be enabled
-- `maxResults` capped at 20
-- Uses REST fetch (not gRPC SDK) because `searchAlongRouteParameters` is not yet exposed in the Node.js gRPC client
-- Mode defaults to `walking` if not specified
-
----
-
-## Places API New vs Legacy
-
-| Aspect | Places API (New) | Places API (Legacy) |
-|---|---|---|
-| GCP service name | "Places API (New)" | "Places API" |
-| Node.js library | `@googlemaps/places` | `@googlemaps/google-maps-services-js` |
-| Protocol | gRPC (+ REST for searchText) | HTTPS REST |
-| Auth | `apiKey` in constructor / `X-Goog-Api-Key` header | `key` query param |
-| Field selection | `X-Goog-FieldMask` header | `fields` param |
-| Resource naming | `places/<id>` | raw `placeId` string |
-| Tools using it | `maps_search_nearby`, `maps_search_places`, `maps_place_details`, `maps_explore_area`, `maps_compare_places`, `maps_search_along_route` (step 2) | geocode, reverseGeocode, directions, distanceMatrix, elevation, timezone |
-| Max results | 20 per request | varies by endpoint |
-| Photos | Returns `photo.name` resource path | Returns `photo_reference` string |
-| Error codes | gRPC status codes (7=PERMISSION_DENIED, 8=RESOURCE_EXHAUSTED) | HTTP status codes |
-
-**Note**: `maps_search_along_route` uses the Routes API for step 1 (polyline extraction) and Places API (New) REST for step 2 (search). Both APIs must be enabled for this tool to function.