mcp-google-api 0.21.0

package/dist/index.d.ts

@@ -0,0 +1,276 @@
+interface SearchResponse {
+    success: boolean;
+    error?: string;
+    data?: any[];
+    location?: any;
+    nextPageToken?: string;
+    fieldMask?: string;
+    raw_response?: any;
+}
+interface PlaceDetailsResponse {
+    success: boolean;
+    error?: string;
+    data?: any;
+    fieldMask?: string;
+}
+interface GeocodeResponse {
+    success: boolean;
+    error?: string;
+    data?: {
+        location: {
+            lat: number;
+            lng: number;
+        };
+        formatted_address: string;
+        place_id: string;
+    };
+}
+interface ReverseGeocodeResponse {
+    success: boolean;
+    error?: string;
+    data?: {
+        formatted_address: string;
+        place_id: string;
+        address_components: any[];
+    };
+}
+interface DistanceMatrixResponse {
+    success: boolean;
+    error?: string;
+    data?: {
+        distances: any[][];
+        durations: any[][];
+        origin_addresses: string[];
+        destination_addresses: string[];
+    };
+}
+interface DirectionsResponse {
+    success: boolean;
+    error?: string;
+    data?: {
+        routes: any[];
+        summary: string;
+        total_distance: {
+            value: number;
+            text: string;
+        };
+        total_duration: {
+            value: number;
+            text: string;
+        };
+    };
+}
+interface TimezoneResponse {
+    success: boolean;
+    error?: string;
+    data?: {
+        timeZoneId: string;
+        timeZoneName: string;
+        utcOffset: number;
+        dstOffset: number;
+        localTime: string;
+    };
+}
+interface WeatherResponse {
+    success: boolean;
+    error?: string;
+    data?: any;
+}
+interface StaticMapResponse {
+    success: boolean;
+    error?: string;
+    data?: {
+        base64: string;
+        size: number;
+        dimensions: string;
+    };
+}
+interface AirQualityResponse {
+    success: boolean;
+    error?: string;
+    data?: any;
+}
+interface ElevationResponse {
+    success: boolean;
+    error?: string;
+    data?: Array<{
+        elevation: number;
+        location: {
+            lat: number;
+            lng: number;
+        };
+    }>;
+}
+declare class PlacesSearcher {
+    private mapsTools;
+    private newPlacesService;
+    private routesService;
+    constructor(apiKey?: string);
+    searchNearby(params: {
+        center: {
+            value: string;
+            isCoordinates: boolean;
+        };
+        keyword?: string;
+        radius?: number;
+        openNow?: boolean;
+        minRating?: number;
+    }): Promise<SearchResponse>;
+    searchText(params: {
+        query: string;
+        locationBias?: {
+            latitude: number;
+            longitude: number;
+            radius?: number;
+        };
+        openNow?: boolean;
+        minRating?: number;
+        includedType?: string;
+        strictTypeFiltering?: boolean;
+        priceLevels?: string[];
+        pageSize?: number;
+        pageToken?: string;
+        languageCode?: string;
+        includeRaw?: boolean;
+    }): Promise<SearchResponse>;
+    getPlaceDetails(placeId: string, maxPhotos?: number, includeRaw?: boolean): Promise<PlaceDetailsResponse>;
+    geocode(address: string): Promise<GeocodeResponse>;
+    reverseGeocode(latitude: number, longitude: number): Promise<ReverseGeocodeResponse>;
+    calculateDistanceMatrix(origins: string[], destinations: string[], mode?: "driving" | "walking" | "bicycling" | "transit", departure_time?: string, avoid_tolls?: boolean, avoid_highways?: boolean): Promise<DistanceMatrixResponse>;
+    getDirections(origin: string, destination: string, mode?: "driving" | "walking" | "bicycling" | "transit", departure_time?: string, arrival_time?: string, avoid_tolls?: boolean, avoid_highways?: boolean): Promise<DirectionsResponse>;
+    getTimezone(latitude: number, longitude: number, timestamp?: number): Promise<TimezoneResponse>;
+    getWeather(latitude: number, longitude: number, type?: "current" | "forecast_daily" | "forecast_hourly", forecastDays?: number, forecastHours?: number): Promise<WeatherResponse>;
+    getAirQuality(latitude: number, longitude: number, includeHealthRecommendations?: boolean, includePollutants?: boolean): Promise<AirQualityResponse>;
+    getStaticMap(params: {
+        center?: string;
+        zoom?: number;
+        size?: string;
+        maptype?: string;
+        markers?: string[];
+        path?: string[];
+    }): Promise<StaticMapResponse>;
+    searchAlongRoute(params: {
+        textQuery: string;
+        origin: string;
+        destination: string;
+        mode?: string;
+        maxResults?: number;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+        data?: any;
+    }>;
+    private resolveLocation;
+    exploreArea(params: {
+        location: string;
+        types?: string[];
+        radius?: number;
+        topN?: number;
+    }): Promise<any>;
+    planRoute(params: {
+        stops: string[];
+        mode?: "driving" | "walking" | "bicycling" | "transit";
+        optimize?: boolean;
+        departure_time?: string;
+        avoid_tolls?: boolean;
+        avoid_highways?: boolean;
+    }): Promise<any>;
+    comparePlaces(params: {
+        query: string;
+        userLocation?: {
+            latitude: number;
+            longitude: number;
+        };
+        limit?: number;
+    }): Promise<any>;
+    getElevation(locations: Array<{
+        latitude: number;
+        longitude: number;
+    }>): Promise<ElevationResponse>;
+    localRankTracker(params: {
+        keywords: string[];
+        placeId: string;
+        center: {
+            latitude: number;
+            longitude: number;
+        };
+        gridSize?: number;
+        gridSpacing?: number;
+    }): Promise<any>;
+    private scanKeywordGrid;
+}
+
+declare class NewPlacesService {
+    private client;
+    private readonly apiKey;
+    private readonly defaultLanguage;
+    private readonly placeFieldMask;
+    private readonly searchNearbyFieldMask;
+    private readonly searchTextFieldMask;
+    constructor(apiKey?: string);
+    searchNearby(params: {
+        location: {
+            lat: number;
+            lng: number;
+        };
+        keyword?: string;
+        radius?: number;
+        maxResultCount?: number;
+    }): Promise<any[]>;
+    searchText(params: {
+        textQuery: string;
+        locationBias?: {
+            lat: number;
+            lng: number;
+            radius?: number;
+        };
+        openNow?: boolean;
+        minRating?: number;
+        includedType?: string;
+        strictTypeFiltering?: boolean;
+        priceLevels?: string[];
+        pageSize?: number;
+        pageToken?: string;
+        languageCode?: string;
+        maxResultCount?: number;
+    }): Promise<any[]>;
+    searchTextFull(params: {
+        textQuery: string;
+        locationBias?: {
+            lat: number;
+            lng: number;
+            radius?: number;
+        };
+        openNow?: boolean;
+        minRating?: number;
+        includedType?: string;
+        strictTypeFiltering?: boolean;
+        priceLevels?: string[];
+        pageSize?: number;
+        pageToken?: string;
+        languageCode?: string;
+        maxResultCount?: number;
+        includeRaw?: boolean;
+    }): Promise<{
+        places: any[];
+        nextPageToken?: string;
+        fieldMask: string;
+        raw?: any;
+    }>;
+    getPhotoUri(photoName: string, maxWidthPx?: number): Promise<string>;
+    getPlaceDetails(placeId: string, includeRaw?: boolean): Promise<any>;
+    private transformSearchResult;
+    private transformPlaceResponse;
+    private extractLegacyPlaceId;
+    private isCurrentlyOpen;
+    private getLocalTimeComponents;
+    private formatOpeningHours;
+    private extractErrorMessage;
+}
+
+declare const Logger: {
+    log: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+};
+
+export { Logger, NewPlacesService, PlacesSearcher };

package/dist/index.js

@@ -0,0 +1,11 @@
+import {
+  Logger,
+  NewPlacesService,
+  PlacesSearcher
+} from "./chunk-VCFXCLJF.js";
+export {
+  Logger,
+  NewPlacesService,
+  PlacesSearcher
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/docs/CONFIGURATION.md

@@ -0,0 +1,116 @@
+# Configurazione
+
+## Google Maps API key
+
+Ottieni una chiave da <https://console.cloud.google.com/apis/credentials> e abilita sulla chiave i servizi che usi:
+
+| Servizio console (nome API) | Tool che lo richiedono | Note |
+| --- | --- | --- |
+| **Places API (New)** (`places-backend-new`) | `maps_search_places`, `maps_search_nearby`, `maps_place_details`, `maps_explore_area`, `maps_compare_places`, `maps_search_along_route`, `maps_local_rank_tracker` | Obbligatoria per la skill `eatspot-discovery`; unica API di ricerca locali usata dal server |
+| **Geocoding API** (`geocoding-backend`) | `maps_geocode`, `maps_reverse_geocode`, `maps_batch_geocode` | Anche fallback interno di risoluzione indirizzi |
+| **Routes API** (`routes`) | `maps_directions`, `maps_distance_matrix`, `maps_plan_route` | |
+| **Time Zone API** (`timezone-backend`) | `maps_timezone` | |
+| **Maps Elevation API** (`elevation-backend`) | `maps_elevation` | In console appare come "Maps Elevation API" |
+| **Maps Static API** (`static-maps-backend`) | `maps_static_map` | Immagine PNG | |
+| **Weather API** (`weather-backend`) | `maps_weather` | Copertura regionale limitata |
+| **Air Quality API** (`airquality`) | `maps_air_quality` | Copertura regionale limitata |
+
+Non richieste da questo server: **Maps Grounding Lite** (solo MCP hosted Google) e **Geolocation API** (nessun tool la usa). L'elenco completo con priorità è in [README.md](../README.md#api-google-cloud-richieste).
+
+The API key can be supplied as follows (decreasing per-request priority on the HTTP transport):
+
+1. HTTP header `X-Google-Maps-API-Key` — per request, useful in multi-session setups
+2. HTTP header `Authorization: Bearer <key>` — per request
+3. CLI flag `--apikey "AIza..."` or environment variable `GOOGLE_MAPS_API_KEY` (or a line in `.env`) — process default
+
+## Variabili d'ambiente
+
+Definite in `.env` (copia da `.env.example`):
+
+| Variabile | Default | Descrizione |
+| --- | --- | --- |
+| `GOOGLE_MAPS_API_KEY` | — | **Obbligatoria.** Chiave Google Maps |
+| `MCP_SERVER_PORT` | `3000` | Porta del trasporto HTTP |
+| `MCP_SERVER_HOST` | `127.0.0.1` | HTTP bind address. Default migrated from `0.0.0.0` to loopback `127.0.0.1`; set `0.0.0.0` to expose on all interfaces |
+| `GOOGLE_MAPS_ENABLED_TOOLS` | `*` | Allowlist separata da virgole dei tool esposti (riduce il contesto per l'LLM). Esempio: `maps_search_places,maps_place_details,maps_geocode` |
+| `MCP_AUTO_UPDATE_DISABLED` | unset (check enabled by default) | Set `1`, `true`, or `yes` to disable the automatic update check performed at server startup; any other value keeps it enabled |
+
+Any command also accepts `--env-file <path>`: it loads exactly that file (exit 1 with a JSON error when missing) and replaces the implicit `.env` discovery chain for that invocation.
+
+## Trasporti
+
+### stdio (predefinito per client locali)
+
+```bash
+scripts/start-mcp.sh            # node dist/cli.js start --stdio
+```
+
+stdout è riservato ai messaggi JSON-RPC; tutti i log del server vanno su stderr.
+
+### Streamable HTTP
+
+```bash
+scripts/start-http.sh                       # http://127.0.0.1:3000/mcp
+MCP_SERVER_PORT=8123 scripts/start-http.sh  # porta personalizzata
+scripts/start-http.sh --port 8123 --host 0.0.0.0
+```
+
+Each MCP session (`mcp-session-id`) can carry its own API key via the `X-Google-Maps-API-Key` or `Authorization: Bearer` headers: tool calls use the session key, not the global default. The server binds to `127.0.0.1` by default (migration from `0.0.0.0`); `SIGINT`/`SIGTERM` close all sessions and the listening socket before exit; startup exits non-zero when no instance can listen.
+
+## 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-api/dist/cli.js", "start", "--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-api/dist/cli.js start --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-api/dist/cli.js","start","--stdio"],"env":{"GOOGLE_MAPS_API_KEY":"AIza..."},"description":"Google Maps MCP"}'
+```
+
+- Alternativa senza installazione: `"command":"npx","args":["-y","mcp-google-api","start","--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
+node dist/cli.js start --stdio                                    # stdio server
+node dist/cli.js start --port 3000 --host 127.0.0.1                # HTTP server (loopback default)
+node dist/cli.js setup --write-env                                # onboarding: checks + .env scaffold (no network)
+node dist/cli.js exec search-places '{"query":"pizzeria Torino"}' # one tool call (params is a JSON string)
+node dist/cli.js doctor                                           # local diagnostics (no network)
+node dist/cli.js doctor --live --apikey "AIza..."                 # + real probes (all three APIs)
+node dist/cli.js doctor --live --probes geocoding,routes          # + selected probes only
+node dist/cli.js --env-file /path/to/.env doctor                  # explicit environment file
+node dist/cli.js snippet --client pi                              # registration snippet (stdout JSON, no files written)
+```
+
+## Diagnostica
+
+```bash
+node dist/cli.js doctor
+```
+
+Verifica versione Node, presenza della API key e (con `--live`) effettua chiamate reali ai servizi Google. The Node floor is `>= 24`, aligned with `package.json` `engines`; the local report also prints the effective configuration (masked key, per-field sources) and the Google APIs required by each enabled tool.

package/docs/TOOLS.md

@@ -0,0 +1,75 @@
+# Catalogo dei tool
+
+18 tool MCP, tutti prefissati `maps_`. L'elenco esposto può essere ridotto con `GOOGLE_MAPS_ENABLED_TOOLS` (vedi [CONFIGURATION.md](CONFIGURATION.md)).
+
+## Ricerca e dettaglio locali (Places API — New)
+
+### `maps_search_places`
+
+Text Search (New) con **filtri server-side** — è il tool principale per ricerche strutturate.
+
+| Parametro | Tipo | Note |
+| --- | --- | --- |
+| `query` | string (obbligatorio) | Query testuale libera |
+| `priceLevels` | enum array | Filtro economico cumulativo lato API: `PRICE_LEVEL_FREE`, `PRICE_LEVEL_INEXPENSIVE`, `PRICE_LEVEL_MODERATE`, `PRICE_LEVEL_EXPENSIVE`, `PRICE_LEVEL_VERY_EXPENSIVE` |
+| `minRating` | number 1.0–5.0 | Filtro rating applicato dall'API |
+| `includedType` | string | **Un solo tipo per chiamata** (contratto Text Search), es. `restaurant`, `cafe`, `bakery` |
+| `strictTypeFiltering` | boolean | Matching rigoroso di `includedType` |
+| `openNow` | boolean | Solo locali attualmente aperti |
+| `locationBias` | oggetto | `{ latitude, longitude, radius? }` (raggio in metri, default 5000) |
+| `pageSize` | 1–20 | Tetto risultati per chiamata (tradotto in `maxResultCount`). Nota SDK: il proto di `@googlemaps/places` (fino a 3.1.0) non include `page_size`/`page_token` → **paginazione oltre 20 risultati/chiamata non disponibile**; per più risultati usare query diverse |
+| `pageToken` | string | Token della pagina successiva |
+| `languageCode` | string | Lingua risultati (`it`, `en`, …) |
+| `includeRaw` | boolean | Allega il payload originale: `raw_place` per ogni risultato, `raw_response` dell'intera pagina e la `field_mask` realmente inviata |
+
+Output: `{ results[], nextPageToken?, field_mask, raw_response? }`. Ogni risultato include `place_id`, `name`, `address`, `location`, `primary_type`, `types`, `business_status`, `google_maps_uri`, `price_level`, **`price_range` (struttura Money originale: `startPrice`/`endPrice` → `currencyCode`/`units`/`nanos`)**, `rating`, `total_ratings`, `regular_opening_hours`, `current_opening_hours`.
+
+### `maps_search_nearby`
+
+Search Nearby (New) attorno a un centro (`center.value` indirizzo/landmark/coordinate, `radius` in metri), con filtro `keyword` (tipo), `openNow`, `minRating` (post-filtro).
+
+### `maps_place_details`
+
+Place Details (New) per `placeId`: contatti, sito, orari (regular + current con `periods`), recensioni con attribuzione, foto (`maxPhotos` 0–10), `price_range`, `business_status`, `types`. Con `includeRaw: true` allega `raw_place` e `field_mask`.
+
+### `maps_explore_area`
+
+Esplora una zona per categorie (default `restaurant`, `cafe`, `tourist_attraction`) con i top-N per tipo.
+
+### `maps_compare_places`
+
+Confronta fino a N locali da una query: tipo, orari, contatti, prezzi, opzioni.
+
+### `maps_search_along_route`
+
+Cerca locali lungo un percorso (origine → destinazione).
+
+### `maps_local_rank_tracker`
+
+Traccia il rank di un locale su una griglia di punti (ARP/ATRP/Solv) per una keyword.
+
+## Geocoding
+
+- `maps_geocode` — indirizzo/nome → coordinate + `place_id`
+- `maps_reverse_geocode` — coordinate → indirizzo
+- `maps_batch_geocode` — fino a 25 richieste batch
+
+## Navigazione
+
+- `maps_directions` — percorso A→B con tappe, modalità, evitamenti
+- `maps_distance_matrix` — matrice origini/destinazioni (Routes API)
+- `maps_plan_route` — pianificazione multi-tappa con ottimizzazione tappe intermedie
+
+## Ambiente
+
+- `maps_elevation` — quota di punti o profilo di un tracciato
+- `maps_timezone` — fuso orario e ora locale
+- `maps_weather` — meteo corrente/previsioni
+- `maps_air_quality` — qualità dell'aria
+- `maps_static_map` — mappa statica (immagine PNG)
+
+## Convenzioni comuni
+
+- Coordinate in input: `{ latitude, longitude }` oppure stringa `"lat,lng"` dove indicato.
+- Tutti i tool restituiscono JSON in `content[0].text`; errori con `isError: true`.
+- I campi grezzi dell'API (es. `price_range` Money) sono **conservati verbatim**, mai convertiti in numeri semplici.

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "mcp-google-api",
+  "version": "0.21.0",
+  "description": "Google API MCP server — 18 Google Maps 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",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "mcp-google-api": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src/resources/skills",
+    "README.md",
+    "CHANGELOG.md",
+    "docs",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/*.unit.test.ts",
+    "test:e2e": "tsx tests/smoke.test.ts",
+    "check:publish-version": "node scripts/check-publish-version.mjs",
+    "verify": "npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "npm run check:publish-version && npm run build"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "keywords": [
+    "google",
+    "google-maps",
+    "maps",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "places",
+    "places-api-new",
+    "geocoding",
+    "directions"
+  ],
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ogekuri/mcp-google-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ogekuri/mcp-google-api/issues"
+  },
+  "homepage": "https://github.com/Ogekuri/mcp-google-api#readme",
+  "dependencies": {
+    "@googlemaps/google-maps-services-js": "^3.4.0",
+    "@googlemaps/places": "^3.1.0",
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "yargs": "^17.7.2",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^24.0.0",
+    "@types/yargs": "^17.0.33",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.72.1"
+  }
+}

package/src/resources/skills/README.md

@@ -0,0 +1,45 @@
+# Skills Resources — Authoring Guide
+
+This directory ships LLM agent skills for the `mcp-google-api` MCP server. Skills are inert instruction assets: no runtime module under `src/` imports them, so adding a skill never requires source-code changes, rebuilds, or test changes.
+
+## Layout contract
+
+```
+src/resources/skills/
+├── manifest.json              # machine-readable registry of all skills
+├── README.md                  # this authoring guide
+└── <skill-id>/                # exactly one skill per directory
+    ├── SKILL.md               # the skill (English, self-contained)
+    └── DEBUG.md               # optional debug overlay (never part of SKILL.md)
+```
+
+Debug instructions are never embedded in `SKILL.md`. A skill that needs a debug section ships it in a dedicated overlay file declared by the manifest `debug` field; `mcp-google-api install` copies content files only and appends the overlay to the installed `SKILL.md` solely when `--debug-skills` is passed. The default install therefore produces a skill with no debug instructions.
+
+## SKILL.md format (Agent Skills compatible: pi, OpenClaw, and similar hosts)
+
+- UTF-8 Markdown file starting with YAML front matter delimited by `---` lines.
+- Front matter fields:
+  - `name`: 1–64 characters, lowercase ASCII letters, digits, hyphens; no leading, trailing, or consecutive hyphens; MUST match the containing directory name.
+  - `description`: non-empty, ≤ 1024 characters; states the capability and the triggering tasks, with important routing cues first.
+- Body: operative instructions in English, self-contained, ≤ ~500 lines. Support files (if ever needed) go under canonical subdirectories (`scripts/`, `references/`, `assets/`, `images/`); `SKILL.md` stays the only file at the skill root.
+- Skills that operate on Google Maps data MUST obtain every data value through the mcp-google-api tools listed in `PRJ-001` of `usereq/docs/REQUIREMENTS.md` and MUST forbid fabricated or simulated data presented as API-verified.
+
+## Adding a new skill
+
+1. Create `src/resources/skills/<skill-id>/SKILL.md` following the format above.
+2. Optional: create `src/resources/skills/<skill-id>/DEBUG.md` holding every debug instruction, and declare it as `"debug": "DEBUG.md"` in the manifest entry. Keep `SKILL.md` free of debug instructions.
+3. Append one entry to `manifest.json` (`id`, `name`, `version`, `language`, `path`, `description`, optional `debug`, optional `adaptedFrom`). Keep `name` equal to `id`, `path` relative to this directory, and `debug` relative to the skill directory.
+4. Commit both changes together. No other project file needs to change.
+
+## Registry entry schema
+
+| Field | Required | Description |
+|---|---|---|
+| `id` | yes | Stable skill identifier; equal to `name` and the directory name. |
+| `name` | yes | Agent Skills front-matter name; must match `id`. |
+| `version` | yes | Semantic version of the skill (skill-local, independent of package version). |
+| `language` | yes | ISO language code of the skill body (`en` by policy). |
+| `path` | yes | Path of `SKILL.md` relative to this directory. |
+| `description` | yes | Short routing summary; consistent with the front-matter `description`. |
+| `debug` | no | Debug overlay path relative to the skill directory (convention: `DEBUG.md`); appended to the installed `SKILL.md` only with `install --debug-skills`. |
+| `adaptedFrom` | no | Provenance note when the skill derives from an external source document. |

package/src/resources/skills/eatspot-discovery/DEBUG.md

@@ -0,0 +1,71 @@
+# EatSpot Discovery — DEBUG Overlay
+
+Appended to `SKILL.md` only when the skill is installed with `mcp-google-api install --debug-skills`.
+Without that option this file is never installed, so the installed skill contains no debug instructions.
+The overlay is additive: it never alters PART I — CORE of `SKILL.md`.
+
+## PART II — DEBUG (temporary, removable)
+
+### D1. Permanent activation
+
+For every search set `DEBUG_ENABLED = TRUE`. The DEBUG section MUST always appear at the bottom of the response: zero results, one or more conformant results, interrupted searches, unavailable API. Part II Section D MUST be the last output section. The DEBUG MUST NOT modify filters or the search.
+
+### D2. Mandatory provenance
+
+Every raw datum MUST be tied to an actual call. Calling `raw` an object you reconstructed is forbidden. Distinguish `API_VERIFIED` and `MCP_SERVER_UNAVAILABLE`. If the origin is not the mcp-google-api server, do not simulate Places API fields or structures.
+
+### D3. Call register
+
+For every actually executed tool call record: progressive call id; tool name; Grade phase; real query and parameters; `field_mask` actually applied (read it from the tool's `field_mask` output); request status; original payload received; errors; validations performed. Do not invent calls or parameters. Do not add credentials or tokens. Do not reconstruct missing responses.
+
+### D4. JSON format
+
+Section D contains exactly one valid JSON array; each element represents one authentic executed call. Diagnostic schema:
+
+```json
+[
+  {
+    "call_id": 1,
+    "source_mode": "API_VERIFIED",
+    "tool": "maps_search_places",
+    "phase_grade": "A",
+    "request_sent": {},
+    "field_mask_sent": [],
+    "raw_response": null,
+    "raw_accessibility": "NOT_ACCESSIBLE",
+    "validations": [],
+    "anomalies": [],
+    "error": null
+  }
+]
+```
+
+This is only the schema, never a real call. In an actual entry: `request_sent` contains the effective parameters; `field_mask_sent` matches the real applied mask; `raw_response` contains the authentic payload (from `raw`/`raw_place` with `includeRaw: true`) or stays `null` when inaccessible; `validations` lists agent interpretations; `anomalies` lists discrepancies. If no call was executed, the array MUST be `[]`; never fabricate a call to avoid an empty array; Section C explains the unavailability.
+
+### D5. Validations separate from raw data
+
+For each actually returned candidate, record separately: `place_id`; `raw_place_index`; `rating_interpreted`; `user_ratings_total_interpreted`; `grade_assigned`; `primary_type_raw`; `category`; `price_level_raw`; `price_range_raw`; `max_price_computed`; `budget_max`; `economic_status`; `final_status`; `exclusion_reasons`. Never copy interpreted values into `raw_response`. Never alter original structures.
+
+### D6. Error codes to detect
+
+`MCP_SERVER_UNAVAILABLE`, `TOOL_CALL_SIMULATED`, `RAW_RESPONSE_RECONSTRUCTED`, `RAW_SCHEMA_NON_CONFORMANT`, `PLACE_ID_MISMATCH`, `PRICE_LEVEL_DIVERGENT`, `PRICE_RANGE_DIVERGENT`, `USER_RATING_COUNT_DIVERGENT`, `PRIMARY_TYPE_DIVERGENT`, `RESPONSE_INCOMPATIBLE_WITH_PRICE_LEVELS`, `PRICE_LEVELS_FILTER_NOT_APPLIED`, `PRICE_EXCEEDS_BUDGET`, `RATING_INSUFFICIENT`, `REVIEWS_INSUFFICIENT`, `GRADE_WRONG`, `HOURS_INCOMPATIBLE`, `OUT_OF_RADIUS`, `FIELD_MASK_INCOMPLETE`, `API_RESPONSE_NOT_ACCESSIBLE`. Register only ascertained anomalies; never invent error codes to mask missing data.
+
+### D7. Critical test — Osteria Veglio
+
+When a response for Place ID `ChIJY2oWYByu0hIRZXOOaToUTA8` arrives, verify value consistency without overwriting. If a response presents `price_level = PRICE_LEVEL_EXPENSIVE`, `price_range.endPrice.units = "70"`, `user_ratings_total = 910`, you MUST NOT publish `PRICE_LEVEL_MODERATE`, "maximum price 30 EUR", or "1703 reviews" as original values of that response. If two real calls conflict, register the conflict and re-verify with `maps_place_details`; never resolve by editing the payload.
+
+### D8. API filter verification
+
+For every `maps_search_places` call record: `priceLevels` actually sent; `minRating` actually sent; `includedType` actually used; `strictTypeFiltering` when present. If `priceLevels` admits only INEXPENSIVE and MODERATE, register as an anomaly any EXPENSIVE candidate in the response; do not force-normalize it; do not declare a call validly filtered when it was only simulated.
+
+### D9. Completeness control and bounded capture
+
+The debug MUST preserve all accessible payloads within response-size limits. Declare partial payloads and truncated records explicitly; never present a partial response as complete. Do not deduplicate raw records: deduplication concerns final selection, not the call register.
+
+Bounded capture: before persisting any register entry, apply the strictest serialized-size limit in force in the execution environment (response limits, tool-result limits, intermediate-storage limits). When the serialized `raw_response` exceeds that limit, persist a declared truncation instead of the full payload: keep the validation-relevant segment — for `maps_search_places`, `raw_place` of ALL returned results (never a subset of results) plus each result's `name`, `place_id`, `rating`, and `user_ratings_total` — and add an explicit truncation declaration naming the omitted parts (reviews, photos, editorial summaries) and the kept ranges. The declaration is agent metadata inside the register entry (e.g. `"raw_response_note": "TRUNCATED: reviews/photos/editorial omitted; all N results kept"`); it MUST never be presented as API data.
+
+Register-entry integrity: before emitting the final JSON array, verify that every referenced register entry exists and holds the recorded payload. When an entry is missing — interrupted capture, size-limit abort, or lost intermediate state — re-execute the tool call; never dereference fields of a missing entry and never reconstruct the payload. When re-execution is impossible, emit the entry with `raw_response: null`, `raw_accessibility: "NOT_ACCESSIBLE"`, anomaly `API_RESPONSE_NOT_ACCESSIBLE`, and the concrete interruption reason in `error`.
+
+### D10. Final output
+
+Produce in order: A. Search summary; B. Validated venues; C. Notes and limitations; D. DEBUG — GOOGLE PLACES API VIA mcp-google-api. Section D MUST end with one valid JSON array and nothing may follow it. Excluded candidates may appear only as technical data in Section D. The DEBUG does not modify functional logic. Removing Part II entirely MUST leave PART I — CORE fully operational.