@cablate/mcp-google-map 0.0.26 → 0.0.28

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cablate/mcp-google-map",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "mcpName": "io.github.cablate/google-map",
-  "description": "Google Maps tools for AI agents — 8 tools (geocode, search, directions, elevation) via MCP server or standalone Agent Skill CLI",
+  "description": "Google Maps tools for AI agents — geocode, search, directions, elevation via MCP server or standalone CLI",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

package/skills/google-maps/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: google-maps
 description: Geospatial query capabilities — geocoding, nearby search, routing, place details, elevation. Trigger when the user mentions locations, addresses, coordinates, navigation, "what's nearby", "how to get there", distance/duration, or any question that inherently involves geographic information — even if they don't explicitly say "map". Update when new tools are added or tool parameters change.
+license: MIT
+version: 0.0.25
+compatibility:
+  - claude-code
+  - cursor
+  - vscode-copilot
+  - openai-codex
+  - gemini-cli
 ---
 
 # Google Maps - Geospatial Query Capabilities
@@ -17,9 +25,11 @@ Without this Skill, the agent can only guess or refuse when asked "how do I get
 
 | Principle | Explanation |
 |-----------|-------------|
-| Chain over single-shot | Most geo questions require chaining: geocode → search-nearby → place-details. Think about the full pipeline when planning queries. |
+| 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 as tables | Users prefer comparison tables and scorecards over raw JSON. Format results for readability. |
 
 ---
 
@@ -75,4 +85,4 @@ npx @cablate/mcp-google-map exec <tool> '<json_params>' [-k API_KEY]
 
 | File | Content | When to read |
 |------|---------|--------------|
-| `references/tools-api.md` | Full parameter specs, response formats, and chaining patterns for all 8 tools | When you need exact parameter names, types, response shapes, or multi-tool workflows |
+| `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 |

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

@@ -160,21 +160,194 @@ Response:
 
 ---
 
-## Common Chaining Patterns
+## Chaining Patterns
 
-**Search → Details**
-```bash
-exec search-places '{"query":"Michelin restaurants in Taipei"}'
-exec place-details '{"placeId":"ChIJ..."}'  # use place_id from results
+### Basic Patterns
+
+**Search → Details** — Find places, then get full info on the best ones.
+```
+search-places {"query":"Michelin restaurants in Taipei"}
+place-details {"placeId":"ChIJ..."}  ← use place_id from results
 ```
 
-**Geocode → Nearby Search**
-```bash
-exec geocode '{"address":"Taipei 101"}'
-exec search-nearby '{"center":{"value":"25.033,121.564","isCoordinates":true},"keyword":"cafe","radius":500}'
+**Geocode → Nearby** — Turn a landmark into coordinates, then explore the area.
+```
+geocode {"address":"Taipei 101"}
+search-nearby {"center":{"value":"25.033,121.564","isCoordinates":true},"keyword":"cafe","radius":500}
 ```
 
-**Multi-point Comparison**
-```bash
-exec distance-matrix '{"origins":["Taipei Main Station","Banqiao Station"],"destinations":["Taoyuan Airport","Songshan Airport"],"mode":"driving"}'
+**Multi-point Comparison** — Compare distances across multiple origins and destinations in one call.
+```
+distance-matrix {"origins":["Taipei Main Station","Banqiao Station"],"destinations":["Taoyuan Airport","Songshan Airport"],"mode":"driving"}
+```
+
+---
+
+## Scenario Recipes
+
+Use these recipes when the user's question maps to a multi-step workflow. Think of each recipe as a **decision tree**, not a script — adapt based on what the user actually needs.
+
+### Recipe 1: Trip Planning ("Plan a day in Tokyo")
+
+This is the most common complex scenario. The goal is a time-ordered itinerary with routes between stops.
+
+**Steps:**
+1. `geocode` — Resolve all mentioned landmarks to coordinates
+2. `search-nearby` — Find restaurants/attractions near each landmark (use coordinates from step 1)
+3. `place-details` — Get ratings, hours, reviews for top candidates (use place_id from step 2)
+4. `distance-matrix` — Compare travel times between all candidate stops to find the optimal order
+5. `directions` — Generate turn-by-turn routes between stops in the final order
+
+**Key decisions:**
+- If the user says "near X", use `search-nearby`. If they say "best Y in Z", use `search-places`.
+- Always check `opening_hours` from `place-details` before including in itinerary.
+- Use `distance-matrix` to order stops efficiently, THEN use `directions` for the final route.
+
+**Example output shape:**
+```
+Morning: Tokyo Tower (9:00) → 12 min walk → Zojoji Temple (9:30)
+Lunch: Sushi Dai (11:30) ★4.6 — 2.1 km, 8 min by transit
+Afternoon: TeamLab (14:00) → Odaiba area
 ```
+
+---
+
+### Recipe 2: "What's nearby?" / Local Discovery
+
+User asks about places around a location. May or may not specify what type.
+
+**Steps:**
+1. `geocode` — Resolve the location (skip if user gave coordinates)
+2. `search-nearby` — Search with keyword + radius. Use `openNow: true` if the user implies "right now"
+3. `place-details` — Get details for the top 3-5 results (ratings, reviews, hours)
+
+**Key decisions:**
+- If no keyword specified, search multiple types: restaurant, cafe, attraction
+- Use `minRating: 4.0` by default unless the user wants comprehensive results
+- Sort results by rating × review count, not just rating alone
+
+---
+
+### Recipe 3: Route Comparison ("Best way to get from A to B")
+
+User wants to compare travel options between two points.
+
+**Steps:**
+1. `directions` with `mode: "driving"` — Get driving route
+2. `directions` with `mode: "transit"` — Get transit route
+3. `directions` with `mode: "walking"` — Get walking route (if distance < 5 km)
+
+**Present as comparison table:**
+```
+| Mode    | Duration | Distance | Notes            |
+|---------|----------|----------|------------------|
+| Driving | 25 min   | 12.3 km  | Via Highway 1    |
+| Transit | 35 min   | —        | Metro Line 2     |
+| Walking | 2h 10min | 10.1 km  | Not recommended  |
+```
+
+---
+
+### Recipe 4: Neighborhood Analysis ("Is this a good area?")
+
+User wants to evaluate a location for living, working, or investing.
+
+**Steps:**
+1. `geocode` — Resolve the address
+2. `search-nearby` — Run multiple searches from the same center:
+   - `keyword: "school"` radius 2000
+   - `keyword: "hospital"` radius 3000
+   - `keyword: "supermarket"` radius 1000
+   - `keyword: "restaurant"` radius 500
+   - `keyword: "park"` radius 1000
+3. `distance-matrix` — Calculate commute time to important locations (office, airport, city center)
+4. `elevation` — Check if the area is in a low-elevation flood zone
+
+**Present as scorecard:**
+```
+📍 742 Evergreen Terrace
+Schools within 2km: 4 (avg ★4.2)
+Hospitals within 3km: 2
+Supermarkets within 1km: 3
+Commute to downtown: 22 min driving, 35 min transit
+Elevation: 45m (not a flood risk)
+```
+
+---
+
+### Recipe 5: Multi-Stop Route ("Visit these 5 places efficiently")
+
+User has a list of places and wants the optimal visit order.
+
+**Steps:**
+1. `geocode` — Resolve all addresses to coordinates
+2. `distance-matrix` — Calculate NxN matrix (all origins × all destinations)
+3. Use the matrix to determine the nearest-neighbor route order
+4. `directions` — Generate route for the final order (chain waypoints)
+
+**Key decisions:**
+- For ≤ 5 stops, nearest-neighbor heuristic is good enough
+- For the `directions` call, set origin = first stop, destination = last stop, and mention intermediate stops in conversation
+- If the user says "return to start", plan a round trip
+
+---
+
+### Recipe 6: Place Comparison ("Which restaurant should I pick?")
+
+User is choosing between specific places.
+
+**Steps:**
+1. `search-places` — Find each place (or use place_id if already known)
+2. `place-details` — Get full details for each candidate
+3. `distance-matrix` — Calculate distance from user's location to each candidate
+
+**Present as comparison:**
+```
+| Restaurant | Rating | Reviews | Distance | Price | Open Now |
+|-----------|--------|---------|----------|-------|----------|
+| Sushi Dai  | ★4.6   | 2,340   | 1.2 km   | $$   | Yes      |
+| Tsukiji    | ★4.3   | 890     | 0.8 km   | $    | Yes      |
+| Omakase    | ★4.8   | 156     | 3.1 km   | $$$$ | No       |
+```
+
+---
+
+### Recipe 7: "Along the Route" Search
+
+User wants to find things along a route (gas stations, rest stops, food).
+
+**Steps:**
+1. `directions` — Get the route first, extract key waypoints from the steps
+2. `search-nearby` — Search near 2-3 midpoints along the route
+3. `place-details` — Get details for top results at each midpoint
+
+**Key decisions:**
+- Extract waypoints at roughly equal intervals along the route
+- Use the `start_location` of route steps at ~1/3 and ~2/3 of the total distance
+- Set `radius` based on road type: 1000m for highways, 500m for city streets
+
+---
+
+## Decision Guide: Which Recipe to Use
+
+| User says... | Recipe | First tool |
+|-------------|--------|------------|
+| "Plan a trip / itinerary / day in X" | Trip Planning | `geocode` |
+| "What's near X / around X" | Local Discovery | `geocode` → `search-nearby` |
+| "How do I get to X" / "route from A to B" | Route Comparison | `directions` |
+| "Is X a good neighborhood" / "analyze this area" | Neighborhood Analysis | `geocode` |
+| "Visit A, B, C, D efficiently" | Multi-Stop Route | `geocode` → `distance-matrix` |
+| "Which X should I pick" / "compare these" | Place Comparison | `search-places` |
+| "Find gas stations on the way to X" | Along the Route | `directions` → `search-nearby` |
+
+---
+
+## Future Composite Tools (Planned)
+
+These high-frequency scenarios are candidates for single-call composite tools in a future version:
+
+| Composite Tool | What it would do | Replaces |
+|---------------|-----------------|----------|
+| `maps_explore_area` | geocode + multi-type search-nearby + place-details for top results | Recipe 2 (3-call → 1-call) |
+| `maps_plan_route` | geocode all stops + distance-matrix + directions in optimal order | Recipe 5 (4-call → 1-call) |
+| `maps_compare_places` | search + details + distance for N candidates | Recipe 6 (3-call → 1-call) |