@cablate/mcp-google-map 0.0.37 → 0.0.38

package/skills/project-docs/SKILL.md

@@ -0,0 +1,66 @@
+---
+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** | 17 tools (14 atomic + 3 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

@@ -0,0 +1,135 @@
+# 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    NewPlacesService
+(Legacy REST SDK)  (Places API New gRPC/REST client)
+```
+
+| 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 (legacy) | `src/services/toolclass.ts` | Wrap `@googlemaps/google-maps-services-js` SDK |
+| API client (new) | `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/toolclass.ts` | Legacy Google Maps SDK wrapper — geocode, directions, distanceMatrix, elevation, timezone, weather, airQuality, staticMap |
+| `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

@@ -0,0 +1,149 @@
+# 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

@@ -0,0 +1,286 @@
+# 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 |