diff --git a/CLAUDE.md b/CLAUDE.md index 15cce47..7c68dc9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,3 +4,21 @@ - **永遠不要直接推 main**。所有變更都要先開 feature branch、推上去、建 PR，等審核通過後才合併。 - Commit 完成後走 `git checkout -b feat/xxx` → `git push -u origin feat/xxx` → `gh pr create` 流程。 + +## Tool 變更 Checklist + +每次新增、刪除、或重新命名 tool 時，以下所有檔案都必須同步更新： + +| # | 檔案 | 更新內容 | +|---|------|---------| +| 1 | `src/tools/maps/*.ts` | Tool 定義（NAME, DESCRIPTION, SCHEMA, ACTION） | +| 2 | `src/config.ts` | 註冊 tool + annotations | +| 3 | `src/cli.ts` | EXEC_TOOLS 列表 + switch case | +| 4 | `tests/smoke.test.ts` | expectedTools 陣列 + tool count assertions | +| 5 | `README.md` | tool 數量（header、vs Grounding Lite 表、Server Info、exec mode）+ Available Tools 表格 + Project Structure | +| 6 | `skills/google-maps/SKILL.md` | Tool Map 表格 | +| 7 | `skills/google-maps/references/tools-api.md` | 參數文件 + chaining patterns | +| 8 | `server.json` | description（如有提到 tool 數量） | +| 9 | `package.json` | description（如有提到 tool 數量） | + +漏更任何一個都會造成文件和實際行為不一致。PR 提交前請逐一確認。 diff --git a/README.md b/README.md index 5e5cc55..f2df2fa 100644 --- a/README.md +++ b/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) diff --git a/skills/google-maps/SKILL.md b/skills/google-maps/SKILL.md index c9fdc8b..6869ec4 100644 --- a/skills/google-maps/SKILL.md +++ b/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?" | --- diff --git a/skills/google-maps/references/tools-api.md b/skills/google-maps/references/tools-api.md index e363f47..4db190a 100644 --- a/skills/google-maps/references/tools-api.md +++ b/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