mcp-google-map 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. package/.env.example +5 -1
  2. package/README.md +126 -81
  3. package/dist/{chunk-K27FX5QH.js → chunk-NAUIQEK4.js} +2 -2
  4. package/dist/chunk-NAUIQEK4.js.map +1 -0
  5. package/dist/cli.d.ts +128 -3
  6. package/dist/cli.js +1345 -88
  7. package/dist/cli.js.map +1 -1
  8. package/dist/index.js +1 -1
  9. package/docs/CONFIGURATION.md +20 -12
  10. package/docs/TOOLS.md +1 -1
  11. package/package.json +9 -6
  12. package/src/resources/skills/README.md +40 -0
  13. package/src/resources/skills/manifest.json +14 -0
  14. package/src/resources/skills/venue-discovery/SKILL.md +304 -0
  15. package/dist/chunk-K27FX5QH.js.map +0 -1
  16. package/docs/GEOSCOUT.md +0 -53
package/.env.example CHANGED
@@ -6,8 +6,12 @@ GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
6
6
  # HTTP transport port (scripts/start-http.sh and default server port)
7
7
  MCP_SERVER_PORT=3000
8
8
 
9
- # HTTP bind address (0.0.0.0 = all interfaces)
9
+ # HTTP bind address (default: 127.0.0.1 loopback; use 0.0.0.0 for all interfaces)
10
10
  MCP_SERVER_HOST=127.0.0.1
11
11
 
12
12
  # Optional: comma-separated allowlist of exposed tools (omit or "*" = all 18)
13
13
  # GOOGLE_MAPS_ENABLED_TOOLS=maps_search_places,maps_place_details,maps_geocode
14
+
15
+ # Automatic update check at server startup (enabled by default).
16
+ # Set to 1, true, or yes to skip the npm registry version check.
17
+ # MCP_AUTO_UPDATE_DISABLED=1
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # mcp-google-map (0.3.0)
1
+ # mcp-google-map (0.5.0)
2
2
 
3
3
  <p align="center">
4
4
  <img src="https://img.shields.io/badge/node-%3E%3D22-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js >= 22">
@@ -9,21 +9,22 @@
9
9
 
10
10
  <p align="center">
11
11
  <strong>Google Maps Platform MCP server — 18 tools for AI agents (stdio + Streamable HTTP)</strong><br>
12
- Server [Model Context Protocol](https://modelcontextprotocol.io) per **Google Maps Platform**, con 18 tool per agenti AI: ricerca Places API (New) con **filtri server-side** (`priceLevels`, `minRating`, `strictTypeFiltering`), paginazione nativa, accesso al **payload raw** delle risposte API, geocoding, indicazioni, matrice delle distanze e altro.
12
+ A [Model Context Protocol](https://modelcontextprotocol.io) server for **Google Maps Platform** with 18 tools for AI agents: Places API (New) search with **server-side filters** (`priceLevels`, `minRating`, `strictTypeFiltering`), raw API payload access, geocoding, directions, distance matrix, and more.
13
13
 
14
- Trasporti supportati: **stdio** (client MCP locali) e **Streamable HTTP**.
14
+ Supported transports: **stdio** (local MCP clients) and **Streamable HTTP**.
15
15
 
16
- > Compatibile con il protocollo di ricerca **GeoScout 6.2** — vedi [docs/GEOSCOUT.md](docs/GEOSCOUT.md).
16
+ > Ships the **venue-discovery** agent skill (`src/resources/skills/`) for budget-, quality-, category-, and schedule-validated venue search.
17
17
 
18
18
  </p>
19
19
 
20
20
  <p align="center">
21
21
  <a href="#feature-highlights">Feature Highlights</a> |
22
- <a href="#requisiti">Requirements</a> |
22
+ <a href="#requirements">Requirements</a> |
23
23
  <a href="#install">Install / Uninstall</a> |
24
- <a href="#avvio-rapido">Quick Start</a> |
25
- <a href="#registrazione-in-un-client-mcp">MCP Clients</a> |
26
- <a href="#documentazione">Docs</a>
24
+ <a href="#quick-start">Quick Start</a> |
25
+ <a href="#command-line-interface">CLI</a> |
26
+ <a href="#registering-in-an-mcp-client">MCP Clients</a> |
27
+ <a href="#documentation">Docs</a>
27
28
  </p>
28
29
  <p align="center">
29
30
  <br>
@@ -36,37 +37,38 @@ Trasporti supportati: **stdio** (client MCP locali) e **Streamable HTTP**.
36
37
  ## Feature Highlights
37
38
 
38
39
  - **18 Google Maps MCP tools** — geocoding, reverse geocoding, Places API (New) text/nearby search, place details, directions, distance matrix, elevation, timezone, weather, air quality, static maps, batch geocode, plus composite tools (explore-area, plan-route, compare-places, search-along-route, local-rank-tracker). Full catalog: [docs/TOOLS.md](docs/TOOLS.md).
39
- - **Server-side Places filters** — `priceLevels`, `minRating`, `openNow`, `strictTypeFiltering`, and location bias are forwarded to Places API (New), not emulated client-side.
40
+ - **Server-side Places filters** — `priceLevels`, `minRating`, `openNow`, `includedType`, `strictTypeFiltering`, and location bias are forwarded to Places API (New) as request fields by `maps_search_places`; in `maps_search_nearby`, `openNow` and `minRating` are applied after the query, so filters can return fewer than 20 results.
40
41
  - **Raw API payloads** — searches and details can return the untouched Google response (`includeRaw: true`) with explicit Field Masks.
41
42
  - **Two transports** — stdio for local MCP clients (pi, Claude Desktop, Cursor, ...) and Streamable HTTP at `/mcp` with per-session API keys.
42
43
  - **Per-request credentials** — key resolution from `X-Google-Maps-API-Key` or `Authorization: Bearer` headers, session key, or `GOOGLE_MAPS_API_KEY` environment.
43
44
  - **Standalone CLI** — `doctor` self-checks, `exec <tool>` one-shot calls, `batch-geocode` with bounded concurrency.
44
- - **GeoScout 6.2 compatible** — see [docs/GEOSCOUT.md](docs/GEOSCOUT.md).
45
+ - **Automatic update check** — at server startup the server compares its version against the latest npm release and prints an upgrade notice on stderr; it never blocks startup and can be disabled with `MCP_AUTO_UPDATE_DISABLED=1` (see [Configuration prerequisites](#configuration-prerequisites)).
46
+ - **Venue-discovery skill** — server-side `priceLevels`/`minRating`/`strictTypeFiltering` filters and raw payloads back the bundled `venue-discovery` skill (`src/resources/skills/`).
45
47
 
46
- ## Requisiti
48
+ ## Requirements
47
49
 
48
50
  - Node.js **>= 22**
49
- - Una **Google Maps API key** (<https://console.cloud.google.com/apis/credentials>) con i servizi abilitati — vedi sotto
51
+ - A **Google Maps API key** (<https://console.cloud.google.com/apis/credentials>) with the services enabled — see below
50
52
 
51
- ## API Google Cloud richieste
53
+ ## Required Google Cloud APIs
52
54
 
53
- Mappatura verificata sui sorgenti: ogni endpoint usato dal server e il tool che lo richiede.
55
+ Mapping verified against the sources: every endpoint the server calls and the tools that call it.
54
56
 
55
- | # | API da abilitare | Endpoint usato dal server | Tool che la richiedono | Necessaria per | Priorità GeoScout |
57
+ | # | API to enable | Endpoint used by the server | Tools that require it | Needed for | Skill priority |
56
58
  |---|---|---|---|---|---|
57
- | 1 | **Places API (New)** | `places.googleapis.com` (`places:searchText`, `places:searchNearby`, `GET places/{id}`, photo media) via `@googlemaps/places` | `maps_search_places`, `maps_search_nearby`, `maps_place_details`, `maps_explore_area`, `maps_compare_places`, `maps_search_along_route`, `maps_local_rank_tracker` | Ricerca/dettaglio locali, filtri `priceLevels`/`minRating`, `priceRange`, orari | **Obbligatoria** |
58
- | 2 | **Geocoding API** | `maps.googleapis.com/maps/api/geocode/json` via `@googlemaps/google-maps-services-js` | `maps_geocode`, `maps_reverse_geocode`, `maps_batch_geocode` (+ fallback interno di risoluzione indirizzi) | Conversione indirizzo ↔ coordinate | Alta |
59
- | 3 | **Routes API** | `routes.googleapis.com` (`computeRoutes`, `computeRouteMatrix`) | `maps_directions`, `maps_distance_matrix`, `maps_plan_route` | Percorsi e matrice distanze | Media |
60
- | 4 | **Time Zone API** | `maps.googleapis.com/maps/api/timezone/json` | `maps_timezone` | Fuso orario / ora locale | Bassa |
61
- | 5 | **Maps Elevation API** *(in console: "Maps Elevation API", servizio `elevation-backend`)* | `maps.googleapis.com/maps/api/elevation/json` | `maps_elevation` | Quota del terreno | Bassa |
62
- | 6 | **Maps Static API** | `maps.googleapis.com/maps/api/staticmap` | `maps_static_map` | Immagine mappa PNG | Bassa |
63
- | 7 | **Weather API** | `weather.googleapis.com/v1` (current, forecast/days, forecast/hours) | `maps_weather` | Meteo corrente/previsioni | Bassa (disponibilità regionale) |
64
- | 8 | **Air Quality API** | `airquality.googleapis.com/v1/currentConditions:lookup` | `maps_air_quality` | Qualità dell'aria | Bassa (disponibilità regionale) |
59
+ | 1 | **Places API (New)** | `places.googleapis.com` (`places:searchText`, `places:searchNearby`, `GET places/{id}`, photo media) via `@googlemaps/places` | `maps_search_places`, `maps_search_nearby`, `maps_place_details`, `maps_explore_area`, `maps_compare_places`, `maps_search_along_route`, `maps_local_rank_tracker` | Place search/details, `priceLevels`/`minRating` filters, `priceRange`, opening hours | **Required** |
60
+ | 2 | **Geocoding API** | `maps.googleapis.com/maps/api/geocode/json` via `@googlemaps/google-maps-services-js` | `maps_geocode`, `maps_reverse_geocode`, `maps_batch_geocode` (+ internal address-resolution fallback) | Address ↔ coordinate conversion | High |
61
+ | 3 | **Routes API** | `routes.googleapis.com` (`computeRoutes`, `computeRouteMatrix`) | `maps_directions`, `maps_distance_matrix`, `maps_plan_route` | Routes and distance matrix | Medium |
62
+ | 4 | **Time Zone API** | `maps.googleapis.com/maps/api/timezone/json` | `maps_timezone` | Time zone / local time | Low |
63
+ | 5 | **Maps Elevation API** *(in the console: "Maps Elevation API", service `elevation-backend`)* | `maps.googleapis.com/maps/api/elevation/json` | `maps_elevation` | Ground elevation | Low |
64
+ | 6 | **Maps Static API** | `maps.googleapis.com/maps/api/staticmap` | `maps_static_map` | PNG map image | Low |
65
+ | 7 | **Weather API** | `weather.googleapis.com/v1` (current, forecast/days, forecast/hours) | `maps_weather` | Current weather / forecasts | Low (regional availability) |
66
+ | 8 | **Air Quality API** | `airquality.googleapis.com/v1/currentConditions:lookup` | `maps_air_quality` | Air quality | Low (regional availability) |
65
67
 
66
- Abilitazione rapida (progetto GCP corrente):
68
+ Quick enablement (current GCP project):
67
69
 
68
70
  ```bash
69
- PROJECT=iltuoprogetto
71
+ PROJECT=your-project
70
72
  gcloud services enable places-backend-new.googleapis.com \
71
73
  geocoding-backend.googleapis.com \
72
74
  routes.googleapis.com \
@@ -77,38 +79,43 @@ gcloud services enable places-backend-new.googleapis.com \
77
79
  airquality.googleapis.com --project=$PROJECT
78
80
  ```
79
81
 
80
- ### Note
82
+ ### Notes
81
83
 
82
- - Per l'uso minimo/GeoScout bastano **Places API (New)** + **Geocoding API**; le altre si abilitano solo se si usano i tool corrispondenti (in alternativa limitare l'esposizione con `GOOGLE_MAPS_ENABLED_TOOLS`).
83
- - **Maps Grounding Lite** e **Geolocation API** **non sono richieste** da questo server: la prima serve all'MCP hosted di Google (`mapstools.googleapis.com`), la seconda non è usata da nessun tool (non c'è `ip_geolocate` in questo fork).
84
- - La vecchia **Places API** (legacy) non è necessaria: il server usa esclusivamente Places API (New).
85
- - Weather API e Air Quality API hanno copertura regionale limitata: fuori copertura il tool restituisce errore dell'API.
84
+ - For minimal venue-discovery use, **Places API (New)** + **Geocoding API** suffice; enable the others only for the corresponding tools (or limit exposure with `GOOGLE_MAPS_ENABLED_TOOLS`).
85
+ - **Maps Grounding Lite** and **Geolocation API** are **not required** by this server: the former belongs to Google's hosted MCP (`mapstools.googleapis.com`), the latter is used by no tool (there is no `ip_geolocate` in this fork).
86
+ - The legacy **Places API** is not needed: the server uses Places API (New) exclusively.
87
+ - Weather API and Air Quality API have limited regional coverage: outside coverage, the tool returns an unsupported-location error message.
86
88
 
87
89
 
88
90
  ## Install
89
91
 
90
- **Prerequisites**: Node.js **>= 22** and a Google Maps API key (see [Requisiti](#requisiti)).
92
+ **Prerequisites**: Node.js **>= 22** and a Google Maps API key (see [Requirements](#requirements)).
91
93
 
92
- ### From npm
94
+ ### Prebuilt package (recommended)
93
95
 
94
96
  ```bash
95
97
  npm install -g mcp-google-map
96
- mcp-google-map doctor # self-check (no API calls)
97
- npx -y mcp-google-map --stdio # one-shot stdio server, no global install
98
+ mcp-google-map setup --write-env # scaffold .env in the current directory (never overwrites)
99
+ $EDITOR .env # set GOOGLE_MAPS_API_KEY
100
+ mcp-google-map doctor # local self-check: Node, package, key, config (no network)
101
+ mcp-google-map --stdio # MCP server over stdio
102
+ mcp-google-map # MCP server over Streamable HTTP at http://127.0.0.1:3000/mcp
98
103
  ```
99
104
 
105
+ One-shot alternative without a global install: `npx -y mcp-google-map --stdio`.
106
+
100
107
  ### From source (this repository) — cross-platform, no bash required
101
108
 
102
109
  ```bash
103
110
  git clone https://github.com/Ogekuri/mcp-google-map.git
104
111
  cd mcp-google-map
105
- npm install
112
+ npm ci # install dependencies from the lockfile
106
113
  npm run build # tsup -> dist/ (ESM)
107
114
  node dist/cli.js --stdio # MCP server over stdio
108
115
  node dist/cli.js --host 127.0.0.1 --port 3000 # Streamable HTTP at /mcp
109
116
  ```
110
117
 
111
- On Linux/macOS the bash helpers in `scripts/` automate the same steps (`scripts/setup.sh`, `scripts/build.sh`, `scripts/start-mcp.sh`, `scripts/start-http.sh`, `scripts/test.sh`); on Windows use the `npm`/`node` commands above.
118
+ On Linux/macOS the bash helpers in `scripts/` wrap the same commands (`scripts/setup.sh`, `scripts/build.sh`, `scripts/start-mcp.sh`, `scripts/start-http.sh`, `scripts/test.sh`); each helper fails with remediation guidance instead of chaining implicit installs or builds. On Windows use the `npm`/`node` commands above.
112
119
 
113
120
  MCP client registration over stdio works cross-platform with plain `node`:
114
121
 
@@ -131,19 +138,53 @@ npm uninstall -g mcp-google-map # npm-based install
131
138
  rm -rf mcp-google-map # from-source clone; also remove any MCP client registration
132
139
  ```
133
140
 
134
- ## Avvio rapido
141
+ ## Quick Start
142
+
143
+ The [prebuilt-package path](#install) is the recommended Quick Start: install, `setup --write-env`, set the key, `doctor`, run. Registration snippets for any client are one command away (JSON on stdout, no files written):
135
144
 
136
145
  ```bash
137
- scripts/setup.sh # installa le dipendenze e crea .env
138
- $EDITOR .env # inserisci GOOGLE_MAPS_API_KEY
139
- scripts/build.sh # compila in dist/
146
+ mcp-google-map snippet --client claude # stdio snippet (npx launcher)
147
+ mcp-google-map snippet --client pi --env-key GOOGLE_MAPS_API_KEY # ${VAR} reference (client-specific expansion)
148
+ mcp-google-map snippet --transport http --port 3100 # HTTP URL snippet
149
+ ```
150
+
151
+ > **Loopback default (migration)**: the HTTP server now binds to `127.0.0.1` by default; it previously bound `0.0.0.0`. To listen on all interfaces pass `--host 0.0.0.0` or set `MCP_SERVER_HOST=0.0.0.0`. In HTTP mode, `SIGINT`/`SIGTERM` close all sessions and the listening socket before exit.
152
+
153
+ ## Command-line interface
140
154
 
141
- scripts/start-mcp.sh # server MCP su stdio (per pi, Claude Desktop, Cursor, ...)
142
- scripts/start-http.sh # server MCP su http://127.0.0.1:3000/mcp
143
- scripts/test.sh # test unitari (nessuna API key richiesta)
155
+ All commands work through the `mcp-google-map` binary (npm install) or `node dist/cli.js` (from source).
156
+
157
+ ```bash
158
+ mcp-google-map --stdio # MCP server over stdio
159
+ mcp-google-map --host 127.0.0.1 --port 3000 # MCP server over Streamable HTTP at /mcp (loopback default)
160
+ mcp-google-map setup --write-env # onboarding: readiness checks + .env scaffold (no network, no prompts)
161
+ mcp-google-map doctor # local self-check: Node, package, key, config, tool profiles (no network)
162
+ mcp-google-map doctor --live --apikey "AIza..." # also probes Geocoding, Places (New), Routes (billable calls)
163
+ mcp-google-map doctor --live --probes geocoding,routes # probe only the selected APIs
164
+ mcp-google-map exec geocode '{"address":"Tokyo Tower"}' # one tool call from the terminal
165
+ mcp-google-map batch-geocode -i addresses.txt -o results.json
166
+ mcp-google-map enable pi claude # enable MCP registration + skills for specific CLIs
167
+ mcp-google-map install # register the stdio server and install skills in every enabled CLI
168
+ mcp-google-map uninstall # reciprocal removal of install in every enabled CLI
169
+ mcp-google-map show # CLI Configuration and Installation Status tables
170
+ mcp-google-map --env-file /path/to/.env doctor # load an explicit environment file
171
+ mcp-google-map snippet --client cursor # print an MCP client registration snippet (no files written)
144
172
  ```
145
173
 
146
- ## Registrazione in un client MCP
174
+ - `exec <tool> [params]` runs one tool and prints JSON; `params` is a JSON string. Tool names accept short (`geocode`), snake_case (`search_places`), and `maps_`-prefixed (`maps_geocode`) forms.
175
+ - `exec` writes results to stdout and errors to stderr; it exits 1 when no API key is configured, the tool reports a failure, the JSON is invalid, or the tool name is unknown.
176
+ - `batch-geocode` reads one address per line from `--input` (use `-` for stdin), geocodes with bounded concurrency (`--concurrency`, default 20, clamped to 1–50), writes a JSON summary `{ total, succeeded, failed, results }` to `--output` or stdout, and exits 1 if any address failed.
177
+ - `setup` is non-interactive: no prompts, no Google API calls, and no writes unless `--write-env` is passed; `--write-env` creates `.env` in `--env-dir` (default: current directory) only when it does not exist and never overwrites it.
178
+ - `snippet` prints a valid `mcpServers` JSON registration to stdout (guidance notes on stderr) and never writes or edits configuration files; by default it embeds a literal placeholder, and `--env-key NAME` emits a `${NAME}` reference whose expansion is client-specific.
179
+ - `--env-file <path>` loads exactly the given environment file for any command and exits 1 with a JSON error when the file is missing (no implicit `.env` fallback).
180
+ - `enable <cli>` / `disable <cli>` manage the persisted enabled-CLI set at `~/.config/mcp-google-map/config.json`; accepted names (case-insensitive): `pi`, `openclaw`, `codex`, `antigravity`, `claude`; unsupported names exit 2 listing the supported ones.
181
+ - `install` registers for every enabled CLI the stdio server entry `mcp-google-map` (`npx -y mcp-google-map --stdio`, embedding the resolved `GOOGLE_MAPS_API_KEY` when set) and installs every bundled skill; `uninstall` is the reciprocal removal. Per-CLI targets: pi `~/.pi/agent/mcp.json` + `~/.pi/agent/skills`, openclaw `~/.openclaw/openclaw.json` + `~/.openclaw/workspace/skills`, codex `~/.codex/config.toml` (`mcp_servers` table) + `~/.codex/skills`, antigravity `~/.gemini/settings.json` + `~/.gemini/config/skills`, claude `~/.claude.json` + `~/.claude/skills`. Existing unrelated configuration entries are always preserved.
182
+ - `show` prints two human-readable tables: CLI Configuration (CLI, Enabled, MCP Config Path, Skills Config Path for all five CLIs) and Installation Status (Type, Name, CLI, Enabled, Installed with OK/MISSING/STALE per enabled CLI).
183
+ - HTTP mode starts even without an API key and logs a warning; stdio mode and the CLI commands require a key (`--apikey` or `GOOGLE_MAPS_API_KEY`). When no HTTP instance can start (invalid or taken port), the process exits non-zero.
184
+
185
+ ## Registering in an MCP client
186
+
187
+ Generate the registration JSON with `mcp-google-map snippet --client <generic|claude|cursor|pi>` (see [Quick Start](#quick-start)), then paste it into the target file. Manual examples:
147
188
 
148
189
  **stdio:**
149
190
 
@@ -151,14 +192,14 @@ scripts/test.sh # test unitari (nessuna API key richiesta)
151
192
  {
152
193
  "mcpServers": {
153
194
  "mcp-google-map": {
154
- "command": "/percorso/assoluto/a/mcp-google-map/scripts/start-mcp.sh",
195
+ "command": "/absolute/path/to/mcp-google-map/scripts/start-mcp.sh",
155
196
  "env": { "GOOGLE_MAPS_API_KEY": "AIza..." }
156
197
  }
157
198
  }
158
199
  }
159
200
  ```
160
201
 
161
- **HTTP** (dopo `scripts/start-http.sh`):
202
+ **HTTP** (after `scripts/start-http.sh`):
162
203
 
163
204
  ```json
164
205
  {
@@ -172,74 +213,78 @@ scripts/test.sh # test unitari (nessuna API key richiesta)
172
213
 
173
214
  ### pi CLI
174
215
 
175
- pi legge i server MCP da `~/.pi/agent/mcp.json` (utente) o `.pi/mcp.json` (progetto, richiede trust). Voce stdio per questo server:
216
+ pi reads MCP servers from `~/.pi/agent/mcp.json` (user) or `.pi/mcp.json` (project, requires trust). stdio entry for this server:
176
217
 
177
218
  ```json
178
219
  {
179
220
  "mcpServers": {
180
221
  "maps": {
181
222
  "command": "node",
182
- "args": ["/percorso/assoluto/a/mcp-google-map/dist/cli.js", "--stdio"],
223
+ "args": ["/absolute/path/to/mcp-google-map/dist/cli.js", "--stdio"],
183
224
  "env": { "GOOGLE_MAPS_API_KEY": "${GOOGLE_MAPS_API_KEY}" }
184
225
  }
185
226
  }
186
227
  }
187
228
  ```
188
229
 
189
- - Da terminale: `pi mcp add maps -- node /percorso/assoluto/a/mcp-google-map/dist/cli.js --stdio` (aggiungere `--env GOOGLE_MAPS_API_KEY=...` per la chiave).
190
- - `${GOOGLE_MAPS_API_KEY}` espande la variabile d'ambiente al volo: la chiave non resta cablata nel file di configurazione.
191
- - Dopo una modifica di `mcp.json` esterna alla sessione, eseguire `/reload` in pi; `/mcp` ispeziona stato, tool ed errori di connessione.
192
- - I tool appaiono con il prefisso `mcp__<server>__`: `mcp__maps__maps_geocode`, `mcp__maps__maps_search_places`, ...
230
+ - From a terminal: `pi mcp add maps -- node /absolute/path/to/mcp-google-map/dist/cli.js --stdio` (add `--env GOOGLE_MAPS_API_KEY=...` to pass the key).
231
+ - `${GOOGLE_MAPS_API_KEY}` expands the environment variable on the fly: the key never stays hard-coded in the configuration file.
232
+ - After editing `mcp.json` outside the session, run `/reload` in pi; `/mcp` inspects status, tools, and connection errors.
233
+ - Tools appear with the `mcp__<server>__` prefix: `mcp__maps__maps_geocode`, `mcp__maps__maps_search_places`, ...
193
234
 
194
235
  ### OpenClaw
195
236
 
196
- OpenClaw gestisce i server MCP in `~/.openclaw/openclaw.json` tramite CLI (verificato su OpenClaw 2026.4.21):
237
+ OpenClaw manages MCP servers in `~/.openclaw/openclaw.json` through its CLI (verified on OpenClaw 2026.4.21):
197
238
 
198
239
  ```bash
199
- openclaw mcp set maps '{"command":"node","args":["/percorso/assoluto/a/mcp-google-map/dist/cli.js","--stdio"],"env":{"GOOGLE_MAPS_API_KEY":"AIza..."},"description":"Google Maps: Places API (New), geocoding, routes, weather"}'
240
+ openclaw mcp set maps '{"command":"node","args":["/absolute/path/to/mcp-google-map/dist/cli.js","--stdio"],"env":{"GOOGLE_MAPS_API_KEY":"AIza..."},"description":"Google Maps: Places API (New), geocoding, routes, weather"}'
200
241
  ```
201
242
 
202
- - Senza installazione locale: usare `"command":"npx","args":["-y","mcp-google-map","--stdio"]` (esegue il pacchetto npm pubblicato).
203
- - Dopo la modifica ricaricare il gateway o riavviare la sessione agente perché il nuovo server venga collegato.
204
- - Ispezione e rimozione: `openclaw mcp list`, `openclaw mcp show maps`, `openclaw mcp unset maps`.
205
- - L'agente OpenClaw può installare e configurare il server in autonomia (shell + `openclaw mcp set`); la creazione della API key su Google Cloud Console resta un'operazione umana.
243
+ - Without a local install: use `"command":"npx","args":["-y","mcp-google-map","--stdio"]` (runs the published npm package).
244
+ - After the change, reload the gateway or restart the agent session so the new server gets connected.
245
+ - Inspect and remove: `openclaw mcp list`, `openclaw mcp show maps`, `openclaw mcp unset maps`.
246
+ - The OpenClaw agent can install and configure the server on its own (shell + `openclaw mcp set`); creating the API key in Google Cloud Console remains a human task.
206
247
 
207
- ### Prerequisiti di configurazione
248
+ ### Configuration prerequisites
208
249
 
209
- 1. **Una sola API key**: crea `GOOGLE_MAPS_API_KEY` su <https://console.cloud.google.com/apis/credentials> e abilita i servizi elencati nella tabella [API Google Cloud richieste](#api-google-cloud-richieste).
210
- 2. **Minimo operativo**: Places API (New) + Geocoding API; abilitare gli altri servizi solo per i tool corrispondenti.
211
- 3. **Limitare l'esposizione**: `GOOGLE_MAPS_ENABLED_TOOLS=maps_geocode,maps_search_places,maps_place_details` riduce i tool registrati (e il contesto per l'LLM).
212
- 4. **Verifica post-installazione**: `mcp-google-map doctor` (nessuna chiamata di rete), poi `mcp-google-map doctor --live --apikey "AIza..."` (probe reali su Geocoding, Places, Routes).
250
+ 1. **A single API key**: create `GOOGLE_MAPS_API_KEY` at <https://console.cloud.google.com/apis/credentials> and enable the services listed in the [Required Google Cloud APIs](#required-google-cloud-apis) table.
251
+ 2. **Minimal operational subset**: Places API (New) + Geocoding API; enable the other services only for the tools you use.
252
+ 3. **Restrict exposure**: `GOOGLE_MAPS_ENABLED_TOOLS=maps_geocode,maps_search_places,maps_place_details` reduces the registered tools (and the LLM context).
253
+ 4. **Post-install verification**: `mcp-google-map doctor` (no network calls), then `mcp-google-map doctor --live --apikey "AIza..."` (real probes against Geocoding, Places, and Routes).
254
+ 5. **Automatic update check**: enabled by default at server startup; set `MCP_AUTO_UPDATE_DISABLED=1` (also `true`/`yes`) to skip the npm registry version check.
213
255
 
214
- ## Struttura del progetto
256
+ ## Project structure
215
257
 
216
258
  ```
217
259
  mcp-google-map/
218
- ├── src/ # sorgenti del server MCP
219
- │ ├── cli.ts # entry point (stdio/HTTP, comandi exec e doctor)
220
- │ ├── config.ts # registrazione dei tool esposti
260
+ ├── src/ # MCP server sources
261
+ │ ├── cli.ts # entry point (stdio/HTTP, exec and doctor commands)
262
+ │ ├── config.ts # registration of the exposed tools
221
263
  │ ├── core/ # BaseMcpServer: MCP SDK, stdio + Streamable HTTP
222
- │ ├── services/ # Places API (New), Geocoding, Routes, clima
223
- │ └── tools/ # definizione dei 18 tool MCP
224
- ├── scripts/ # script bash di supporto (setup/build/start/test)
225
- ├── docs/ # documentazione del progetto
226
- └── tests/ # test unitari (mock) + smoke/e2e (API key reale)
264
+ │ ├── services/ # Places API (New), Geocoding, Routes, environment
265
+ │ ├── tools/ # definition of the 18 MCP tools
266
+ │ └── utils/ # API key resolution, request context, update check
267
+ ├── scripts/ # helper bash scripts (setup/build/start/test)
268
+ ├── docs/ # project documentation
269
+ └── tests/ # unit tests (mocked) + smoke/e2e (real API key)
227
270
  ```
228
271
 
229
- ## Documentazione
272
+ ## Documentation
230
273
 
231
- - [docs/TOOLS.md](docs/TOOLS.md) — catalogo dei tool e parametri
232
- - [docs/CONFIGURATION.md](docs/CONFIGURATION.md) — variabili d'ambiente, trasporti, API key
233
- - [docs/GEOSCOUT.md](docs/GEOSCOUT.md) — compatibilità GeoScout 6.2 (filtri economici, FieldMask, payload raw)
274
+ - [docs/TOOLS.md](docs/TOOLS.md) — tool catalog and parameters
275
+ - [docs/CONFIGURATION.md](docs/CONFIGURATION.md) — environment variables, transports, API key
276
+ - [src/resources/skills/](src/resources/skills/) — bundled `venue-discovery` agent skill (budget filters, FieldMask, raw payload)
234
277
 
235
- ## Sviluppo
278
+ ## Development
236
279
 
237
280
  ```bash
238
- npm run dev # build incrementale in watch
281
+ npm ci # install dependencies from the lockfile
282
+ npm run verify # single pipeline: typecheck + unit tests + build
283
+ npm run dev # incremental watch build
239
284
  npm run typecheck # tsc --noEmit
240
- scripts/test.sh # unit test
285
+ npm test # unit tests
241
286
  ```
242
287
 
243
- ## Licenza
288
+ ## License
244
289
 
245
- GPL-3.0 — vedi [LICENSE](LICENSE).
290
+ GPL-3.0 — see [LICENSE](LICENSE).
package/dist/{chunk-K27FX5QH.js → chunk-NAUIQEK4.js} RENAMED
@@ -817,7 +817,7 @@ var NewPlacesService = class {
817
817
  return result.places;
818
818
  }
819
819
  /**
820
- * Text Search (New) with full GeoScout 6.2 support:
820
+ * Text Search (New) with the full venue-discovery filter surface (REQ-027, REQ-109):
821
821
  * - priceLevels: cumulative server-side economic filter (enum strings)
822
822
  * - strictTypeFiltering: strict place-type filtering
823
823
  * - minRating, includedType, openNow: server-side filters
@@ -1857,4 +1857,4 @@ export {
1857
1857
  PlacesSearcher,
1858
1858
  Logger
1859
1859
  };
1860
- //# sourceMappingURL=chunk-K27FX5QH.js.map
1860
+ //# sourceMappingURL=chunk-NAUIQEK4.js.map