@cablate/mcp-google-map 0.0.65 → 0.0.67

package/.codex-plugin/plugin.json

@@ -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.67",
+  "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

@@ -1,3 +1,13 @@
+# MCP Google Maps
+
+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.
+
+<p align="center"><b>English</b> | <a href="./README.zh-TW.md">繁體中文</a></p>
+
+<p align="center">
+  <img src="./assets/banner.webp" alt="MCP Google Maps — AI-Powered Geospatial Tools" 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>
@@ -6,22 +16,45 @@
 </p>
 
 <p align="center">
-  <img src="./assets/banner.webp" alt="MCP Google Maps — AI-Powered Geospatial Tools" width="800">
+  <img src="./assets/demo-grid-en.png" alt="Travel planning demo — Kyoto 2-day, Tokyo outdoor, Japan 5-day, Bangkok budget" width="800">
 </p>
 
-<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>
+- **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
 
-<p align="center">
-  <b>English</b> | <a href="./README.zh-TW.md">繁體中文</a>
-</p>
+## Choose how to use it
 
-<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>
+| If you want to… | Use | 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` |
+
+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.
+
+## Fastest start: Codex Plugin
+
+```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:
+
+```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.
+
+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:
+
+- `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
 
-- **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/))
+For a complete no-MCP walkthrough, see the [Agent Skill demo](./examples/agent-skill-demo.md).
 
 ### vs Google Grounding Lite
 
@@ -42,7 +75,7 @@
 | Self-hosted | Yes | Google-managed only |
 | Agent Skill | Yes | No |
 
-### Quick Start
+### CLI and server quick checks
 
 ```bash
 # stdio (Claude Desktop, Cursor, etc.)
@@ -89,24 +122,9 @@ All tools are annotated with `readOnlyHint: true` and `destructiveHint: false`
 
 ## Installation
 
-### Codex Plugin (3 Agent Skills, no MCP required)
-
-Install the CabLate marketplace, then install the Skill-only plugin:
-
-```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 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.
-
-At runtime, Codex sees the name and description of each Skill and loads the full instructions only when the request matches:
-
-- `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
+The [fastest-start section](#fastest-start-codex-plugin) covers the Codex Plugin. Use one of the following configurations when you specifically need MCP.
 
-### Method 1: stdio (Recommended for most clients)
+### MCP stdio (recommended for local clients)
 
 Works with Claude Desktop, Cursor, VS Code, and any MCP client that supports stdio:
 
@@ -137,7 +155,7 @@ Works with Claude Desktop, Cursor, VS Code, and any MCP client that supports std
 
 Omit or set to `*` for all 18 tools (default).
 
-### Method 2: HTTP Server
+### Streamable HTTP
 
 For multi-session deployments, per-request API key isolation, or remote access:
 

package/README.zh-TW.md

@@ -1,3 +1,13 @@
+# MCP Google Maps
+
+讓 AI 代理可靠地取得 Google Maps 地點搜尋、地址解析、路線、天氣、空氣品質與 Local SEO 資料。你可以安裝 Codex Plugin，讓代理直接呼叫 CLI；也可以透過 MCP 使用同一組 18 個工具。
+
+<p align="center"><a href="./README.md">English</a> | <b>繁體中文</b></p>
+
+<p align="center">
+  <img src="./assets/banner.webp" alt="MCP Google Maps — AI 驅動的地理空間工具" 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>
@@ -6,22 +16,45 @@
 </p>
 
 <p align="center">
-  <img src="./assets/banner.webp" alt="MCP Google Maps — AI 驅動的地理空間工具" width="800">
+  <img src="./assets/demo-grid-zh.png" alt="旅行規劃展示 — 京都二日遊、東京戶外一日、日本五日、曼谷背包客" width="800">
 </p>
 
-<h3 align="center"><b>讓你的 AI 代理理解真實世界 —<br>地理編碼、路線規劃、地點搜尋、空間推理。</b></h3>
+- **18 個工具** — 14 個原子工具與 4 個高階工作流程
+- **三種連接方式** — Codex Plugin、MCP stdio、Streamable HTTP
+- **三個用途明確的 Skills** — 一般地圖、旅行規劃、Local SEO
 
-<p align="center">
-  <a href="./README.md">English</a> | <b>繁體中文</b>
-</p>
+## 選擇使用方式
 
-<p align="center">
-  <img src="./assets/demo-grid-zh.png" alt="旅行規劃展示 — 京都二日遊、東京戶外一日、日本五日、曼谷背包客" width="800">
-</p>
+| 你的需求 | 建議方式 | 實際執行方式 |
+|---|---|---|
+| 讓 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` |
+
+三種方式都需要 Node.js 18+ 與 Google Maps Platform API key。地點與路線工作流程還要先在 [Google Cloud Console](https://console.cloud.google.com) 啟用 **Places API (New)** 與 **Routes API**。實際 API 請求可能產生 Google 費用。
+
+## 最快開始：Codex Plugin
+
+```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：
+
+```bash
+npx -y @cablate/mcp-google-map doctor
+```
+
+環境正確時，Node.js、套件與 API key 檢查會通過，`live-api` 會顯示略過。只有在你確定要送出可能計費的測試請求時，才使用 `doctor --live`。
 
-- **18 個工具** — 14 個原子工具 + 4 個組合工具（explore-area、plan-route、compare-places、local-rank-tracker）
-- **3 種模式** — stdio、StreamableHTTP、獨立 exec CLI
-- **3 個 Agent Skills** — 分別處理一般地圖、旅行規劃與 Local SEO（[`skills/`](./skills/)）
+Plugin **不會**啟動或註冊 MCP server。Codex 執行時先看到三個 Skill 的名稱與描述，只有請求符合時才載入完整指令：
+
+- `google-maps` — 地點搜尋、地址解析、路線、區域與環境資訊
+- `google-maps-travel-planning` — 單日與多日旅行行程
+- `google-maps-local-seo` — 商家能見度與地理排名分析
+
+完整的非 MCP 操作步驟見 [Agent Skill 示範](./examples/agent-skill-demo.md)。
 
 ### vs Google Grounding Lite
 
@@ -42,7 +75,7 @@
 | 自架部署 | 有 | 僅 Google 託管 |
 | Agent Skill | 有 | 無 |
 
-### 快速開始
+### CLI 與 server 快速檢查
 
 ```bash
 # stdio（Claude Desktop、Cursor 等）
@@ -85,28 +118,13 @@ npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
 
 所有工具標註 `readOnlyHint: true` 和 `destructiveHint: false` — MCP 客戶端可自動核准，無需使用者確認。
 
-> **前置條件**：使用地點相關工具前，請在 [Google Cloud Console](https://console.cloud.google.com) 啟用 **Places API (New)**。
+> **前置條件**：使用地點與路線相關工具前，請在 [Google Cloud Console](https://console.cloud.google.com) 啟用 **Places API (New)** 與 **Routes API**。
 
 ## 安裝
 
-### Codex Plugin（3 個 Agent Skills，不需要 MCP）
-
-先加入 CabLate marketplace，再安裝只包含 Skill 的 plugin：
-
-```bash
-codex plugin marketplace add cablate/mcp-google-map --ref main
-codex plugin add mcp-google-map@cablate
-```
-
-請在 Codex 可讀取的環境中設定 `GOOGLE_MAPS_API_KEY`，並確認已安裝 Node.js 18+ 與 `npx`，然後開啟新對話。Plugin 會探索三個用途明確的 Skills，並教代理直接執行 `npx -y @cablate/mcp-google-map exec ...`；它不會註冊或啟動 MCP server。下方的 MCP 設定仍是另一種獨立使用方式。
-
-執行階段會先看到每個 Skill 的名稱與描述，只有請求符合時才載入完整指令：
-
-- `google-maps` — 地點搜尋、地址解析、路線、區域與環境資訊
-- `google-maps-travel-planning` — 單日與多日旅行行程
-- `google-maps-local-seo` — Google 商家檔案能見度與地理排名分析
+[最快開始](#最快開始codex-plugin)已說明 Codex Plugin。只有在你確定需要 MCP 時，才選擇下列其中一種設定。
 
-### 方法一：stdio（大多數客戶端推薦）
+### MCP stdio（本機 client 推薦）
 
 適用於 Claude Desktop、Cursor、VS Code 及任何支援 stdio 的 MCP 客戶端：
 
@@ -137,7 +155,7 @@ codex plugin add mcp-google-map@cablate
 
 不設定或設為 `*` 即啟用全部 18 個工具（預設）。
 
-### 方法二：HTTP Server
+### Streamable HTTP
 
 適用於多 session 部署、per-request API key 隔離或遠端存取：
 

package/examples/agent-skill-demo.md

@@ -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

@@ -1,6 +1,6 @@
 {
   "name": "@cablate/mcp-google-map",
-  "version": "0.0.65",
+  "version": "0.0.67",
   "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

@@ -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.67",
+  "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"