mde-maps

mde-maps — Google Maps Platform

When NOT to use

• Generic GIS / spatial math with no Google Maps Platform APIs
• Mapbox-only or Leaflet/OpenStreetMap-only stacks (no GMP)
• Unrelated mapping tutorials or homework off the mdeai repo
• Non-mdeAI products—still read-only here; prefer not to expand scope in this skill

Load order (keep context small)

1. This SKILL.md — Quick routing table + Consolidated sibling note.
2. GMP doc questions — MCP Maps Code Assist first (§ Code Assist workflow below); then one references/*.md for the task.
3. One references/*.md file for implementation (do not bulk-load google-offline/ unless grepping mirrors).
4. references/all-apis.md only when running or editing gmaps.py batch CLI work.

Cursor rule: .cursor/rules/mdeai-google-maps.mdc · MCP setup: .cursor/MCP-GOOGLE-MAPS.md · Project: .mcp.json key google-maps-code-assist

---

Maps Code Assist MCP workflow

Official: developers.google.com/maps/ai/code-assist · Source: github/maps/platform-ai/ (GEMINI.md)

Use hosted HTTP only — https://mapscodeassist.googleapis.com/mcp. The npm package @googlemaps/code-assist-mcp is deprecated 2026-07-01 per platform-ai README.

Step	MCP tool	When
1	retrieve-instructions → { "name": "instructions" }	Always first for any map/places/routes/geocoding task
2	retrieve-google-maps-platform-docs → { "llmQuery", "filter?", "source": "mdeai-app" }	Concrete API/mask/vis.gl questions

Not for production runtime — no live search_places. For live geo tools use Grounding Lite (mapstools.googleapis.com) — references/maps-grounding.md § Mode 2.

Full setup: references/maps-ai-code-assist.md

---

Canonical github/maps/ clones (read-only)

Index: github/maps/README.md · Scores: index.md §4

Folder	Phase	mdeapp action
react-google-maps/	MVP	npm @vis.gl/react-google-maps — MAP-001
codelab-maps-platform-101-react-js/	MVP	AdvancedMarker + clusterer patterns
grounding-lite-mcp-sample-app/	MVP	MAP-002 Mastra grounding
js-markerclusterer/	MVP	npm @googlemaps/markerclusterer — MAP-009
js-api-samples/	All	Field masks, JS API samples
google-maps-services-js/	MVP+	Edge Places — MAP-004–005
platform-ai/	Dev	Code Assist MCP source only
ag-ui-adk-grounding-app/	Post-MVP	UX reference — not Mastra
react-wrapper/	—	Do not use (archived)

Never copy vendor src/ into mdeapp/ — read patterns, install npm packages.

Quick routing

Task	Go to
Architecture — how Places API + Grounding + Grounding Lite work together, decision tree, cost model, failure modes	references/architecture.md
Places offline exports — full-text Places / UI Kit / Contextual View (places-official/)	references/places-official/README.md
Places API (New) — official doc map, URLs, masks, Colombia rules (PLACES-002)	references/places-api-web-service.md
Places API (New) — @googlemaps/places examples (PLACES-005-010)	references/places-api-new.md
PRD / audit — Places API (New) v2.1 feature matrix + score (PLACES-002–081)	Repo: tasks/maps/maps-prd-v2.md, tasks/maps/places-api-new-audit.md
mdeAI — Gemini Maps grounding + red flags + GEO_PATTERNS (GROUNDING-001)	references/maps-grounding.md
mdeAI — ChatMap.tsx, AdvancedMarkerElement, pins	references/maps-js-api.md
Interactive — search_places, get_directions, show_on_map in Claude session	§ Interactive MCP tools below
CLI batch — geocoding, routes, weather, solar, 20+ APIs	references/all-apis.md
Security — API key architecture, HTML pages, embed iframes	references/security-and-optimization.md
Maps AI Code Assist MCP — RAG over official Maps docs (mapscodeassist.googleapis.com)	references/maps-ai-code-assist.md
Maps Grounding Lite MCP — live search_places / lookup_weather / compute_routes (mapstools.googleapis.com)	references/maps-grounding.md § Mode 2
Offline vendor page mirrors (references/google-offline/*.md) — grep / offline only; live docs + curated refs win on conflict	references/official-docs-mirror.md
Former google-maps skill — removed 2026-05-14 (last stub copy in _archive/2026-05-14/google-maps-stub/)	§ Interactive MCP tools below
Former google-maps-api skill — gmaps.py + operator rules	scripts/gmaps.py + references/gmaps-cli-behavior.md + references/all-apis.md
Former react-google-maps skill — @vis.gl/react-google-maps	references/react-vis-gl/README.md

Consolidated sibling skills (read once)

These top-level skills are thin stubs (or archived names) that point here — one maintenance surface for mdeai:

Symlink / folder	Role now
google-maps	Archived 2026-05-14 — skill folder removed; last SKILL.md under _archive/2026-05-14/google-maps-stub/.
google-maps-api	Redirect stub only; gmaps.py lives in mde-maps/scripts/ (vendor README/plugin → _archive/2026-05-14/google-maps-api-vendor/).
react-google-maps	Redirect only; vis.gl reference/*.md copied under references/react-vis-gl/.

---

Offline Google documentation (local mirror)

Google Maps / Grounding / MCP pages exported as Markdown live under references/google-offline/ — each file has YAML frontmatter (doc_type: google_offline_mirror). Use for local search and air-gapped reading; they are not authoritative.

• Index + conflict rules: references/official-docs-mirror.md
• Do not treat mirrors as SoT for billing, tool schemas, or launch gates — cross-check live developers.google.com and grounding-lite-mcp-sample-app when implementing GROUNDING-001 / 057 / 065.

---

mdeAI environment

VITE_GOOGLE_MAPS_API_KEY    — Frontend (browser) — Maps JS API, AdvancedMarkerElement
GOOGLE_PLACES_API_KEY       — Server-side only — Places API (New), enrichment scripts
GOOGLE_MAPS_API_KEY         — Edge functions — Directions, Routes
GOOGLE_ROUTES_API_KEY       — Edge functions — Routes API

Medellín anchor: { latitude: 6.2442, longitude: -75.5812 } — default locationBias center and Maps grounding latLng.

Never put GOOGLE_PLACES_API_KEY in a VITE_ var — visible in browser DevTools.

---

Interactive MCP tools

Use these when answering location questions in a Claude session (not for mdeAI production code). Tools call Google Maps APIs live.

Tools available

search_places(query, location?, radius?, type?, open_now?, language?)
  query     — text query ("restaurants in Laureles")
  location  — "lat,lng" center (optional)
  radius    — meters, max 50000 (optional)
  type      — place type filter ("restaurant", "tourist_attraction", "hotel")
  open_now  — boolean, default false
  language  — language code, default "en"

search_nearby_places(location, radius, keyword?, type?, rank_by?, open_now?, language?)
  location  — "lat,lng" (required)
  radius    — meters (required, max 50000)
  rank_by   — "prominence" (default) or "distance"

get_place_details(place_id, language?, reviews_sort?)
  place_id  — from search results
  reviews_sort — "most_relevant" (default) or "newest"

get_directions(origin, destination, mode?, alternatives?, avoid?, language?)
  mode      — "driving" (default), "walking", "bicycling", "transit"
  avoid     — "tolls", "highways", or "ferries"

geocode_address(address, language?, region?)
  region    — country code for regional bias

reverse_geocode(latlng, language?)
  latlng    — "lat,lng"

show_on_map(map_type, markers?, directions?, center?, zoom?)
  map_type  — "markers", "directions", or "area"
  markers   — array of {lat, lng} objects

Response pattern — Text → Map → Text

Always follow this sequence. Never call show_on_map in parallel with other calls.

1. Text — introduce what you'll show ("Here are top restaurants near Poblado:")
2. Map — call show_on_map to render results
3. Text — explain results in plain language (names, ratings, notes)

Multiple categories: sequential maps — events then restaurants, not parallel.

Never echo raw map_data JSON (coordinates, markers, zoom) in your text response. The map renders visually; describe places by name and quality only.

Intent → tool mapping

User says	Tool to use
"Where is X?"	geocode_address
"Find restaurants near..."	search_places or search_nearby_places
"What are the hours for...?"	get_place_details
"How do I get from A to B?"	get_directions
"What address is at these coords

---

Content truncated.