diff --git a/README.md b/README.md
index 026d060..749788f 100644
--- a/README.md
+++ b/README.md
@@ -1,132 +1,101 @@
-# MCP Google Maps
+# Google Maps for AI agents
-Give AI agents reliable Google Maps search, geocoding, routing, weather, air quality, and local SEO data. Use it as a Codex Plugin with standalone CLI calls, or connect the same 18 tools through MCP.
+**Stop rebuilding place search, routing, and location workflows for every AI app.**
-English | 繁體中文
+`@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.
+
+English · 繁體中文
+
+
- 
- 
+ 
+
-
- 
-
+## Why use it?
+
+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.
+
+- **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.
+
+
+
+## What can an agent do?
+
+| 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 |
-- **18 tools** — 14 atomic tools and 4 higher-level workflows
-- **Three ways to connect** — Codex Plugin, MCP over stdio, or Streamable HTTP
-- **Three focused Skills** — general maps, travel planning, and local SEO
+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 how to use it
+## Choose your integration
-| If you want to… | Use | What runs |
+| Use | Best for | What runs |
|---|---|---|
-| Let Codex answer map, travel, or local SEO questions without configuring MCP | **Codex Plugin** | The matching Skill loads on demand and calls the standalone CLI |
-| Add Google Maps tools to Claude Desktop, Cursor, VS Code, or another local MCP client | **MCP stdio** | The client starts one local MCP process |
-| Serve multiple or remote MCP sessions | **Streamable HTTP** | A self-hosted HTTP server at `/mcp` |
+| **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` |
-All options require Node.js 18+ and a Google Maps Platform API key. Enable **Places API (New)** and **Routes API** in [Google Cloud Console](https://console.cloud.google.com) for place and route workflows. Google may charge for live API requests.
+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**.
-## Fastest start: Codex Plugin
+## Start with Codex—no MCP required
```bash
codex plugin marketplace add cablate/mcp-google-map --ref main
codex plugin add mcp-google-map@cablate
```
-Set `GOOGLE_MAPS_API_KEY` in the environment where Codex runs, then start a new conversation and ask a location question. Confirm local readiness without calling Google APIs:
+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:
```bash
npx -y @cablate/mcp-google-map doctor
```
-A ready installation reports successful Node.js, package, and API-key checks; `live-api` is skipped. Use `doctor --live` only when you intend to make potentially billable test requests.
+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.
-The plugin does **not** start or register an MCP server. At runtime, Codex first sees the names and descriptions of three Skills and loads full instructions only when the request matches:
+Try asking:
-- `google-maps` — place search, geocoding, routes, neighborhood, and environmental facts
-- `google-maps-travel-planning` — day trips and multi-day itineraries
-- `google-maps-local-seo` — business visibility and geographic rank analysis
+> Plan a practical two-day Kyoto itinerary. Group nearby places, check travel times, and explain any opening-hour assumptions.
-For a complete no-MCP walkthrough, see the [Agent Skill demo](./examples/agent-skill-demo.md).
+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.
-### vs Google Grounding Lite
+## Use the standalone CLI
-| | This project | [Grounding Lite](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) |
-|---|---|---|
-| 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 |
-
-### CLI and server quick checks
+Every MCP tool also has a short CLI name:
```bash
-# stdio (Claude Desktop, Cursor, etc.)
-npx @cablate/mcp-google-map --stdio
-
-# exec CLI — no server needed
-npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
-
-# HTTP server
-npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
+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"}'
```
-## Special Thanks
-
-Special thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add support for `streamablehttp`.
-
-## Available Tools
-
-| 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). |
+Each call is stateless. Successful calls return `{ "success": true, "data": ... }` on stdout; failures exit nonzero and write structured JSON to stderr.
-All tools are annotated with `readOnlyHint: true` and `destructiveHint: false` — MCP clients can auto-approve these without user confirmation.
+For bulk address enrichment:
-> **Prerequisite**: Enable **Places API (New)** and **Routes API** in [Google Cloud Console](https://console.cloud.google.com) before using place-related and routing tools.
-
-## Installation
-
-The [fastest-start section](#fastest-start-codex-plugin) covers the Codex Plugin. Use one of the following configurations when you specifically need MCP.
+```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 -
+```
-### MCP stdio (recommended for local clients)
+## Connect an MCP client
-Works with Claude Desktop, Cursor, VS Code, and any MCP client that supports stdio:
+### stdio
```json
{
@@ -134,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.
### Streamable HTTP
-For multi-session deployments, per-request API key isolation, or remote access:
-
```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**:
-
-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.
-
-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.
+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.
-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.
+## Tool catalog
-### Batch Geocode
+| 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` |
-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.
+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).
+## API key and Google Cloud setup
+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.
-### API Key Configuration
+Credential priority is:
-API keys can be provided in three ways (priority order):
+1. `X-Google-Maps-API-Key` HTTP request header
+2. `--apikey` command-line option
+3. `GOOGLE_MAPS_API_KEY` environment variable
-1. **HTTP Headers** (Highest priority)
+Prefer environment variables or request headers. Command-line secrets can appear in shell history and process listings.
- ```json
- {
- "mcp-google-map": {
- "transport": "streamableHttp",
- "url": "http://localhost:3000/mcp",
- "headers": {
- "X-Google-Maps-API-Key": "YOUR_API_KEY"
- }
- }
- }
- ```
+## Trust and limits
-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
-
-```
-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
-```
+Live E2E calls require `GOOGLE_MAPS_API_KEY` and may be billable: `npm run test:e2e`.
-## Tech Stack
+Contributions are welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. Release history is in [CHANGELOG.md](./CHANGELOG.md).
-- **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
+## Acknowledgements
-## 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
-
-
- 
-
-
-[](https://star-history.dera.page/#cablate/mcp-google-map&Date)
+[MIT](./LICENSE)
diff --git a/README.zh-TW.md b/README.zh-TW.md
index b098d2b..d0f23d4 100644
--- a/README.zh-TW.md
+++ b/README.zh-TW.md
@@ -1,132 +1,101 @@
-# MCP Google Maps
+# 給 AI 代理使用的 Google Maps
-讓 AI 代理可靠地取得 Google Maps 地點搜尋、地址解析、路線、天氣、空氣品質與 Local SEO 資料。你可以安裝 Codex Plugin，讓代理直接呼叫 CLI；也可以透過 MCP 使用同一組 18 個工具。
+**不用再為每一個 AI 應用重做地點搜尋、路線與位置工作流程。**
-English | 繁體中文
+`@cablate/mcp-google-map` 將 Google Maps Platform 整理成 18 個唯讀代理工具與三個用途明確的 Skills。代理可以搜尋真實地點、驗證路線、比較選項、建立可執行的旅行計畫，或分析在地搜尋能見度；既可透過 MCP，也可直接使用獨立 CLI。
-
-
-
+整合方式由你決定：不想設定 MCP 時安裝 Codex Plugin；桌面 MCP client 使用 stdio；共享或遠端部署則使用 Streamable HTTP。
-
-
-
-
-
-
+English · 繁體中文
+
+
- 
+
+
+
+
-- **18 個工具** — 14 個原子工具與 4 個高階工作流程
-- **三種連接方式** — Codex Plugin、MCP stdio、Streamable HTTP
-- **三個用途明確的 Skills** — 一般地圖、旅行規劃、Local SEO
+## 為什麼要用？
+
+把原始 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` 只註冊需要的工具，也可直接使用完整工具集。
+
+
+
+## 代理能完成什麼？
+
+| 成果 | 本專案提供的能力 |
+|---|---|
+| 搜尋並評估真實地點 | 自然語言與附近搜尋、地點詳情、評分、營業時間、評論與距離比較 |
+| 建立地理上可執行的行程 | 候選地點探索、沿途停靠點、旅行時間檢查、多站最佳化、天氣與靜態地圖 |
+| 研究一個區域 | 多類別區域探索，加上距離、海拔、時區、天氣與空氣品質查詢 |
+| 規劃外勤或配送 | 路線矩陣，以及最多 25 個停靠點的順序最佳化 |
+| 分析在地搜尋能見度 | 地理網格排名、競爭者探索、ARP、ATRP 與 SoLV 指標 |
+| 補全位置資料 | 單筆或批次地址解析、反向地址解析與結構化 JSON 輸出 |
+
+這些是資料與規劃工具，不保證安全、無障礙、即時營業狀態或排名成果。應用程式若顯示 Places 評論、照片或 AI 摘要，必須遵守[內容署名與保存指引](./skills/_shared/content-attribution.md)。
-## 選擇使用方式
+## 選擇整合方式
-| 你的需求 | 建議方式 | 實際執行方式 |
+| 使用方式 | 適合情境 | 實際執行內容 |
|---|---|---|
-| 讓 Codex 回答地圖、旅行或 Local SEO 問題，不想設定 MCP | **Codex Plugin** | 符合需求的 Skill 按需載入，並直接呼叫 CLI |
-| 在 Claude Desktop、Cursor、VS Code 或其他本機 MCP client 加入 Google Maps 工具 | **MCP stdio** | Client 啟動一個本機 MCP 程序 |
-| 提供多 session 或遠端 MCP 存取 | **Streamable HTTP** | 自架 HTTP server，端點為 `/mcp` |
+| **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` |
-三種方式都需要 Node.js 18+ 與 Google Maps Platform API key。地點與路線工作流程還要先在 [Google Cloud Console](https://console.cloud.google.com) 啟用 **Places API (New)** 與 **Routes API**。實際 API 請求可能產生 Google 費用。
+所有方式都需要 Node.js 18+ 與 Google Maps Platform API key，實際 API 呼叫可能產生費用。請啟用所選工具需要的 API；常見地點與路線流程會使用 **Places API (New)**、**Routes API**，通常也需要 **Geocoding API**。
-## 最快開始：Codex Plugin
+## 從 Codex 開始，不需要 MCP
```bash
codex plugin marketplace add cablate/mcp-google-map --ref main
codex plugin add mcp-google-map@cablate
```
-在 Codex 的執行環境設定 `GOOGLE_MAPS_API_KEY`，重新開啟對話後直接提出地點問題。先用下列命令檢查本機環境，不會呼叫 Google API：
+在 Codex 的執行環境設定 `GOOGLE_MAPS_API_KEY`，再開啟新對話。先檢查本機環境，不會送出 Google API 請求：
```bash
npx -y @cablate/mcp-google-map doctor
```
-環境正確時，Node.js、套件與 API key 檢查會通過，`live-api` 會顯示略過。只有在你確定要送出可能計費的測試請求時，才使用 `doctor --live`。
+成功時，`node`、`package` 與 `api-key` 檢查會通過，`live-api` 會略過。只有在你確定要送出可能計費的 Geocoding、Places 與 Routes 測試時，才使用 `doctor --live`。
-Plugin **不會**啟動或註冊 MCP server。Codex 執行時先看到三個 Skill 的名稱與描述，只有請求符合時才載入完整指令：
+可以直接問：
-- `google-maps` — 地點搜尋、地址解析、路線、區域與環境資訊
-- `google-maps-travel-planning` — 單日與多日旅行行程
-- `google-maps-local-seo` — 商家能見度與地理排名分析
+> 規劃一個實際可行的京都兩日行程。把鄰近地點排在一起、檢查交通時間，並說明營業時間有哪些假設。
-完整的非 MCP 操作步驟見 [Agent Skill 示範](./examples/agent-skill-demo.md)。
+Codex 會依請求選擇一般地圖研究、旅行規劃或 Local SEO Skill。Plugin 不會註冊或啟動 MCP server。可參考[非 MCP 完整示範](./examples/agent-skill-demo.md)重現整個流程。
-### vs Google Grounding Lite
+## 使用獨立 CLI
-| | 本專案 | [Grounding Lite](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) |
-|---|---|---|
-| 工具數 | **18** | 3 |
-| 地理編碼 | 有 | 無 |
-| 逐步導航 | 有 | 無 |
-| 海拔查詢 | 有 | 無 |
-| 距離矩陣 | 有 | 無 |
-| 地點詳情 | 有 | 無 |
-| 時區查詢 | 有 | 無 |
-| 天氣查詢 | 有 | 有 |
-| 空氣品質 | 有 | 無 |
-| 地圖圖片 | 有 | 無 |
-| 組合工具（探索、規劃、比較） | 有 | 無 |
-| 開源 | MIT | 否 |
-| 自架部署 | 有 | 僅 Google 託管 |
-| Agent Skill | 有 | 無 |
-
-### CLI 與 server 快速檢查
+每一個 MCP 工具都有簡短的 CLI 名稱：
```bash
-# stdio（Claude Desktop、Cursor 等）
-npx @cablate/mcp-google-map --stdio
-
-# exec CLI — 不需啟動 server
-npx @cablate/mcp-google-map exec geocode '{"address":"台北101"}'
-
-# HTTP server
-npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
+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"}'
```
-## 特別感謝
-
-感謝 [@junyinnnn](https://github.com/junyinnnn) 協助實作 `streamablehttp` 支援。
-
-## 可用工具
+每次呼叫皆為無狀態。成功時在 stdout 回傳 `{ "success": true, "data": ... }`；失敗時以非零狀態結束，並在 stderr 輸出結構化 JSON。
-| 工具 | 說明 |
-|------|------|
-| `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 指標 |
+批次補全地址可使用：
-所有工具標註 `readOnlyHint: true` 和 `destructiveHint: false` — MCP 客戶端可自動核准，無需使用者確認。
-
-> **前置條件**：使用地點與路線相關工具前，請在 [Google Cloud Console](https://console.cloud.google.com) 啟用 **Places API (New)** 與 **Routes API**。
-
-## 安裝
-
-[最快開始](#最快開始codex-plugin)已說明 Codex Plugin。只有在你確定需要 MCP 時，才選擇下列其中一種設定。
+```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 -
+```
-### MCP stdio（本機 client 推薦）
+## 連接 MCP client
-適用於 Claude Desktop、Cursor、VS Code 及任何支援 stdio 的 MCP 客戶端：
+### stdio
```json
{
@@ -134,295 +103,83 @@ npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
"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 個工具（預設）。
+若要減少工具清單占用的上下文，可加入 `"GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"`。不設定或使用 `*` 即暴露全部工具。
### Streamable HTTP
-適用於多 session 部署、per-request API key 隔離或遠端存取：
-
```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 資訊
-
-- **傳輸方式**：stdio（`--stdio`）或 Streamable HTTP（預設）
-- **工具數**：18 個 Google Maps 工具（14 原子 + 4 組合）— 可透過 `GOOGLE_MAPS_ENABLED_TOOLS` 篩選
-
-### CLI Exec 模式（Agent Skill）
+只有 server 確實需要接受外部連線時才綁定 `0.0.0.0`。多租戶部署建議使用 `X-Google-Maps-API-Key` request header，讓不同 session 的 key 保持隔離。
-不啟動 MCP server，直接使用工具：
-
-```bash
-npx @cablate/mcp-google-map exec geocode '{"address":"台北101"}'
-npx @cablate/mcp-google-map exec search-places '{"query":"東京拉麵"}'
-```
+## 工具目錄
-全部 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/)。
+| 分類 | 工具 |
+|---|---|
+| 地點與探索 | `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、只用 Agent Skill**：
+全部 18 個工具都宣告 `readOnlyHint: true` 與 `destructiveHint: false`。完整參數、回應格式與工作流程範例見[工具參考](./skills/google-maps/references/tools-api.md)。
-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。
+## API key 與 Google Cloud 設定
-先執行 `npx -y @cablate/mcp-google-map doctor`，即可在不呼叫 Google API、不產生 API 費用的情況下檢查本機準備狀態。告知使用者測試請求可能產生 Google Maps Platform 費用後，可用 `doctor --live` 分別驗證 Geocoding、Places API (New) 與 Routes API。
+API key 所屬的 Google Cloud project 必須已啟用 billing，且 key restrictions 要與執行環境相容。[設定與診斷指南](./skills/_shared/setup-and-diagnostics.md)列出每項能力需要的 API，以及常見錯誤的處理方式。
-完整的非 MCP 操作步驟見 [Agent Skill 示範](./examples/agent-skill-demo.md)。若代理工具或應用程式會呈現 Places 評論、照片或 AI 摘要，請遵照[內容署名與保存指引](./skills/_shared/content-attribution.md)；工具會保留來源及揭露欄位，但不會替你的介面完成署名呈現。
+憑證優先順序如下：
-### 批次地理編碼
+1. `X-Google-Maps-API-Key` HTTP request header
+2. `--apikey` 命令列參數
+3. `GOOGLE_MAPS_API_KEY` 環境變數
-從檔案批次地理編碼：
+建議使用環境變數或 request header。命令列中的秘密可能出現在 shell 歷史或程序清單。
-```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
-
-
-
-
-
-[](https://star-history.dera.page/#cablate/mcp-google-map&Date)
+[MIT](./LICENSE)