mcp-google-map 0.2.0 → 0.3.0

package/README.md

@@ -1,4 +1,4 @@
-# mcp-google-map (0.2.0)
+# mcp-google-map (0.3.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/node-%3E%3D22-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js >= 22">
@@ -89,7 +89,7 @@ gcloud services enable places-backend-new.googleapis.com \
 
 **Prerequisites**: Node.js **>= 22** and a Google Maps API key (see [Requisiti](#requisiti)).
 
-### From npm (once published)
+### From npm
 
 ```bash
 npm install -g mcp-google-map
@@ -170,6 +170,47 @@ scripts/test.sh         # test unitari (nessuna API key richiesta)
 }
 ```
 
+### pi CLI
+
+pi legge i server MCP da `~/.pi/agent/mcp.json` (utente) o `.pi/mcp.json` (progetto, richiede trust). Voce stdio per questo server:
+
+```json
+{
+  "mcpServers": {
+    "maps": {
+      "command": "node",
+      "args": ["/percorso/assoluto/a/mcp-google-map/dist/cli.js", "--stdio"],
+      "env": { "GOOGLE_MAPS_API_KEY": "${GOOGLE_MAPS_API_KEY}" }
+    }
+  }
+}
+```
+
+- 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).
+- `${GOOGLE_MAPS_API_KEY}` espande la variabile d'ambiente al volo: la chiave non resta cablata nel file di configurazione.
+- Dopo una modifica di `mcp.json` esterna alla sessione, eseguire `/reload` in pi; `/mcp` ispeziona stato, tool ed errori di connessione.
+- I tool appaiono con il prefisso `mcp__<server>__`: `mcp__maps__maps_geocode`, `mcp__maps__maps_search_places`, ...
+
+### OpenClaw
+
+OpenClaw gestisce i server MCP in `~/.openclaw/openclaw.json` tramite CLI (verificato su OpenClaw 2026.4.21):
+
+```bash
+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"}'
+```
+
+- Senza installazione locale: usare `"command":"npx","args":["-y","mcp-google-map","--stdio"]` (esegue il pacchetto npm pubblicato).
+- Dopo la modifica ricaricare il gateway o riavviare la sessione agente perché il nuovo server venga collegato.
+- Ispezione e rimozione: `openclaw mcp list`, `openclaw mcp show maps`, `openclaw mcp unset maps`.
+- 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.
+
+### Prerequisiti di configurazione
+
+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).
+2. **Minimo operativo**: Places API (New) + Geocoding API; abilitare gli altri servizi solo per i tool corrispondenti.
+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).
+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).
+
 ## Struttura del progetto
 
 ```

package/docs/CONFIGURATION.md

@@ -54,6 +54,42 @@ scripts/start-http.sh --port 8123 --host 0.0.0.0
 
 Ogni sessione MCP (`mcp-session-id`) può ricevere una API key propria via header `X-Goog-Api-Key`: le chiamate dei tool usano la chiave della sessione, non quella globale.
 
+## Registrazione nei client MCP
+
+### pi CLI
+
+Voce stdio per `~/.pi/agent/mcp.json` (utente) o `.pi/mcp.json` (progetto, richiede trust):
+
+```json
+{
+  "mcpServers": {
+    "maps": {
+      "command": "node",
+      "args": ["/percorso/assoluto/a/mcp-google-map/dist/cli.js", "--stdio"],
+      "env": { "GOOGLE_MAPS_API_KEY": "${GOOGLE_MAPS_API_KEY}" }
+    }
+  }
+}
+```
+
+- `${VAR}` espande variabili d'ambiente: la chiave non resta cablata nel file di configurazione.
+- `pi mcp add maps -- node /percorso/assoluto/a/mcp-google-map/dist/cli.js --stdio` registra da terminale; `/reload` in sessione dopo modifiche esterne; `/mcp` ispeziona la connessione.
+
+### OpenClaw
+
+```bash
+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 MCP"}'
+```
+
+- Alternativa senza installazione: `"command":"npx","args":["-y","mcp-google-map","--stdio"]`.
+- Ricaricare il gateway o riavviare la sessione agente dopo la modifica; `openclaw mcp list` / `openclaw mcp show maps` per verificare.
+
+### Prerequisiti chiave e API Google
+
+- **Una sola chiave** `GOOGLE_MAPS_API_KEY` (priorità di risoluzione in [Google Maps API key](#google-maps-api-key)); servizi da abilitare e sottoinsieme minimo (Places API (New) + Geocoding API): tabella in [README.md](../README.md#api-google-cloud-richieste).
+- Limitare i tool esposti con [`GOOGLE_MAPS_ENABLED_TOOLS`](#variabili-dambiente).
+- Verifica post-installazione: `node dist/cli.js doctor` e `node dist/cli.js doctor --live --apikey "AIza..."`.
+
 ## Comandi CLI
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-map",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Google Maps MCP server — 18 tools for AI agents: geocoding, Places API (New) search with server-side filters, directions, distance matrix and more, via stdio or Streamable HTTP",
   "type": "module",
   "main": "dist/index.js",