feat: add maps_local_rank_tracker for local SEO grid ranking (#65)

* feat: add maps_local_rank_tracker — geographic grid rank tracking for local SEO

N×N grid search simulating LocalFalcon-style rank tracking. Searches the same
keyword from multiple coordinates around a center point, returns rank at each
grid point, top-3 competitors, and summary metrics (ARP, ATRP, SoLV).

Also removes output/ directory (unused drafts) and adds it to .gitignore.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style: fix prettier formatting

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: make exec air-quality test tolerant of service unavailability

Google Air Quality API occasionally returns "service unavailable" in CI.
Match the same tolerance pattern used by the MCP tool-call test.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cablate

.gitignore

@@ -4,4 +4,5 @@ credentials.json
 .env
 .agents/*
 .mcpregistry_*
-.mcp.json
+.mcp.json
+output/

README.md

@@ -19,15 +19,15 @@
   <img src="./assets/demo-grid-en.png" alt="Travel planning demo — Kyoto 2-day, Tokyo outdoor, Japan 5-day, Bangkok budget" width="800">
 </p>
 
-- **17 tools** — 14 atomic + 3 composite (explore-area, plan-route, compare-places)
+- **18 tools** — 14 atomic + 4 composite (explore-area, plan-route, compare-places, local-rank-tracker)
 - **3 modes** — stdio, StreamableHTTP, standalone exec CLI
 - **Agent Skill** — built-in skill definition teaches AI how to chain geo tools ([`skills/google-maps/`](./skills/google-maps/))
 
 ### vs Google Grounding Lite
 
 | | This project | [Grounding Lite](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) |
 |---|---|---|
-| Tools | **17** | 3 |
+| Tools | **18** | 3 |
 | Geocoding | Yes | No |
 | Step-by-step directions | Yes | No |
 | Elevation | Yes | No |
@@ -81,6 +81,7 @@ Special thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add sup
 | `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. |
 | `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. Returns rank at each point, top-3 competitors, and metrics (ARP, ATRP, SoLV). |
 
 All tools are annotated with `readOnlyHint: true` and `destructiveHint: false` — MCP clients can auto-approve these without user confirmation.
 
@@ -117,7 +118,7 @@ Works with Claude Desktop, Cursor, VS Code, and any MCP client that supports std
 }
 ```
 
-Omit or set to `*` for all 17 tools (default).
+Omit or set to `*` for all 18 tools (default).
 
 ### Method 2: HTTP Server
 
@@ -143,7 +144,7 @@ Then configure your MCP client:
 ### Server Information
 
 - **Transport**: stdio (`--stdio`) or Streamable HTTP (default)
-- **Tools**: 17 Google Maps tools (14 atomic + 3 composite) — filterable via `GOOGLE_MAPS_ENABLED_TOOLS`
+- **Tools**: 18 Google Maps tools (14 atomic + 4 composite) — filterable via `GOOGLE_MAPS_ENABLED_TOOLS`
 
 ### CLI Exec Mode (Agent Skill)
 
@@ -154,7 +155,7 @@ npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
 npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'
 ```
 
-All 17 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`. See [`skills/google-maps/`](./skills/google-maps/) for the agent skill definition and full parameter docs.
+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/google-maps/`](./skills/google-maps/) for the agent skill definition and full parameter docs.
 
 ### Batch Geocode
 
@@ -267,7 +268,8 @@ src/
 │       ├── 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)
+│       ├── 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)
@@ -322,6 +324,7 @@ For enterprise security reviews, see [Security Assessment Clarifications](./SECU
 | `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

README.zh-TW.md

@@ -19,15 +19,15 @@
   <img src="./assets/demo-grid-zh.png" alt="旅行規劃展示 — 京都二日遊、東京戶外一日、日本五日、曼谷背包客" width="800">
 </p>
 
-- **17 個工具** — 14 個原子工具 + 3 個組合工具（explore-area、plan-route、compare-places）
+- **18 個工具** — 14 個原子工具 + 4 個組合工具（explore-area、plan-route、compare-places、local-rank-tracker）
 - **3 種模式** — stdio、StreamableHTTP、獨立 exec CLI
 - **Agent Skill** — 內建技能定義，教 AI 如何串接地理工具（[`skills/google-maps/`](./skills/google-maps/)）
 
 ### vs Google Grounding Lite
 
 | | 本專案 | [Grounding Lite](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) |
 |---|---|---|
-| 工具數 | **17** | 3 |
+| 工具數 | **18** | 3 |
 | 地理編碼 | 有 | 無 |
 | 逐步導航 | 有 | 無 |
 | 海拔查詢 | 有 | 無 |
@@ -81,6 +81,7 @@ npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
 | `maps_explore_area` | 一次呼叫探索某地周邊 — 搜尋多種地點類型並取得詳情 |
 | `maps_plan_route` | 規劃最佳化多站路線 — 地理編碼、最佳順序、回傳導航 |
 | `maps_compare_places` | 並排比較地點 — 搜尋、取得詳情，可選計算距離 |
+| `maps_local_rank_tracker` | 地理網格排名追蹤（類似 LocalFalcon）— 追蹤商家在不同位置的搜尋排名，回傳 ARP、ATRP、SoLV 指標 |
 
 所有工具標註 `readOnlyHint: true` 和 `destructiveHint: false` — MCP 客戶端可自動核准，無需使用者確認。
 
@@ -117,7 +118,7 @@ npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
 }
 ```
 
-不設定或設為 `*` 即啟用全部 17 個工具（預設）。
+不設定或設為 `*` 即啟用全部 18 個工具（預設）。
 
 ### 方法二：HTTP Server
 
@@ -143,7 +144,7 @@ npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
 ### Server 資訊
 
 - **傳輸方式**：stdio（`--stdio`）或 Streamable HTTP（預設）
-- **工具數**：17 個 Google Maps 工具（14 原子 + 3 組合）— 可透過 `GOOGLE_MAPS_ENABLED_TOOLS` 篩選
+- **工具數**：18 個 Google Maps 工具（14 原子 + 4 組合）— 可透過 `GOOGLE_MAPS_ENABLED_TOOLS` 篩選
 
 ### CLI Exec 模式（Agent Skill）
 
@@ -154,7 +155,7 @@ npx @cablate/mcp-google-map exec geocode '{"address":"台北101"}'
 npx @cablate/mcp-google-map exec search-places '{"query":"東京拉麵"}'
 ```
 
-全部 17 個工具可用：`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`。完整參數文件見 [`skills/google-maps/`](./skills/google-maps/)。
+全部 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`。完整參數文件見 [`skills/google-maps/`](./skills/google-maps/)。
 
 ### 批次地理編碼
 
@@ -264,7 +265,8 @@ src/
 │       ├── searchAlongRoute.ts   # maps_search_along_route 工具
 │       ├── exploreArea.ts        # maps_explore_area（組合）
 │       ├── planRoute.ts          # maps_plan_route（組合）
-│       └── comparePlaces.ts      # maps_compare_places（組合）
+│       ├── comparePlaces.ts      # maps_compare_places（組合）
+│       └── localRankTracker.ts   # maps_local_rank_tracker（組合）
 └── utils/
     ├── apiKeyManager.ts          # API key 管理
     └── requestContext.ts         # Per-request context（API key 隔離）
@@ -318,6 +320,7 @@ skills/
 | `maps_explore_area` | 一次呼叫的社區概覽（組合工具） | **完成** |
 | `maps_plan_route` | 最佳化多站行程（組合工具） | **完成** |
 | `maps_compare_places` | 並排地點比較（組合工具） | **完成** |
+| `maps_local_rank_tracker` | 地理網格排名追蹤 — Local SEO 分析（組合工具） | **完成** |
 | `GOOGLE_MAPS_ENABLED_TOOLS` | 篩選工具以減少上下文用量 | **完成** |
 
 ### 計畫中