@cablate/mcp-google-map 0.0.24 → 0.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cablate/mcp-google-map",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "description": "Google Maps MCP server with streamable HTTP transport support for location services, geocoding, and navigation",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,8 @@
   "files": [
     "dist",
     "dist/**/*.map",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "scripts": {
     "build": "tsup --dts",
@@ -28,16 +29,21 @@
   },
   "keywords": [
     "google",
+    "google-maps",
     "map",
-    "api",
-    "llm",
-    "typescript",
     "mcp",
-    "server",
-    "streamable",
-    "location",
+    "mcp-server",
+    "model-context-protocol",
+    "agent-skill",
+    "ai-agent",
+    "geospatial",
     "geocoding",
-    "navigation"
+    "places",
+    "directions",
+    "navigation",
+    "location",
+    "streamable-http",
+    "typescript"
   ],
   "author": "CabLate",
   "license": "MIT",

package/skills/google-maps/SKILL.md

@@ -0,0 +1,78 @@
+---
+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.
+---
+
+# Google Maps - Geospatial Query Capabilities
+
+## Overview
+
+Gives an AI Agent the ability to reason about physical space — understand locations, distances, routes, and elevation, and naturally weave that information into conversation.
+
+Without this Skill, the agent can only guess or refuse when asked "how do I get from Taipei 101 to the National Palace Museum?". With it, the agent returns exact coordinates, step-by-step routes, and travel times.
+
+---
+
+## Core Principles
+
+| Principle | Explanation |
+|-----------|-------------|
+| Chain over single-shot | Most geo questions require chaining: geocode → search-nearby → place-details. Think about the full pipeline when planning queries. |
+| 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. |
+
+---
+
+## Tool Map
+
+8 tools in three categories — pick by scenario:
+
+### Place Discovery
+| Tool | When to use | Example |
+|------|-------------|---------|
+| `geocode` | Have an address/landmark, need coordinates | "What are the coordinates of Tokyo Tower?" |
+| `reverse-geocode` | Have coordinates, need an address | "What's at 35.65, 139.74?" |
+| `search-nearby` | Know a location, find nearby places by type | "Coffee shops near my hotel" |
+| `search-places` | Natural language place search | "Best ramen in Tokyo" |
+| `place-details` | Have a place_id, need full info | "Opening hours and reviews for this restaurant?" |
+
+### Routing & Distance
+| Tool | When to use | Example |
+|------|-------------|---------|
+| `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
+| Tool | When to use | Example |
+|------|-------------|---------|
+| `elevation` | Query altitude | "Elevation profile along this hiking trail" |
+
+---
+
+## Invocation
+
+```bash
+npx @cablate/mcp-google-map exec <tool> '<json_params>' [-k API_KEY]
+```
+
+- **API Key**: `-k` flag or `GOOGLE_MAPS_API_KEY` environment variable
+- **Output**: JSON to stdout, errors to stderr
+- **Stateless**: each call is independent
+
+---
+
+## When to Update This Skill
+
+| Trigger | What to update |
+|---------|----------------|
+| New tool added to the package | Tool Map table + references/tools-api.md |
+| Tool parameters changed | references/tools-api.md |
+| New chaining pattern discovered in practice | references/tools-api.md chaining section |
+
+---
+
+## Reference
+
+| 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 |

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

@@ -0,0 +1,180 @@
+# Google Maps Tools - Parameter & Response Reference
+
+## geocode
+
+Convert an address or landmark name to GPS coordinates.
+
+```bash
+exec geocode '{"address": "Tokyo Tower"}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| address | string | yes | Address or landmark name |
+
+Response:
+```json
+{
+  "success": true,
+  "data": {
+    "location": { "lat": 35.6585805, "lng": 139.7454329 },
+    "formatted_address": "4-chome-2-8 Shibakoen, Minato City, Tokyo 105-0011, Japan",
+    "place_id": "ChIJCewJkL2LGGAR3Qmk0vCTGkg"
+  }
+}
+```
+
+---
+
+## reverse-geocode
+
+Convert GPS coordinates to a street address.
+
+```bash
+exec reverse-geocode '{"latitude": 35.6586, "longitude": 139.7454}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| latitude | number | yes | Latitude |
+| longitude | number | yes | Longitude |
+
+Response:
+```json
+{
+  "success": true,
+  "data": {
+    "formatted_address": "...",
+    "place_id": "ChIJ...",
+    "address_components": [...]
+  }
+}
+```
+
+---
+
+## search-nearby
+
+Find places near a location by type.
+
+```bash
+exec search-nearby '{"center": {"value": "35.6586,139.7454", "isCoordinates": true}, "keyword": "restaurant", "radius": 500}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| center | object | yes | `{ value: string, isCoordinates: boolean }` — address or `lat,lng` |
+| keyword | string | no | Place type (restaurant, cafe, hotel, gas_station, hospital, etc.) |
+| radius | number | no | Search radius in meters (default: 1000) |
+| openNow | boolean | no | Only show currently open places |
+| minRating | number | no | Minimum rating (0-5) |
+
+Response: `{ success, location, data: [{ name, place_id, formatted_address, geometry, rating, user_ratings_total, opening_hours }] }`
+
+---
+
+## search-places
+
+Free-text place search. More flexible than search-nearby.
+
+```bash
+exec search-places '{"query": "ramen in Tokyo"}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| query | string | yes | Natural language search query |
+| locationBias | object | no | `{ latitude, longitude, radius? }` to bias results toward |
+| openNow | boolean | no | Only show currently open places |
+| minRating | number | no | Minimum rating (1.0-5.0) |
+| includedType | string | no | Place type filter |
+
+Response: `{ success, data: [{ name, place_id, address, location, rating, total_ratings, open_now }] }`
+
+---
+
+## place-details
+
+Get full details for a place by its place_id (from search results). Returns reviews, phone, website, hours, photos.
+
+```bash
+exec place-details '{"placeId": "ChIJCewJkL2LGGAR3Qmk0vCTGkg"}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| placeId | string | yes | Google Maps place ID (from search results) |
+
+---
+
+## directions
+
+Get step-by-step navigation between two points.
+
+```bash
+exec directions '{"origin": "Tokyo Tower", "destination": "Shibuya Station", "mode": "transit"}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| origin | string | yes | Starting point (address or landmark) |
+| destination | string | yes | End point (address or landmark) |
+| mode | string | no | Travel mode: driving, walking, bicycling, transit |
+| departure_time | string | no | Departure time (ISO 8601 or "now") |
+| arrival_time | string | no | Desired arrival time (transit only) |
+
+---
+
+## distance-matrix
+
+Calculate travel distances and times between multiple origins and destinations.
+
+```bash
+exec distance-matrix '{"origins": ["Tokyo Tower"], "destinations": ["Shibuya Station", "Shinjuku Station"], "mode": "driving"}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| origins | string[] | yes | List of origin addresses |
+| destinations | string[] | yes | List of destination addresses |
+| mode | string | no | Travel mode: driving, walking, bicycling, transit |
+
+---
+
+## elevation
+
+Get elevation data for geographic coordinates.
+
+```bash
+exec elevation '{"locations": [{"latitude": 35.6586, "longitude": 139.7454}]}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| locations | object[] | yes | Array of `{ latitude, longitude }` |
+
+Response:
+```json
+[{ "elevation": 17.23, "location": { "lat": 35.6586, "lng": 139.7454 }, "resolution": 610.81 }]
+```
+
+---
+
+## Common Chaining Patterns
+
+**Search → Details**
+```bash
+exec search-places '{"query":"Michelin restaurants in Taipei"}'
+exec 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}'
+```
+
+**Multi-point Comparison**
+```bash
+exec distance-matrix '{"origins":["Taipei Main Station","Banqiao Station"],"destinations":["Taoyuan Airport","Songshan Airport"],"mode":"driving"}'
+```