npm - @cablate/mcp-google-map - Versions diffs - 0.0.65 → 0.0.68 - Mend

@cablate/mcp-google-map 0.0.65 → 0.0.68

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 (6) hide show

package/.codex-plugin/plugin.json +4 -4
package/README.md +100 -331
package/README.zh-TW.md +102 -327
package/examples/agent-skill-demo.md +18 -5
package/package.json +1 -1
package/plugin.json +2 -2

package/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "mcp-google-map",
-  "version": "0.0.65",
-  "description": "Use focused Skills for Google Maps place research, travel planning, and local SEO through a standalone CLI.",
+  "version": "0.0.68",
+  "description": "Use Google Maps for place research, travel planning, and local SEO through focused Skills and a standalone CLI—no MCP setup required.",
   "author": {
     "name": "CabLate",
     "url": "https://github.com/cablate"
@@ -20,8 +20,8 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "Google Maps CLI",
-    "shortDescription": "Focused maps, travel planning, and local SEO workflows through a standalone CLI.",
-    "longDescription": "Three focused Skills guide an AI agent to use the @cablate/mcp-google-map CLI for general geospatial research, evidence-backed travel planning, and local SEO analysis. No MCP connection is required.",
+    "shortDescription": "Google Maps, travel planning, and local SEO without MCP setup.",
+    "longDescription": "Three focused Skills guide an AI agent to use the @cablate/mcp-google-map standalone CLI for place research, evidence-backed travel planning, and local SEO analysis. The plugin does not start or register an MCP server.",
     "developerName": "CabLate",
     "category": "Productivity",
     "capabilities": [

package/README.md CHANGED Viewed

@@ -1,114 +1,101 @@
+# Google Maps for AI agents
+**Stop rebuilding place search, routing, and location workflows for every AI app.**
+`@cablate/mcp-google-map` turns Google Maps Platform into 18 read-only agent tools and three focused Skills. An agent can find real places, verify routes, compare options, build practical itineraries, or audit local search visibility—through MCP or a standalone CLI.
+You choose the integration model: Codex Plugin when you want Skills without MCP setup, stdio for desktop MCP clients, or Streamable HTTP for shared and remote deployments.
+<p align="center"><b>English</b> · <a href="./README.zh-TW.md">繁體中文</a></p>
+<p align="center"><img src="./assets/banner.webp" alt="Google Maps tools and workflows for AI agents" width="800"></p>
 <p align="center">
   <a href="https://www.npmjs.com/package/@cablate/mcp-google-map"><img src="https://img.shields.io/npm/v/@cablate/mcp-google-map" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/@cablate/mcp-google-map"><img src="https://img.shields.io/npm/dm/@cablate/mcp-google-map" alt="npm downloads"></a>
-  <a href="https://github.com/cablate/mcp-google-map/stargazers"><img src="https://img.shields.io/github/stars/cablate/mcp-google-map?style=social" alt="GitHub stars"></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/github/license/cablate/mcp-google-map" alt="license"></a>
+  <a href="https://github.com/cablate/mcp-google-map/actions/workflows/ci.yml"><img src="https://github.com/cablate/mcp-google-map/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/github/license/cablate/mcp-google-map" alt="MIT license"></a>
 </p>
-<p align="center">
-  <img src="./assets/banner.webp" alt="MCP Google Maps — AI-Powered Geospatial Tools" width="800">
-</p>
+## Why use it?
-<h3 align="center"><b>Give your AI agent the ability to understand the physical world —<br>geocode, route, search, and reason about locations.</b></h3>
+Giving an agent a raw Maps API is only the beginning. Useful answers often require several dependent calls: resolve a place, preserve its identity, search around it, check opening details, calculate travel time, and explain what was actually verified. This project packages that work into one consistent interface.
-<p align="center">
-  <b>English</b> | <a href="./README.zh-TW.md">繁體中文</a>
-</p>
+- **Move from lookup to outcome.** Atomic tools handle geocoding, place details, directions, weather, air quality, and maps. Composite tools explore areas, compare candidates, optimize stops, and measure local rankings.
+- **Use the same capabilities with or without MCP.** The standalone `exec` CLI works with Agent Skills and automation; the MCP server exposes the same 18 tools over stdio or HTTP.
+- **Give agents workflow guidance, not just function names.** Three Skills cover general map research, evidence-backed travel planning, and local SEO. Codex loads their full instructions only when a request matches.
+- **Keep deployment and credentials under your control.** Run locally or self-host. API keys remain in your environment or request headers, with per-session isolation for HTTP deployments.
+- **Start narrow and grow later.** Register only the tools you need with `GOOGLE_MAPS_ENABLED_TOOLS`, or use the full catalog.
-<p align="center">
-  <img src="./assets/demo-grid-en.png" alt="Travel planning demo — Kyoto 2-day, Tokyo outdoor, Japan 5-day, Bangkok budget" width="800">
-</p>
+<p align="center"><img src="./assets/demo-grid-en.png" alt="Examples of travel planning with checked places and routes" width="800"></p>
-- **18 tools** — 14 atomic + 4 composite (explore-area, plan-route, compare-places, local-rank-tracker)
-- **3 modes** — stdio, StreamableHTTP, standalone exec CLI
-- **3 Agent Skills** — focused workflows for general maps, travel planning, and local SEO ([`skills/`](./skills/))
+## What can an agent do?
-### vs Google Grounding Lite
+| Outcome | How the project helps |
+|---|---|
+| Find and evaluate real places | Natural-language and nearby search, place details, ratings, hours, reviews, and distance comparison |
+| Build a trip that works geographically | Candidate discovery, along-route stops, travel-time checks, multi-stop optimization, weather, and static maps |
+| Research a neighborhood | Multi-category exploration plus targeted distance, elevation, timezone, weather, and air-quality checks |
+| Plan field work or deliveries | Route matrices and optimized stop ordering for up to 25 stops |
+| Audit local search visibility | Geographic grid ranking, competitor discovery, ARP, ATRP, and SoLV metrics |
+| Enrich location data | Single or batch geocoding, reverse geocoding, and structured JSON output |
-| | This project | [Grounding Lite](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) |
+These are data and planning tools, not guarantees of safety, accessibility, opening status, or ranking outcomes. Applications displaying Places reviews, photos, or AI summaries must follow the [content attribution and storage guidance](./skills/_shared/content-attribution.md).
+## Choose your integration
+| Use | Best for | What runs |
 |---|---|---|
-| Tools | **18** | 3 |
-| Geocoding | Yes | No |
-| Step-by-step directions | Yes | No |
-| Elevation | Yes | No |
-| Distance matrix | Yes | No |
-| Place details | Yes | No |
-| Timezone | Yes | No |
-| Weather | Yes | Yes |
-| Air quality | Yes | No |
-| Map images | Yes | No |
-| Composite tools (explore, plan, compare) | Yes | No |
-| Open source | MIT | No |
-| Self-hosted | Yes | Google-managed only |
-| Agent Skill | Yes | No |
-### Quick Start
+| **Codex Plugin** | Asking Codex map, travel, or local SEO questions without MCP configuration | A matching Skill loads on demand and calls the standalone CLI |
+| **Standalone CLI** | Scripts, automation, and other Skill-compatible agents | One stateless command returns JSON |
+| **MCP stdio** | Claude Desktop, Cursor, VS Code, and other local MCP clients | The client starts a local MCP process |
+| **Streamable HTTP** | Multi-session, containerized, LAN, or remote access | A self-hosted server exposes `/mcp` |
-```bash
-# stdio (Claude Desktop, Cursor, etc.)
-npx @cablate/mcp-google-map --stdio
+All options require Node.js 18+ and a Google Maps Platform API key. Live calls may be billable. Enable the APIs needed by your selected tools; common place and route workflows require **Places API (New)**, **Routes API**, and often **Geocoding API**.
-# exec CLI — no server needed
-npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
+## Start with Codex—no MCP required
-# HTTP server
-npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
+```bash
+codex plugin marketplace add cablate/mcp-google-map --ref main
+codex plugin add mcp-google-map@cablate
 ```
-## Special Thanks
+Set `GOOGLE_MAPS_API_KEY` in the environment where Codex runs, then start a new conversation. Verify the local setup without making a Google API request:
-Special thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add support for `streamablehttp`.
-## Available Tools
+```bash
+npx -y @cablate/mcp-google-map doctor
+```
-| Tool | Description |
-|------|-------------|
-| `maps_search_nearby` | Find places near a location by type (restaurant, cafe, hotel, etc.). Supports filtering by radius, rating, and open status. |
-| `maps_search_places` | Free-text place search (e.g., "sushi restaurants in Tokyo"). Supports location bias, rating, open-now filters. |
-| `maps_place_details` | Get full details for a place by its place_id — reviews, phone, website, hours. Optional `maxPhotos` param returns photo URLs. |
-| `maps_geocode` | Convert an address or landmark name into GPS coordinates. |
-| `maps_reverse_geocode` | Convert GPS coordinates into a street address. |
-| `maps_distance_matrix` | Calculate travel distances and times between multiple origins and destinations. Driving mode supports `avoid_tolls` and `avoid_highways`. |
-| `maps_directions` | Get step-by-step navigation between two points with route details. Driving mode supports `avoid_tolls` and `avoid_highways`. |
-| `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 or forecast — temperature, humidity, wind, UV, precipitation. |
-| `maps_air_quality` | Get air quality index, pollutant concentrations, and health recommendations by demographic group. |
-| `maps_static_map` | Generate a map image with markers, paths, or routes — returned inline for the user to see directly. |
-| `maps_batch_geocode` | Geocode up to 50 addresses in one call — returns coordinates for each. |
-| `maps_search_along_route` | Search for places along a route between two points — ranked by minimal detour time. |
-| **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 — uses Routes API waypoint optimization (up to 25 stops) for efficient ordering. Driving mode supports `avoid_tolls` and `avoid_highways`. |
-| `maps_compare_places` | Compare places side-by-side — searches, gets details, and optionally calculates distances. |
-| `maps_local_rank_tracker` | Track a business's local search ranking across a geographic grid — like LocalFalcon. Supports up to 3 keywords for batch scanning. Returns rank at each point, top-3 competitors, and metrics (ARP, ATRP, SoLV). |
+Success means the `node`, `package`, and `api-key` checks pass and `live-api` is skipped. Use `doctor --live` only when you intend to send potentially billable checks to Geocoding, Places, and Routes.
-All tools are annotated with `readOnlyHint: true` and `destructiveHint: false` — MCP clients can auto-approve these without user confirmation.
+Try asking:
-> **Prerequisite**: Enable **Places API (New)** and **Routes API** in [Google Cloud Console](https://console.cloud.google.com) before using place-related and routing tools.
+> Plan a practical two-day Kyoto itinerary. Group nearby places, check travel times, and explain any opening-hour assumptions.
-## Installation
+Codex selects `google-maps` for general location research, `google-maps-travel-planning` for itineraries, or `google-maps-local-seo` for business visibility analysis. The plugin does not register or start an MCP server. See the [no-MCP walkthrough](./examples/agent-skill-demo.md) for a reproducible example.
-### Codex Plugin (3 Agent Skills, no MCP required)
+## Use the standalone CLI
-Install the CabLate marketplace, then install the Skill-only plugin:
+Every MCP tool also has a short CLI name:
 ```bash
-codex plugin marketplace add cablate/mcp-google-map --ref main
-codex plugin add mcp-google-map@cablate
+npx -y @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
+npx -y @cablate/mcp-google-map exec search-places '{"query":"quiet cafes in Kyoto"}'
+npx -y @cablate/mcp-google-map exec directions '{"origin":"Tokyo Station","destination":"Tokyo Skytree","mode":"transit"}'
 ```
-Set `GOOGLE_MAPS_API_KEY` in the environment available to Codex, make sure Node.js 18+ and `npx` are installed, then start a new conversation. The plugin discovers three focused Skills and teaches the agent to run `npx -y @cablate/mcp-google-map exec ...` directly. It does not register or start an MCP server; the MCP setup below remains an independent option.
+Each call is stateless. Successful calls return `{ "success": true, "data": ... }` on stdout; failures exit nonzero and write structured JSON to stderr.
-At runtime, Codex sees the name and description of each Skill and loads the full instructions only when the request matches:
+For bulk address enrichment:
-- `google-maps` — place search, geocoding, routes, neighborhood and environmental facts
-- `google-maps-travel-planning` — day trips and multi-day itineraries
-- `google-maps-local-seo` — Google Business Profile visibility and geographic rank analysis
+```bash
+npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
+cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -
+```
-### Method 1: stdio (Recommended for most clients)
+## Connect an MCP client
-Works with Claude Desktop, Cursor, VS Code, and any MCP client that supports stdio:
+### stdio
 ```json
 {
@@ -116,301 +103,83 @@ Works with Claude Desktop, Cursor, VS Code, and any MCP client that supports std
     "google-maps": {
       "command": "npx",
       "args": ["-y", "@cablate/mcp-google-map", "--stdio"],
-      "env": {
-        "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY"
-      }
+      "env": { "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY" }
     }
   }
 }
 ```
-**Reduce context usage** — If you only need a subset of tools, set `GOOGLE_MAPS_ENABLED_TOOLS` to limit which tools are registered:
-```json
-{
-  "env": {
-    "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY",
-    "GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"
-  }
-}
-```
-Omit or set to `*` for all 18 tools (default).
+To reduce tool-list context, add a comma-separated allowlist such as `"GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"`. Omit it or use `*` to expose all tools.
-### Method 2: HTTP Server
-For multi-session deployments, per-request API key isolation, or remote access:
+### Streamable HTTP
 ```bash
-npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
-# Bind to all interfaces for remote access (e.g. Docker, LAN)
-npx @cablate/mcp-google-map --host 0.0.0.0 --port 3000 --apikey "YOUR_API_KEY"
+npx @cablate/mcp-google-map --host 127.0.0.1 --port 3000 --apikey "YOUR_API_KEY"
 ```
-Then configure your MCP client:
 ```json
 {
   "mcpServers": {
     "google-maps": {
       "type": "http",
-      "url": "http://localhost:3000/mcp"
+      "url": "http://127.0.0.1:3000/mcp"
     }
   }
 }
 ```
-### Server Information
-- **Transport**: stdio (`--stdio`) or Streamable HTTP (default)
-- **Tools**: 18 Google Maps tools (14 atomic + 4 composite) — filterable via `GOOGLE_MAPS_ENABLED_TOOLS`
-### CLI Exec Mode (Agent Skill)
-Use tools directly without running the MCP server:
-```bash
-npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
-npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'
-```
-All 18 tools available: `geocode`, `reverse-geocode`, `search-nearby`, `search-places`, `place-details`, `directions`, `distance-matrix`, `elevation`, `timezone`, `weather`, `air-quality`, `static-map`, `batch-geocode-tool`, `search-along-route`, `explore-area`, `plan-route`, `compare-places`, `local-rank-tracker`. See [`skills/`](./skills/) for the Skill definitions and full parameter docs.
-To use the **Agent Skill without MCP**:
+Bind to `0.0.0.0` only when the server must accept external connections. For multi-tenant deployments, prefer the `X-Google-Maps-API-Key` request header so keys remain isolated by session.
-1. Install the entire [`skills/`](./skills/) tree in your agent's Skills directory, following that client's instructions. Keep all three Skill folders and `_shared/` together so cross-Skill references continue to resolve. Installing the npm package alone does not register a Skill unless the package is installed through its plugin marketplace.
-2. Make Node.js 18+ and `npx` available to the agent, and set `GOOGLE_MAPS_API_KEY` in its environment. Prefer the environment variable to `--apikey`, which can expose a key in shell history or process listings.
-3. Ask the agent a location question. The Skill guides it to call the standalone CLI, for example `npx -y @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'`. No MCP server or MCP client configuration is needed.
+## Tool catalog
-Run `npx -y @cablate/mcp-google-map doctor` for a non-billable local readiness check. After informing the user that test requests may incur Google Maps Platform charges, `doctor --live` can verify Geocoding, Places API (New), and Routes API independently.
+| Group | Tools |
+|---|---|
+| Places and discovery | `maps_search_places`, `maps_search_nearby`, `maps_place_details`, `maps_explore_area`, `maps_compare_places`, `maps_search_along_route` |
+| Location and routing | `maps_geocode`, `maps_reverse_geocode`, `maps_directions`, `maps_distance_matrix`, `maps_plan_route`, `maps_batch_geocode` |
+| Context and visualization | `maps_elevation`, `maps_timezone`, `maps_weather`, `maps_air_quality`, `maps_static_map` |
+| Local SEO | `maps_local_rank_tracker` |
-For a reproducible no-MCP walkthrough, see the [Agent Skill demo](./examples/agent-skill-demo.md). If your agent or app displays Places reviews, photos, or AI summaries, follow the [content attribution and storage guidance](./skills/_shared/content-attribution.md); the tool preserves source/disclosure metadata but does not render a compliant UI for you.
+All 18 tools declare `readOnlyHint: true` and `destructiveHint: false`. Exact parameters, response shapes, and workflow recipes live in the [tool reference](./skills/google-maps/references/tools-api.md).
-### Batch Geocode
+## API key and Google Cloud setup
-Geocode hundreds of addresses from a file:
-```bash
-npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
-cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -
-```
-Input: one address per line. Output: JSON with `{ total, succeeded, failed, results[] }`. Default concurrency: 20 parallel requests.
+The key must belong to a Google Cloud project with billing enabled and restrictions compatible with the runtime. The [setup and diagnostics guide](./skills/_shared/setup-and-diagnostics.md) maps each capability to its required API and explains common failures.
+Credential priority is:
+1. `X-Google-Maps-API-Key` HTTP request header
+2. `--apikey` command-line option
+3. `GOOGLE_MAPS_API_KEY` environment variable
-### API Key Configuration
+Prefer environment variables or request headers. Command-line secrets can appear in shell history and process listings.
-API keys can be provided in three ways (priority order):
+## Trust and limits
-1. **HTTP Headers** (Highest priority)
-   ```json
-   {
-     "mcp-google-map": {
-       "transport": "streamableHttp",
-       "url": "http://localhost:3000/mcp",
-       "headers": {
-         "X-Google-Maps-API-Key": "YOUR_API_KEY"
-       }
-     }
-   }
-   ```
-2. **Command Line**
-   ```bash
-   mcp-google-map --apikey YOUR_API_KEY
-   ```
-3. **Environment Variable** (.env file or command line)
-   ```env
-   GOOGLE_MAPS_API_KEY=your_api_key_here
-   MCP_SERVER_PORT=3000
-   MCP_SERVER_HOST=0.0.0.0
-   ```
+- Place and route facts come from the Google Maps Platform APIs enabled for your project; weather availability has regional limitations.
+- A successful API response does not prove accessibility, safety, legal suitability, or real-time availability.
+- The package preserves source and disclosure metadata where returned, but your interface remains responsible for compliant attribution and storage.
+- HTTP mode supports per-session API-key isolation and DNS rebinding protection.
+- This project is MIT licensed and self-hostable. See [SECURITY.md](./SECURITY.md) for vulnerability reporting and [Security Assessment Clarifications](./SECURITY_ASSESSMENT.md) for the review checklist.
 ## Development
-### Local Development
 ```bash
-# Clone the repository
 git clone https://github.com/cablate/mcp-google-map.git
 cd mcp-google-map
-# Install dependencies
-npm install
-# Set up environment variables
-cp .env.example .env
-# Edit .env with your API key
-# Build the project
+npm ci
 npm run build
-# Start the server
-npm start
-# Or run in development mode
-npm run dev
-```
-### Testing
-```bash
-# Run smoke tests (no API key required for basic tests)
+npm run test:unit
 npm test
-# Run full E2E tests (requires GOOGLE_MAPS_API_KEY)
-npm run test:e2e
 ```
-### Project Structure
+Live E2E calls require `GOOGLE_MAPS_API_KEY` and may be billable: `npm run test:e2e`.
-```
-src/
-├── cli.ts                        # CLI entry point
-├── config.ts                     # Tool registration and server config
-├── index.ts                      # Package exports
-├── core/
-│   └── BaseMcpServer.ts          # MCP server with streamable HTTP transport
-├── services/
-│   ├── NewPlacesService.ts       # Google Places API (New) client
-│   ├── PlacesSearcher.ts         # Service facade layer
-│   ├── RoutesService.ts          # Google Routes API client (directions, distance matrix, waypoint optimization)
-│   └── toolclass.ts              # Google Maps API client (geocoding, timezone, elevation, static map)
-├── tools/
-│   └── maps/
-│       ├── searchNearby.ts       # maps_search_nearby tool
-│       ├── searchPlaces.ts       # maps_search_places tool
-│       ├── placeDetails.ts       # maps_place_details tool
-│       ├── geocode.ts            # maps_geocode tool
-│       ├── reverseGeocode.ts     # maps_reverse_geocode tool
-│       ├── distanceMatrix.ts     # maps_distance_matrix tool
-│       ├── directions.ts         # maps_directions tool
-│       ├── elevation.ts          # maps_elevation tool
-│       ├── timezone.ts           # maps_timezone tool
-│       ├── weather.ts            # maps_weather tool
-│       ├── airQuality.ts         # maps_air_quality tool
-│       ├── staticMap.ts          # maps_static_map tool
-│       ├── batchGeocode.ts       # maps_batch_geocode tool
-│       ├── searchAlongRoute.ts   # maps_search_along_route tool
-│       ├── exploreArea.ts        # maps_explore_area (composite)
-│       ├── planRoute.ts          # maps_plan_route (composite)
-│       ├── comparePlaces.ts      # maps_compare_places (composite)
-│       └── localRankTracker.ts   # maps_local_rank_tracker (composite)
-└── utils/
-    ├── apiKeyManager.ts          # API key management
-    └── requestContext.ts         # Per-request context (API key isolation)
-tests/
-└── smoke.test.ts                 # Smoke + E2E test suite
-skills/
-├── google-maps/                  # General place, route, and environment workflow
-│   ├── SKILL.md
-│   └── references/tools-api.md   # Tool parameters + generic recipes
-├── google-maps-travel-planning/  # Day-trip and itinerary workflow
-│   ├── SKILL.md
-│   └── references/travel-planning.md
-├── google-maps-local-seo/        # Business visibility and grid-rank workflow
-│   ├── SKILL.md
-│   └── references/local-seo.md
-└── _shared/                      # On-demand resources used by all three Skills
-    ├── setup-and-diagnostics.md
-    └── content-attribution.md
-.agents/
-├── plugins/marketplace.json      # CabLate marketplace catalog
-└── skills/project-docs/          # Maintainer-only development Skill
-.codex-plugin/plugin.json         # Codex compatibility manifest
-plugin.json                       # Portable Agent Plugin manifest
-```
+Contributions are welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. Release history is in [CHANGELOG.md](./CHANGELOG.md).
-## Tech Stack
+## Acknowledgements
-- **TypeScript** - Type-safe development
-- **Node.js** - Runtime environment
-- **@googlemaps/places** - Google Places API (New) for place search and details
-- **Google Routes API** - Directions, distance matrix, and waypoint optimization via REST
-- **@googlemaps/google-maps-services-js** - Geocoding, timezone, elevation
-- **@modelcontextprotocol/sdk** - MCP protocol implementation (v1.27+)
-- **Express.js** - HTTP server framework
-- **Zod** - Schema validation
-## Security
-- API keys are handled server-side
-- Per-session API key isolation for multi-tenant deployments
-- DNS rebinding protection available for production
-- Input validation using Zod schemas
-For enterprise security reviews, see [Security Assessment Clarifications](./SECURITY_ASSESSMENT.md) — a 23-item checklist covering licensing, data protection, credential management, tool contamination, and AI agent execution environment verification.
-To report a vulnerability, see [SECURITY.md](SECURITY.md).
-## Roadmap
-### Recent Additions
-| Tool / Feature | What it unlocks | Status |
-|------|----------------|--------|
-| `maps_static_map` | Map images with pins/routes — multimodal AI can "see" the map | **Done** |
-| `maps_air_quality` | AQI, pollutants — health-aware travel, outdoor planning | **Done** |
-| `maps_batch_geocode` | Geocode up to 50 addresses in one call — data enrichment | **Done** |
-| `maps_search_along_route` | Find places along a route ranked by detour time — trip planning | **Done** |
-| `maps_explore_area` | One-call neighborhood overview (composite) | **Done** |
-| `maps_plan_route` | Optimized multi-stop itinerary (composite) | **Done** |
-| `maps_compare_places` | Side-by-side place comparison (composite) | **Done** |
-| `maps_local_rank_tracker` | Geographic grid rank tracking — local SEO analysis (composite) | **Done** |
-| `GOOGLE_MAPS_ENABLED_TOOLS` | Filter tools to reduce context usage | **Done** |
-### Planned
-| Feature | What it unlocks | Status |
-|---------|----------------|--------|
-| `maps_place_photo` | Place photos for multimodal AI — "see" the restaurant ambiance | Planned |
-| Language parameter | Multi-language responses (ISO 639-1) across all tools | Planned |
-| MCP Prompt Templates | `/travel-planner`, `/neighborhood-scout` slash commands in Claude Desktop | Planned |
-| Geo-Reasoning Benchmark | 10-scenario test suite measuring LLM geospatial reasoning accuracy | Research |
-### Use Cases We're Building Toward
-These are the real-world scenarios driving our tool decisions:
-- **Travel planning** — "Plan a day trip in Tokyo" (geocode → search → directions → weather)
-- **Real estate analysis** — "Analyze this neighborhood: schools, commute, flood risk" (search-nearby × N + elevation + distance-matrix)
-- **Logistics optimization** — "Route these 12 deliveries efficiently from the warehouse" (plan-route)
-- **Field sales** — "Visit 6 clients in Chicago, minimize drive time, find lunch spots" (plan-route + search-nearby)
-- **Disaster response** — "Nearest open hospitals? Am I in a flood zone?" (search-nearby + elevation)
-- **Content creation** — "Top 5 neighborhoods in Austin with restaurant density and airport distance" (explore-area + distance-matrix)
-- **Accessibility** — "Wheelchair-accessible restaurants, avoid steep routes" (search-nearby + place-details + elevation)
-- **Local SEO** — "Audit my restaurant's ranking vs competitors within 1km" (search-places + compare-places + explore-area)
-## Changelog
-See [CHANGELOG.md](./CHANGELOG.md) for version history.
+Thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add Streamable HTTP support.
 ## License
-MIT
-## Contributing
-Community participation and contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding guidelines, and the pull request process.
-- Submit Issues: Report bugs or provide suggestions
-- Create Pull Requests: Submit code improvements
-- Documentation: Help improve documentation
-## Contact
-- Email: [reahtuoo310109@gmail.com](mailto:reahtuoo310109@gmail.com)
-- GitHub: [CabLate](https://github.com/cablate/)
-## Star History
-<a href="https://glama.ai/mcp/servers/@cablate/mcp-google-map">
-  <img width="380" height="200" src="https://glama.ai/mcp/servers/@cablate/mcp-google-map/badge" alt="Google Map Server MCP server" />
-</a>
-[![Star History Chart](https://star-history.dera.page/svg?repos=cablate/mcp-google-map&type=Date)](https://star-history.dera.page/#cablate/mcp-google-map&Date)
+[MIT](./LICENSE)

package/README.zh-TW.md CHANGED Viewed

@@ -1,114 +1,101 @@
-<p align="center">
-  <a href="https://www.npmjs.com/package/@cablate/mcp-google-map"><img src="https://img.shields.io/npm/v/@cablate/mcp-google-map" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/@cablate/mcp-google-map"><img src="https://img.shields.io/npm/dm/@cablate/mcp-google-map" alt="npm downloads"></a>
-  <a href="https://github.com/cablate/mcp-google-map/stargazers"><img src="https://img.shields.io/github/stars/cablate/mcp-google-map?style=social" alt="GitHub stars"></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/github/license/cablate/mcp-google-map" alt="license"></a>
-</p>
+# 給 AI 代理使用的 Google Maps
-<p align="center">
-  <img src="./assets/banner.webp" alt="MCP Google Maps — AI 驅動的地理空間工具" width="800">
-</p>
+**不用再為每一個 AI 應用重做地點搜尋、路線與位置工作流程。**
-<h3 align="center"><b>讓你的 AI 代理理解真實世界 —<br>地理編碼、路線規劃、地點搜尋、空間推理。</b></h3>
+`@cablate/mcp-google-map` 將 Google Maps Platform 整理成 18 個唯讀代理工具與三個用途明確的 Skills。代理可以搜尋真實地點、驗證路線、比較選項、建立可執行的旅行計畫，或分析在地搜尋能見度；既可透過 MCP，也可直接使用獨立 CLI。
-<p align="center">
-  <a href="./README.md">English</a> | <b>繁體中文</b>
-</p>
+整合方式由你決定：不想設定 MCP 時安裝 Codex Plugin；桌面 MCP client 使用 stdio；共享或遠端部署則使用 Streamable HTTP。
+<p align="center"><a href="./README.md">English</a> · <b>繁體中文</b></p>
+<p align="center"><img src="./assets/banner.webp" alt="提供給 AI 代理的 Google Maps 工具與工作流程" width="800"></p>
 <p align="center">
-  <img src="./assets/demo-grid-zh.png" alt="旅行規劃展示 — 京都二日遊、東京戶外一日、日本五日、曼谷背包客" width="800">
+  <a href="https://www.npmjs.com/package/@cablate/mcp-google-map"><img src="https://img.shields.io/npm/v/@cablate/mcp-google-map" alt="npm 版本"></a>
+  <a href="https://www.npmjs.com/package/@cablate/mcp-google-map"><img src="https://img.shields.io/npm/dm/@cablate/mcp-google-map" alt="npm 下載數"></a>
+  <a href="https://github.com/cablate/mcp-google-map/actions/workflows/ci.yml"><img src="https://github.com/cablate/mcp-google-map/actions/workflows/ci.yml/badge.svg" alt="CI 狀態"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/github/license/cablate/mcp-google-map" alt="MIT 授權"></a>
 </p>
-- **18 個工具** — 14 個原子工具 + 4 個組合工具（explore-area、plan-route、compare-places、local-rank-tracker）
-- **3 種模式** — stdio、StreamableHTTP、獨立 exec CLI
-- **3 個 Agent Skills** — 分別處理一般地圖、旅行規劃與 Local SEO（[`skills/`](./skills/)）
+## 為什麼要用？
+把原始 Maps API 交給代理只是第一步。真正有用的答案通常依賴一連串呼叫：確認地點、保留同一個地點的識別資訊、搜尋周邊、檢查營業資料、計算旅行時間，再清楚說明哪些內容真的驗證過。本專案把這些工作整理成一致的介面。
+- **從單次查詢走到可用成果。** 原子工具處理地址解析、地點詳情、導航、天氣、空氣品質與地圖；組合工具可探索區域、比較候選地點、最佳化停靠順序與分析在地排名。
+- **同一套能力可用或不用 MCP。** 獨立 `exec` CLI 適合 Agent Skills 與自動化；MCP server 則透過 stdio 或 HTTP 暴露相同的 18 個工具。
+- **不只提供函式名稱，也提供代理工作方法。** 三個 Skills 分別處理一般地圖研究、具證據的旅行規劃與 Local SEO。Codex 只有在請求符合時才載入完整指令。
+- **部署方式與憑證仍由你控制。** 可在本機執行或自行架設；API key 保留在環境變數或 request header，HTTP 部署亦支援每個 session 隔離。
+- **可以先小規模導入。** 透過 `GOOGLE_MAPS_ENABLED_TOOLS` 只註冊需要的工具，也可直接使用完整工具集。
+<p align="center"><img src="./assets/demo-grid-zh.png" alt="使用已檢查地點與路線進行旅行規劃的範例" width="800"></p>
+## 代理能完成什麼？
-### vs Google Grounding Lite
+| 成果 | 本專案提供的能力 |
+|---|---|
+| 搜尋並評估真實地點 | 自然語言與附近搜尋、地點詳情、評分、營業時間、評論與距離比較 |
+| 建立地理上可執行的行程 | 候選地點探索、沿途停靠點、旅行時間檢查、多站最佳化、天氣與靜態地圖 |
+| 研究一個區域 | 多類別區域探索，加上距離、海拔、時區、天氣與空氣品質查詢 |
+| 規劃外勤或配送 | 路線矩陣，以及最多 25 個停靠點的順序最佳化 |
+| 分析在地搜尋能見度 | 地理網格排名、競爭者探索、ARP、ATRP 與 SoLV 指標 |
+| 補全位置資料 | 單筆或批次地址解析、反向地址解析與結構化 JSON 輸出 |
-| | 本專案 | [Grounding Lite](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) |
+這些是資料與規劃工具，不保證安全、無障礙、即時營業狀態或排名成果。應用程式若顯示 Places 評論、照片或 AI 摘要，必須遵守[內容署名與保存指引](./skills/_shared/content-attribution.md)。
+## 選擇整合方式
+| 使用方式 | 適合情境 | 實際執行內容 |
 |---|---|---|
-| 工具數 | **18** | 3 |
-| 地理編碼 | 有 | 無 |
-| 逐步導航 | 有 | 無 |
-| 海拔查詢 | 有 | 無 |
-| 距離矩陣 | 有 | 無 |
-| 地點詳情 | 有 | 無 |
-| 時區查詢 | 有 | 無 |
-| 天氣查詢 | 有 | 有 |
-| 空氣品質 | 有 | 無 |
-| 地圖圖片 | 有 | 無 |
-| 組合工具（探索、規劃、比較） | 有 | 無 |
-| 開源 | MIT | 否 |
-| 自架部署 | 有 | 僅 Google 託管 |
-| Agent Skill | 有 | 無 |
-### 快速開始
+| **Codex Plugin** | 不設定 MCP，直接讓 Codex 回答地圖、旅行或 Local SEO 問題 | 符合請求的 Skill 按需載入並呼叫獨立 CLI |
+| **獨立 CLI** | 腳本、自動化與其他支援 Skill 的代理 | 單次無狀態命令回傳 JSON |
+| **MCP stdio** | Claude Desktop、Cursor、VS Code 與其他本機 MCP clients | Client 啟動本機 MCP 程序 |
+| **Streamable HTTP** | 多 session、容器、區域網路或遠端存取 | 自架 server 暴露 `/mcp` |
-```bash
-# stdio（Claude Desktop、Cursor 等）
-npx @cablate/mcp-google-map --stdio
+所有方式都需要 Node.js 18+ 與 Google Maps Platform API key，實際 API 呼叫可能產生費用。請啟用所選工具需要的 API；常見地點與路線流程會使用 **Places API (New)**、**Routes API**，通常也需要 **Geocoding API**。
-# exec CLI — 不需啟動 server
-npx @cablate/mcp-google-map exec geocode '{"address":"台北101"}'
+## 從 Codex 開始，不需要 MCP
-# HTTP server
-npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
+```bash
+codex plugin marketplace add cablate/mcp-google-map --ref main
+codex plugin add mcp-google-map@cablate
 ```
-## 特別感謝
-感謝 [@junyinnnn](https://github.com/junyinnnn) 協助實作 `streamablehttp` 支援。
+在 Codex 的執行環境設定 `GOOGLE_MAPS_API_KEY`，再開啟新對話。先檢查本機環境，不會送出 Google API 請求：
-## 可用工具
+```bash
+npx -y @cablate/mcp-google-map doctor
+```
-| 工具 | 說明 |
-|------|------|
-| `maps_search_nearby` | 依類型搜尋附近地點（餐廳、咖啡廳、飯店等），支援半徑、評分、營業中篩選 |
-| `maps_search_places` | 自然語言地點搜尋（如「東京拉麵」），支援位置偏好、評分、營業中篩選 |
-| `maps_place_details` | 以 place_id 取得地點完整資訊 — 評論、電話、網站、營業時間。可選 `maxPhotos` 參數取得照片 URL。 |
-| `maps_geocode` | 將地址或地標名稱轉換為 GPS 座標 |
-| `maps_reverse_geocode` | 將 GPS 座標轉換為街道地址 |
-| `maps_distance_matrix` | 計算多個起點與終點間的旅行距離和時間 |
-| `maps_directions` | 取得兩點間的逐步導航路線 |
-| `maps_elevation` | 查詢地理座標的海拔高度（公尺） |
-| `maps_timezone` | 查詢座標的時區 ID、名稱、UTC/DST 偏移量和當地時間 |
-| `maps_weather` | 查詢當前天氣或預報 — 溫度、濕度、風速、紫外線、降水 |
-| `maps_air_quality` | 查詢空氣品質指數、污染物濃度，以及各族群健康建議 |
-| `maps_static_map` | 產生帶標記、路徑或路線的地圖圖片 — 直接內嵌在對話中 |
-| `maps_batch_geocode` | 一次地理編碼最多 50 個地址 |
-| `maps_search_along_route` | 搜尋兩點間路線沿途的地點 — 依最小繞路時間排序 |
-| **組合工具** | |
-| `maps_explore_area` | 一次呼叫探索某地周邊 — 搜尋多種地點類型並取得詳情 |
-| `maps_plan_route` | 規劃最佳化多站路線 — 地理編碼、最佳順序、回傳導航 |
-| `maps_compare_places` | 並排比較地點 — 搜尋、取得詳情，可選計算距離 |
-| `maps_local_rank_tracker` | 地理網格排名追蹤（類似 LocalFalcon）— 支援最多 3 個關鍵字批量掃描，回傳 ARP、ATRP、SoLV 指標 |
+成功時，`node`、`package` 與 `api-key` 檢查會通過，`live-api` 會略過。只有在你確定要送出可能計費的 Geocoding、Places 與 Routes 測試時，才使用 `doctor --live`。
-所有工具標註 `readOnlyHint: true` 和 `destructiveHint: false` — MCP 客戶端可自動核准，無需使用者確認。
+可以直接問：
-> **前置條件**：使用地點相關工具前，請在 [Google Cloud Console](https://console.cloud.google.com) 啟用 **Places API (New)**。
+> 規劃一個實際可行的京都兩日行程。把鄰近地點排在一起、檢查交通時間，並說明營業時間有哪些假設。
-## 安裝
+Codex 會依請求選擇一般地圖研究、旅行規劃或 Local SEO Skill。Plugin 不會註冊或啟動 MCP server。可參考[非 MCP 完整示範](./examples/agent-skill-demo.md)重現整個流程。
-### Codex Plugin（3 個 Agent Skills，不需要 MCP）
+## 使用獨立 CLI
-先加入 CabLate marketplace，再安裝只包含 Skill 的 plugin：
+每一個 MCP 工具都有簡短的 CLI 名稱：
 ```bash
-codex plugin marketplace add cablate/mcp-google-map --ref main
-codex plugin add mcp-google-map@cablate
+npx -y @cablate/mcp-google-map exec geocode '{"address":"台北101"}'
+npx -y @cablate/mcp-google-map exec search-places '{"query":"京都安靜的咖啡廳"}'
+npx -y @cablate/mcp-google-map exec directions '{"origin":"台北車站","destination":"台北101","mode":"transit"}'
 ```
-請在 Codex 可讀取的環境中設定 `GOOGLE_MAPS_API_KEY`，並確認已安裝 Node.js 18+ 與 `npx`，然後開啟新對話。Plugin 會探索三個用途明確的 Skills，並教代理直接執行 `npx -y @cablate/mcp-google-map exec ...`；它不會註冊或啟動 MCP server。下方的 MCP 設定仍是另一種獨立使用方式。
+每次呼叫皆為無狀態。成功時在 stdout 回傳 `{ "success": true, "data": ... }`；失敗時以非零狀態結束，並在 stderr 輸出結構化 JSON。
-執行階段會先看到每個 Skill 的名稱與描述，只有請求符合時才載入完整指令：
+批次補全地址可使用：
-- `google-maps` — 地點搜尋、地址解析、路線、區域與環境資訊
-- `google-maps-travel-planning` — 單日與多日旅行行程
-- `google-maps-local-seo` — Google 商家檔案能見度與地理排名分析
+```bash
+npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
+cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -
+```
-### 方法一：stdio（大多數客戶端推薦）
+## 連接 MCP client
-適用於 Claude Desktop、Cursor、VS Code 及任何支援 stdio 的 MCP 客戶端：
+### stdio
 ```json
 {
@@ -116,295 +103,83 @@ codex plugin add mcp-google-map@cablate
     "google-maps": {
       "command": "npx",
       "args": ["-y", "@cablate/mcp-google-map", "--stdio"],
-      "env": {
-        "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY"
-      }
+      "env": { "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY" }
     }
   }
 }
 ```
-**減少上下文用量** — 如果只需要部分工具，設定 `GOOGLE_MAPS_ENABLED_TOOLS` 限制註冊的工具：
-```json
-{
-  "env": {
-    "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY",
-    "GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"
-  }
-}
-```
-不設定或設為 `*` 即啟用全部 18 個工具（預設）。
-### 方法二：HTTP Server
+若要減少工具清單占用的上下文，可加入 `"GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"`。不設定或使用 `*` 即暴露全部工具。
-適用於多 session 部署、per-request API key 隔離或遠端存取：
+### Streamable HTTP
 ```bash
-npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
-# 綁定所有網路介面以支援遠端存取（例如 Docker、區域網路）
-npx @cablate/mcp-google-map --host 0.0.0.0 --port 3000 --apikey "YOUR_API_KEY"
+npx @cablate/mcp-google-map --host 127.0.0.1 --port 3000 --apikey "YOUR_API_KEY"
 ```
-然後設定你的 MCP 客戶端：
 ```json
 {
   "mcpServers": {
     "google-maps": {
       "type": "http",
-      "url": "http://localhost:3000/mcp"
+      "url": "http://127.0.0.1:3000/mcp"
     }
   }
 }
 ```
-### Server 資訊
+只有 server 確實需要接受外部連線時才綁定 `0.0.0.0`。多租戶部署建議使用 `X-Google-Maps-API-Key` request header，讓不同 session 的 key 保持隔離。
-- **傳輸方式**：stdio（`--stdio`）或 Streamable HTTP（預設）
-- **工具數**：18 個 Google Maps 工具（14 原子 + 4 組合）— 可透過 `GOOGLE_MAPS_ENABLED_TOOLS` 篩選
+## 工具目錄
-### CLI Exec 模式（Agent Skill）
+| 分類 | 工具 |
+|---|---|
+| 地點與探索 | `maps_search_places`、`maps_search_nearby`、`maps_place_details`、`maps_explore_area`、`maps_compare_places`、`maps_search_along_route` |
+| 位置與路線 | `maps_geocode`、`maps_reverse_geocode`、`maps_directions`、`maps_distance_matrix`、`maps_plan_route`、`maps_batch_geocode` |
+| 環境資訊與視覺化 | `maps_elevation`、`maps_timezone`、`maps_weather`、`maps_air_quality`、`maps_static_map` |
+| Local SEO | `maps_local_rank_tracker` |
-不啟動 MCP server，直接使用工具：
+全部 18 個工具都宣告 `readOnlyHint: true` 與 `destructiveHint: false`。完整參數、回應格式與工作流程範例見[工具參考](./skills/google-maps/references/tools-api.md)。
-```bash
-npx @cablate/mcp-google-map exec geocode '{"address":"台北101"}'
-npx @cablate/mcp-google-map exec search-places '{"query":"東京拉麵"}'
-```
+## API key 與 Google Cloud 設定
-全部 18 個工具可用：`geocode`、`reverse-geocode`、`search-nearby`、`search-places`、`place-details`、`directions`、`distance-matrix`、`elevation`、`timezone`、`weather`、`air-quality`、`static-map`、`batch-geocode-tool`、`search-along-route`、`explore-area`、`plan-route`、`compare-places`、`local-rank-tracker`。Skill 定義與完整參數文件見 [`skills/`](./skills/)。
+API key 所屬的 Google Cloud project 必須已啟用 billing，且 key restrictions 要與執行環境相容。[設定與診斷指南](./skills/_shared/setup-and-diagnostics.md)列出每項能力需要的 API，以及常見錯誤的處理方式。
-若要**不透過 MCP、只用 Agent Skill**：
+憑證優先順序如下：
-1. 依你的代理工具說明，將整個 [`skills/`](./skills/) 目錄樹安裝到它的 Skills 目錄；三個 Skill 資料夾與 `_shared/` 必須放在一起，跨 Skill 參考才會正常解析。除非透過 Plugin Marketplace 安裝，否則只安裝 npm 套件不會自動把 Skill 註冊到代理工具。
-2. 讓代理工具可使用 Node.js 18+、`npx`，並在其環境設定 `GOOGLE_MAPS_API_KEY`。建議使用環境變數；`--apikey` 可能讓金鑰出現在 shell 歷史或程序清單。
-3. 直接向代理工具提問地點問題。Skill 會引導它呼叫獨立 CLI，例如 `npx -y @cablate/mcp-google-map exec geocode '{"address":"台北101"}'`；不必啟動 MCP server 或設定 MCP client。
+1. `X-Google-Maps-API-Key` HTTP request header
+2. `--apikey` 命令列參數
+3. `GOOGLE_MAPS_API_KEY` 環境變數
-先執行 `npx -y @cablate/mcp-google-map doctor`，即可在不呼叫 Google API、不產生 API 費用的情況下檢查本機準備狀態。告知使用者測試請求可能產生 Google Maps Platform 費用後，可用 `doctor --live` 分別驗證 Geocoding、Places API (New) 與 Routes API。
+建議使用環境變數或 request header。命令列中的秘密可能出現在 shell 歷史或程序清單。
-完整的非 MCP 操作步驟見 [Agent Skill 示範](./examples/agent-skill-demo.md)。若代理工具或應用程式會呈現 Places 評論、照片或 AI 摘要，請遵照[內容署名與保存指引](./skills/_shared/content-attribution.md)；工具會保留來源及揭露欄位，但不會替你的介面完成署名呈現。
+## 信任與限制
-### 批次地理編碼
-從檔案批次地理編碼：
-```bash
-npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
-cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -
-```
-輸入：每行一個地址。輸出：JSON `{ total, succeeded, failed, results[] }`。預設並行度：20。
-### API Key 設定
-API key 可透過三種方式提供（優先順序）：
-1. **HTTP Headers**（最高優先）
-   ```json
-   {
-     "mcp-google-map": {
-       "transport": "streamableHttp",
-       "url": "http://localhost:3000/mcp",
-       "headers": {
-         "X-Google-Maps-API-Key": "YOUR_API_KEY"
-       }
-     }
-   }
-   ```
-2. **命令列參數**
-   ```bash
-   mcp-google-map --apikey YOUR_API_KEY
-   ```
-3. **環境變數**（.env 檔案或命令列）
-   ```env
-   GOOGLE_MAPS_API_KEY=your_api_key_here
-   MCP_SERVER_PORT=3000
-   MCP_SERVER_HOST=0.0.0.0
-   ```
+- 地點與路線事實來自你為專案啟用的 Google Maps Platform APIs；天氣服務有區域限制。
+- API 成功回應不等於已證明無障礙、安全、法律適用性或即時可用性。
+- 套件會保留 API 回傳的來源與揭露 metadata，但你的介面仍有責任符合署名與保存規範。
+- HTTP 模式支援每個 session 的 API key 隔離與 DNS rebinding 防護。
+- 本專案採 MIT 授權且可自行架設。漏洞回報請見 [SECURITY.md](./SECURITY.md)；企業審查可參考 [Security Assessment Clarifications](./SECURITY_ASSESSMENT.md)。
 ## 開發
-### 本地開發
 ```bash
-# 複製專案
 git clone https://github.com/cablate/mcp-google-map.git
 cd mcp-google-map
-# 安裝依賴
-npm install
-# 設定環境變數
-cp .env.example .env
-# 編輯 .env 填入你的 API key
-# 建置專案
+npm ci
 npm run build
-# 啟動 server
-npm start
-# 或以開發模式執行
-npm run dev
-```
-### 測試
-```bash
-# 執行 smoke tests（基本測試不需要 API key）
+npm run test:unit
 npm test
-# 執行完整 E2E 測試（需要 GOOGLE_MAPS_API_KEY）
-npm run test:e2e
-```
-### 專案結構
-```
-src/
-├── cli.ts                        # CLI 進入點
-├── config.ts                     # 工具註冊與 server 設定
-├── index.ts                      # 套件匯出
-├── core/
-│   └── BaseMcpServer.ts          # MCP server（streamable HTTP 傳輸）
-├── services/
-│   ├── NewPlacesService.ts       # Google Places API (New) 客戶端
-│   ├── PlacesSearcher.ts         # Service facade 層
-│   └── toolclass.ts              # Legacy Google Maps API 客戶端
-├── tools/
-│   └── maps/
-│       ├── searchNearby.ts       # maps_search_nearby 工具
-│       ├── searchPlaces.ts       # maps_search_places 工具
-│       ├── placeDetails.ts       # maps_place_details 工具
-│       ├── geocode.ts            # maps_geocode 工具
-│       ├── reverseGeocode.ts     # maps_reverse_geocode 工具
-│       ├── distanceMatrix.ts     # maps_distance_matrix 工具
-│       ├── directions.ts         # maps_directions 工具
-│       ├── elevation.ts          # maps_elevation 工具
-│       ├── timezone.ts           # maps_timezone 工具
-│       ├── weather.ts            # maps_weather 工具
-│       ├── airQuality.ts         # maps_air_quality 工具
-│       ├── staticMap.ts          # maps_static_map 工具
-│       ├── batchGeocode.ts       # maps_batch_geocode 工具
-│       ├── searchAlongRoute.ts   # maps_search_along_route 工具
-│       ├── exploreArea.ts        # maps_explore_area（組合）
-│       ├── planRoute.ts          # maps_plan_route（組合）
-│       ├── comparePlaces.ts      # maps_compare_places（組合）
-│       └── localRankTracker.ts   # maps_local_rank_tracker（組合）
-└── utils/
-    ├── apiKeyManager.ts          # API key 管理
-    └── requestContext.ts         # Per-request context（API key 隔離）
-tests/
-└── smoke.test.ts                 # Smoke + E2E 測試套件
-skills/
-├── google-maps/                  # 一般地點、路線與環境資訊工作流程
-│   ├── SKILL.md
-│   └── references/tools-api.md   # 工具參數 + 一般場景食譜
-├── google-maps-travel-planning/  # 單日與多日行程工作流程
-│   ├── SKILL.md
-│   └── references/travel-planning.md
-├── google-maps-local-seo/        # 商家能見度與地理排名工作流程
-│   ├── SKILL.md
-│   └── references/local-seo.md
-└── _shared/                      # 三個 Skills 按需載入的共用資源
-    ├── setup-and-diagnostics.md
-    └── content-attribution.md
-.agents/
-├── plugins/marketplace.json      # CabLate marketplace 目錄
-└── skills/project-docs/          # 僅供維護者使用的開發 Skill
-.codex-plugin/plugin.json         # Codex 相容 manifest
-plugin.json                       # 可攜式 Agent Plugin manifest
 ```
-## 技術棧
-- **TypeScript** - 型別安全開發
-- **Node.js** - 執行環境
-- **@googlemaps/places** - Google Places API (New) 地點搜尋與詳情
-- **@googlemaps/google-maps-services-js** - Legacy API 地理編碼、導航、距離矩陣、海拔
-- **@modelcontextprotocol/sdk** - MCP 協議實作（v1.27+）
-- **Express.js** - HTTP server 框架
-- **Zod** - Schema 驗證
-## 安全性
-- API key 在 server 端處理
-- 多租戶部署的 per-session API key 隔離
-- 正式環境可啟用 DNS rebinding 防護
-- 使用 Zod schemas 進行輸入驗證
-企業安全審查請參考 [Security Assessment Clarifications](./SECURITY_ASSESSMENT.md) — 涵蓋授權、資料保護、憑證管理、工具污染、AI 代理執行環境驗證的 23 項檢查清單。
-## 路線圖
-### 近期新增
-| 工具 / 功能 | 解鎖場景 | 狀態 |
-|------|----------------|--------|
-| `maps_static_map` | 帶標記/路線的地圖圖片 — 多模態 AI 可「看見」地圖 | **完成** |
-| `maps_air_quality` | AQI、污染物 — 健康出行、戶外規劃 | **完成** |
-| `maps_batch_geocode` | 一次地理編碼最多 50 個地址 — 資料增強 | **完成** |
-| `maps_search_along_route` | 沿路線搜尋地點，依繞路時間排序 — 旅行規劃 | **完成** |
-| `maps_explore_area` | 一次呼叫的社區概覽（組合工具） | **完成** |
-| `maps_plan_route` | 最佳化多站行程（組合工具） | **完成** |
-| `maps_compare_places` | 並排地點比較（組合工具） | **完成** |
-| `maps_local_rank_tracker` | 地理網格排名追蹤 — Local SEO 分析（組合工具） | **完成** |
-| `GOOGLE_MAPS_ENABLED_TOOLS` | 篩選工具以減少上下文用量 | **完成** |
-### 計畫中
-| 功能 | 解鎖場景 | 狀態 |
-|---------|----------------|--------|
-| `maps_place_photo` | 地點照片供多模態 AI 使用 — 「看見」餐廳氛圍 | 計畫中 |
-| 語言參數 | 所有工具支援多語言回應（ISO 639-1） | 計畫中 |
-| MCP Prompt Templates | Claude Desktop 中的 `/travel-planner`、`/neighborhood-scout` 斜線指令 | 計畫中 |
-| Geo-Reasoning Benchmark | 10 場景測試套件，衡量 LLM 地理空間推理準確度 | 研究中 |
+即時 E2E 呼叫需要 `GOOGLE_MAPS_API_KEY`，且可能計費：`npm run test:e2e`。
-### 我們在建構的應用場景
+歡迎參與貢獻。送出 pull request 前請先閱讀 [CONTRIBUTING.md](./CONTRIBUTING.md)；版本紀錄見 [CHANGELOG.md](./CHANGELOG.md)。
-以下是驅動工具開發方向的真實場景：
-- **旅行規劃** — 「規劃東京一日遊」（geocode → search → directions → weather）
-- **房地產分析** — 「分析這個社區：學校、通勤、洪水風險」（search-nearby × N + elevation + distance-matrix）
-- **物流優化** — 「從倉庫出發，最佳化這 12 個配送地址的路線」（plan-route）
-- **外勤銷售** — 「拜訪芝加哥 6 個客戶，最小化車程，找午餐地點」（plan-route + search-nearby）
-- **災害應變** — 「最近有開的醫院？我在洪水區嗎？」（search-nearby + elevation）
-- **內容創作** — 「Austin 前 5 社區的餐廳密度和機場距離」（explore-area + distance-matrix）
-- **無障礙** — 「輪椅可達的餐廳，避開陡坡路線」（search-nearby + place-details + elevation）
-- **Local SEO** — 「分析我的餐廳在 1 公里內跟競爭對手的排名差距」（search-places + compare-places + explore-area）
-## 更新日誌
+## 特別感謝
-見 [CHANGELOG.md](./CHANGELOG.md)。
+感謝 [@junyinnnn](https://github.com/junyinnnn) 協助加入 Streamable HTTP 支援。
 ## 授權
-MIT
-## 貢獻
-歡迎社群參與和貢獻！
-- 提交 Issue：回報 bug 或提供建議
-- 建立 Pull Request：提交程式碼改進
-- 文件：協助改善文件
-## 聯絡
-- Email: [reahtuoo310109@gmail.com](mailto:reahtuoo310109@gmail.com)
-- GitHub: [CabLate](https://github.com/cablate/)
-## Star History
-<a href="https://glama.ai/mcp/servers/@cablate/mcp-google-map">
-  <img width="380" height="200" src="https://glama.ai/mcp/servers/@cablate/mcp-google-map/badge" alt="Google Map Server MCP server" />
-</a>
-[![Star History Chart](https://star-history.dera.page/svg?repos=cablate/mcp-google-map&type=Date)](https://star-history.dera.page/#cablate/mcp-google-map&Date)
+[MIT](./LICENSE)

package/examples/agent-skill-demo.md CHANGED Viewed

@@ -1,16 +1,29 @@
 # Agent Skill demo (no MCP server)
-This walkthrough demonstrates the two pieces separately: the plugin's Agent Skills tell an agent which geographic workflow and tool to use, and the package CLI performs the API call. It does not require an MCP client or server. Build and run the CLI from the same repository revision as the Skills so the instructions and executable stay aligned.
+This walkthrough verifies the no-MCP path end to end: the plugin's Agent Skills choose a geographic workflow, and the npm package CLI performs the API call. You do not need an MCP client or server.
 ## 1. Install the Skills
-Prefer installing the Codex plugin from the CabLate marketplace. For a manual installation, clone a chosen release tag and copy the whole `skills/` tree according to the client's instructions. Keep the three Skill folders and `_shared/` together. Installing npm alone does not register a Skill unless it is installed through the plugin marketplace.
+Install the Codex plugin from the CabLate marketplace:
-Check that your agent can discover `google-maps`, `google-maps-travel-planning`, and `google-maps-local-seo`, and can run shell commands. Provide a Google Maps Platform API key to the agent's environment as `GOOGLE_MAPS_API_KEY` through your normal secret-management method; never paste it into the prompt or commit it. Node.js 18+ and `npx` must be available.
+```bash
+codex plugin marketplace add cablate/mcp-google-map --ref main
+codex plugin add mcp-google-map@cablate
+```
+Start a new conversation after installation. For a manual installation in another Skill-compatible agent, clone a chosen release tag and copy the whole `skills/` tree according to that client's instructions. Keep the three Skill folders and `_shared/` together. Installing the npm package alone does not register a Skill.
+Check that your agent can discover `google-maps`, `google-maps-travel-planning`, and `google-maps-local-seo`, and can run shell commands. Provide a Google Maps Platform API key to the agent's environment as `GOOGLE_MAPS_API_KEY` through your normal secret-management method; never paste it into the prompt or commit it. Node.js 18+ and `npx` must be available. Enable Places API (New) and Routes API for workflows that use them.
 ## 2. Validate without an API call
-From the cloned repository, install and build the package, then run the local doctor:
+For a marketplace installation, run:
+```bash
+npx -y @cablate/mcp-google-map doctor
+```
+For a cloned repository, install and build the package, then run the same check against the checkout:
 ```bash
 npm ci
@@ -18,7 +31,7 @@ npm run build
 node dist/cli.js doctor
 ```
-The report should pass the Node.js, package, and API-key checks and skip `live-api`. It makes no Google API requests. To test Geocoding, Places (New), and Routes after disclosing that the calls may be billable, run `node dist/cli.js doctor --live`.
+Success means the Node.js, package, and API-key checks pass and `live-api` is skipped. This check makes no Google API requests. To test Geocoding, Places (New), and Routes, run the same command with `--live`; those calls may be billable.
 ## 3. Try one live request

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cablate/mcp-google-map",
-  "version": "0.0.65",
+  "version": "0.0.68",
   "mcpName": "io.github.cablate/google-map",
   "description": "18 Google Maps tools for AI agents — geocode, search, directions, weather, air quality, local rank tracking, map images via MCP server or standalone CLI",
   "type": "module",

package/plugin.json CHANGED Viewed

@@ -1,8 +1,8 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "mcp-google-map",
-  "version": "0.0.65",
-  "description": "Use focused Skills for Google Maps place research, travel planning, and local SEO through a standalone CLI.",
+  "version": "0.0.68",
+  "description": "Use Google Maps for place research, travel planning, and local SEO through focused Skills and a standalone CLI—no MCP setup required.",
   "author": {
     "name": "CabLate",
     "url": "https://github.com/cablate"