Skip to content

Preserve Places attribution metadata and refresh project trust guidance #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cablate merged 1 commit into from
Sep 16, 2026
Merged

Preserve Places attribution metadata and refresh project trust guidance #96

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,8 @@ To use the **Agent Skill without MCP**:

You can verify the CLI is available with `npx -y @cablate/mcp-google-map exec --help` before making a billable API call.

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/google-maps/references/content-attribution.md); the tool preserves source/disclosure metadata but does not render a compliant UI for you.

### Batch Geocode

Geocode hundreds of addresses from a file:
Expand Down
2 changes: 2 additions & 0 deletions README.zh-TW.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,8 @@ npx @cablate/mcp-google-map exec search-places '{"query":"東京拉麵"}'

呼叫可能計費的 API 前，可先用 `npx -y @cablate/mcp-google-map exec --help` 確認 CLI 可用。

完整的非 MCP 操作步驟見 [Agent Skill 示範](./examples/agent-skill-demo.md)。若代理工具或應用程式會呈現 Places 評論、照片或 AI 摘要，請遵照[內容署名與保存指引](./skills/google-maps/references/content-attribution.md)；工具會保留來源及揭露欄位，但不會替你的介面完成署名呈現。

### 批次地理編碼

從檔案批次地理編碼：
Expand Down
203 changes: 21 additions & 182 deletions docs/backlog-and-strategy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,191 +1,30 @@
# mcp-google-map Backlog & Strategy
# mcp-google-map backlog

> Consolidated: 2026-03-20
> Source: dev-roadmap-spec.md, strategy-todo.md, mcp-google-map-growth-strategy-2026.md (all retired)
> Current state: v0.0.44, 17 tools, ~192+ GitHub stars
This is a current maintenance and product roadmap, not a release-status ledger. For the current version and tool count, use [`package.json`](../package.json) and the [README](../README.md), not a number copied into this file. Earlier market-size claims, competitor counts, and growth forecasts were removed because they had no maintained evidence or expiry date; Git history retains them if historical context is needed.

This file contains ONLY items that have NOT been implemented and strategic insights that remain relevant. All completed items have been removed.
## Product quality and adoption

---
1. **Agent Skill onboarding evidence.** The [no-MCP walkthrough](../examples/agent-skill-demo.md) documents a reproducible CLI path. Test actual Skill discovery and tool selection in representative clients before claiming cross-client support. A short screen recording may then show the verified flow; do not substitute a staged transcript for an observed run.
2. **Geo-reasoning evaluation.** Start with a small set of versioned tasks that exercise tool selection, parameters, result interpretation, cost, and latency. Publish raw task definitions and evaluation criteria with any result; do not make an unsupported “tool vs no tool” success-rate claim.
3. **MCP prompt templates.** Consider travel planning, neighborhood scouting, and multi-stop routing templates only after checking which target MCP clients expose prompts to users. Reuse the existing Skill recipes where appropriate; avoid maintaining two divergent sets of instructions.
4. **Contributor feedback.** Collect reproducible user reports and installation friction before expanding the tool catalog. Existing tools cover geocoding, search, routes, environment data, maps, and four composite workflows.

## Backlog: Features
## Trust and maintenance

### MCP Prompt Templates (from dev-roadmap-spec P1)
- Keep Google Maps content display guidance aligned with the [Places API policies](https://developers.google.com/maps/documentation/places/web-service/policies), particularly attribution for reviews/photos, AI-summary disclosures, source links, and storage limits. The package is a data/tool layer; downstream applications still own their rendered UI, terms, and privacy notices.
- Triage production dependency advisories by affected path and exploit preconditions, then update compatible versions and verify build, tests, and live API behavior. An audit count alone is not proof of an exploitable path.
- Keep the packaged Agent Skill synchronized with its source using `python3 scripts/package-skill.py --check` in CI. Update its tool map and API reference whenever tools change.

**Status**: Not started | **Effort**: ~6hr
## Deferred ideas

MCP Prompts 讓 Claude Desktop / Cursor 使用者一鍵進入 geo agent 模式，不需要讀文件。
- **Isochrone approximation:** Google Maps Platform has no direct isochrone API in this project. An approximate polygon from distance-matrix probes needs a concrete user requirement and accuracy/cost bounds before implementation.
- **Geo-agent scaffold:** A separate starter template may be useful after the Skill onboarding study; first determine which setup steps are not already covered by the Skill and README.
- **Directory and content submissions:** Validate each directory's current submission path and requirements before spending maintainer time. Prefer a verified demo and honest capability claims over stale comparison tables.

```typescript
// 3 prompts to register in BaseMcpServer.ts:
{
name: "travel-planner",
description: "Plan a trip with geo tools",
arguments: [
{ name: "destination", required: true },
{ name: "duration", required: false },
{ name: "style", required: false } // budget, luxury, foodie
]
},
{
name: "neighborhood-scout",
description: "Analyze a location for living/working",
arguments: [
{ name: "location", required: true },
{ name: "priorities", required: false } // schools, transit, restaurants
]
},
{
name: "route-optimizer",
description: "Optimize a multi-stop route",
arguments: [
{ name: "stops", required: true },
{ name: "mode", required: false }
]
}
```
## Previously rejected

Implementation: `BaseMcpServer.ts` 加 `prompts` capability，Prompt 內容從 `tools-api.md` Scenario Recipes 提取。

### Geo-Reasoning Benchmark (from dev-roadmap-spec P2)

**Status**: Not started | **Effort**: Phase 1 ~2 weeks

10 scenarios (Easy 2 + Medium 3 + Hard 3 + Expert 2), 5 metrics (Tool Selection Accuracy, Parameter Correctness, Chain Efficiency, Result Quality, Latency).

Key metric — **Composite Tool Efficiency Score (CES)**:
```
CES = min_required_calls / actual_calls_made
```

Marketing angle: "Without geo tools: 4% success (MIT TravelPlanner). With mcp-google-map: 87%+"

Phase 1: 5 YAML scenarios + automated evaluator + README results table
Phase 2: 全 10 scenarios + LLM-as-Judge + multi-LLM comparison

### Geo Agent Scaffold (from strategy-todo Backlog)

**Status**: Not started | **Effort**: TBD

Pre-built agent prompt template — 「你是一個旅遊規劃專家，你有以下地理工具...」。讓人可以一行指令啟動 geo-aware AI agent。

### maps_isochrone (from dev-roadmap-spec P3)

**Status**: Deprioritized | **Effort**: ~8hr

Google 沒有 isochrone API。最佳路徑：Distance Matrix 8 方向探測 + static map 畫 approximated polygon。ROI 目前不夠，待有明確需求再做。

---

## Backlog: Growth & Marketing

### Pending Submissions (manual)

| Platform | Type | Status |
|---|---|---|
| pulsemcp.com | Web form | Not submitted |
| mcpservers.org | Web form | Not submitted |
| mcp.so | Web form | Not submitted |
| mcpmarket.com | Web form | Not submitted |
| mcpserverfinder.com | Web form | Not submitted |
| Cline Marketplace | PR to `cline/mcp-marketplace` | Not submitted |

### Content Marketing (not started)

| Item | Effort | Notes |
|---|---|---|
| Blog post / Dev.to article | Medium | "Why your AI agent needs geospatial capabilities" |
| Demo video (30-60 sec) | Medium | Screen recording of Claude Code + mcp-google-map trip planning |
| Twitter/X launch campaign | Low | Needs demo video first |
| HN "Show HN" post | Low | README ready, can execute anytime |

---

## Strategic Insights (still relevant)

### Competitive Positioning

**vs Google Grounding Lite (official MCP)**:
- Grounding Lite: 3 tools, managed hosting, no API key needed, experimental
- Us: 17 tools, self-hosted, full control, Agent Skill, exec CLI
- Key gaps they have that we don't: none anymore (we added weather, timezone, air quality)
- Key things we have that they don't: geocoding, directions, elevation, distance matrix, place details, batch geocode, composite tools, Agent Skill

**vs Mapbox MCP (315 stars)**:
- Mapbox: 20+ tools, offline Turf.js, TSP, Isochrone, separate Agent Skills repo
- Us: Google Maps API (larger user base), Skills embedded in npm package, exec CLI, MIT

**vs baidu-maps/mcp (411 stars)**:
- China market only, not direct competition internationally

### MCP + Agent Skills Ecosystem

- Agent Skills 已是跨平台標準（Claude Code, VS Code, OpenAI Codex, Cursor, Gemini CLI）
- AAIF (Linux Foundation): Anthropic, Google, Microsoft, OpenAI 共同治理
- Anthropic 的 anthropics/skills (92.9k stars) 目前沒有任何 geo/maps skill — 空白機會
- 我們的 `skills/google-maps/` 已 90% 符合 skillpm 格式
- PR #644 已提交到 anthropics/skills

### Geo-AI Market Signals

- Google "Ask Maps" (2026-03-12): Gemini 驅動的對話式地圖搜尋，驗證賽道
- MIT 研究：LLM 無 tool 輔助時旅行規劃成功率只有 ~4%
- 62% 年輕旅客已用 AI 工具做旅行規劃
- ChatGPT 沒有原生 Maps 整合 — MCP 填補空白
- UPS 每減少一英里/司機/天 = $50M/年 savings

### Our Moat (validated)

| Type | Advantage |
|---|---|
| Technical | StreamableHTTP multi-tenant, per-session API key, Tool Annotations |
| Design | Agent Skill (教 AI 怎麼思考地理問題), exec CLI, chaining patterns |
| Market | Google Maps category leader (192 vs #2 at 14), npm user base |

### High-Value Use Case Tiers (for marketing/positioning)

**Tier 1 (huge market + perfect tool coverage)**:
- Real estate analysis ($47T market)
- Logistics multi-stop optimization ($200B+)
- B2B field sales optimization
- E-commerce delivery estimation ($6.3T)

**Tier 2 (large market + good coverage)**:
- Data enrichment (CSV batch geocoding, $15B+)
- Disaster response ($30B+)
- Content creation (travel/city guides, $600B+)
- Accessible route planning (61M disabled users)

### README / Marketing Playbook

Key elements proven to work (from Figma 13.7k, Playwright 28.8k, Serena 21.5k analysis):
1. One-click install badges (Playwright) — already partially done
2. GitHub-native video demo (Serena) — NOT DONE
3. 3-bullet value proposition (Serena) — done in current README
4. Star History chart — done
5. vs comparison table (Playwright) — done (vs Grounding Lite)
6. GitHub alert boxes `[!TIP]` (Serena) — done

Still missing:
- Demo video (highest ROI remaining item)
- User testimonials / community feedback section

### Growth Projections (research-backed)

| Milestone | Timeline | Driver |
|---|---|---|
| 300+ stars | 2-4 weeks | Registry submissions + content |
| 500+ stars | 1-2 months | HN/Reddit + blog post |
| 1,000+ stars | 3-4 months | Sustained content + community |

Reference: HN front page averages +121 stars/24hr (median much lower). First 1000 is hardest, then organic discovery accelerates.

---

## Decided Not To Build

| Item | Reason | Source |
|---|---|---|
| maps_validate_address | $17/1000 too expensive, backend-only use case, geocode covers 60% | dev-roadmap-spec |
| Spatial Context / Memory | Claude conversation history already solves this, composite tools reduce chaining | dev-roadmap-spec |
| Language parameter for all tools | Existing behavior sufficient, deprioritized | strategy-todo |
| Idea | Reason to revisit only with new evidence |
|------|------------------------------------------|
| Address Validation tool | Separate pricing and a narrower use case than existing geocoding |
| Spatial memory layer | Would duplicate host-agent conversation state without a demonstrated gap |
| Language parameter on every tool | Broad API change without a validated user need |
39 changes: 39 additions & 0 deletions examples/agent-skill-demo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Agent Skill demo (no MCP server)

This walkthrough demonstrates the two pieces separately: the Agent Skill tells an agent which geographic 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 Skill so the instructions and executable stay aligned.

## 1. Install the Skill

Clone this repository at a chosen release tag, then copy the whole `skills/google-maps/` directory into your agent's Skills directory according to that client's instructions. Keep `SKILL.md` and `references/` together. If the client accepts `.skill` archives, import `skills/google-maps/SKILL.skill` instead. Installing npm alone does not register the Skill.

Check that your agent can discover `google-maps` and 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.

## 2. Validate without an API call

From the cloned repository, install and build the package, then run its CLI help:

```bash
npm ci
npm run build
node dist/cli.js exec --help
```

The help should list `geocode` and `search-places`. This only checks CLI availability; it does not prove that your key or Google APIs are enabled.

## 3. Try one live request

Ask your agent:

> Use the google-maps Skill, without MCP, to find the coordinates of Tokyo Tower. Tell me which tool you used and cite Google Maps as the data source.

The agent should select `maps_geocode` and run an `exec geocode` call from the same checkout like:

```bash
node dist/cli.js exec geocode '{"address":"Tokyo Tower"}'
```

Success means the CLI exits 0 and returns JSON with `success: true`, a `data.location` latitude/longitude, and a `data.place_id`. The exact coordinates and address may change; do not compare them to a hard-coded snapshot. A failed call exits nonzero and writes JSON to stderr. This step calls a billable Google API using your key.

For a published-package check from **outside** this repository, the equivalent command is `npx -y @cablate/mcp-google-map exec --help`. Running `npx` inside a checkout of the same package can resolve the local package instead of the published executable.

If you ask for place reviews, photos, or an AI summary in a later step, read the Skill's [content-attribution guidance](../skills/google-maps/references/content-attribution.md) before displaying them. This geocoding example does not validate every Google Maps Platform policy requirement for a downstream app.
Loading
Loading