@cablate/mcp-google-map 0.0.33 → 0.0.35

package/README.md

@@ -6,7 +6,7 @@
 
 Give your AI agent the ability to understand the physical world — geocode, route, search, and reason about locations.
 
-- **10 tools** — geocode, reverse-geocode, search-nearby, search-places, place-details, directions, distance-matrix, elevation, timezone, weather
+- **13 tools** — 10 atomic + 3 composite (explore-area, plan-route, compare-places)
 - **3 modes** — stdio, StreamableHTTP, standalone exec CLI
 - **Agent Skill** — built-in skill definition teaches AI how to chain geo tools ([`skills/google-maps/`](./skills/google-maps/))
 
@@ -14,7 +14,7 @@ Give your AI agent the ability to understand the physical world — geocode, rou
 
 | | This project | [Grounding Lite](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) |
 |---|---|---|
-| Tools | **10** | 3 |
+| Tools | **13** | 3 |
 | Geocoding | Yes | No |
 | Step-by-step directions | Yes | No |
 | Elevation | Yes | No |
@@ -22,6 +22,7 @@ Give your AI agent the ability to understand the physical world — geocode, rou
 | Place details | Yes | No |
 | Timezone | Yes | No |
 | Weather | Yes | Yes |
+| Composite tools (explore, plan, compare) | Yes | No |
 | Open source | MIT | No |
 | Self-hosted | Yes | Google-managed only |
 | Agent Skill | Yes | No |
@@ -56,7 +57,11 @@ Special thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add sup
 | `maps_directions` | Get step-by-step navigation between two points with route details. |
 | `maps_elevation` | Get elevation (meters above sea level) for geographic coordinates. |
 | `maps_timezone` | Get timezone ID, name, UTC/DST offsets, and local time for coordinates. |
-| `maps_weather` | Get current weather conditions — temperature, humidity, wind, UV, precipitation. |
+| `maps_weather` | Get current weather conditions or forecast — temperature, humidity, wind, UV, precipitation. |
+| **Composite Tools** | |
+| `maps_explore_area` | Explore what's around a location — searches multiple place types and gets details in one call. |
+| `maps_plan_route` | Plan an optimized multi-stop route — geocodes, finds best order, returns directions. |
+| `maps_compare_places` | Compare places side-by-side — searches, gets details, and optionally calculates distances. |
 
 All tools are annotated with `readOnlyHint: true` and `destructiveHint: false` — MCP clients can auto-approve these without user confirmation.
 
@@ -106,7 +111,7 @@ Then configure your MCP client:
 ### Server Information
 
 - **Transport**: stdio (`--stdio`) or Streamable HTTP (default)
-- **Tools**: 10 Google Maps tools
+- **Tools**: 13 Google Maps tools (10 atomic + 3 composite)
 
 ### CLI Exec Mode (Agent Skill)
 
@@ -117,7 +122,7 @@ npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
 npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'
 ```
 
-All 10 tools available: `geocode`, `reverse-geocode`, `search-nearby`, `search-places`, `place-details`, `directions`, `distance-matrix`, `elevation`, `timezone`, `weather`. See [`skills/google-maps/`](./skills/google-maps/) for the agent skill definition and full parameter docs.
+All 13 tools available: `geocode`, `reverse-geocode`, `search-nearby`, `search-places`, `place-details`, `directions`, `distance-matrix`, `elevation`, `timezone`, `weather`, `explore-area`, `plan-route`, `compare-places`. See [`skills/google-maps/`](./skills/google-maps/) for the agent skill definition and full parameter docs.
 
 ### API Key Configuration
 
@@ -209,7 +214,10 @@ src/
 │       ├── directions.ts         # maps_directions tool
 │       ├── elevation.ts          # maps_elevation tool
 │       ├── timezone.ts           # maps_timezone tool
-│       └── weather.ts            # maps_weather tool
+│       ├── weather.ts            # maps_weather tool
+│       ├── exploreArea.ts        # maps_explore_area (composite)
+│       ├── planRoute.ts          # maps_plan_route (composite)
+│       └── comparePlaces.ts      # maps_compare_places (composite)
 └── utils/
     ├── apiKeyManager.ts          # API key management
     └── requestContext.ts         # Per-request context (API key isolation)
@@ -241,6 +249,38 @@ skills/
 
 For enterprise security reviews, see [Security Assessment Clarifications](./SECURITY_ASSESSMENT.md) — a 23-item checklist covering licensing, data protection, credential management, tool contamination, and AI agent execution environment verification.
 
+## Roadmap
+
+### New Tools
+
+| Tool | What it unlocks | Status |
+|------|----------------|--------|
+| `maps_static_map` | Return map images with pins/routes — multimodal AI can "see" the map | Planned |
+| `maps_air_quality` | AQI, pollutants — health-aware travel, outdoor planning, real estate | Planned |
+| `maps_validate_address` | Standardize and verify addresses — logistics/e-commerce | Planned |
+| `maps_isochrone` | "Show me everything within 30 min drive" — reachability analysis | Planned |
+| `maps_batch_geocode` | Geocode hundreds of addresses in one call — data enrichment | Planned |
+
+### Capabilities
+
+| Feature | What it unlocks | Status |
+|---------|----------------|--------|
+| Spatial Context | Agent remembers "the area we were just looking at" across turns | Research |
+| Geo Agent Template | One command to spin up a full geo-aware AI agent | Research |
+| Geo-Reasoning Benchmark | 10-scenario test suite measuring LLM geospatial reasoning accuracy | Research |
+
+### Use Cases We're Building Toward
+
+These are the real-world scenarios driving our tool decisions:
+
+- **Travel planning** — "Plan a day trip in Tokyo" (geocode → search → directions → weather)
+- **Real estate analysis** — "Analyze this neighborhood: schools, commute, flood risk" (search-nearby × N + elevation + distance-matrix)
+- **Logistics optimization** — "Route these 12 deliveries efficiently from the warehouse" (plan-route)
+- **Field sales** — "Visit 6 clients in Chicago, minimize drive time, find lunch spots" (plan-route + search-nearby)
+- **Disaster response** — "Nearest open hospitals? Am I in a flood zone?" (search-nearby + elevation)
+- **Content creation** — "Top 5 neighborhoods in Austin with restaurant density and airport distance" (explore-area + distance-matrix)
+- **Accessibility** — "Wheelchair-accessible restaurants, avoid steep routes" (search-nearby + place-details + elevation)
+
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md) for version history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cablate/mcp-google-map",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "mcpName": "io.github.cablate/google-map",
   "description": "Google Maps tools for AI agents — geocode, search, directions, elevation via MCP server or standalone CLI",
   "type": "module",

package/skills/google-maps/SKILL.md

@@ -35,7 +35,7 @@ Without this Skill, the agent can only guess or refuse when asked "how do I get
 
 ## Tool Map
 
-8 tools in three categories — pick by scenario:
+13 tools in four categories — pick by scenario:
 
 ### Place Discovery
 | Tool | When to use | Example |
@@ -52,10 +52,19 @@ Without this Skill, the agent can only guess or refuse when asked "how do I get
 | `directions` | How to get from A to B | "Route from Taipei Main Station to the airport" |
 | `distance-matrix` | Compare distances across multiple points | "Which of these 3 hotels is closest to the airport?" |
 
-### Terrain
+### Environment
 | Tool | When to use | Example |
 |------|-------------|---------|
 | `elevation` | Query altitude | "Elevation profile along this hiking trail" |
+| `timezone` | Need local time at a destination | "What time is it in Tokyo?" |
+| `weather` | Weather at a location (current or forecast) | "What's the weather in Paris?" |
+
+### Composite (one-call shortcuts)
+| Tool | When to use | Example |
+|------|-------------|---------|
+| `explore-area` | Overview of a neighborhood | "What's around Tokyo Tower?" |
+| `plan-route` | Multi-stop optimized itinerary | "Visit these 5 places efficiently" |
+| `compare-places` | Side-by-side comparison | "Which ramen shop near Shibuya?" |
 
 ---
 

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

@@ -160,6 +160,95 @@ Response:
 
 ---
 
+## timezone
+
+Get timezone and local time for coordinates.
+
+```bash
+exec timezone '{"latitude": 35.6586, "longitude": 139.7454}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| latitude | number | yes | Latitude |
+| longitude | number | yes | Longitude |
+| timestamp | number | no | Unix timestamp in ms (defaults to now) |
+
+Response:
+```json
+{ "timeZoneId": "Asia/Tokyo", "timeZoneName": "Japan Standard Time", "utcOffset": 32400, "dstOffset": 0, "localTime": "2026-03-14T16:19:16.000" }
+```
+
+---
+
+## weather
+
+Get current weather or forecast. Coverage: most regions, but China, Japan, South Korea, Cuba, Iran, North Korea, Syria are unsupported.
+
+```bash
+exec weather '{"latitude": 37.4220, "longitude": -122.0841}'
+exec weather '{"latitude": 37.4220, "longitude": -122.0841, "type": "forecast_daily", "forecastDays": 3}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| latitude | number | yes | Latitude |
+| longitude | number | yes | Longitude |
+| type | string | no | `current` (default), `forecast_daily`, `forecast_hourly` |
+| forecastDays | number | no | 1-10, for forecast_daily (default: 5) |
+| forecastHours | number | no | 1-240, for forecast_hourly (default: 24) |
+
+---
+
+## explore-area (composite)
+
+Explore a neighborhood in one call. Internally chains geocode → search-nearby (per type) → place-details (top N).
+
+```bash
+exec explore-area '{"location": "Tokyo Tower", "types": ["restaurant", "cafe"], "topN": 2}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| location | string | yes | Address or landmark |
+| types | string[] | no | Place types to search (default: restaurant, cafe, attraction) |
+| radius | number | no | Search radius in meters (default: 1000) |
+| topN | number | no | Top results per type to get details for (default: 3) |
+
+---
+
+## plan-route (composite)
+
+Plan an optimized multi-stop route. Internally chains geocode → distance-matrix → nearest-neighbor → directions.
+
+```bash
+exec plan-route '{"stops": ["Tokyo Tower", "Shibuya Station", "Shinjuku Station", "Ueno Park"], "mode": "driving"}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| stops | string[] | yes | Addresses or landmarks (min 2) |
+| mode | string | no | driving, walking, bicycling, transit (default: driving) |
+| optimize | boolean | no | Auto-optimize visit order (default: true) |
+
+---
+
+## compare-places (composite)
+
+Compare places side-by-side. Internally chains search-places → place-details → distance-matrix.
+
+```bash
+exec compare-places '{"query": "ramen near Shibuya", "limit": 3}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| query | string | yes | Search query |
+| userLocation | object | no | `{ latitude, longitude }` — adds distance/drive time |
+| limit | number | no | Max places to compare (default: 5) |
+
+---
+
 ## Chaining Patterns
 
 ### Basic Patterns