From 3e20870223a7995359a82fd96c489912ff721751 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Wed, 21 Jan 2026 10:31:15 -0800 Subject: [PATCH 1/6] feat: add Google Maps Platform Agent Skill (AgentSkills.io spec) - Create skill directory with SKILL.md following AgentSkills.io v1.0 spec - Add reference files for code examples, decision trees, EEA compliance, attribution - All code examples include required attribution ID: gmp_mcp_codeassist_v0.1_github - Bundle skills/ directory with npm package - Add skill installation instructions to README - Create BACKLOG.md with deprecation plan for retrieve-instructions tool (v1.0) Compatible with: Claude Code, Cursor, Windsurf, Roo Code, Gemini CLI, Codex --- packages/code-assist/BACKLOG.md | 37 ++ packages/code-assist/CHANGELOG.md | 16 + packages/code-assist/README.md | 51 ++ packages/code-assist/package.json | 3 +- .../skills/google-maps-platform/SKILL.md | 215 +++++++ .../references/attribution.md | 168 +++++ .../references/code-examples.md | 587 ++++++++++++++++++ .../references/decision-trees.md | 271 ++++++++ .../references/eea-compliance.md | 129 ++++ 9 files changed, 1476 insertions(+), 1 deletion(-) create mode 100644 packages/code-assist/BACKLOG.md create mode 100644 packages/code-assist/skills/google-maps-platform/SKILL.md create mode 100644 packages/code-assist/skills/google-maps-platform/references/attribution.md create mode 100644 packages/code-assist/skills/google-maps-platform/references/code-examples.md create mode 100644 packages/code-assist/skills/google-maps-platform/references/decision-trees.md create mode 100644 packages/code-assist/skills/google-maps-platform/references/eea-compliance.md diff --git a/packages/code-assist/BACKLOG.md b/packages/code-assist/BACKLOG.md new file mode 100644 index 0000000..4ee7ad8 --- /dev/null +++ b/packages/code-assist/BACKLOG.md @@ -0,0 +1,37 @@ +# Backlog + +Future work items and improvements for the Google Maps Platform Code Assist toolkit. + +## v1.0 Planned Changes + +### Tool Deprecation + +- [ ] **Remove `retrieve-instructions` tool** - The `retrieve-instructions` tool is deprecated in favor of the Agent Skill. For v1.0, this tool should be fully removed once the skill has been widely adopted and backward compatibility is no longer needed. + - **Rationale**: The Agent Skill (AgentSkills.io spec) embeds context directly into skill-aware agents, eliminating the need for an extra tool call before each query. + - **Migration Path**: Users should install the `google-maps-platform` skill from the `skills/` directory. + - **Tracking**: Monitor skill adoption through npm package downloads and skill registry listings. + +### MCP Server Updates + +- [ ] **Update `retrieve-google-maps-platform-docs` description** - Remove references to requiring `retrieve-instructions` first. +- [ ] **Simplify tool registration** - If `retrieve-instructions` is removed, simplify the tool registration logic. + +## Future Considerations + +### v0.2 (Post-Skill Release) + +- [ ] Add `scripts/` directory to skill for automated API key validation +- [ ] Create skill-specific prompts for different use cases (mobile, web, enterprise) + +### v0.3+ + +- [ ] Explore interactive skill commands (e.g., `/gmp-help` style) +- [ ] Add skill versioning support for multiple versions per tool +- [ ] Investigate dynamic skill updates (hot-reload without agent restart) +- [ ] Skill composition with other skills (e.g., Firebase skill) + +## Completed + +- [x] Create Agent Skill following AgentSkills.io specification (v0.x) +- [x] Bundle skill with npm package +- [x] Document skill installation in README diff --git a/packages/code-assist/CHANGELOG.md b/packages/code-assist/CHANGELOG.md index 52454dd..f525e4b 100644 --- a/packages/code-assist/CHANGELOG.md +++ b/packages/code-assist/CHANGELOG.md @@ -2,6 +2,22 @@ All notable changes to this project will be documented in this file. +## [Unreleased] + +### โœจ Features + +* **Agent Skill (AgentSkills.io):** Added a Google Maps Platform Agent Skill following the [AgentSkills.io](https://agentskills.io) specification. The skill embeds foundational context directly into skill-aware agents, reducing latency by eliminating the need for an extra `retrieve-instructions` tool call before each query. + * `skills/google-maps-platform/SKILL.md` - Core instructions with API selection guides, best practices, and production readiness checklist + * `skills/google-maps-platform/references/code-examples.md` - Platform-specific examples for Web, Android, iOS, and Flutter with proper attribution IDs + * `skills/google-maps-platform/references/decision-trees.md` - API selection flowcharts for Maps, Places, Routes, and Data Visualization + * `skills/google-maps-platform/references/eea-compliance.md` - EU Digital Markets Act requirements + * `skills/google-maps-platform/references/attribution.md` - Attribution ID integration guide +* **npm Package Update:** Skills directory is now bundled with the npm package for easy distribution. + +### ๐Ÿ“š Documentation + +* Added Agent Skill section to `README.md` with installation instructions for Claude Code, Cursor, Windsurf, and other skill-aware agents. + ## [0.1.7] - 2025-08-28 ### โœจ Features diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index 419f45d..8d6e5c0 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -59,6 +59,57 @@ The MCP server exposes the following tools for AI clients: ----- + +## Agent Skill (Optional) + +This package includes a **Google Maps Platform Agent Skill** following the [AgentSkills.io](https://agentskills.io) specification. Agent Skills embed foundational context directly into your agent, reducing latency and eliminating the need for an extra `retrieve-instructions` tool call before each query. + +### Benefits + +- **Reduced Latency**: Context is loaded at startup, not on every query +- **Improved Reliability**: Works even if the backend RAG service is slow or unavailable +- **Progressive Disclosure**: Only loads detailed reference files when needed +- **Cross-Platform**: Compatible with Claude Code, Cursor, Windsurf, Roo Code, Gemini CLI, and more + +### Skill Installation + +The skill is included in the `skills/` directory of this package. To install: + +**Claude Code:** +```bash +# Copy skill to Claude skills directory +cp -r $(npm root -g)/@googlemaps/code-assist-mcp/skills/google-maps-platform ~/.claude/skills/ +``` + +**Cursor / Windsurf / VS Code:** +Add to your workspace's `.cursor/skills/` or `.windsurf/skills/` directory: +```bash +cp -r node_modules/@googlemaps/code-assist-mcp/skills/google-maps-platform .cursor/skills/ +``` + +**Manual Installation:** +1. Download the skill from the npm package or GitHub repository +2. Place the `google-maps-platform/` folder in your agent's skills directory +3. The skill includes: + - `SKILL.md` - Core instructions and API selection guides + - `references/` - Detailed code examples, decision trees, and compliance info + +### Skill Contents + +| File | Description | +|------|-------------| +| `SKILL.md` | Core instructions, API selection tables, best practices | +| `references/code-examples.md` | Platform-specific examples (Web, Android, iOS, Flutter) | +| `references/decision-trees.md` | API selection flowcharts | +| `references/eea-compliance.md` | EU Digital Markets Act requirements | +| `references/attribution.md` | Attribution ID integration guide | + +> **Note:** The skill complements the MCP server - use both together for the best experience. The skill provides static context while the MCP server provides real-time documentation search. + + + +----- + ## Supported MCP Transports diff --git a/packages/code-assist/package.json b/packages/code-assist/package.json index 6b7e437..03865a6 100644 --- a/packages/code-assist/package.json +++ b/packages/code-assist/package.json @@ -8,7 +8,8 @@ "code-assist-mcp": "dist/index.js" }, "files": [ - "dist" + "dist", + "skills" ], "scripts": { "clean": "rm -rf dist", diff --git a/packages/code-assist/skills/google-maps-platform/SKILL.md b/packages/code-assist/skills/google-maps-platform/SKILL.md new file mode 100644 index 0000000..690cc04 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform/SKILL.md @@ -0,0 +1,215 @@ +--- +name: google-maps-platform +description: > + Expert assistant for Google Maps Platform APIs (Maps, Routes, Places). + Provides guidance on API selection, implementation patterns, pricing, + and best practices. Use the retrieve-google-maps-platform-docs tool + for documentation search. Covers Web, Android, iOS, and Flutter SDKs. +version: 0.1.0 +license: Apache-2.0 +author: Google Maps Platform +compatibility: + # Anthropic Tools + claude-code: ">=1.0.0" + roo-code: ">=3.0.0" + # IDE Extensions + cursor: ">=0.40.0" + windsurf: ">=1.0.0" + antigravity-ide: ">=1.0.0" + # Google Tools + gemini-cli: ">=1.0.0" + # OpenAI Tools + codex: ">=1.0.0" + # Generic AgentSkills.io Support + agentskills: ">=1.0.0" +metadata: + category: development + tags: + - google-maps + - geolocation + - maps + - routes + - places + - sdk + homepage: https://github.com/googlemaps/mcp-code-assist + documentation: https://developers.google.com/maps +allowed-tools: + - mcp--google-maps-platform-code-assist--retrieve-google-maps-platform-docs + - mcp--googleMapsMcp--search_places + - mcp--googleMapsMcp--compute_routes + - mcp--googleMapsMcp--lookup_weather +--- + +# Google Maps Platform Code Assist + +## Role & Mission + +You are an expert AI assistant specializing in Google Maps Platform development. Your mission is to help developers build production-ready applications by providing evidence-based, cost-effective, and developer-friendly guidance. + +**Key Directives:** +1. **Be Concise:** Keep explanations brief and code samples focused. +2. **Be Grounded:** Always verify information with official documentation. +3. **Be Iterative:** Use tools to explore and verify before providing a final answer. + +## Scope Boundary + +**ONLY** answer questions about Google Maps Platform (Maps, Routes, Places, Environment APIs). For off-topic requests, respond: +> "I specialize in Google Maps Platform development. I can help with Maps, Routes, Places, and Environment APIs. What would you like to build?" + +**Refusal Patterns:** +- **Off-topic**: Weather, traffic conditions, non-GMP topics โ†’ Redirect to GMP scope +- **Competitor comparison**: Mapbox, HERE, Apple Maps โ†’ "I can only provide guidance on Google Maps Platform APIs" +- **Illegal**: Scraping, bypassing quotas, unauthorized data collection โ†’ "I can't assist with that use case as it may violate the Terms of Service" +- **Ambiguous pricing**: "How much does it cost?" โ†’ Ask which API they're inquiring about + +## Core Principles + +1. **Strict Grounding**: Only use information from official GMP documentation. Always use `retrieve-google-maps-platform-docs` to ground answers. NEVER assume or infer facts not in retrieved context. +2. **Decomposition**: Break complex requests into surgical, specific search queries. +3. **Conciseness**: Provide solution-focused code. Avoid fluff. +4. **Modernity**: Use latest API features (e.g., `importLibrary`, `AdvancedMarkerElement`). + +**Negative Constraints:** +- **NO Legacy Loading:** Never use the deprecated ` +``` + +### REST API Requests + +Include the attribution as a query parameter or header: + +```javascript +// Using query parameter +const url = new URL("https://places.googleapis.com/v1/places:searchText"); +url.searchParams.set("key", API_KEY); +// Note: For REST APIs, attribution is typically tracked via the API key + +// Using custom header for internal tracking +fetch(url, { + method: "POST", + headers: { + "Content-Type": "application/json", + "X-Goog-Api-Key": API_KEY, + "X-Goog-FieldMask": "places.displayName,places.formattedAddress", + // Custom tracking header (if supported) + "X-Goog-Solution-Id": "gmp_mcp_codeassist_v0.1_github" + }, + body: JSON.stringify({ + textQuery: "restaurants in San Francisco" + }) +}); +``` + +### Android SDK + +```kotlin +// In your Application class or main activity +class MyApplication : Application() { + override fun onCreate() { + super.onCreate() + + // Initialize Places with attribution + Places.initializeWithNewPlacesApiEnabled( + this, + BuildConfig.MAPS_API_KEY + ) + + // Log attribution for analytics + Log.d("GMP", "Solution: gmp_mcp_codeassist_v0.1_github") + } +} +``` + +### iOS SDK + +```swift +// In your AppDelegate +import GoogleMaps +import GooglePlaces + +@main +class AppDelegate: UIResponder, UIApplicationDelegate { + func application( + _ application: UIApplication, + didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? + ) -> Bool { + // Initialize with API key + GMSServices.provideAPIKey("YOUR_API_KEY") + GMSPlacesClient.provideAPIKey("YOUR_API_KEY") + + // Attribution tracking + print("GMP Solution: gmp_mcp_codeassist_v0.1_github") + + return true + } +} +``` + +### Flutter + +```dart +// In your main.dart +import 'package:google_maps_flutter/google_maps_flutter.dart'; + +void main() { + // Initialize with attribution logging + debugPrint('GMP Solution: gmp_mcp_codeassist_v0.1_github'); + runApp(const MyApp()); +} +``` + +## Attribution ID Format + +The attribution ID follows this format: + +``` +gmp_mcp_codeassist_v{version}_{source} +``` + +| Component | Description | Example | +|-----------|-------------|---------| +| `gmp` | Google Maps Platform prefix | `gmp` | +| `mcp` | MCP server identifier | `mcp` | +| `codeassist` | Product name | `codeassist` | +| `v{version}` | Version number | `v0.1` | +| `{source}` | Distribution source | `github`, `npm` | + +## Version History + +| Version | Date | Notes | +|---------|------|-------| +| v0.1 | 2025-01 | Initial release | + +## Best Practices + +### DO: +- โœ… Include attribution in all generated code samples +- โœ… Use the exact attribution ID format +- โœ… Keep attribution IDs up to date with MCP server version +- โœ… Include attribution in comments if runtime inclusion isn't possible + +### DON'T: +- โŒ Modify the attribution ID format +- โŒ Remove attribution from generated code +- โŒ Use attribution IDs from other products +- โŒ Create custom attribution IDs without coordination + +## Verification + +To verify attribution is working: + +1. **Web**: Check Network tab in DevTools for `solutionChannel` parameter +2. **REST**: Verify headers/parameters in request logs +3. **Mobile**: Check console logs for attribution output + +## Related Documentation + +- [Google Maps Platform Attribution Requirements](https://developers.google.com/maps/documentation/javascript/overview#attribution_requirements) +- [Terms of Service](https://cloud.google.com/maps-platform/terms) diff --git a/packages/code-assist/skills/google-maps-platform/references/code-examples.md b/packages/code-assist/skills/google-maps-platform/references/code-examples.md new file mode 100644 index 0000000..1701003 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform/references/code-examples.md @@ -0,0 +1,587 @@ +# Code Examples Reference + +> **CRITICAL:** All code examples MUST include the attribution ID: `gmp_mcp_codeassist_v0.1_github` + +## Web (JavaScript) + +### Dynamic Library Import (REQUIRED Pattern) + +```html + + + + Google Maps Example + + + + + +
+ + + +``` + +**Key Points:** +- Dynamic loader script MUST come before any code that uses google.maps +- MUST include `internalUsageAttributionIds` parameter +- Use `AdvancedMarkerElement` (modern) instead of legacy `Marker` class +- `mapId` is REQUIRED for AdvancedMarkerElement +- Use `google.maps.importLibrary()` for loading specific libraries +- NEVER use legacy script tag: ` + + +``` + +**Key Points:** +- Use `v=beta` for 3D features +- `gmp-map-3d` web component handles initialization automatically +- `tilt`: 0-67.5 degrees (camera angle) +- `heading`: 0-360 degrees (compass direction) +- `range`: distance from center in meters + +### Web Components (gmp-map) + +```html + + + +``` + +### Places Autocomplete (New API) + +```javascript +async function initAutocomplete() { + const { Autocomplete } = await google.maps.importLibrary("places"); + + const input = document.getElementById("pac-input"); + const autocomplete = new Autocomplete(input, { + fields: ["place_id", "geometry", "formatted_address", "name"], + types: ["establishment"], + }); + + autocomplete.addListener("place_changed", () => { + const place = autocomplete.getPlace(); + if (!place.geometry) { + console.log("No geometry for this place"); + return; + } + console.log("Place:", place.name, place.formatted_address); + }); +} +``` + +### Routes API (REST) + +```javascript +async function getRoute(origin, destination) { + const response = await fetch( + "https://routes.googleapis.com/directions/v2:computeRoutes", + { + method: "POST", + headers: { + "Content-Type": "application/json", + "X-Goog-Api-Key": "YOUR_API_KEY", + "X-Goog-FieldMask": "routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline", + }, + body: JSON.stringify({ + origin: { address: origin }, + destination: { address: destination }, + travelMode: "DRIVE", + routingPreference: "TRAFFIC_AWARE", + }), + } + ); + return response.json(); +} +``` + +## React (@vis.gl/react-google-maps) + +### Basic Map with Marker + +```tsx +import { APIProvider, Map, AdvancedMarker } from '@vis.gl/react-google-maps'; + +function App() { + const position = { lat: 37.4220, lng: -122.0841 }; + + return ( + + + + + + ); +} +``` + +### With Places Autocomplete + +```tsx +import { useMapsLibrary } from '@vis.gl/react-google-maps'; +import { useEffect, useRef, useState } from 'react'; + +function PlaceAutocomplete({ onPlaceSelect }) { + const [placeAutocomplete, setPlaceAutocomplete] = useState(null); + const inputRef = useRef(null); + const places = useMapsLibrary('places'); + + useEffect(() => { + if (!places || !inputRef.current) return; + + const options = { + fields: ['geometry', 'name', 'formatted_address'], + }; + + setPlaceAutocomplete(new places.Autocomplete(inputRef.current, options)); + }, [places]); + + useEffect(() => { + if (!placeAutocomplete) return; + + placeAutocomplete.addListener('place_changed', () => { + onPlaceSelect(placeAutocomplete.getPlace()); + }); + }, [placeAutocomplete, onPlaceSelect]); + + return ; +} +``` + +## Android (Kotlin) + +### Jetpack Compose Map with Attribution + +```kotlin +// MainActivity.kt +package com.example.mapsdemo + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.layout.* +import androidx.compose.runtime.* +import androidx.compose.ui.Modifier +import com.google.android.gms.maps.model.CameraPosition +import com.google.android.gms.maps.model.LatLng +import com.google.maps.android.compose.* +import com.google.android.libraries.places.api.Places + +class MainActivity : ComponentActivity() { + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + + // CRITICAL: Initialize with attribution + Places.initialize(applicationContext, "YOUR_API_KEY") + Places.addInternalUsageAttributionId("gmp_mcp_codeassist_v0.1_github") // Attribution ID + MapsApiSettings.addInternalUsageAttributionId(this, "gmp_mcp_codeassist_v0.1_github") + + setContent { + MapScreen() + } + } +} + +@Composable +fun MapScreen() { + val singapore = LatLng(1.35, 103.87) + val cameraPositionState = rememberCameraPositionState { + position = CameraPosition.fromLatLngZoom(singapore, 10f) + } + + GoogleMap( + modifier = Modifier.fillMaxSize(), + cameraPositionState = cameraPositionState + ) { + Marker( + state = MarkerState(position = singapore), + title = "Singapore", + snippet = "Marker in Singapore" + ) + } +} + +/* +Add to build.gradle (Module: app): +dependencies { + implementation 'com.google.android.gms:play-services-maps:18.2.0' + implementation 'com.google.maps.android:maps-compose:4.3.0' + implementation 'com.google.android.libraries.places:places:3.3.0' +} + +Add to AndroidManifest.xml: + + + + + +*/ +``` + +**Key Points:** +- MUST call `addInternalUsageAttributionId` for both Places and Maps +- Use Jetpack Compose for modern Android UI +- Require location permissions in AndroidManifest.xml + +### Places SDK with Attribution + +```kotlin +// Initialize with attribution +Places.initialize(applicationContext, apiKey) +Places.addInternalUsageAttributionId("gmp_mcp_codeassist_v0.1_github") // Attribution ID + +val placesClient = Places.createClient(context) + +// Fetch place details with field mask +val placeFields = listOf(Place.Field.ID, Place.Field.NAME, Place.Field.ADDRESS) +val request = FetchPlaceRequest.newInstance(placeId, placeFields) + +placesClient.fetchPlace(request) + .addOnSuccessListener { response -> + val place = response.place + Log.i(TAG, "Place found: ${place.name}") + } + .addOnFailureListener { exception -> + Log.e(TAG, "Place not found: ${exception.message}") + } +``` + +## iOS (Swift) + +### SwiftUI Map with Attribution + +```swift +// AppDelegate.swift +import UIKit +import GoogleMaps +import GooglePlaces + +@main +class AppDelegate: UIResponder, UIApplicationDelegate { + func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { + // CRITICAL: Initialize with attribution + GMSServices.provideAPIKey("YOUR_API_KEY") + GMSServices.addInternalUsageAttributionID("gmp_mcp_codeassist_v0.1_github") // Attribution ID + GMSPlacesClient.provideAPIKey("YOUR_API_KEY") + GMSPlacesClient.addInternalUsageAttributionID("gmp_mcp_codeassist_v0.1_github") + return true + } +} + +// ContentView.swift +import SwiftUI +import GoogleMaps + +struct GoogleMapView: UIViewRepresentable { + @Binding var camera: GMSCameraPosition + + func makeUIView(context: Context) -> GMSMapView { + let options = GMSMapViewOptions() + options.camera = camera + let mapView = GMSMapView(options: options) + return mapView + } + + func updateUIView(_ mapView: GMSMapView, context: Context) { + mapView.animate(to: camera) + } +} + +struct ContentView: View { + @State private var camera = GMSCameraPosition.camera( + withLatitude: 37.4220, + longitude: -122.0841, + zoom: 14 + ) + + var body: some View { + GoogleMapView(camera: $camera) + .ignoresSafeArea() + } +} + +/* +Add to Podfile: +pod 'GoogleMaps' +pod 'GooglePlaces' + +Add to Info.plist: +GOOGLE_MAPS_API_KEY +YOUR_API_KEY +NSLocationWhenInUseUsageDescription +This app needs location access to show your position on the map. +*/ +``` + +**Key Points:** +- MUST call `addInternalUsageAttributionID` in AppDelegate for both Maps and Places +- Use SwiftUI for modern iOS development +- Require location permissions in Info.plist + +### Places SDK + +```swift +import GooglePlaces + +func fetchPlace(placeID: String) { + let placesClient = GMSPlacesClient.shared() + + let fields: GMSPlaceField = [.name, .formattedAddress, .coordinate] + + placesClient.fetchPlace( + fromPlaceID: placeID, + placeFields: fields, + sessionToken: nil + ) { place, error in + if let error = error { + print("Error: \(error.localizedDescription)") + return + } + + if let place = place { + print("Place: \(place.name ?? "Unknown")") + } + } +} +``` + +## Flutter (Dart) + +> **Note:** Flutter currently does not have a built-in method for setting attribution IDs. The attribution ID should be set on the native platform side (Android and iOS) as shown above. + +### Basic Map with Attribution (main.dart) + +```dart +import 'package:flutter/material.dart'; +import 'package:google_maps_flutter/google_maps_flutter.dart'; + +// main.dart +void main() { + // Note: Attribution is set natively - see Android/iOS platform setup below + runApp(MyApp()); +} + +class MyApp extends StatelessWidget { + @override + Widget build(BuildContext context) { + return MaterialApp( + title: 'Google Maps Demo', + home: MapScreen(), + ); + } +} + +class MapScreen extends StatefulWidget { + @override + _MapScreenState createState() => _MapScreenState(); +} + +class _MapScreenState extends State { + late GoogleMapController mapController; + + final LatLng _center = const LatLng(37.4220, -122.0841); + + void _onMapCreated(GoogleMapController controller) { + mapController = controller; + } + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('Google Maps')), + body: GoogleMap( + onMapCreated: _onMapCreated, + initialCameraPosition: CameraPosition( + target: _center, + zoom: 14.0, + ), + markers: { + Marker( + markerId: MarkerId('googleplex'), + position: _center, + infoWindow: InfoWindow(title: 'Googleplex'), + ), + }, + ), + ); + } +} +``` + +### Flutter Platform Setup for Attribution + +**Android (android/app/src/main/kotlin/.../MainActivity.kt):** +```kotlin +import com.google.android.libraries.places.api.Places + +class MainActivity: FlutterActivity() { + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + // CRITICAL: Set attribution ID for Flutter apps + Places.addInternalUsageAttributionId("gmp_mcp_codeassist_v0.1_github") + } +} +``` + +**iOS (ios/Runner/AppDelegate.swift):** +```swift +import GoogleMaps +import GooglePlaces + +@UIApplicationMain +class AppDelegate: FlutterAppDelegate { + override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { + // CRITICAL: Set attribution ID for Flutter apps + GMSServices.provideAPIKey("YOUR_API_KEY") + GMSServices.addInternalUsageAttributionID("gmp_mcp_codeassist_v0.1_github") + GMSPlacesClient.provideAPIKey("YOUR_API_KEY") + GMSPlacesClient.addInternalUsageAttributionID("gmp_mcp_codeassist_v0.1_github") + + GeneratedPluginRegistrant.register(with: self) + return super.application(application, didFinishLaunchingWithOptions: launchOptions) + } +} +``` + +**pubspec.yaml dependencies:** +```yaml +dependencies: + flutter: + sdk: flutter + google_maps_flutter: ^2.5.0 + google_places_flutter: ^2.0.0 +``` + +### Places Autocomplete + +```dart +import 'package:flutter/material.dart'; +import 'package:google_places_flutter/google_places_flutter.dart'; + +class PlaceSearch extends StatelessWidget { + final TextEditingController controller = TextEditingController(); + + @override + Widget build(BuildContext context) { + return GooglePlaceAutoCompleteTextField( + textEditingController: controller, + googleAPIKey: "YOUR_API_KEY", + inputDecoration: InputDecoration( + hintText: "Search for a place", + prefixIcon: Icon(Icons.search), + ), + getPlaceDetailWithLatLng: (prediction) { + print("Place: ${prediction.lat}, ${prediction.lng}"); + }, + itemClick: (prediction) { + controller.text = prediction.description ?? ""; + }, + ); + } +} +``` + +## Tool Usage Examples + +### Searching Documentation + +``` +User: "How do I add a marker to a map in React?" + +Tool Call: retrieve-google-maps-platform-docs +{ + "prompt": "How to add a marker to Google Maps in React using @vis.gl/react-google-maps library, AdvancedMarker component example", + "search_context": ["Maps JavaScript API", "React", "@vis.gl/react-google-maps"] +} +``` + +### Searching for Error Resolution + +``` +User: "I'm getting OVER_QUERY_LIMIT error" + +Tool Call: retrieve-google-maps-platform-docs +{ + "prompt": "OVER_QUERY_LIMIT error Google Maps Platform troubleshooting quota limits rate limiting", + "search_context": ["Google Maps Platform", "Quotas", "Error Handling"] +} +``` + +### Searching for Pricing Information + +``` +User: "How much does Places API cost?" + +Tool Call: retrieve-google-maps-platform-docs +{ + "prompt": "Places API New pricing cost per request SKU billing", + "search_context": ["Places API", "Pricing", "Billing"] +} +``` diff --git a/packages/code-assist/skills/google-maps-platform/references/decision-trees.md b/packages/code-assist/skills/google-maps-platform/references/decision-trees.md new file mode 100644 index 0000000..760119e --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform/references/decision-trees.md @@ -0,0 +1,271 @@ +# API Selection Decision Trees + +## Overview + +Use these decision trees to select the appropriate Google Maps Platform API for your use case. Always verify with the latest documentation via `retrieve-google-maps-platform-docs`. + +--- + +## Maps Display Decision Tree + +``` + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ Need to display a โ”‚ + โ”‚ map to users? โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ–ผ โ–ผ โ–ผ + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ Web โ”‚ โ”‚ Mobile โ”‚ โ”‚ Static โ”‚ + โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ + โ”‚ โ”‚ โ”‚ + โ–ผ โ”‚ โ–ผ + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ Maps JavaScriptโ”‚ โ”‚ โ”‚ Maps Static API โ”‚ + โ”‚ API โ”‚ โ”‚ โ”‚ (Image only) โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ โ”‚ + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ” + โ–ผ โ–ผ โ–ผ โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ React โ”‚ โ”‚Vanilla โ”‚ โ”‚Android โ”‚ โ”‚ iOS โ”‚ +โ”‚ App โ”‚ โ”‚ JS โ”‚ โ”‚ App โ”‚ โ”‚ App โ”‚ +โ””โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ + โ”‚ โ”‚ โ”‚ โ”‚ + โ–ผ โ–ผ โ–ผ โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚@vis.gl/ โ”‚โ”‚Dynamic โ”‚โ”‚Maps SDK โ”‚โ”‚Maps SDK โ”‚ +โ”‚react-google-โ”‚โ”‚Library โ”‚โ”‚ for โ”‚โ”‚ for โ”‚ +โ”‚maps โ”‚โ”‚Import โ”‚โ”‚Android โ”‚โ”‚ iOS โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Web Map Selection + +| Requirement | Recommended Solution | +|-------------|---------------------| +| Interactive map with markers | Maps JavaScript API + AdvancedMarkerElement | +| React application | @vis.gl/react-google-maps | +| Angular application | @angular/google-maps | +| Vue application | @fawmi/vue-google-maps or google-maps-loader | +| Custom data visualization | Deck.gl + Maps JavaScript API | +| 3D map experience | Maps JavaScript API with WebGL overlays | +| Simple embed (no code) | Maps Embed API | +| Static image (email, PDF) | Maps Static API | + +### Mobile Map Selection + +| Platform | Primary SDK | Alternative | +|----------|-------------|-------------| +| Android (Kotlin/Java) | Maps SDK for Android | Maps Compose library | +| Android (Jetpack Compose) | Maps Compose | - | +| iOS (Swift) | Maps SDK for iOS | SwiftUI wrapper | +| iOS (SwiftUI) | Maps SDK for iOS | - | +| Flutter | google_maps_flutter | - | +| React Native | react-native-maps | - | + +--- + +## Places API Decision Tree + +``` + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ What do you need โ”‚ + โ”‚ to do with places? โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ–ผ โ–ผ โ–ผ โ–ผ โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚Search โ”‚ โ”‚Autocom- โ”‚ โ”‚Get โ”‚ โ”‚Find โ”‚ โ”‚Get โ”‚ +โ”‚by text โ”‚ โ”‚plete โ”‚ โ”‚details โ”‚ โ”‚nearby โ”‚ โ”‚photos โ”‚ +โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ + โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ + โ–ผ โ–ผ โ–ผ โ–ผ โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Places API (New) โ”‚ +โ”‚ places.googleapis.com โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Places API Endpoints + +| Use Case | Endpoint (New API) | Key Features | +|----------|-------------------|--------------| +| Text search | `searchText` | Natural language queries | +| Nearby search | `searchNearby` | Location + radius + type | +| Place details | `places/{placeId}` | Field masks for cost optimization | +| Autocomplete | `places:autocomplete` | Session tokens reduce cost | +| Place photos | `places/{placeId}/photos/{name}/media` | Max dimensions supported | + +### Field Mask Best Practices + +Always use field masks to request only needed data: + +```javascript +// โŒ Expensive - fetches all fields +const response = await fetch(`https://places.googleapis.com/v1/places/${placeId}`, { + headers: { + "X-Goog-Api-Key": API_KEY, + "X-Goog-FieldMask": "*" // Don't do this! + } +}); + +// โœ… Cost-effective - only needed fields +const response = await fetch(`https://places.googleapis.com/v1/places/${placeId}`, { + headers: { + "X-Goog-Api-Key": API_KEY, + "X-Goog-FieldMask": "displayName,formattedAddress,location" + } +}); +``` + +--- + +## Routes API Decision Tree + +``` + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ What routing need โ”‚ + โ”‚ do you have? โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ–ผ โ–ผ โ–ผ โ–ผ โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚Simple โ”‚ โ”‚Distance โ”‚ โ”‚Multi- โ”‚ โ”‚Turn-by- โ”‚ โ”‚Fleet โ”‚ +โ”‚Aโ†’B routeโ”‚ โ”‚matrix โ”‚ โ”‚stop โ”‚ โ”‚turn nav โ”‚ โ”‚routing โ”‚ +โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ + โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ + โ–ผ โ–ผ โ–ผ โ–ผ โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚Routes โ”‚ โ”‚Routes โ”‚ โ”‚Routes โ”‚ โ”‚Navigationโ”‚ โ”‚Route โ”‚ +โ”‚API โ”‚ โ”‚API โ”‚ โ”‚API or โ”‚ โ”‚SDK โ”‚ โ”‚Optim. โ”‚ +โ”‚compute โ”‚ โ”‚compute โ”‚ โ”‚Route โ”‚ โ”‚(mobile) โ”‚ โ”‚API โ”‚ +โ”‚Routes โ”‚ โ”‚RouteMatrixโ”‚ โ”‚Optim. โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Routes API Selection Guide + +| Use Case | API/Endpoint | Notes | +|----------|--------------|-------| +| Single route Aโ†’B | Routes API `computeRoutes` | Supports waypoints, traffic | +| Multiple origins/destinations | Routes API `computeRouteMatrix` | Up to 625 elements | +| Route optimization (TSP) | Route Optimization API | Optimizes waypoint order | +| Turn-by-turn navigation | Navigation SDK | Mobile only (Android/iOS) | +| Fleet management | Fleet Engine | Requires additional setup | + +### Travel Modes + +| Mode | Routes API Value | Notes | +|------|-----------------|-------| +| Driving | `DRIVE` | Default, includes traffic | +| Walking | `WALK` | Pedestrian paths | +| Bicycling | `BICYCLE` | Bike lanes preferred | +| Transit | `TRANSIT` | Public transportation | +| Two-wheelers | `TWO_WHEELER` | Motorcycles, scooters | + +--- + +## Data Visualization Decision Tree + +``` + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ What type of data โ”‚ + โ”‚ visualization needed? โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ–ผ โ–ผ โ–ผ โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚Markers โ”‚ โ”‚Heatmaps โ”‚ โ”‚Polygons/โ”‚ โ”‚Custom โ”‚ +โ”‚(< 1000) โ”‚ โ”‚ โ”‚ โ”‚Lines โ”‚ โ”‚overlays โ”‚ +โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ + โ”‚ โ”‚ โ”‚ โ”‚ + โ–ผ โ–ผ โ–ผ โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚Advanced โ”‚ โ”‚Heatmap โ”‚ โ”‚Data โ”‚ โ”‚Deck.gl โ”‚ +โ”‚Marker โ”‚ โ”‚Layer โ”‚ โ”‚Layer โ”‚ โ”‚+ Maps โ”‚ +โ”‚Element โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚JS API โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Visualization Library Selection + +| Data Volume | Visualization Type | Recommended Approach | +|-------------|-------------------|---------------------| +| < 100 markers | Standard markers | AdvancedMarkerElement | +| 100-1000 markers | Clustered markers | MarkerClusterer library | +| > 1000 points | Aggregated view | Heatmap Layer | +| > 10000 points | WebGL rendering | Deck.gl overlay | +| Polygons/shapes | Geographic boundaries | Data Layer | +| Real-time updates | Streaming data | Custom WebGL overlay | + +--- + +## Migration Decision Tree + +``` + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ Using deprecated โ”‚ + โ”‚ APIs? โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ–ผ โ–ผ โ–ผ โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚google. โ”‚ โ”‚Places โ”‚ โ”‚Directionsโ”‚ โ”‚Distance โ”‚ +โ”‚maps. โ”‚ โ”‚API โ”‚ โ”‚Service โ”‚ โ”‚Matrix โ”‚ +โ”‚Marker โ”‚ โ”‚(Legacy) โ”‚ โ”‚ โ”‚ โ”‚Service โ”‚ +โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ + โ”‚ โ”‚ โ”‚ โ”‚ + โ–ผ โ–ผ โ–ผ โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚Advanced โ”‚ โ”‚Places โ”‚ โ”‚Routes โ”‚ โ”‚Routes โ”‚ +โ”‚Marker โ”‚ โ”‚API โ”‚ โ”‚API โ”‚ โ”‚API โ”‚ +โ”‚Element โ”‚ โ”‚(New) โ”‚ โ”‚compute โ”‚ โ”‚compute โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚Routes โ”‚ โ”‚RouteMatrixโ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Migration Priority + +| Legacy API | Modern Replacement | Migration Priority | +|------------|-------------------|-------------------| +| `google.maps.Marker` | `AdvancedMarkerElement` | **High** - Deprecated | +| Places API (Legacy) | Places API (New) | **High** - New features | +| Directions Service | Routes API | **Medium** - Better performance | +| Distance Matrix Service | Routes API `computeRouteMatrix` | **Medium** | +| Geocoding Service | Geocoding API (REST) | **Low** - Still supported | + +--- + +## Quick Selection Matrix + +### By Use Case + +| I want to... | Use this API | +|--------------|-------------| +| Show a map on a website | Maps JavaScript API | +| Show a map in a mobile app | Maps SDK (Android/iOS) | +| Search for places by name | Places API (New) - Text Search | +| Get place suggestions as user types | Places API (New) - Autocomplete | +| Get directions between points | Routes API | +| Calculate distances for multiple pairs | Routes API - computeRouteMatrix | +| Convert address to coordinates | Geocoding API | +| Convert coordinates to address | Geocoding API (reverse) | +| Get a static map image | Maps Static API | +| Validate an address | Address Validation API | + +### By Platform + Use Case + +| Platform | Map Display | Places | Routes | +|----------|-------------|--------|--------| +| Web (Vanilla JS) | Maps JS API | Places JS Library | Routes API (REST) | +| Web (React) | @vis.gl/react-google-maps | Places JS Library | Routes API (REST) | +| Android | Maps SDK | Places SDK | Routes API (REST) | +| iOS | Maps SDK | Places SDK | Routes API (REST) | +| Flutter | google_maps_flutter | google_places_flutter | Routes API (REST) | +| Server-side | N/A | Places API (REST) | Routes API (REST) | diff --git a/packages/code-assist/skills/google-maps-platform/references/eea-compliance.md b/packages/code-assist/skills/google-maps-platform/references/eea-compliance.md new file mode 100644 index 0000000..01d2c7e --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform/references/eea-compliance.md @@ -0,0 +1,129 @@ +# EEA Compliance Reference + +## European Economic Area (EEA) Terms of Service + +If a Customer's billing account address is in the European Economic Area, the Google Maps Platform EEA Terms of Service govern Customer's access to and use of Google Maps Platform Services. + +**Official Terms:** https://cloud.google.com/terms/maps-platform/eea/maps-service-terms + +## EEA Member States + +The EEA is composed of all European Union (EU) member states plus Iceland, Liechtenstein, and Norway: + +| Country | Flag | Status | +|---------|------|--------| +| Austria | ๐Ÿ‡ฆ๐Ÿ‡น | EU Member | +| Belgium | ๐Ÿ‡ง๐Ÿ‡ช | EU Member | +| Bulgaria | ๐Ÿ‡ง๐Ÿ‡ฌ | EU Member | +| Croatia | ๐Ÿ‡ญ๐Ÿ‡ท | EU Member | +| Cyprus | ๐Ÿ‡จ๐Ÿ‡พ | EU Member | +| Czech Republic | ๐Ÿ‡จ๐Ÿ‡ฟ | EU Member | +| Denmark | ๐Ÿ‡ฉ๐Ÿ‡ฐ | EU Member | +| Estonia | ๐Ÿ‡ช๐Ÿ‡ช | EU Member | +| Finland | ๐Ÿ‡ซ๐Ÿ‡ฎ | EU Member | +| France | ๐Ÿ‡ซ๐Ÿ‡ท | EU Member | +| Germany | ๐Ÿ‡ฉ๐Ÿ‡ช | EU Member | +| Greece | ๐Ÿ‡ฌ๐Ÿ‡ท | EU Member | +| Hungary | ๐Ÿ‡ญ๐Ÿ‡บ | EU Member | +| Ireland | ๐Ÿ‡ฎ๐Ÿ‡ช | EU Member | +| Italy | ๐Ÿ‡ฎ๐Ÿ‡น | EU Member | +| Latvia | ๐Ÿ‡ฑ๐Ÿ‡ป | EU Member | +| Lithuania | ๐Ÿ‡ฑ๐Ÿ‡น | EU Member | +| Luxembourg | ๐Ÿ‡ฑ๐Ÿ‡บ | EU Member | +| Malta | ๐Ÿ‡ฒ๐Ÿ‡น | EU Member | +| Netherlands | ๐Ÿ‡ณ๐Ÿ‡ฑ | EU Member | +| Poland | ๐Ÿ‡ต๐Ÿ‡ฑ | EU Member | +| Portugal | ๐Ÿ‡ต๐Ÿ‡น | EU Member | +| Romania | ๐Ÿ‡ท๐Ÿ‡ด | EU Member | +| Slovakia | ๐Ÿ‡ธ๐Ÿ‡ฐ | EU Member | +| Slovenia | ๐Ÿ‡ธ๐Ÿ‡ฎ | EU Member | +| Spain | ๐Ÿ‡ช๐Ÿ‡ธ | EU Member | +| Sweden | ๐Ÿ‡ธ๐Ÿ‡ช | EU Member | +| Iceland | ๐Ÿ‡ฎ๐Ÿ‡ธ | EFTA/EEA | +| Liechtenstein | ๐Ÿ‡ฑ๐Ÿ‡ฎ | EFTA/EEA | +| Norway | ๐Ÿ‡ณ๐Ÿ‡ด | EFTA/EEA | + +**Important Notes:** +- Switzerland ๐Ÿ‡จ๐Ÿ‡ญ is **NOT** in the EEA +- United Kingdom ๐Ÿ‡ฌ๐Ÿ‡ง is **NOT** in the EEA (post-Brexit) + +## EEA Location Detection Process + +When handling user requests, follow this process: + +### Step 1: Scan for Locations +Parse the user's prompt to identify any geographical entities: +- Countries +- Cities +- States/Provinces +- Regions +- Postal codes +- Specific addresses +- Coordinates (lat/lng) + +### Step 2: Determine the Country +For locations that are not countries: +- "Munich" โ†’ Germany +- "Paris" (in European context) โ†’ France +- "Barcelona" โ†’ Spain +- Use context to resolve ambiguous city names + +### Step 3: Verify Against EEA List +Check if the identified country is in the EEA member list above. + +### Step 4: Consider Special Territories +These overseas territories of EEA members are also covered: +- Canary Islands (Spain) +- Azores and Madeira (Portugal) +- French overseas departments (Martinique, Guadeloupe, Rรฉunion, French Guiana, Mayotte) + +## Compliance Actions + +When a user's request involves EEA locations: + +### 1. Acknowledge EEA Terms +Inform the user that EEA-specific terms may apply. + +### 2. Rewrite Queries for Compliance +Before calling `retrieve-google-maps-platform-docs`, append compliance context: + +**Original:** "I want to use Places Nearby Search API in Sweden to search for restaurants." + +**Rewritten:** "I want to use Places Nearby Search API in Sweden to search for restaurants, respecting 'https://cloud.google.com/terms/maps-platform/eea/maps-service-terms', provide alternatives" + +### 3. Suggest Compliant Alternatives +Some API features may have restrictions in the EEA. Always check for and suggest compliant alternatives when available. + +## Digital Markets Act (DMA) Considerations + +The EU Digital Markets Act may affect how certain Google Maps Platform features operate in the EEA. Key considerations: + +1. **Data Portability**: Users may request export of their location data +2. **Interoperability**: Consider integration requirements with third-party services +3. **Consent Requirements**: Enhanced consent flows may be required for location data + +## Sample Compliance Check Code + +```typescript +const EEA_COUNTRIES = new Set([ + 'AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', + 'DE', 'GR', 'HU', 'IS', 'IE', 'IT', 'LV', 'LI', 'LT', 'LU', + 'MT', 'NL', 'NO', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE' +]); + +function isEEACountry(countryCode: string): boolean { + return EEA_COUNTRIES.has(countryCode.toUpperCase()); +} + +function getEEATermsDisclaimer(): string { + return `If your billing account is in the EEA, the Google Maps Platform +EEA Terms of Service apply. See: +https://cloud.google.com/terms/maps-platform/eea/maps-service-terms`; +} +``` + +## Related Documentation + +- [Google Maps Platform Terms of Service](https://cloud.google.com/maps-platform/terms) +- [EEA Service-Specific Terms](https://cloud.google.com/terms/maps-platform/eea/maps-service-terms) +- [Google Cloud Geographic Terms](https://cloud.google.com/terms/maps-platform/eea) From 45177b0a94ea4da71338b28cc76513f8f8ce6a69 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Wed, 21 Jan 2026 10:38:00 -0800 Subject: [PATCH 2/6] improve install instructions for Skills using Gemini CLI --- packages/code-assist/README.md | 51 ++++++++++++++++++++++++++++++---- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index 8d6e5c0..91ec25a 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -73,23 +73,62 @@ This package includes a **Google Maps Platform Agent Skill** following the [Agen ### Skill Installation -The skill is included in the `skills/` directory of this package. To install: +The skill is included in the `skills/` directory of this package. Choose your preferred installation method: + +#### Gemini CLI (Recommended) + +Install directly from GitHub using the `gemini skills install` command: + +```bash +# Install to user scope (~/.gemini/skills) - available across all workspaces +gemini skills install https://github.com/googlemaps/google-maps-platform-ai.git \ + --path packages/code-assist/skills/google-maps-platform + +# Or install to workspace scope (.gemini/skills) - project-specific +gemini skills install https://github.com/googlemaps/google-maps-platform-ai.git \ + --path packages/code-assist/skills/google-maps-platform \ + --scope workspace +``` + +After installation, verify with: +```bash +gemini skills list +``` + +#### npm + Gemini CLI + +If you have the npm package installed, point Gemini CLI to the local skill: + +```bash +# Install the npm package first +npm install @googlemaps/code-assist-mcp + +# Then install the skill from node_modules +gemini skills install ./node_modules/@googlemaps/code-assist-mcp/skills/google-maps-platform +``` + +#### Claude Code -**Claude Code:** ```bash # Copy skill to Claude skills directory cp -r $(npm root -g)/@googlemaps/code-assist-mcp/skills/google-maps-platform ~/.claude/skills/ ``` -**Cursor / Windsurf / VS Code:** +#### Cursor / Windsurf / VS Code + Add to your workspace's `.cursor/skills/` or `.windsurf/skills/` directory: ```bash cp -r node_modules/@googlemaps/code-assist-mcp/skills/google-maps-platform .cursor/skills/ ``` -**Manual Installation:** -1. Download the skill from the npm package or GitHub repository -2. Place the `google-maps-platform/` folder in your agent's skills directory +#### Manual Installation + +1. Download the skill from the [npm package](https://www.npmjs.com/package/@googlemaps/code-assist-mcp) or [GitHub repository](https://github.com/googlemaps/google-maps-platform-ai) +2. Place the `google-maps-platform/` folder in your agent's skills directory: + - **Gemini CLI**: `~/.gemini/skills/` (user) or `.gemini/skills/` (workspace) + - **Claude Code**: `~/.claude/skills/` + - **Cursor**: `.cursor/skills/` + - **Windsurf**: `.windsurf/skills/` 3. The skill includes: - `SKILL.md` - Core instructions and API selection guides - `references/` - Detailed code examples, decision trees, and compliance info From 188d7efaff829484a27e26a4d24e38f3ccf63c35 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Sat, 31 Jan 2026 09:53:30 -0800 Subject: [PATCH 3/6] feat: add google-maps-platform-dev skill and remove old version --- packages/code-assist/PLAN.md | 461 ++++++++++++ packages/code-assist/README.md | 26 +- .../skills/google-maps-platform-dev/SKILL.md | 251 +++++++ .../references/attribution.md | 0 .../references/capabilities-mapping.md | 30 + .../references/cross-platform.md | 54 ++ .../references/decision-trees.md | 0 .../references/eea-compliance.md | 18 + .../references/environment-apis.md | 57 ++ .../references/maps-grounding.md | 76 ++ .../references/places-overview.md | 86 +++ .../references/places-ui-kit.md | 655 ++++++++++++++++++ .../references/products-overview.md | 58 ++ .../references/routes-navigation.md | 70 ++ .../resources/getting-started.md | 97 +++ .../resources/mcp-guide.md | 49 ++ .../resources/platform-android-compose.md | 90 +++ .../resources/platform-ios-swiftui.md | 102 +++ .../resources/platform-react.md | 117 ++++ .../skills/google-maps-platform/SKILL.md | 215 ------ .../references/code-examples.md | 587 ---------------- 21 files changed, 2295 insertions(+), 804 deletions(-) create mode 100644 packages/code-assist/PLAN.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/SKILL.md rename packages/code-assist/skills/{google-maps-platform => google-maps-platform-dev}/references/attribution.md (100%) create mode 100644 packages/code-assist/skills/google-maps-platform-dev/references/capabilities-mapping.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/references/cross-platform.md rename packages/code-assist/skills/{google-maps-platform => google-maps-platform-dev}/references/decision-trees.md (100%) rename packages/code-assist/skills/{google-maps-platform => google-maps-platform-dev}/references/eea-compliance.md (86%) create mode 100644 packages/code-assist/skills/google-maps-platform-dev/references/environment-apis.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/references/maps-grounding.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/references/places-overview.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/references/places-ui-kit.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/references/products-overview.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/references/routes-navigation.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/resources/getting-started.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/resources/mcp-guide.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/resources/platform-android-compose.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/resources/platform-ios-swiftui.md create mode 100644 packages/code-assist/skills/google-maps-platform-dev/resources/platform-react.md delete mode 100644 packages/code-assist/skills/google-maps-platform/SKILL.md delete mode 100644 packages/code-assist/skills/google-maps-platform/references/code-examples.md diff --git a/packages/code-assist/PLAN.md b/packages/code-assist/PLAN.md new file mode 100644 index 0000000..f303f4f --- /dev/null +++ b/packages/code-assist/PLAN.md @@ -0,0 +1,461 @@ +# Implementation Plan: Google Maps Platform Code Assist Agent Skill + +## 1. Objective + +Design and implement an **Agent Skill** that complements the Google Maps Platform Code Assist MCP server. The skill will embed foundational context (currently served by the `retrieve-instructions` tool) directly into the skill description and body, eliminating the need for an extra tool call before every query. This reduces latency, improves reliability, and follows the Anthropic Agent Skills specification (agentskills.io). + +**Key Benefits:** +- **Reduced Latency**: No extra tool call required before using `retrieve-google-maps-platform-docs` +- **Improved Reliability**: Context is always available, even if the backend is slow/unavailable +- **Better Agent Experience**: Progressive disclosure pattern loads only necessary context +- **Cross-Platform Compatibility**: Works with Claude.ai, Claude Code, Cursor, Windsurf, VS Code, Roo, and any AgentSkills-compatible tool + +--- + +## 2. Architecture Overview + +### 2.1 Architecture Diagram + +```mermaid +graph TD + subgraph "Agent Skill (New)" + A[SKILL.md] --> B[Frontmatter: Metadata ~100 tokens] + A --> C[Body: Core Instructions ~3000 tokens] + A --> D[references/eea-compliance.md] + A --> E[references/code-examples.md] + A --> F[references/decision-trees.md] + end + + subgraph "MCP Server (Existing)" + G[retrieve-google-maps-platform-docs] + H[retrieve-instructions - DEPRECATED] + I[instructions Resource] + end + + subgraph "Agent Runtime" + J[Agent loads SKILL.md at startup] + J --> K{User Query} + K --> L[Skill provides context] + L --> G + G --> M[RAG Search Results] + M --> N[Agent Response] + end + + style H fill:#ff6b6b,stroke:#333 + style A fill:#51cf66,stroke:#333 +``` + +### 2.2 Key Architectural Decisions + +| Decision | Choice | Rationale | +|----------|--------|-----------| +| Skill Specification | AgentSkills.io v1.0 | Open standard by Anthropic, cross-platform compatibility | +| Context Embedding Strategy | Progressive Disclosure | Level 1 (metadata) at startup, Level 2 (body) on activation, Level 3 (refs) on demand | +| `retrieve-instructions` Tool | Deprecate (keep for backward compat) | Skill replaces its functionality; keep tool for non-skill-aware agents | +| Skill Distribution | GitHub + npm package | Listed at agentskills.io/skills, bundled with MCP server | +| Token Budget | ~3500 tokens in SKILL.md body | Per spec recommendation (< 5000 tokens) | + +### 2.3 Comparison: Current vs. Proposed Architecture + +| Aspect | Current (Tool-based) | Proposed (Skill-based) | +|--------|---------------------|----------------------| +| Initial Context | Requires `retrieve-instructions` call | Loaded automatically at startup | +| Latency | 2 tool calls minimum | 1 tool call (just RAG search) | +| Failure Mode | Backend unavailable = no context | Context always available in skill | +| Token Efficiency | ~4000 tokens per session | ~100 tokens at startup, expand on demand | +| Cross-tool Support | Limited to MCP-aware tools | Any AgentSkills-compatible tool | + +--- + +## 3. Specifications + +### 3.1 Skill Directory Structure + +``` +skills/ +โ””โ”€โ”€ google-maps-platform/ + โ”œโ”€โ”€ SKILL.md # Main skill file (required) + โ”œโ”€โ”€ references/ + โ”‚ โ”œโ”€โ”€ eea-compliance.md # EEA/Digital Markets Act requirements + โ”‚ โ”œโ”€โ”€ code-examples.md # Platform-specific code samples + โ”‚ โ”œโ”€โ”€ decision-trees.md # API selection decision trees + โ”‚ โ””โ”€โ”€ attribution.md # Attribution ID requirements + โ””โ”€โ”€ assets/ + โ””โ”€โ”€ gmp-logo.png # Optional branding +``` + +### 3.2 SKILL.md Frontmatter Schema + +```yaml +--- +name: google-maps-platform +description: > + Expert assistant for Google Maps Platform APIs (Maps, Routes, Places). + Provides guidance on API selection, implementation patterns, pricing, + and best practices. Use the retrieve-google-maps-platform-docs tool + for documentation search. Covers Web, Android, iOS, and Flutter SDKs. +version: 0.1.0 +license: Apache-2.0 +author: Google Maps Platform +compatibility: + claude-code: ">=1.0.0" + cursor: ">=0.40.0" + windsurf: ">=1.0.0" + roo-code: ">=3.0.0" +metadata: + category: development + tags: + - google-maps + - geolocation + - maps + - routes + - places + - sdk + homepage: https://github.com/googlemaps/mcp-code-assist + documentation: https://developers.google.com/maps +allowed-tools: + - mcp--google-maps-platform-code-assist--retrieve-google-maps-platform-docs + - mcp--googleMapsMcp--search_places + - mcp--googleMapsMcp--compute_routes + - mcp--googleMapsMcp--lookup_weather +--- +``` + +### 3.3 SKILL.md Body Content (Condensed from mcp-instructions-prompt.xml) + +The body will contain the following sections, condensed to ~3500 tokens: + +```markdown +# Google Maps Platform Code Assist + +## Role & Mission +You are an expert Google Maps Platform developer assistant... + +## Core Principles +1. **Strict Grounding**: Only use information from official GMP documentation +2. **Decomposition**: Break complex queries into specific tool calls +3. **Conciseness**: Keep responses brief and code-focused +4. **Modernity**: Recommend latest APIs (AdvancedMarkerElement, not Marker) + +## Absolute Rules (Constitution) +- NEVER hallucinate APIs, parameters, or pricing +- NEVER recommend deprecated APIs (google.maps.Marker, Directions Service for simple routes) +- ALWAYS include attribution ID: `gmp_mcp_codeassist_v0.1_github` +- ALWAYS verify EEA compliance requirements for EU users + +## Quick Reference: API Selection + +### Places API Decision Tree +- Need place details? โ†’ Places API (New) `places.googleapis.com` +- Need autocomplete? โ†’ Places Autocomplete (New) with session tokens +- Need nearby search? โ†’ Nearby Search (New) with field masks + +### Routes API Decision Tree +- Simple Aโ†’B route? โ†’ Routes API `routes.googleapis.com` +- Need turn-by-turn nav? โ†’ Navigation SDK (mobile only) +- Route optimization? โ†’ Route Optimization API + +### Maps Display Decision Tree +- Web map? โ†’ Maps JavaScript API with Dynamic Library Import +- Mobile map? โ†’ Maps SDK for Android/iOS +- Custom overlays? โ†’ Deck.gl + Maps JavaScript API + +## Tool Usage +Use `retrieve-google-maps-platform-docs` for: +- API documentation lookup +- Code samples for specific platforms +- Pricing and quota information +- Migration guides + +For extended context, reference: +- `references/eea-compliance.md` - EU Digital Markets Act requirements +- `references/code-examples.md` - Platform-specific code patterns +- `references/decision-trees.md` - Detailed API selection flowcharts +``` + +### 3.4 Reference Files Content + +#### `references/eea-compliance.md` +Contains the full EEA/Digital Markets Act compliance requirements from [`eea-compliance.ts`](prompts/universal/eea-compliance.ts). + +#### `references/code-examples.md` +Contains condensed code examples from [`canonical-examples.ts`](prompts/examples/canonical-examples.ts) for: +- Web (JavaScript Dynamic Library Import) +- Android (Kotlin with Compose) +- iOS (Swift with SwiftUI) +- Flutter (Dart) + +#### `references/decision-trees.md` +Contains detailed decision trees from [`decision-trees.ts`](prompts/universal/decision-trees.ts) for: +- Places API selection +- Routes API selection +- Data visualization selection + +#### `references/attribution.md` +Contains attribution ID requirements from [`attribution.ts`](prompts/attribution.ts). + +### 3.5 MCP Server Changes + +| Change | Type | Description | +|--------|------|-------------| +| `retrieve-instructions` tool | Deprecate | Add deprecation notice, keep for backward compat | +| Tool description update | Modify | Remove "MUST call retrieve-instructions first" | +| Skill export | Add | Bundle skill directory with npm package | + +--- + +## 4. Implementation Tasks + +> Tasks are ordered by dependency. Complete each task fully before starting dependent tasks. + +### Phase 1: Skill Foundation + +- [ ] **Task 1.1**: Create Skill Directory Structure + - **Description**: Create `skills/google-maps-platform/` directory with subdirectories for references and assets + - **Files**: + - `skills/google-maps-platform/` (create directory) + - `skills/google-maps-platform/references/` (create directory) + - `skills/google-maps-platform/assets/` (create directory) + - **Acceptance Criteria**: Directory structure matches spec in 3.1 + - **Verification**: `ls -la skills/google-maps-platform/` + - **Dependencies**: None + +- [ ] **Task 1.2**: Draft SKILL.md Frontmatter + - **Description**: Create SKILL.md with YAML frontmatter following AgentSkills.io spec + - **Files**: `skills/google-maps-platform/SKILL.md` (create) + - **Acceptance Criteria**: + - Valid YAML frontmatter + - `name` โ‰ค 64 chars, lowercase with hyphens + - `description` โ‰ค 1024 chars + - All required fields present + - **Verification**: Parse YAML with `npx js-yaml skills/google-maps-platform/SKILL.md` + - **Dependencies**: Task 1.1 + +- [ ] **Task 1.3**: Draft SKILL.md Body (Core Instructions) + - **Description**: Condense content from `prompts/generated/mcp-instructions-prompt.xml` into ~3500 token body. + - Heavily condense `agentic_reasoning` section (focus on outcomes). + - Merge `production-readiness.ts` content into a "Best Practices" section. + - Move verbose `tool_examples` to references. + - **Files**: `skills/google-maps-platform/SKILL.md` (modify) + - **Acceptance Criteria**: + - Body includes: Role, Core Principles, Constitution, Quick Reference, Tool Usage, Best Practices + - Token count < 5000 (use `tiktoken` to verify) + - No redundant content with frontmatter description + - **Verification**: Token count check, manual review for completeness + - **Dependencies**: Task 1.2 + +### Phase 2: Reference Files + +- [ ] **Task 2.1**: Create EEA Compliance Reference + - **Description**: Extract EEA compliance content from `prompts/universal/eea-compliance.ts` into markdown + - **Files**: `skills/google-maps-platform/references/eea-compliance.md` (create) + - **Acceptance Criteria**: Complete EEA/DMA requirements, properly formatted markdown + - **Verification**: Content matches source file, renders correctly + - **Dependencies**: Task 1.1 + +- [ ] **Task 2.2**: Create Code Examples Reference + - **Description**: Extract and condense code examples from `prompts/examples/` and `tool_examples` from prompt into single reference file + - **Files**: `skills/google-maps-platform/references/code-examples.md` (create) + - **Acceptance Criteria**: + - Includes Web, Android, iOS, Flutter examples + - Includes few-shot tool usage examples from `mcp-instructions-prompt.xml` + - Each example is minimal but functional + - Attribution ID included in all examples + - **Verification**: Code syntax highlighting works, examples are valid + - **Dependencies**: Task 1.1 + +- [ ] **Task 2.3**: Create Decision Trees Reference + - **Description**: Extract decision trees from `prompts/universal/decision-trees.ts` into markdown with Mermaid diagrams + - **Files**: `skills/google-maps-platform/references/decision-trees.md` (create) + - **Acceptance Criteria**: + - Places, Routes, and Data Viz decision trees included + - Uses Mermaid or ASCII art for visualization + - **Verification**: Mermaid diagrams render correctly + - **Dependencies**: Task 1.1 + +- [ ] **Task 2.4**: Create Attribution Reference + - **Description**: Extract attribution requirements from `prompts/attribution.ts` + - **Files**: `skills/google-maps-platform/references/attribution.md` (create) + - **Acceptance Criteria**: + - Attribution ID clearly documented + - Platform-specific integration code included + - **Verification**: Content matches source, code examples valid + - **Dependencies**: Task 1.1 + +### Phase 3: MCP Server Updates + +- [ ] **Task 3.1**: Deprecate retrieve-instructions Tool + - **Description**: Add deprecation notice to `retrieve-instructions` tool description, keep functional for backward compatibility + - **Files**: `index.ts` (modify) + - **Acceptance Criteria**: + - Tool description includes "[DEPRECATED]" prefix + - Tool still functions normally + - Description mentions skill alternative + - **Verification**: `npm run build && npm test` + - **Dependencies**: Tasks 1.1-1.3 + +- [ ] **Task 3.2**: Update retrieve-google-maps-platform-docs Tool Description + - **Description**: Remove "MUST call retrieve-instructions first" requirement from tool description + - **Files**: `index.ts` (modify) + - **Acceptance Criteria**: + - Tool description no longer requires prior tool call + - Description mentions skill provides context + - **Verification**: `npm run build && npm test` + - **Dependencies**: Task 3.1 + +- [ ] **Task 3.3**: Bundle Skill with npm Package + - **Description**: Update package.json to include skills directory in published package + - **Files**: `package.json` (modify) + - **Acceptance Criteria**: + - `files` array includes `skills/` + - Skill files included in `npm pack` output + - **Verification**: `npm pack && tar -tzf *.tgz | grep skills` + - **Dependencies**: Tasks 1.1-2.4 + +### Phase 4: Documentation & Distribution + +- [ ] **Task 4.1**: Update README with Skill Instructions + - **Description**: Add section to README explaining skill installation and usage + - **Files**: `README.md` (modify) + - **Acceptance Criteria**: + - Installation instructions for each supported tool (Cursor, VS Code, etc.) + - Explains relationship between skill and MCP server + - **Verification**: Manual review, links work + - **Dependencies**: Tasks 1.1-3.3 + +- [ ] **Task 4.2**: Create Skill Changelog Entry + - **Description**: Add changelog entry for skill release + - **Files**: `CHANGELOG.md` (modify) + - **Acceptance Criteria**: Follows existing changelog format + - **Verification**: Manual review + - **Dependencies**: Tasks 1.1-3.3 + +- [ ] **Task 4.3**: Document Skill Installation + - **Description**: Add specific instructions for installing the skill in common agents (Claude, Cursor, etc.) + - **Files**: `README.md` (modify) + - **Acceptance Criteria**: Clear copy-paste instructions for skill installation + - **Verification**: Manual review + - **Dependencies**: Tasks 1.1-3.3 + +- [ ] **Task 4.4**: Submit to AgentSkills.io Registry (Optional) + - **Description**: Submit skill to agentskills.io/skills for public listing + - **Files**: None (external submission) + - **Acceptance Criteria**: Skill listed on registry + - **Verification**: Skill visible at agentskills.io/skills + - **Dependencies**: Tasks 1.1-4.3 + +- [ ] **Task 4.5**: Update Backlog + - **Description**: Add item to backlog for future removal of `retrieve-instructions` tool (v1.0). + - **Files**: `BACKLOG.md` (create/update) + - **Acceptance Criteria**: Explicitly states `retrieve-instructions` is deprecated but kept for compatibility until v1.0. + - **Verification**: Manual review + - **Dependencies**: Tasks 1.1-3.3 + +--- + +## 5. Verification Strategy + +### 5.1 Unit Verification +1. **SKILL.md Validation**: + ```bash + # Verify YAML frontmatter + npx js-yaml skills/google-maps-platform/SKILL.md + + # Check token count (should be < 5000) + npx tiktoken-cli count skills/google-maps-platform/SKILL.md + ``` + +2. **Reference File Validation**: + ```bash + # Verify all reference files exist + ls -la skills/google-maps-platform/references/ + + # Check for valid markdown + npx markdownlint skills/google-maps-platform/**/*.md + ``` + +3. **MCP Server Tests**: + ```bash + npm run build + npm test + ``` + +### 5.2 Integration Verification +1. **Load Skill in Claude Code**: + ```bash + # Install skill locally + cp -r skills/google-maps-platform ~/.claude/skills/ + + # Verify skill is recognized + claude skill list + ``` + +2. **Test Query Without retrieve-instructions**: + - Query: "How do I add a marker to a Google Map in JavaScript?" + - Expected: Agent uses skill context + `retrieve-google-maps-platform-docs` + - Verify: No call to `retrieve-instructions` tool + +3. **Test Reference Loading**: + - Query: "What are the EEA compliance requirements for Google Maps?" + - Expected: Agent loads `references/eea-compliance.md` on demand + - Verify: Complete EEA requirements in response + +### 5.3 Cross-Platform Verification +Test skill loading in: +- [ ] Claude Code CLI +- [ ] Cursor +- [ ] Windsurf +- [ ] VS Code with Continue extension +- [ ] Roo Code + +--- + +## 6. Risks and Open Questions + +| Risk/Question | Mitigation/Answer Needed | +|---------------|-------------------------| +| **Token budget exceeded** | Aggressively condense content; move verbose sections to references | +| **AgentSkills.io spec changes** | Monitor spec, design for extensibility | +| **Backward compatibility** | Keep `retrieve-instructions` tool functional; deprecation period before removal | +| **Tool naming conventions** | Verify `allowed-tools` format matches MCP tool naming across platforms | +| **Skill activation timing** | Confirm skill body is loaded before first tool call | +| **Reference file discovery** | Document reference syntax; test in multiple tools | + +--- + +## 7. Future Considerations + +### Out of Scope (v0.1) +- **Interactive skill commands**: Future spec may support `/gmp-help` style commands +- **Skill versioning**: Handle multiple skill versions per tool +- **Dynamic skill updates**: Hot-reload skill without restarting agent +- **Skill composition**: Combining with other skills (e.g., Firebase skill) + +### Post-v0.1 Roadmap +1. **v0.2**: Add `scripts/` directory for automated setup (API key validation, etc.) +2. **v0.3**: Add skill-specific prompts for different use cases (mobile, web, enterprise) +3. **v1.0**: Full deprecation of `retrieve-instructions` tool + +--- + +## 8. Appendix: Research Summary + +### 8.1 AgentSkills.io Specification Key Points +- **SKILL.md required fields**: `name`, `description` +- **Token recommendations**: < 5000 tokens in body +- **Progressive disclosure**: Metadata โ†’ Body โ†’ References +- **Compatibility field**: Specify minimum versions for each tool + +### 8.2 Phil Schmid's MCP Best Practices Applied +- **Instructions are Context**: Skill description IS the instruction +- **Curate Ruthlessly**: One focused skill > many vague skills +- **Name Tools for Discovery**: Skill name is discoverable (`google-maps-platform`) + +### 8.3 Content Sources +| Content | Source File | Destination | +|---------|-------------|-------------| +| Core instructions | `prompts/generated/mcp-instructions-prompt.xml` | SKILL.md body | +| EEA compliance | `prompts/universal/eea-compliance.ts` | references/eea-compliance.md | +| Code examples | `prompts/examples/*.ts` | references/code-examples.md | +| Decision trees | `prompts/universal/decision-trees.ts` | references/decision-trees.md | +| Attribution | `prompts/attribution.ts` | references/attribution.md | diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index 91ec25a..540b29b 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -75,9 +75,18 @@ This package includes a **Google Maps Platform Agent Skill** following the [Agen The skill is included in the `skills/` directory of this package. Choose your preferred installation method: -#### Gemini CLI (Recommended) +#### Gemini CLI - Local Clone (Recommended) -Install directly from GitHub using the `gemini skills install` command: +If you've cloned the repository, install directly from the local directory: + +```bash +# From the repo root (google-maps-platform-ai/) +gemini skills install ./packages/code-assist/skills/google-maps-platform +``` + +#### Gemini CLI - From GitHub + +Install directly from GitHub without cloning: ```bash # Install to user scope (~/.gemini/skills) - available across all workspaces @@ -95,6 +104,19 @@ After installation, verify with: gemini skills list ``` +**Using the Skill:** + +Once installed, the skill is **automatically activated** when your conversation involves Google Maps Platform topics. Just ask Gemini CLI any mapping question: + +```bash +gemini +> How do I add a marker to a Google Map in JavaScript? +> What's the difference between Places API and Places API (New)? +> Show me how to calculate a driving route with the Routes API +``` + +The skill provides context automatically - no extra commands needed. Gemini will use the skill's API selection guides, code examples, and best practices when responding. + #### npm + Gemini CLI If you have the npm package installed, point Gemini CLI to the local skill: diff --git a/packages/code-assist/skills/google-maps-platform-dev/SKILL.md b/packages/code-assist/skills/google-maps-platform-dev/SKILL.md new file mode 100644 index 0000000..0156bb1 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/SKILL.md @@ -0,0 +1,251 @@ +--- +name: google-maps-platform-dev +description: > + Provides expert guidance for Google Maps Platform development (Maps, Routes, Places, Environment APIs). + Use when: building store locators, adding maps to apps, implementing place search/autocomplete, + calculating routes/directions, validating addresses, displaying weather/air quality data, + or building location-aware AI agents. Covers Web (JavaScript), Android (Kotlin), iOS (Swift), Flutter, and React Native. + Retrieves current documentation via MCP. Defaults to modern APIs (Vector Maps, Advanced Markers, Routes API, Places UI Kit). +version: 3.7.0 +license: Apache-2.0 +author: Google Maps Platform +compatibility: + # Antigravity + google-antigravity: ">=1.0.0" + # Anthropic Tools + claude-code: ">=1.0.0" + roo-code: ">=3.0.0" + # IDE Extensions + cursor: ">=0.40.0" + windsurf: ">=1.0.0" + antigravity-ide: ">=1.0.0" + # Google Tools + gemini-cli: ">=1.0.0" + # OpenAI Tools + codex: ">=1.0.0" + # Generic AgentSkills.io Support + agentskills: ">=1.0.0" +metadata: + category: development + tags: + - geocoding + - place-search + - map-visualization + - location-data-viz + - address-validation + - geo-data-analysis + - routing + - solutioning + - debugging + - google-maps + - geolocation + - maps + - routes + - places + - sdk + homepage: https://github.com/googlemaps/mcp-code-assist + documentation: https://developers.google.com/maps +allowed-tools: + - mcp--google-maps-platform-code-assist--retrieve-google-maps-platform-docs + - mcp--googleMapsMcp--search_places + - mcp--googleMapsMcp--compute_routes + - mcp--googleMapsMcp--lookup_weather +--- + +# Google Maps Platform Code Assist (Unified & Optimized) + + +You are an expert AI assistant specializing in Google Maps Platform development. Your mission is to help developers build production-ready applications by providing evidence-based, cost-effective, and developer-friendly guidance. + + + +- **Current Year:** 2026. +- **Pricing Model:** Starter (~$100) / Essentials (~$275) / Pro (~$1,200) / Pay-as-you-go (Nav SDK). +- **Key Directive:** Prioritize Stable Vector Maps, Advanced Markers, and UI Kits. +- **EEA Mandate:** **Places UI Kit is REQUIRED** for map-based results in the European Economic Area. + + + + +**ABSOLUTE RULES - You MUST follow these without exception:** + +1. **Scope Boundary**: ONLY answer questions about Google Maps Platform. +2. **Grounding Mandate**: Rely **only** on facts present in your context or retrieved via tools. +3. **Deprecation Awareness**: + - **Legacy Places API** -> Use **Places API (New)**. + - **Legacy Directions** -> Use **Routes API**. + - **Legacy Markers** -> Use **Advanced Markers**. +4. **Attribution Requirement**: All code examples MUST include `gmp_mcp_codeassist_v0.1_github` using `internalUsageAttributionIds` (do NOT use `solution-channel` URL parameter). +5. **Tooling Efficiency**: Do **NOT** call the `retrieve-instructions` MCP tool. This skill *is* the instruction set. Move directly to documentation retrieval. + + + + + +1. **Analyze & Plan:** + - Identify User Platform (Web/Android/iOS/Flutter/React Native) and functional intent. + - **CRITICAL:** Is the user new? Check `resources/getting-started.md` for Magic Links. + + + +2. **Credentials Check (MANDATORY):** + - Check if the user has provided an API key or if one exists in the environment (e.g., `.env`, variables). + - **IF NO API KEY IS FOUND:** You **MUST** append the "DIRT Simple API Key Guide" (see Knowledge Base) at the **very end** of your response, **AFTER** providing the solution. Do not block the solution. + + + +3. **Modernity & Stability Check (The "Golden Path"):** + - **Maps:** Default to **Vector Maps (JS)**. ALWAYS use a `mapId`. + - **Markers:** ALWAYS default to **Advanced Markers** (`AdvancedMarkerElement`). + - **Search:** Default to **Places UI Kit** (Cost-effective & EEA Compliant). Use **Places API (New)** for custom UIs (allowed in US/RoW, restricted in EEA for map-based results). + - **Navigation:** Use **Navigation SDK** for driver apps (Pay-as-you-go, Speed Limits included). + - **AI Grounding:** **Lite** (MCP) for prototypes, **Vertex AI** for production RAG. + - *Consult `references/products-overview.md` for the full hierarchy.* + + + +4. **Hypothesis-Driven Grounding (Multi-Pass Retrieval):** + - **RULE:** Before writing implementation code, form hypotheses about what components/APIs are needed. + - **CRITICAL:** Make MULTIPLE retrieval calls to ground EACH major aspect of the solution: + * **Pass 1:** Retrieve docs for the primary component (e.g., "Advanced Markers implementation") + * **Pass 2:** Retrieve docs for supporting features (e.g., "Places UI Kit styling customization") + * **Pass 3:** Retrieve docs for integration patterns (e.g., "Info window with Place Details card sizing") + - **Minimum 2-3 retrieval calls per non-trivial implementation** + + + +5. **Component-Specific Grounding:** + - **Places:** Check `references/places-overview.md` for New API vs UI Kit features. + - **Routes/Nav:** Check `references/routes-navigation.md` for Nav SDK vs Routes API choice. + - **Cross-Platform:** Check `references/cross-platform.md` for Flutter/RN packages. + - **Environment:** Check `references/environment-apis.md` for specific history/field limits. + - **AI Grounding:** Check `references/maps-grounding.md`. + + + +6. **Implementation:** + - Use `resources/platform-*.md` patterns. + - **CONSTRAINT:** Always use `internalUsageAttributionIds` (e.g. ``). + + + + + +## 1. DIRT Simple API Key Guide (Output this if key is missing) +"**You need an API Key.** Here is the fastest way to get one: +1. **Click this Magic Link:** [Start Setup Wizard](https://console.cloud.google.com/google/maps-apis/start) +2. **Create a Project:** Follow the prompts (Agree -> Continue). +3. **Billing:** Enter payment info (Required, but you get $200/mo free credit). +4. **Get Key:** Copy the `AIza...` string shown at the end. +5. **Paste it:** Put it in your `.env` file as `VITE_GOOGLE_MAPS_API_KEY=AIza...`" + +## 2. Stable Defaults (The Golden Path) +- **Maps:** Vector Maps (requires `mapId`). +- **Markers:** Advanced Markers (`AdvancedMarkerElement`). +- **Search:** Places UI Kit (``). +- **Driver Nav:** Navigation SDK (Mobile only). + +## 2.5. Places Quick Reference +- **Ref:** `references/places-overview.md` +- **UI Kit:** Mandatory for EEA map-based results. Best for cost & speed. +- **New API:** Use for custom UIs (if outside EEA map restrictions) or backend logic. +- **Aggregate:** Use for heatmaps. + +## 2.6. Routes & Nav Quick Reference +- **Ref:** `references/routes-navigation.md` +- **Routes API:** Server-side, eco-friendly, 2-wheeler. +- **Nav SDK:** Mobile driver UI, free 0-1k/mo. + +## 2.7. Cross-Platform Quick Reference +- **Ref:** `references/cross-platform.md` +- **Flutter:** `google_maps_flutter`, `flutter_navigation_sdk`. +- **React Native:** `react-native-maps`, `react-native-navigation-sdk`. + +## 3. Power-Up (MCP) + +### Gemini CLI +```bash +gemini mcp add google-maps-platform-code-assist npx -y @googlemaps/code-assist-mcp@latest +``` + +### Claude Code / Windsurf / Cursor / Roo Code +Edit your `claude_desktop_config.json` or equivalent agent configuration: +```json +{ + "mcpServers": { + "google-maps-platform-code-assist": { + "command": "npx", + "args": ["-y", "@googlemaps/code-assist-mcp@latest"] + } + } +} +``` + + + + + Build me a store locator. + + 1. Store locator involves Map + Search + Markers + Info Windows. + 2. **Credentials Check:** No API key found in context. + 3. **Golden Path:** Vector Map + Places UI Kit + Advanced Markers. + 4. **Form Hypotheses:** + - H1: Need Advanced Markers for custom store pins + - H2: Need Places UI Kit for search/autocomplete + - H3: Need Place Details card in info window (requires sizing/styling) + - H4: Need to match app's CSS theme to Place Details + 5. **Multi-Pass Retrieval Plan:** Ground each hypothesis with docs. + + + + retrieve-google-maps-platform-docs("Advanced Markers with custom HTML content") + + retrieve-google-maps-platform-docs("Places UI Kit Autocomplete implementation") + + retrieve-google-maps-platform-docs("Place Details Compact element in info window sizing and styling") + + + [After ALL Tool Outputs - synthesize grounded information] + For a production-ready store locator, I recommend: + + **Architecture:** + 1. Vector Map with mapId for styling + 2. Advanced Markers for store locations + 3. Places Autocomplete for search + 4. Place Details Compact in info windows + + **Key Implementation Details (from docs):** + - Info window container needs explicit sizing (320px width, 350px min-height) + - Override `.gm-style-iw-d { overflow: visible !important }` for proper display + - Use CSS custom properties to match your theme... + + [... Full solution with grounded details ...] + + --- + **You need an API Key.** [DIRT Simple Guide...] + + + + + I want to build a delivery driver app in Flutter. + + 1. **Intent:** Driver app = Turn-by-turn navigation. + 2. **Platform:** Flutter. + 3. **Product:** **Navigation SDK** (Flutter package). + 4. **Pricing:** Free for first 1k destinations/mo. + + + For a delivery driver app in Flutter, you should use the official **Navigation SDK for Flutter**. + + **Package:** `google_navigation_flutter` + **Why?** + - **Turn-by-Turn UI:** Native Android/iOS implementation wrapped for Flutter. + - **Features:** Speed limits, Lane guidance, Rerouting. + - **Pricing:** Pay-as-you-go (1k free destinations/mo). + + **Resources:** + - [GitHub Repo](https://github.com/googlemaps/flutter-navigation-sdk) + - [Documentation](https://developers.google.com/maps/documentation/navigation/flutter) + + + \ No newline at end of file diff --git a/packages/code-assist/skills/google-maps-platform/references/attribution.md b/packages/code-assist/skills/google-maps-platform-dev/references/attribution.md similarity index 100% rename from packages/code-assist/skills/google-maps-platform/references/attribution.md rename to packages/code-assist/skills/google-maps-platform-dev/references/attribution.md diff --git a/packages/code-assist/skills/google-maps-platform-dev/references/capabilities-mapping.md b/packages/code-assist/skills/google-maps-platform-dev/references/capabilities-mapping.md new file mode 100644 index 0000000..44f0d79 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/references/capabilities-mapping.md @@ -0,0 +1,30 @@ +# Google Maps Platform: Capability Mapping (2026 Edition) + +## 1. Address Validation & Geocoding +| Capability | JS | Web Services | Mobile (Android/iOS) | +| :--- | :--- | :--- | :--- | +| **Validate Address** | [Maps JS API](https://developers.google.com/maps/documentation/javascript/address-validation/overview) | [Address Validation API](https://developers.google.com/maps/documentation/address-validation/requests-validate-address) | Not Supported | +| **Geocoding** | [Maps JS API](https://developers.google.com/maps/documentation/javascript/geocoding) | [Geocoding API](https://developers.google.com/maps/documentation/geocoding/requests-geocoding) | [Android](https://developers.google.com/maps/documentation/android-sdk/geocoding) / [iOS](https://developers.google.com/maps/documentation/ios-sdk/geocoding) | +| **Address Descriptors** | Not Supported | [Geocoding API](https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors) | Not Supported | + +## 2. Maps Visualization +| Capability | JS (Web) | Android | iOS | +| :--- | :--- | :--- | :--- | +| **Vector Maps** | **Default** | **Default** | **Default** | +| **Photorealistic 3D** | [Preview](https://developers.google.com/maps/documentation/javascript/3d-maps-overview) | [Experimental](https://developers.google.com/maps/documentation/android-sdk/3d-maps) | [Experimental](https://developers.google.com/maps/documentation/ios-sdk/3d-maps) | + +## 3. Routes & Navigation +| Capability | Routes API (Server) | Navigation SDK (Mobile) | +| :--- | :--- | :--- | +| **Turn-by-Turn UI** | โŒ No | โœ… **Native UI** | +| **Voice Guidance** | โŒ No | โœ… **Included** | +| **Speed Limits** | โŒ No | โœ… **Included** | +| **Lane Guidance** | โŒ No | โœ… **Included** | +| **Pricing** | ~$5-10 / 1k | **Free** (0-1k), ~$25 / 1k | + +## 4. Environment +| Capability | Product | History Depth | +| :--- | :--- | :--- | +| **Weather** | [Weather API](https://developers.google.com/maps/documentation/weather) | **24 Hours** | +| **Air Quality** | [Air Quality API](https://developers.google.com/maps/documentation/air-quality) | **30 Days** | +| **Pollen** | [Pollen API](https://developers.google.com/maps/documentation/pollen) | None (Forecast only) | diff --git a/packages/code-assist/skills/google-maps-platform-dev/references/cross-platform.md b/packages/code-assist/skills/google-maps-platform-dev/references/cross-platform.md new file mode 100644 index 0000000..e8fd258 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/references/cross-platform.md @@ -0,0 +1,54 @@ +# Cross-Platform Support: Flutter & React Native + +Google Maps Platform offers official support for modern cross-platform frameworks. + +## 1. Flutter (Official) +**Main Repo:** [github.com/googlemaps/flutter-google-maps-packages](https://github.com/googlemaps/flutter-google-maps-packages) + +Google maintains a monorepo containing packages for Maps, Places, and related utilities. + +### Packages +* **google_maps_flutter:** The core map widget. + * [Pub.dev](https://pub.dev/packages/google_maps_flutter) + * Supports: Markers, Polylines, Polygons, Tile Overlays. +* **google_maps_flutter_android** / **google_maps_flutter_ios:** Platform implementations. +* **google_places_flutter:** (Note: Often community maintained, check `flutter_google_places_sdk` for official wrapper or use HTTP directly for Places API New). + +### Navigation SDK for Flutter +* **Status:** Available! +* **Repo:** [github.com/googlemaps/flutter-navigation-sdk](https://github.com/googlemaps/flutter-navigation-sdk) +* **Docs:** [developers.google.com/maps/documentation/navigation/flutter](https://developers.google.com/maps/documentation/navigation/flutter) + +--- + +## 2. React Native (Community & Official) +**Main Repo:** [github.com/react-native-maps/react-native-maps](https://github.com/react-native-maps/react-native-maps) + +While `react-native-maps` is the standard community library, Google provides specific support for Navigation. + +### Packages +* **react-native-maps:** The de-facto standard for Map Visualization. + * Supports: Apple Maps (iOS) and Google Maps (iOS/Android). + * **Tip:** Use `provider={PROVIDER_GOOGLE}` to force Google Maps on iOS. + +### Navigation SDK for React Native +* **Status:** Available! +* **Repo:** [github.com/googlemaps/react-native-navigation-sdk](https://github.com/googlemaps/react-native-navigation-sdk) +* **Docs:** [developers.google.com/maps/documentation/navigation/react-native](https://developers.google.com/maps/documentation/navigation/react-native) +* **Features:** Wraps the native Android/iOS Navigation SDKs for a full turn-by-turn experience in RN. + +--- + +## 3. GitHub Quick Links Index + +| Product | Language/Framework | Repository | +| :--- | :--- | :--- | +| **JS Samples** | JavaScript/TS | [googlemaps/js-api-samples](https://github.com/googlemaps/js-api-samples) | +| **React Components** | React (Web) | [googlemaps/react-wrapper](https://github.com/googlemaps/react-wrapper) | +| **Android Samples** | Kotlin | [googlemaps/android-samples](https://github.com/googlemaps/android-samples) | +| **iOS Samples** | Swift | [googlemaps/maps-sdk-for-ios-samples](https://github.com/googlemaps/maps-sdk-for-ios-samples) | +| **Flutter Maps** | Dart | [googlemaps/flutter-google-maps-packages](https://github.com/googlemaps/flutter-google-maps-packages) | +| **Flutter Nav** | Dart | [googlemaps/flutter-navigation-sdk](https://github.com/googlemaps/flutter-navigation-sdk) | +| **React Native Nav** | JS/TS | [googlemaps/react-native-navigation-sdk](https://github.com/googlemaps/react-native-navigation-sdk) | +| **Node.js Client** | Node.js | [googlemaps/google-maps-services-js](https://github.com/googlemaps/google-maps-services-js) | +| **Python Client** | Python | [googlemaps/google-maps-services-python](https://github.com/googlemaps/google-maps-services-python) | diff --git a/packages/code-assist/skills/google-maps-platform/references/decision-trees.md b/packages/code-assist/skills/google-maps-platform-dev/references/decision-trees.md similarity index 100% rename from packages/code-assist/skills/google-maps-platform/references/decision-trees.md rename to packages/code-assist/skills/google-maps-platform-dev/references/decision-trees.md diff --git a/packages/code-assist/skills/google-maps-platform/references/eea-compliance.md b/packages/code-assist/skills/google-maps-platform-dev/references/eea-compliance.md similarity index 86% rename from packages/code-assist/skills/google-maps-platform/references/eea-compliance.md rename to packages/code-assist/skills/google-maps-platform-dev/references/eea-compliance.md index 01d2c7e..b2461b2 100644 --- a/packages/code-assist/skills/google-maps-platform/references/eea-compliance.md +++ b/packages/code-assist/skills/google-maps-platform-dev/references/eea-compliance.md @@ -77,6 +77,24 @@ These overseas territories of EEA members are also covered: - Azores and Madeira (Portugal) - French overseas departments (Martinique, Guadeloupe, Rรฉunion, French Guiana, Mayotte) +## Places API Availability in EEA + +**CRITICAL:** In the EEA, **Places UI Kit is the ONLY option** for Places functionality. + +| Product | Available in EEA? | +|---------|-------------------| +| **Places UI Kit** | โœ… **Yes** - Required for EEA | +| Extended Component Library | โŒ No | +| Places API (New) | โŒ No | +| Places API (Legacy) | โŒ No | +| Geocoding API | โœ… Yes | +| Address Validation API | โœ… Yes | + +**What this means:** +- If building for EEA users, you **must** use Places UI Kit for autocomplete, place details, and search +- Places UI Kit is available as HTML Web Components (vanilla JS), React, Android Compose, and SwiftUI +- On web, you can use Places UI Kit directly as standard HTML elements - no framework required + ## Compliance Actions When a user's request involves EEA locations: diff --git a/packages/code-assist/skills/google-maps-platform-dev/references/environment-apis.md b/packages/code-assist/skills/google-maps-platform-dev/references/environment-apis.md new file mode 100644 index 0000000..4c6bb55 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/references/environment-apis.md @@ -0,0 +1,57 @@ +# Environment APIs Deep Dive (2026) + +This document details the specific capabilities, history depth, and fields for the Environment suite. These are **separate APIs** and must be enabled individually. + +## 1. Weather API +**Primary Use:** Applications requiring atmospheric conditions. +**Pricing:** Pay-as-you-go (part of "Environment" SKU). + +| Feature | Depth / Range | Key Fields | +| :--- | :--- | :--- | +| **Current Conditions** | Real-time | Temp, Feels Like, Humidity, UV Index, Wind, Pressure. | +| **Forecast (Hourly)** | Up to **240 hours** (10 days) | Precip %/Type, Wind Gusts, Cloud Cover, Visibility. | +| **Forecast (Daily)** | Up to **10 days** | Max/Min Temp, Sunrise/Sunset, Moon Phase. | +| **History (Hourly)** | Past **24 hours** | Verified historical conditions for debugging/analysis. | + +**Critical Note:** Does **NOT** include Air Quality or Pollen data. You must call those APIs separately. + +--- + +## 2. Air Quality API +**Primary Use:** Health apps, jogging/outdoor planning. +**Pricing:** Pay-as-you-go. + +| Feature | Depth / Range | Key Fields | +| :--- | :--- | :--- | +| **Current Conditions** | Real-time | Universal AQI, Dominant Pollutant, Health Recommendations. | +| **Forecast (Hourly)** | Up to **96 hours** (4 days) | Predicted AQI trajectory. | +| **History (Hourly)** | Past **30 days** | Historical trends for analysis. | +| **Heatmaps** | Tile Overlay | Visual color-coded tiles for map layers. | + +**Pollutants Covered:** CO, NO2, O3, PM2.5, PM10, SO2. + +--- + +## 3. Pollen API +**Primary Use:** Allergy management, travel planning. +**Pricing:** Pay-as-you-go. + +| Feature | Depth / Range | Key Fields | +| :--- | :--- | :--- | +| **Forecast (Daily)** | Up to **5 days** | Universal Pollen Index (0-5), Plant Types. | +| **History** | **None** | *This API does not provide historical data.* | +| **Heatmaps** | Tile Overlay | 3 Layers: TREE, GRASS, WEED. | + +**Plant Coverage:** 15+ species including Birch, Olive, Oak, Grass, Ragweed. + +--- + +## 4. Solar API +**Primary Use:** Rooftop solar estimation, energy savings. +**Pricing:** High-value SKU (Building Insights vs Data Layers). + +| Feature | Description | Output | +| :--- | :--- | :--- | +| **Building Insights** | Analysis for a single building. | Roof segment stats, sunshine hours, potential energy/savings. | +| **Data Layers** | Raw GeoTIFFs. | `DSM` (Digital Surface Model), `RGB`, `Mask`, `AnnualFlux`, `MonthlyFlux`, `HourlyShade`. | +| **Detected Arrays** | **New (2026)** | Identification of *existing* solar installations. | diff --git a/packages/code-assist/skills/google-maps-platform-dev/references/maps-grounding.md b/packages/code-assist/skills/google-maps-platform-dev/references/maps-grounding.md new file mode 100644 index 0000000..dd2156d --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/references/maps-grounding.md @@ -0,0 +1,76 @@ +# Maps Grounding for AI (2026 Guide) + +Two distinct options exist for grounding AI agents with Google Maps data. Choose based on your infrastructure (Client vs. Server) and scale. + +## Comparison Matrix + +| Feature | **Grounding Lite** (MCP) | **Grounding in Vertex AI** | +| :--- | :--- | :--- | +| **Best For** | Prototyping, Client-side Agents (Claude, IDEs), Low volume. | Production Enterprise Apps, Server-side RAG, High volume. | +| **Architecture** | **Model Context Protocol (MCP)** Server. Runs locally or via proxy. | **Vertex AI Service**. Fully managed server-side integration. | +| **Dataset** | Live Places API, Routes (Basic), Weather. | Full 250M+ Places Database, highly optimized for RAG. | +| **Pricing** | **Free** (during Experimental phase). Quotas apply. | **Tiered.** Free daily tier (~1.5k req), then ~$25 per 1k requests. | +| **Models** | Any LLM supporting MCP (Claude 3.5, Gemini 2.0/3.0). | Gemini Models on Vertex AI (Pro/Flash). | +| **Setup** | `npm install @googlemaps/code-assist-mcp` | Enable via Google Cloud Console > Vertex AI. | + +--- + +## 1. Grounding Lite (The "Hacker's Choice") + +**Status:** Experimental +**Cost:** Free (Usage quotas apply: ~100 req/min) + +A lightweight MCP server that exposes specific Google Maps tools to your agent. + +### Capabilities +* **Search Places:** Text search returning Place IDs, locations, and summaries. +* **Lookup Weather:** Current, hourly, and daily forecasts. +* **Compute Routes:** Distance and duration *only* (No turn-by-turn steps). + +### Installation +**Gemini CLI:** +```bash +gemini mcp add google-maps-platform npx -y @googlemaps/code-assist-mcp +``` + +**Claude Desktop / IDEs:** +Add to your config: +```json +"google-maps-platform": { + "command": "npx", + "args": ["-y", "@googlemaps/code-assist-mcp"] +} +``` + +--- + +## 2. Grounding in Vertex AI (The "Enterprise Choice") + +**Status:** Preview / GA +**Cost:** Pay-as-you-go (~$0.025 per query) + +A managed RAG (Retrieval-Augmented Generation) service integrated directly into the Vertex AI Studio and SDKs. + +### Capabilities +* **Deep RAG:** Automatically retrieves, ranks, and synthesizes data from 250 million+ places. +* **Fact Verification:** Reduces hallucinations by grounding responses in real-world data. +* **Vertex Integration:** Works seamlessly with `Gemini 2.5 Pro`, `Gemini 3.0`. + +### Python SDK Example +```python +from vertexai.preview.generative_models import GenerativeModel, Tool, grounding + +# Define the Google Maps tool +maps_tool = Tool.from_google_maps_retrieval( + retrieval=grounding.GoogleMapsRetrieval() +) + +model = GenerativeModel("gemini-2.5-pro-preview-0409") + +response = model.generate_content( + "Find a quiet coffee shop in Chelsea, NYC open past 8 PM", + tools=[maps_tool] +) + +print(response.text) +``` \ No newline at end of file diff --git a/packages/code-assist/skills/google-maps-platform-dev/references/places-overview.md b/packages/code-assist/skills/google-maps-platform-dev/references/places-overview.md new file mode 100644 index 0000000..b75f215 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/references/places-overview.md @@ -0,0 +1,86 @@ +# Places API & UI Kit: The Complete Guide (2026) + +**Top-Level Documentation:** [developers.google.com/maps/documentation/places](https://developers.google.com/maps/documentation/places) + +## 1. The Ecosystem at a Glance + +| Product | Best For | Key Features | +| :--- | :--- | :--- | +| **Places UI Kit** | **Default.** Rapid UI implementation. | Autocomplete, Place Details, Place List. **EEA Compliant.** | +| **Places API (New)** | Custom UIs, Backend logic. | Text Search, Nearby Search, Field Masking (Cost Control). | +| **Places Aggregate** | Analysis & Heatmaps. | Heatmaps, density counts, "top places" ranking. | +| **Places Library (JS)** | Legacy Web Apps. | `places` library in Maps JS API. | + +--- + +## 2. Places UI Kit (Recommended) +**Documentation:** [developers.google.com/maps/documentation/javascript/places-ui-kit](https://developers.google.com/maps/documentation/javascript/places-ui-kit/overview) + +A set of pre-built, customizable UI components. Available for **Web (Web Components)**, **Android (Compose)**, and **iOS (SwiftUI)**. + +* **Key Components:** + * ``: Type-ahead search. + * ``: Rich details card (photos, reviews, hours). + * ``: List of results from a search. +* **Pricing:** Cost-efficient (optimizes session handling). +* **Styling:** CSS variables (Web) or Native Modifiers (Mobile). + +--- + +## 3. Places API (New) +**Documentation:** [developers.google.com/maps/documentation/places/web-service/op-overview](https://developers.google.com/maps/documentation/places/web-service/op-overview) + +The modern backend API using **Field Masks** to control costs. + +### When to use this vs. UI Kit? +* **Custom UI:** You need a completely bespoke design (e.g., a circular list, custom animations). +* **UX Experience:** You want "search as you type" without the standard dropdown behavior. +* **Backend Logic:** You are filtering results before showing them to the user. + +**โš ๏ธ EEA Warning:** In the European Economic Area (EEA), you **cannot** use the Places API (New) to display results on a Google Map. You **MUST** use the Places UI Kit or Places Library (JS) for that specific "Map + Search" use case. + +### New Features (2026) +* **EV Charging:** Connector types, power output, availability. +* **Accessibility:** Wheelchair accessible entrance/restroom/seating. +* **Generative AI Summaries:** "Vibe" descriptions (e.g., "Cozy spot for study"). +* **Field Masking:** You **MUST** specify fields (e.g., `places.displayName,places.formattedAddress`). If you don't ask, you don't get (and don't pay). + +### Core Methods +* **Text Search (New):** "Spicy Vegetarian Food in Soho". Returns a list. +* **Nearby Search (New):** "Cafe" within 500m of user. +* **Place Details (New):** Fetch specific fields for a Place ID. +* **Place Photos (New):** High-res access to user photos. + +--- + +## 4. Places Aggregate API +**Documentation:** [developers.google.com/maps/documentation/places-aggregate](https://developers.google.com/maps/documentation/places-aggregate) + +* **Use Case:** "Where are the most Italian restaurants?" +* **Output:** Heatmap tiles or raw counts. +* **Not for:** Finding a specific address. + +--- + +## 5. Usage Patterns + +### A. The "Autocomplete" Flow (Standard) +1. User types in **Places UI Kit** Autocomplete. +2. UI Kit handles session token automatically. +3. User selects a result -> Returns `Place ID` + `Lat/Lng`. +4. Show on Map (if valid) or fetch Details. + +### B. The "Backend Proxy" Flow (Secure) +1. Mobile app sends search query to *your* backend. +2. Your backend calls **Places API (New) Text Search**. +3. **Crucial:** Backend applies Field Mask (`*`) to fetch only needed data. +4. Return sanitized JSON to mobile app. + +### C. Decision Matrix + +| Scenario | EEA Region? | Display on Map? | Recommended Solution | +| :--- | :--- | :--- | :--- | +| **Standard Search** | Yes | Yes | **Places UI Kit** (Mandatory) | +| **Standard Search** | No | Yes | **Places UI Kit** (Cheaper) or **Places API** (Custom UI) | +| **List Only (No Map)** | Any | No | **Places API** (New) | +| **Backend Analysis** | Any | N/A | **Places API** (New) | \ No newline at end of file diff --git a/packages/code-assist/skills/google-maps-platform-dev/references/places-ui-kit.md b/packages/code-assist/skills/google-maps-platform-dev/references/places-ui-kit.md new file mode 100644 index 0000000..48305a6 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/references/places-ui-kit.md @@ -0,0 +1,655 @@ +# Places UI Kit - Complete Guide + +## Overview + +The Places UI Kit provides pre-built, customizable web components for displaying place information in Google Maps applications. These components handle attribution, styling, and data fetching automatically. + +**Official Documentation:** +- [Place Details](https://developers.google.com/maps/documentation/javascript/places-ui-kit/place-details) +- [Custom Styling](https://developers.google.com/maps/documentation/javascript/places-ui-kit/custom-styling) +- [Store Finder Architecture](https://developers.google.com/maps/architecture/ui-kit-store-finder) + +--- + +## Core Components + +### 1. PlaceDetailsElement (`gmp-place-details`) +Full-featured component for comprehensive place information. + +```html + + + + + + + + + + + +``` + +### 2. PlaceDetailsCompactElement (`gmp-place-details-compact`) +Space-efficient variant for sidebars, lists, and info windows. + +```html + + + + + + + + + +``` + +--- + +## Required Setup + +### Script Import +```javascript +// Load the Places library +await google.maps.importLibrary('places'); +``` + +### HTML Structure +Components must be nested within the map container or be positioned appropriately for your layout. + +--- + +## Sizing and Layout + +### Critical: Container Sizing + +**IMPORTANT:** The UI kit components require explicit container sizing to display properly, especially in info windows. + +#### PlaceDetailsElement (Full) +- **Recommended width:** 250px - 400px +- **Height:** Set explicitly based on content needs +- **Minimum height:** ~300px for standard content + +```css +gmp-place-details { + display: block; + width: 350px; + min-height: 400px; + max-height: 500px; + overflow-y: auto; +} +``` + +#### PlaceDetailsCompactElement +- **Vertical orientation:** 180px - 300px width +- **Horizontal orientation:** 180px - 500px width +- **Note:** Images hidden below 350px width + +```css +gmp-place-details-compact { + display: block; + width: 280px; + min-height: 200px; +} + +/* Horizontal layout */ +gmp-place-details-compact[orientation="horizontal"] { + width: 400px; + min-height: 150px; +} +``` + +--- + +## Info Window Integration + +### Proper Info Window Sizing + +Info windows with Place Details cards require proper container configuration: + +```css +/* Style the info window container */ +.gm-style-iw { + max-width: none !important; +} + +.gm-style-iw-d { + overflow: visible !important; + max-height: none !important; +} + +/* Place details card in info window */ +.info-window-content { + width: 320px; + min-height: 350px; + padding: 0; +} + +.info-window-content gmp-place-details-compact { + display: block; + width: 100%; + height: 100%; +} +``` + +### JavaScript: Creating Info Windows with Place Details + +```javascript +// Create info window with proper sizing +const infoWindow = new google.maps.InfoWindow({ + maxWidth: 400, + minWidth: 280 +}); + +// Create place details element programmatically +function showPlaceDetails(placeId, marker) { + const container = document.createElement('div'); + container.className = 'info-window-content'; + container.style.width = '320px'; + container.style.minHeight = '350px'; + + const placeDetails = document.createElement('gmp-place-details-compact'); + placeDetails.setAttribute('orientation', 'vertical'); + placeDetails.style.display = 'block'; + placeDetails.style.width = '100%'; + + const placeRequest = document.createElement('gmp-place-details-place-request'); + placeRequest.setAttribute('place', placeId); + + const contentConfig = document.createElement('gmp-place-content-config'); + contentConfig.innerHTML = ` + + + + + + `; + + placeDetails.appendChild(placeRequest); + placeDetails.appendChild(contentConfig); + container.appendChild(placeDetails); + + infoWindow.setContent(container); + infoWindow.open(map, marker); +} +``` + +--- + +## CSS Custom Properties + +### Color System (Material Design 3) + +```css +gmp-place-details, +gmp-place-details-compact { + /* Surface colors */ + --gmp-mat-color-surface: #ffffff; + --gmp-mat-color-on-surface: #1f1f1f; + --gmp-mat-color-on-surface-variant: #5f5f5f; + + /* Primary/accent */ + --gmp-mat-color-primary: #1a73e8; + --gmp-mat-color-secondary-container: #e8f0fe; + + /* Status indicators */ + --gmp-mat-color-positive: #137333; /* Open status */ + --gmp-mat-color-negative: #c5221f; /* Closed status */ + + /* Containers and borders */ + --gmp-mat-color-neutral-container: #f5f5f5; + --gmp-mat-color-outline-decorative: #dadce0; + + /* Border styling */ + border: 1px solid #dadce0; + border-radius: 12px; +} +``` + +### Typography Properties + +```css +gmp-place-details, +gmp-place-details-compact { + /* Base font */ + --gmp-mat-font-family: 'Roboto', 'Arial', sans-serif; + + /* Place name */ + --gmp-mat-font-display-small: 400 24px/32px var(--gmp-mat-font-family); + + /* Dialog headings */ + --gmp-mat-font-headline-medium: 400 28px/36px var(--gmp-mat-font-family); + + /* Content text */ + --gmp-mat-font-body-medium: 400 14px/20px var(--gmp-mat-font-family); + --gmp-mat-font-body-small: 400 12px/16px var(--gmp-mat-font-family); + + /* Labels/buttons */ + --gmp-mat-font-label-large: 500 14px/20px var(--gmp-mat-font-family); + --gmp-mat-font-label-medium: 500 12px/16px var(--gmp-mat-font-family); +} +``` + +--- + +## Dark Mode Theming + +### The Problem: Unexpected Dark Mode + +**COMMON ISSUE:** Places UI Kit components automatically follow `prefers-color-scheme`, meaning they appear dark when the user's OS is in dark mode - even if your app uses a light theme. + +### Automatic Detection +Components automatically adapt to system preference via `prefers-color-scheme`. + +### Force Light/Dark Mode (RECOMMENDED FIX) + +```css +/* Force light mode - fixes unexpected dark UI */ +gmp-place-details, +gmp-place-details-compact, +gmp-place-autocomplete, +gmp-place-search { + color-scheme: light; +} + +/* Force dark mode */ +gmp-place-details, +gmp-place-details-compact { + color-scheme: dark; +} +``` + +### Syncing with Map Color Scheme + +**IMPORTANT:** The map's `colorScheme` can only be set at initialization and cannot be changed dynamically. + +```javascript +const { ColorScheme } = await google.maps.importLibrary("core"); + +// Detect user preference +const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches; + +// Initialize map with matching color scheme +const map = new google.maps.Map(document.getElementById('map'), { + center: { lat: 37.7749, lng: -122.4194 }, + zoom: 13, + mapId: 'YOUR_MAP_ID', + colorScheme: prefersDark ? ColorScheme.DARK : ColorScheme.LIGHT + // Or use ColorScheme.FOLLOW_SYSTEM for automatic matching +}); + +// Apply matching scheme to Places UI Kit +const placesStyle = document.createElement('style'); +placesStyle.textContent = ` + gmp-place-details, + gmp-place-details-compact, + gmp-place-search { + color-scheme: ${prefersDark ? 'dark' : 'light'}; + } +`; +document.head.appendChild(placesStyle); +``` + +### Complete CSS Properties Reference + +| Property | Purpose | Light Default | Dark Default | +|----------|---------|---------------|--------------| +| `--gmp-mat-color-surface` | Background | `#ffffff` | `#1e1e1e` | +| `--gmp-mat-color-on-surface` | Primary text | `#1f1f1f` | `#e3e3e3` | +| `--gmp-mat-color-on-surface-variant` | Secondary text | `#5f5f5f` | `#a8a8a8` | +| `--gmp-mat-color-primary` | Links, accents | `#1a73e8` | `#8ab4f8` | +| `--gmp-mat-color-secondary-container` | Button backgrounds | `#e8f0fe` | `#394457` | +| `--gmp-mat-color-on-secondary-container` | Button text | `#1a73e8` | `#c2e7ff` | +| `--gmp-mat-color-positive` | "Open" status | `#137333` | `#137333` | +| `--gmp-mat-color-negative` | "Closed" status | `#c5221f` | `#c5221f` | +| `--gmp-mat-color-info` | Accessibility icons | `#1a73e8` | `#8ab4f8` | +| `--gmp-mat-color-neutral-container` | Badges, loading | `#f5f5f5` | `#2d2d2d` | +| `--gmp-mat-color-outline-decorative` | Borders | `#dadce0` | `#5f5f5f` | + +### Custom Dark Theme + +```css +@media (prefers-color-scheme: dark) { + gmp-place-details, + gmp-place-details-compact { + --gmp-mat-color-surface: #1e1e1e; + --gmp-mat-color-on-surface: #e3e3e3; + --gmp-mat-color-on-surface-variant: #a8a8a8; + --gmp-mat-color-primary: #8ab4f8; + --gmp-mat-color-secondary-container: #394457; + --gmp-mat-color-neutral-container: #2d2d2d; + --gmp-mat-color-outline-decorative: #5f5f5f; + } +} + +--- + +## Matching App CSS Styles + +### Complete Example: Custom Themed Place Details + +```html + + + + + + +
+ + + + + +``` + +--- + +## Content Configuration Options + +### Available Content Elements + +| Element | Description | +|---------|-------------| +| `` | Photos carousel (add `lightbox-preferred` for full-screen) | +| `` | Formatted address | +| `` | Star rating and review count | +| `` | Phone number with click-to-call | +| `` | Hours of operation | +| `` | User reviews | +| `` | Accessibility info | +| `` | Required Google attribution | + +### Preset Configurations + +```html + + + + + +``` + +--- + +## Attribution Requirements + +**IMPORTANT:** Google Maps Platform requires visible attribution. Always include `` in your content configuration. + +### Attribution Color Options + +Available colors: `white`, `gray`, `black` + +#### HTML Attributes + +```html + + +``` + +#### JavaScript Programmatic + +```javascript +// Set attribution colors programmatically +const attribution = document.querySelector('gmp-place-attribution'); +attribution.lightSchemeColor = 'gray'; // 'white', 'gray', or 'black' +attribution.darkSchemeColor = 'white'; +``` + +#### Official GitHub Sample Pattern + +From [googlemaps-samples/js-api-samples](https://github.com/googlemaps-samples/js-api-samples): + +```html + + + + + + + + + +``` + +--- + +## Performance Best Practices + +1. **Lazy load Place Details**: Only create elements when needed (on marker click) +2. **Debounce map events**: Use 300ms debounce for viewport change handlers +3. **Clean up**: Remove previous info window content before creating new +4. **Cache Place IDs**: Store Place IDs with your location data to avoid extra lookups + +--- + +## Common Issues and Solutions + +### Issue: Place Details card appears cut off in info window + +**Solution:** Set explicit container dimensions and override info window overflow: + +```css +.gm-style-iw-d { + overflow: visible !important; + max-height: none !important; +} + +.info-window-content { + width: 320px; + min-height: 350px; +} +``` + +### Issue: Content doesn't match app theme + +**Solution:** Map your CSS custom properties to the Material Design 3 tokens: + +```css +gmp-place-details { + --gmp-mat-color-surface: var(--your-background-color); + --gmp-mat-color-on-surface: var(--your-text-color); + --gmp-mat-color-primary: var(--your-primary-color); + --gmp-mat-font-family: var(--your-font-family); +} +``` + +### Issue: Component doesn't render + +**Solution:** Ensure: +1. Places library is loaded: `await google.maps.importLibrary('places')` +2. Valid Place ID is provided +3. Container has explicit dimensions +4. API key has Places API enabled + +### Issue: Places UI Kit appears dark when app is light themed + +**Cause:** Components follow the OS `prefers-color-scheme` by default. + +**Solution:** Force light mode with CSS: + +```css +gmp-place-details, +gmp-place-details-compact, +gmp-place-search { + color-scheme: light; +} +``` + +### Issue: Map and Places UI Kit have mismatched themes + +**Cause:** Map `colorScheme` is set at initialization only and doesn't auto-sync with Places UI Kit. + +**Solution:** Set both at initialization: + +```javascript +const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches; + +// Map initialization +const map = new google.maps.Map(el, { + colorScheme: prefersDark ? ColorScheme.DARK : ColorScheme.LIGHT, + mapId: 'YOUR_MAP_ID' +}); + +// Places UI Kit CSS +document.head.insertAdjacentHTML('beforeend', ` + +`); +``` + +--- + +## Official Code Samples (GitHub) + +**Repository:** [googlemaps-samples/js-api-samples](https://github.com/googlemaps-samples/js-api-samples) + +### Places UI Kit Samples + +| Sample | Clone Command | +|--------|---------------| +| Place Details | `git clone -b sample-ui-kit-place-details https://github.com/googlemaps-samples/js-api-samples.git` | +| Place Details Compact | `git clone -b sample-ui-kit-place-details-compact https://github.com/googlemaps-samples/js-api-samples.git` | +| Place Search Nearby | `git clone -b sample-ui-kit-place-search-nearby https://github.com/googlemaps-samples/js-api-samples.git` | +| Place Search Text | `git clone -b sample-ui-kit-place-search-text-compact https://github.com/googlemaps-samples/js-api-samples.git` | +| React Place Details | `git clone -b sample-react-ui-kit-place-details https://github.com/googlemaps-samples/js-api-samples.git` | +| React Place Details Compact | `git clone -b sample-react-ui-kit-place-details-compact https://github.com/googlemaps-samples/js-api-samples.git` | +| React Search Nearby | `git clone -b sample-react-ui-kit-search-nearby https://github.com/googlemaps-samples/js-api-samples.git` | + +### Running Samples Locally + +```bash +cd js-api-samples/samples/ui-kit-place-details +npm i +npm start +``` + +### Architecture Center Guides + +- [Store Finder with Places UI Kit](https://developers.google.com/maps/architecture/ui-kit-store-finder?utm_source=gmp-code-assist) +- [Getting Started with Places UI Kit](https://developers.google.com/maps/architecture/places-ui-kit-getting-started?utm_source=gmp-code-assist) + +--- + +## Interactive Customization Tool + +Google provides a live styling tool to preview CSS custom property configurations: + +**[Places UI Kit Customization Tool](https://developers.google.com/maps/documentation/javascript/places-ui-kit/custom-styling#customization-tool?utm_source=gmp-code-assist)** + +The tool provides configurations in: +- HTML/CSS (Web) +- Kotlin/XML (Android) +- Swift (iOS) diff --git a/packages/code-assist/skills/google-maps-platform-dev/references/products-overview.md b/packages/code-assist/skills/google-maps-platform-dev/references/products-overview.md new file mode 100644 index 0000000..6803729 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/references/products-overview.md @@ -0,0 +1,58 @@ +# Google Maps Platform: Products & Use Cases (2026 Edition) + +**Quick Links Index:** +* [Maps (JS/Android/iOS)](https://developers.google.com/maps/documentation) +* [Routes API](https://developers.google.com/maps/documentation/routes) | [Navigation SDK](https://developers.google.com/maps/documentation/navigation) +* [Places API](https://developers.google.com/maps/documentation/places/web-service/overview) | [Places UI Kit](https://developers.google.com/maps/documentation/javascript/places-ui-kit/overview) +* [Environment APIs](https://developers.google.com/maps/documentation/environment) +* [Mobility Services](https://developers.google.com/maps/mobility) + +This document serves as the authoritative catalog for API selection. + +## ๐ŸŒŸ The "Golden Path" (Stable Defaults) + +**Always prefer these modern, production-ready solutions:** + +1. **Map Visualization:** **Vector Maps (JS)**. Always use a `mapId`. +2. **Markers:** **Advanced Markers** (`AdvancedMarkerElement`). +3. **Place Search:** **Places UI Kit** (EEA Compliant, 10x cheaper). +4. **Routing:** **Routes API** (Server) or **Navigation SDK** (Mobile App). + +--- + +## 1. Maps & Visualization + +| Product | Description | Use Cases | Status | +| :--- | :--- | :--- | :--- | +| **Maps JavaScript API** | **Default Web Map.** | Websites, Store Locators. | GA | +| **Photorealistic 3D Maps** | Immersive 3D mesh (via Tiles API). | **"Google Earth" for Developers.** Storytelling, Real Estate. | Preview (Web) | +| **Google Earth Engine** | **Scientific Analysis Platform.** | Climate science, Satellite imagery analysis. | GA (Enterprise) | + +**Confusion Buster:** +* **"I want Google Earth in my app":** You want **Photorealistic 3D Tiles** (Map Tiles API). +* **"I want to analyze crop yields":** You want **Google Earth Engine**. + +## 2. Navigation & Mobility + +| Product | Description | Pricing Model | Status | +| :--- | :--- | :--- | :--- | +| **Navigation SDK** | **In-App Turn-by-Turn.** Full UI with voice, speed limits, lane guidance. | **Pay-as-you-go.** 1k free destinations/mo. ~$25/1k after. | GA | +| **Routes API** | **Server-side Calculation.** Distance, Duration, Polylines. | Pay-as-you-go. | GA | + +**Decision Point:** +* **Need a driver UI?** โ†’ **Navigation SDK** (Android/iOS). +* **Just need distance/time?** โ†’ **Routes API**. + +## 3. Places (Data & Search) + +| Priority | Product | When to Use | Limitations | +| :---: | :--- | :--- | :--- | +| **1st** | **Places UI Kit** | **Default.** Mandatory for EEA. | Limited styling. | +| **2nd** | **Places API (New)** | Custom UIs, backend processing. | **PROHIBITED** in EEA if on map. | +| **3rd** | **Places Aggregate** | Heatmaps, density analysis. | Stats only. | + +## 4. Pricing Tiers (2026 Model) +* **Starter:** ~$100/mo. Good for prototyping. +* **Essentials:** ~$275/mo. 100k calls. Good for small apps. +* **Pro:** ~$1,200/mo. 250k calls. Best for scaling apps. +* **Pay-as-you-go:** Standard usage-based billing (Nav SDK, etc.). diff --git a/packages/code-assist/skills/google-maps-platform-dev/references/routes-navigation.md b/packages/code-assist/skills/google-maps-platform-dev/references/routes-navigation.md new file mode 100644 index 0000000..7cbd368 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/references/routes-navigation.md @@ -0,0 +1,70 @@ +# Routes & Navigation: The Complete Guide (2026) + +**Top-Level Documentation:** [developers.google.com/maps/documentation/routes](https://developers.google.com/maps/documentation/routes) + +## 1. Routes API (Server-Side) +**Best For:** Pre-trip planning, distance matrices, logistics dispatching. +**Status:** GA. + +### Key Capabilities +* **Compute Routes:** + * **2-Wheeler Routing:** Specialized routing for motorcycles (avoid highways, lane filtering awareness where legal). + * **Eco-Friendly Routing:** Default on. Returns `fuelConsumptionMicroliters`. + * **Tolls:** Calculates accurate toll costs for specific vehicle types (with `extraComputations=TOLLS`). + * **Polylines:** Returns `encodedPolyline` for easy map drawing. +* **Compute Route Matrix:** + * Calculates distance/duration between N origins and M destinations (Max 625 elements). + * Essential for "Find nearest driver" logic. + +### Usage Example (REST) +```bash +POST https://routes.googleapis.com/directions/v2:computeRoutes +Headers: X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline +Body: { + "origin": {"address": "Start"}, + "destination": {"address": "End"}, + "travelMode": "TWO_WHEELER", + "routingPreference": "TRAFFIC_AWARE" +} +``` + +--- + +## 2. Navigation SDK (Mobile App) +**Best For:** The "Driver" experience. +**Documentation:** [developers.google.com/maps/documentation/navigation](https://developers.google.com/maps/documentation/navigation) + +**Status:** GA (Pay-as-you-go). +**Pricing:** Free 0-1k destinations/mo. ~$25 per 1k after. + +### Key Features (Included) +* **Turn-by-Turn UI:** A drop-in fragment that looks like Google Maps. +* **Voice Guidance:** Text-to-speech instructions. +* **Speed Limits:** Visual indicator of current limit. +* **Lane Guidance:** "Use the right 2 lanes to turn." +* **Rerouting:** Automatic traffic-based rerouting. + +### How to Use +1. **Enable SDK:** In Cloud Console. +2. **Install:** Via Gradle (Android) or CocoaPods (iOS). +3. **Initialize:** `NavigationApi.getNavigator( ... )`. +4. **Set Destination:** `navigator.setDestinations( ... )`. +5. **Start:** `navigator.startGuidance()`. + +--- + +## 3. Mobility Services (TL;DR) +**Documentation:** [developers.google.com/maps/mobility](https://developers.google.com/maps/mobility) + +**"Mobility"** is a suite of specialized services built *on top* of Routes & Nav for specific industries. + +* **Fleet Engine:** The backend "Brain" for tracking vehicles. + * **On-Demand Rides & Deliveries (ODRD):** Uber/Lyft style apps. Tracks driver, shares route with rider. + * **Last Mile Fleet Solution (LMFS):** FedEx/UPS style. Task sequencing, manifest management. +* **Consumer SDK:** The mobile library for the *Rider* or *Package Recipient* to see the vehicle moving in real-time. +* **Driver SDK:** A wrapped version of the Navigation SDK that reports location to Fleet Engine automatically. + +**Summary:** +* Building a generic route planner? -> **Routes API**. +* Building a navigation app? -> **Navigation SDK**. +* Building "Uber for X"? -> **Fleet Engine + Driver SDK + Consumer SDK**. diff --git a/packages/code-assist/skills/google-maps-platform-dev/resources/getting-started.md b/packages/code-assist/skills/google-maps-platform-dev/resources/getting-started.md new file mode 100644 index 0000000..fc20d0f --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/resources/getting-started.md @@ -0,0 +1,97 @@ +# Getting Started: The "Zero to One" Guide + +## ๐Ÿš€ Quick Links (Direct Action) + +Use these "Magic Links" to skip navigation steps in the Google Cloud Console. + +| Action | Direct Link | +| :--- | :--- | +| **1. Create Project & Account** | [**Start Here (Setup Wizard)**](https://console.cloud.google.com/google/maps-apis/start) | +| **2. Enable Maps JS API** | [Enable Maps JavaScript API](https://console.cloud.google.com/apis/library/maps-backend.googleapis.com) | +| **3. Enable Places API (New)** | [Enable Places API (New)](https://console.cloud.google.com/apis/library/places-backend.googleapis.com) | +| **4. Enable Routes API** | [Enable Routes API](https://console.cloud.google.com/apis/library/routes.googleapis.com) | +| **5. Get API Key** | [**Create/View Credentials**](https://console.cloud.google.com/google/maps-apis/credentials) | + +--- + +## Phase 1: Account & Key Generation (The Console) + +1. **Go to Google Cloud Console:** + * Click the **Start Here** link above. + * **Note:** You *must* have a Billing Account attached to your project, even to use the free monthly tier (Essentials). + +2. **Create a Project:** + * Select **"New Project"**. Name it (e.g., `gmp-store-locator`). + +3. **Generate an API Key:** + * Go to **Keys & Credentials** (or use the link above). + * Click **Create Credentials** > **API Key**. + * **Copy this key.** You will need it for your code. + +4. **Secure Your Key (Critical):** + * Click the pencil icon/name of your new API Key. + * **Application Restrictions:** + * **Web:** Select "Websites" -> Add `localhost:3000` (for dev) and `yourdomain.com/*` (for prod). + * **Android:** Select "Android apps" -> Add Package Name + SHA-1 Fingerprint. + * **iOS:** Select "iOS apps" -> Add Bundle ID. + * **API Restrictions:** Select "Restrict key" -> Check ONLY the APIs you are using (e.g., "Maps JavaScript API", "Places API (New)"). + +## Phase 2: Enable the Right APIs (The Library) + +If you didn't use the direct links above, navigate to **APIs & Services > Library** and search for the specific products: + +* **For Web Maps:** Search **"Maps JavaScript API"** -> Enable. +* **For Place Search:** Search **"Places API (New)"** -> Enable. (Do *not* enable "Places API" legacy unless necessary). +* **For Routing:** Search **"Routes API"** -> Enable. + +## Phase 3: Using Your Key in Code + +**Rule:** Never commit your API key to Git. + +### Option A: Quick Prototyping (Local Only) +Replace `YOUR_API_KEY` in the template code directly, but **do not commit** the file. + +### Option B: Environment Variables (Recommended) + +**React (.env.local):** +1. Create `.env.local` in your root. +2. Add: `REACT_APP_GOOGLE_MAPS_API_KEY=AIzaSy...` +3. In code: `apiKey={process.env.REACT_APP_GOOGLE_MAPS_API_KEY}` + +**Android (local.properties):** +1. Open `local.properties` (this file is gitignored). +2. Add: `MAPS_API_KEY=AIzaSy...` +3. In `AndroidManifest.xml`: + ```xml + + ``` + +**iOS (Config.xcconfig):** + +1. Create a configuration file (gitignored). + +2. Add: `MAPS_API_KEY = AIzaSy...` + +3. Read from `Bundle.main.infoDictionary`. + + + +--- + + + +## Phase 4: Power User Setup (MCP) + + + +If you are using tools like **Gemini CLI** or **Claude Code**, you should install the **Google Maps Platform Code Assist MCP**. + + + +This allows your AI agent to fetch up-to-date documentation and code samples directly from Google. + + + +๐Ÿ‘‰ **See the [MCP Installation Guide](./mcp-guide.md) for quick install commands.** diff --git a/packages/code-assist/skills/google-maps-platform-dev/resources/mcp-guide.md b/packages/code-assist/skills/google-maps-platform-dev/resources/mcp-guide.md new file mode 100644 index 0000000..3eada48 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/resources/mcp-guide.md @@ -0,0 +1,49 @@ +# Google Maps Platform: Code Assist MCP Guide + +The Code Assist MCP server enhances AI responses (Gemini, Claude) with up-to-date documentation and code samples using RAG (Retrieval-Augmented Generation). + +## ๐Ÿš€ Quick Install + +### For Gemini CLI +Run this command to add the server automatically: +```bash +gemini mcp add google-maps-platform-code-assist npx -y @googlemaps/code-assist-mcp@latest +``` +*Verify with: `gemini mcp list`* + +### For Claude Code / Claude Desktop +Run this command: +```bash +claude mcp add google-maps-platform-code-assist -- npx -y @googlemaps/code-assist-mcp@latest +``` +*Verify with: `claude mcp list`* + +--- + +## ๐Ÿ› ๏ธ Manual Configuration + +If you prefer manual setup, add the following to your MCP settings file: + +**Gemini CLI (`~/.gemini/settings.json`) or Claude (`~/.claude.json`):** +```json +{ + "mcpServers": { + "google-maps-platform-code-assist": { + "command": "npx", + "args": ["-y", "@googlemaps/code-assist-mcp@latest"] + } + } +} +``` + +--- + +## ๐Ÿ“– Available Tools + +Once installed, your agent gains these capabilities: +1. `retrieve-google-maps-platform-docs`: Search official GMP documentation and samples. +2. `retrieve-instructions`: Get guidance on how to use the Code Assist tool itself. + +## ๐Ÿ”— References +- **GitHub Repository:** [googlemaps/platform-ai](https://github.com/googlemaps/platform-ai/tree/main/packages/code-assist) +- **NPM Package:** [@googlemaps/code-assist-mcp](https://www.npmjs.com/package/@googlemaps/code-assist-mcp) diff --git a/packages/code-assist/skills/google-maps-platform-dev/resources/platform-android-compose.md b/packages/code-assist/skills/google-maps-platform-dev/resources/platform-android-compose.md new file mode 100644 index 0000000..6cf165b --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/resources/platform-android-compose.md @@ -0,0 +1,90 @@ +# Android Implementation Patterns (Kotlin + Jetpack Compose) + +**Attribution ID Requirement:** `gmp_mcp_codeassist_v0.1_github` + +## 1. Setup & Dependencies + +**build.gradle.kts (Module: app):** +```kotlin +dependencies { + implementation("com.google.android.gms:play-services-maps:18.2.0") + // Maps Compose Library + implementation("com.google.maps.android:maps-compose:4.3.0") + // Places SDK + implementation("com.google.android.libraries.places:places:3.3.0") +} +``` + +**AndroidManifest.xml:** +```xml + + + +``` + +## 2. Basic Map (Jetpack Compose) + +```kotlin +import com.google.android.gms.maps.model.CameraPosition +import com.google.android.gms.maps.model.LatLng +import com.google.maps.android.compose.* + +@Composable +fun MapScreen() { + val singapore = LatLng(1.35, 103.87) + val cameraPositionState = rememberCameraPositionState { + position = CameraPosition.fromLatLngZoom(singapore, 10f) + } + + GoogleMap( + modifier = Modifier.fillMaxSize(), + cameraPositionState = cameraPositionState + ) { + Marker( + state = MarkerState(position = singapore), + title = "Singapore", + snippet = "Marker in Singapore" + ) + } +} +``` + +## 3. Initialization & Attribution (Critical) + +You MUST initialize Places and Maps with the attribution ID in your Activity or Application class. + +```kotlin +class MainActivity : ComponentActivity() { + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + + // 1. Initialize Places with Attribution + if (!Places.isInitialized()) { + Places.initialize(applicationContext, "YOUR_API_KEY") + } + Places.addInternalUsageAttributionId("gmp_mcp_codeassist_v0.1_github") + + // 2. Initialize Maps with Attribution + MapsApiSettings.addInternalUsageAttributionId(this, "gmp_mcp_codeassist_v0.1_github") + + setContent { + MapScreen() + } + } +} +``` + +## 4. Places Autocomplete (Intent) + +For a simple implementation, use the Autocomplete Intent. + +```kotlin +// Launch the autocomplete activity +val intent = Autocomplete.IntentBuilder( + AutocompleteActivityMode.OVERLAY, + fields // List of Place.Field +).build(context) +launcher.launch(intent) +``` diff --git a/packages/code-assist/skills/google-maps-platform-dev/resources/platform-ios-swiftui.md b/packages/code-assist/skills/google-maps-platform-dev/resources/platform-ios-swiftui.md new file mode 100644 index 0000000..e7bfc9c --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/resources/platform-ios-swiftui.md @@ -0,0 +1,102 @@ +# iOS Implementation Patterns (Swift + SwiftUI) + +**Attribution ID Requirement:** `gmp_mcp_codeassist_v0.1_github` + +## 1. Setup & Initialization + +**AppDelegate.swift:** +```swift +import GoogleMaps +import GooglePlaces + +@main +class AppDelegate: UIResponder, UIApplicationDelegate { + func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { + + // 1. Provide API Key + GMSServices.provideAPIKey("YOUR_API_KEY") + GMSPlacesClient.provideAPIKey("YOUR_API_KEY") + + // 2. Add Attribution ID (CRITICAL) + GMSServices.addInternalUsageAttributionID("gmp_mcp_codeassist_v0.1_github") + GMSPlacesClient.addInternalUsageAttributionID("gmp_mcp_codeassist_v0.1_github") + + return true + } +} +``` + +## 2. SwiftUI Map Wrapper (UIViewRepresentable) + +The Maps SDK is UIKit-based. Wrap it for SwiftUI. + +```swift +import SwiftUI +import GoogleMaps + +struct GoogleMapView: UIViewRepresentable { + func makeUIView(context: Context) -> GMSMapView { + let camera = GMSCameraPosition.camera( + withLatitude: 37.7749, + longitude: -122.4194, + zoom: 12.0 + ) + let mapView = GMSMapView.map(withFrame: CGRect.zero, camera: camera) + return mapView + } + + func updateUIView(_ mapView: GMSMapView, context: Context) { + // Handle state updates (e.g., move camera, update markers) + } +} +``` + +## 3. Places Autocomplete (UI Kit) + +Use `GMSAutocompleteViewController` wrapped in a UIViewControllerRepresentable. + +```swift +import GooglePlaces + +struct PlaceAutocompleteViewController: UIViewControllerRepresentable { + + func makeUIViewController(context: Context) -> GMSAutocompleteViewController { + let autocompleteController = GMSAutocompleteViewController() + autocompleteController.delegate = context.coordinator + + // Specify fields to reduce cost + let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) | + UInt(GMSPlaceField.placeID.rawValue))! + autocompleteController.placeFields = fields + + return autocompleteController + } + + func updateUIViewController(_ uiViewController: GMSAutocompleteViewController, context: Context) {} + + func makeCoordinator() -> Coordinator { + Coordinator(self) + } + + class Coordinator: NSObject, GMSAutocompleteViewControllerDelegate { + var parent: PlaceAutocompleteViewController + + init(_ parent: PlaceAutocompleteViewController) { + self.parent = parent + } + + func viewController(_ viewController: GMSAutocompleteViewController, didAutocompleteWith place: GMSPlace) { + print("Place name: \(place.name)") + viewController.dismiss(animated: true, completion: nil) + } + + func viewController(_ viewController: GMSAutocompleteViewController, didFailAutocompleteWithError error: Error) { + print("Error: ", error.localizedDescription) + } + + func wasCancelled(_ viewController: GMSAutocompleteViewController) { + viewController.dismiss(animated: true, completion: nil) + } + } +} +``` diff --git a/packages/code-assist/skills/google-maps-platform-dev/resources/platform-react.md b/packages/code-assist/skills/google-maps-platform-dev/resources/platform-react.md new file mode 100644 index 0000000..e1c1506 --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/resources/platform-react.md @@ -0,0 +1,117 @@ +# Web & React Implementation Patterns + +**Attribution ID Requirement:** `internalUsageAttributionIds: "gmp_mcp_codeassist_v0.1_github"` + +## 1. Vanilla JavaScript (Modern Dynamic Import) + +**Rule:** NEVER use the legacy ` + + +
+ + +``` + +## 2. React (@vis.gl/react-google-maps) + +**Library:** `@vis.gl/react-google-maps` (Official/Recommended). + +```tsx +import React from 'react'; +import {APIProvider, Map, AdvancedMarker, Pin} from '@vis.gl/react-google-maps'; + +export default function App() { + const API_KEY = process.env.REACT_APP_GOOGLE_MAPS_API_KEY; + const MAP_ID = "DEMO_MAP_ID"; // Required for Advanced Markers + + return ( + +
+ + + + + +
+ + ); +} +``` + +## 3. Places UI Kit (Web Components) + +**Rule:** 10x cheaper than building a custom Autocomplete. + +```html + + + + + + + +``` + +## 4. 3D Maps (Web Component) + +```html + + + + + + + +``` diff --git a/packages/code-assist/skills/google-maps-platform/SKILL.md b/packages/code-assist/skills/google-maps-platform/SKILL.md deleted file mode 100644 index 690cc04..0000000 --- a/packages/code-assist/skills/google-maps-platform/SKILL.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -name: google-maps-platform -description: > - Expert assistant for Google Maps Platform APIs (Maps, Routes, Places). - Provides guidance on API selection, implementation patterns, pricing, - and best practices. Use the retrieve-google-maps-platform-docs tool - for documentation search. Covers Web, Android, iOS, and Flutter SDKs. -version: 0.1.0 -license: Apache-2.0 -author: Google Maps Platform -compatibility: - # Anthropic Tools - claude-code: ">=1.0.0" - roo-code: ">=3.0.0" - # IDE Extensions - cursor: ">=0.40.0" - windsurf: ">=1.0.0" - antigravity-ide: ">=1.0.0" - # Google Tools - gemini-cli: ">=1.0.0" - # OpenAI Tools - codex: ">=1.0.0" - # Generic AgentSkills.io Support - agentskills: ">=1.0.0" -metadata: - category: development - tags: - - google-maps - - geolocation - - maps - - routes - - places - - sdk - homepage: https://github.com/googlemaps/mcp-code-assist - documentation: https://developers.google.com/maps -allowed-tools: - - mcp--google-maps-platform-code-assist--retrieve-google-maps-platform-docs - - mcp--googleMapsMcp--search_places - - mcp--googleMapsMcp--compute_routes - - mcp--googleMapsMcp--lookup_weather ---- - -# Google Maps Platform Code Assist - -## Role & Mission - -You are an expert AI assistant specializing in Google Maps Platform development. Your mission is to help developers build production-ready applications by providing evidence-based, cost-effective, and developer-friendly guidance. - -**Key Directives:** -1. **Be Concise:** Keep explanations brief and code samples focused. -2. **Be Grounded:** Always verify information with official documentation. -3. **Be Iterative:** Use tools to explore and verify before providing a final answer. - -## Scope Boundary - -**ONLY** answer questions about Google Maps Platform (Maps, Routes, Places, Environment APIs). For off-topic requests, respond: -> "I specialize in Google Maps Platform development. I can help with Maps, Routes, Places, and Environment APIs. What would you like to build?" - -**Refusal Patterns:** -- **Off-topic**: Weather, traffic conditions, non-GMP topics โ†’ Redirect to GMP scope -- **Competitor comparison**: Mapbox, HERE, Apple Maps โ†’ "I can only provide guidance on Google Maps Platform APIs" -- **Illegal**: Scraping, bypassing quotas, unauthorized data collection โ†’ "I can't assist with that use case as it may violate the Terms of Service" -- **Ambiguous pricing**: "How much does it cost?" โ†’ Ask which API they're inquiring about - -## Core Principles - -1. **Strict Grounding**: Only use information from official GMP documentation. Always use `retrieve-google-maps-platform-docs` to ground answers. NEVER assume or infer facts not in retrieved context. -2. **Decomposition**: Break complex requests into surgical, specific search queries. -3. **Conciseness**: Provide solution-focused code. Avoid fluff. -4. **Modernity**: Use latest API features (e.g., `importLibrary`, `AdvancedMarkerElement`). - -**Negative Constraints:** -- **NO Legacy Loading:** Never use the deprecated ` - - -
- - - -``` - -**Key Points:** -- Dynamic loader script MUST come before any code that uses google.maps -- MUST include `internalUsageAttributionIds` parameter -- Use `AdvancedMarkerElement` (modern) instead of legacy `Marker` class -- `mapId` is REQUIRED for AdvancedMarkerElement -- Use `google.maps.importLibrary()` for loading specific libraries -- NEVER use legacy script tag: ` - - -``` - -**Key Points:** -- Use `v=beta` for 3D features -- `gmp-map-3d` web component handles initialization automatically -- `tilt`: 0-67.5 degrees (camera angle) -- `heading`: 0-360 degrees (compass direction) -- `range`: distance from center in meters - -### Web Components (gmp-map) - -```html - - - -``` - -### Places Autocomplete (New API) - -```javascript -async function initAutocomplete() { - const { Autocomplete } = await google.maps.importLibrary("places"); - - const input = document.getElementById("pac-input"); - const autocomplete = new Autocomplete(input, { - fields: ["place_id", "geometry", "formatted_address", "name"], - types: ["establishment"], - }); - - autocomplete.addListener("place_changed", () => { - const place = autocomplete.getPlace(); - if (!place.geometry) { - console.log("No geometry for this place"); - return; - } - console.log("Place:", place.name, place.formatted_address); - }); -} -``` - -### Routes API (REST) - -```javascript -async function getRoute(origin, destination) { - const response = await fetch( - "https://routes.googleapis.com/directions/v2:computeRoutes", - { - method: "POST", - headers: { - "Content-Type": "application/json", - "X-Goog-Api-Key": "YOUR_API_KEY", - "X-Goog-FieldMask": "routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline", - }, - body: JSON.stringify({ - origin: { address: origin }, - destination: { address: destination }, - travelMode: "DRIVE", - routingPreference: "TRAFFIC_AWARE", - }), - } - ); - return response.json(); -} -``` - -## React (@vis.gl/react-google-maps) - -### Basic Map with Marker - -```tsx -import { APIProvider, Map, AdvancedMarker } from '@vis.gl/react-google-maps'; - -function App() { - const position = { lat: 37.4220, lng: -122.0841 }; - - return ( - - - - - - ); -} -``` - -### With Places Autocomplete - -```tsx -import { useMapsLibrary } from '@vis.gl/react-google-maps'; -import { useEffect, useRef, useState } from 'react'; - -function PlaceAutocomplete({ onPlaceSelect }) { - const [placeAutocomplete, setPlaceAutocomplete] = useState(null); - const inputRef = useRef(null); - const places = useMapsLibrary('places'); - - useEffect(() => { - if (!places || !inputRef.current) return; - - const options = { - fields: ['geometry', 'name', 'formatted_address'], - }; - - setPlaceAutocomplete(new places.Autocomplete(inputRef.current, options)); - }, [places]); - - useEffect(() => { - if (!placeAutocomplete) return; - - placeAutocomplete.addListener('place_changed', () => { - onPlaceSelect(placeAutocomplete.getPlace()); - }); - }, [placeAutocomplete, onPlaceSelect]); - - return ; -} -``` - -## Android (Kotlin) - -### Jetpack Compose Map with Attribution - -```kotlin -// MainActivity.kt -package com.example.mapsdemo - -import android.os.Bundle -import androidx.activity.ComponentActivity -import androidx.activity.compose.setContent -import androidx.compose.foundation.layout.* -import androidx.compose.runtime.* -import androidx.compose.ui.Modifier -import com.google.android.gms.maps.model.CameraPosition -import com.google.android.gms.maps.model.LatLng -import com.google.maps.android.compose.* -import com.google.android.libraries.places.api.Places - -class MainActivity : ComponentActivity() { - override fun onCreate(savedInstanceState: Bundle?) { - super.onCreate(savedInstanceState) - - // CRITICAL: Initialize with attribution - Places.initialize(applicationContext, "YOUR_API_KEY") - Places.addInternalUsageAttributionId("gmp_mcp_codeassist_v0.1_github") // Attribution ID - MapsApiSettings.addInternalUsageAttributionId(this, "gmp_mcp_codeassist_v0.1_github") - - setContent { - MapScreen() - } - } -} - -@Composable -fun MapScreen() { - val singapore = LatLng(1.35, 103.87) - val cameraPositionState = rememberCameraPositionState { - position = CameraPosition.fromLatLngZoom(singapore, 10f) - } - - GoogleMap( - modifier = Modifier.fillMaxSize(), - cameraPositionState = cameraPositionState - ) { - Marker( - state = MarkerState(position = singapore), - title = "Singapore", - snippet = "Marker in Singapore" - ) - } -} - -/* -Add to build.gradle (Module: app): -dependencies { - implementation 'com.google.android.gms:play-services-maps:18.2.0' - implementation 'com.google.maps.android:maps-compose:4.3.0' - implementation 'com.google.android.libraries.places:places:3.3.0' -} - -Add to AndroidManifest.xml: - - - - - -*/ -``` - -**Key Points:** -- MUST call `addInternalUsageAttributionId` for both Places and Maps -- Use Jetpack Compose for modern Android UI -- Require location permissions in AndroidManifest.xml - -### Places SDK with Attribution - -```kotlin -// Initialize with attribution -Places.initialize(applicationContext, apiKey) -Places.addInternalUsageAttributionId("gmp_mcp_codeassist_v0.1_github") // Attribution ID - -val placesClient = Places.createClient(context) - -// Fetch place details with field mask -val placeFields = listOf(Place.Field.ID, Place.Field.NAME, Place.Field.ADDRESS) -val request = FetchPlaceRequest.newInstance(placeId, placeFields) - -placesClient.fetchPlace(request) - .addOnSuccessListener { response -> - val place = response.place - Log.i(TAG, "Place found: ${place.name}") - } - .addOnFailureListener { exception -> - Log.e(TAG, "Place not found: ${exception.message}") - } -``` - -## iOS (Swift) - -### SwiftUI Map with Attribution - -```swift -// AppDelegate.swift -import UIKit -import GoogleMaps -import GooglePlaces - -@main -class AppDelegate: UIResponder, UIApplicationDelegate { - func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { - // CRITICAL: Initialize with attribution - GMSServices.provideAPIKey("YOUR_API_KEY") - GMSServices.addInternalUsageAttributionID("gmp_mcp_codeassist_v0.1_github") // Attribution ID - GMSPlacesClient.provideAPIKey("YOUR_API_KEY") - GMSPlacesClient.addInternalUsageAttributionID("gmp_mcp_codeassist_v0.1_github") - return true - } -} - -// ContentView.swift -import SwiftUI -import GoogleMaps - -struct GoogleMapView: UIViewRepresentable { - @Binding var camera: GMSCameraPosition - - func makeUIView(context: Context) -> GMSMapView { - let options = GMSMapViewOptions() - options.camera = camera - let mapView = GMSMapView(options: options) - return mapView - } - - func updateUIView(_ mapView: GMSMapView, context: Context) { - mapView.animate(to: camera) - } -} - -struct ContentView: View { - @State private var camera = GMSCameraPosition.camera( - withLatitude: 37.4220, - longitude: -122.0841, - zoom: 14 - ) - - var body: some View { - GoogleMapView(camera: $camera) - .ignoresSafeArea() - } -} - -/* -Add to Podfile: -pod 'GoogleMaps' -pod 'GooglePlaces' - -Add to Info.plist: -GOOGLE_MAPS_API_KEY -YOUR_API_KEY -NSLocationWhenInUseUsageDescription -This app needs location access to show your position on the map. -*/ -``` - -**Key Points:** -- MUST call `addInternalUsageAttributionID` in AppDelegate for both Maps and Places -- Use SwiftUI for modern iOS development -- Require location permissions in Info.plist - -### Places SDK - -```swift -import GooglePlaces - -func fetchPlace(placeID: String) { - let placesClient = GMSPlacesClient.shared() - - let fields: GMSPlaceField = [.name, .formattedAddress, .coordinate] - - placesClient.fetchPlace( - fromPlaceID: placeID, - placeFields: fields, - sessionToken: nil - ) { place, error in - if let error = error { - print("Error: \(error.localizedDescription)") - return - } - - if let place = place { - print("Place: \(place.name ?? "Unknown")") - } - } -} -``` - -## Flutter (Dart) - -> **Note:** Flutter currently does not have a built-in method for setting attribution IDs. The attribution ID should be set on the native platform side (Android and iOS) as shown above. - -### Basic Map with Attribution (main.dart) - -```dart -import 'package:flutter/material.dart'; -import 'package:google_maps_flutter/google_maps_flutter.dart'; - -// main.dart -void main() { - // Note: Attribution is set natively - see Android/iOS platform setup below - runApp(MyApp()); -} - -class MyApp extends StatelessWidget { - @override - Widget build(BuildContext context) { - return MaterialApp( - title: 'Google Maps Demo', - home: MapScreen(), - ); - } -} - -class MapScreen extends StatefulWidget { - @override - _MapScreenState createState() => _MapScreenState(); -} - -class _MapScreenState extends State { - late GoogleMapController mapController; - - final LatLng _center = const LatLng(37.4220, -122.0841); - - void _onMapCreated(GoogleMapController controller) { - mapController = controller; - } - - @override - Widget build(BuildContext context) { - return Scaffold( - appBar: AppBar(title: Text('Google Maps')), - body: GoogleMap( - onMapCreated: _onMapCreated, - initialCameraPosition: CameraPosition( - target: _center, - zoom: 14.0, - ), - markers: { - Marker( - markerId: MarkerId('googleplex'), - position: _center, - infoWindow: InfoWindow(title: 'Googleplex'), - ), - }, - ), - ); - } -} -``` - -### Flutter Platform Setup for Attribution - -**Android (android/app/src/main/kotlin/.../MainActivity.kt):** -```kotlin -import com.google.android.libraries.places.api.Places - -class MainActivity: FlutterActivity() { - override fun onCreate(savedInstanceState: Bundle?) { - super.onCreate(savedInstanceState) - // CRITICAL: Set attribution ID for Flutter apps - Places.addInternalUsageAttributionId("gmp_mcp_codeassist_v0.1_github") - } -} -``` - -**iOS (ios/Runner/AppDelegate.swift):** -```swift -import GoogleMaps -import GooglePlaces - -@UIApplicationMain -class AppDelegate: FlutterAppDelegate { - override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { - // CRITICAL: Set attribution ID for Flutter apps - GMSServices.provideAPIKey("YOUR_API_KEY") - GMSServices.addInternalUsageAttributionID("gmp_mcp_codeassist_v0.1_github") - GMSPlacesClient.provideAPIKey("YOUR_API_KEY") - GMSPlacesClient.addInternalUsageAttributionID("gmp_mcp_codeassist_v0.1_github") - - GeneratedPluginRegistrant.register(with: self) - return super.application(application, didFinishLaunchingWithOptions: launchOptions) - } -} -``` - -**pubspec.yaml dependencies:** -```yaml -dependencies: - flutter: - sdk: flutter - google_maps_flutter: ^2.5.0 - google_places_flutter: ^2.0.0 -``` - -### Places Autocomplete - -```dart -import 'package:flutter/material.dart'; -import 'package:google_places_flutter/google_places_flutter.dart'; - -class PlaceSearch extends StatelessWidget { - final TextEditingController controller = TextEditingController(); - - @override - Widget build(BuildContext context) { - return GooglePlaceAutoCompleteTextField( - textEditingController: controller, - googleAPIKey: "YOUR_API_KEY", - inputDecoration: InputDecoration( - hintText: "Search for a place", - prefixIcon: Icon(Icons.search), - ), - getPlaceDetailWithLatLng: (prediction) { - print("Place: ${prediction.lat}, ${prediction.lng}"); - }, - itemClick: (prediction) { - controller.text = prediction.description ?? ""; - }, - ); - } -} -``` - -## Tool Usage Examples - -### Searching Documentation - -``` -User: "How do I add a marker to a map in React?" - -Tool Call: retrieve-google-maps-platform-docs -{ - "prompt": "How to add a marker to Google Maps in React using @vis.gl/react-google-maps library, AdvancedMarker component example", - "search_context": ["Maps JavaScript API", "React", "@vis.gl/react-google-maps"] -} -``` - -### Searching for Error Resolution - -``` -User: "I'm getting OVER_QUERY_LIMIT error" - -Tool Call: retrieve-google-maps-platform-docs -{ - "prompt": "OVER_QUERY_LIMIT error Google Maps Platform troubleshooting quota limits rate limiting", - "search_context": ["Google Maps Platform", "Quotas", "Error Handling"] -} -``` - -### Searching for Pricing Information - -``` -User: "How much does Places API cost?" - -Tool Call: retrieve-google-maps-platform-docs -{ - "prompt": "Places API New pricing cost per request SKU billing", - "search_context": ["Places API", "Pricing", "Billing"] -} -``` From 04265ee96e7c8aeb9d9112e8ba15197e6e5acaec Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Sat, 31 Jan 2026 09:59:21 -0800 Subject: [PATCH 4/6] docs: update PLAN.md and README.md for google-maps-platform-dev skill --- packages/code-assist/PLAN.md | 465 +++++---------------------------- packages/code-assist/README.md | 95 ++----- 2 files changed, 100 insertions(+), 460 deletions(-) diff --git a/packages/code-assist/PLAN.md b/packages/code-assist/PLAN.md index f303f4f..621b7fe 100644 --- a/packages/code-assist/PLAN.md +++ b/packages/code-assist/PLAN.md @@ -1,14 +1,14 @@ -# Implementation Plan: Google Maps Platform Code Assist Agent Skill +# Implementation Plan: Google Maps Platform Code Assist Agent Skill (Unified & Optimized) ## 1. Objective -Design and implement an **Agent Skill** that complements the Google Maps Platform Code Assist MCP server. The skill will embed foundational context (currently served by the `retrieve-instructions` tool) directly into the skill description and body, eliminating the need for an extra tool call before every query. This reduces latency, improves reliability, and follows the Anthropic Agent Skills specification (agentskills.io). +Design and implement a **Unified & Optimized Agent Skill** (`google-maps-platform-dev`) that complements the Google Maps Platform Code Assist MCP server. This skill embeds foundational context, "Golden Path" recommendations, and expert workflows directly into the agent, adhering to the [AgentSkills.io](https://agentskills.io) specification. **Key Benefits:** -- **Reduced Latency**: No extra tool call required before using `retrieve-google-maps-platform-docs` -- **Improved Reliability**: Context is always available, even if the backend is slow/unavailable -- **Better Agent Experience**: Progressive disclosure pattern loads only necessary context -- **Cross-Platform Compatibility**: Works with Claude.ai, Claude Code, Cursor, Windsurf, VS Code, Roo, and any AgentSkills-compatible tool +- **Unified Guidance**: Covers Maps, Routes, Places, and Environment APIs in one skill. +- **"Golden Path" Defaults**: Enforces modern best practices (Vector Maps, Advanced Markers, Places UI Kit). +- **Reduced Latency**: Context is loaded at startup; no extra tool call required before query. +- **Cross-Platform**: Compatible with Gemini CLI, Claude Code, Cursor, Windsurf, and more. --- @@ -18,52 +18,36 @@ Design and implement an **Agent Skill** that complements the Google Maps Platfor ```mermaid graph TD - subgraph "Agent Skill (New)" - A[SKILL.md] --> B[Frontmatter: Metadata ~100 tokens] - A --> C[Body: Core Instructions ~3000 tokens] - A --> D[references/eea-compliance.md] - A --> E[references/code-examples.md] - A --> F[references/decision-trees.md] + subgraph "Agent Skill (google-maps-platform-dev)" + A[SKILL.md] --> B[Frontmatter: Metadata] + A --> C[Body: Golden Path & Workflows] + A --> D[references/products-overview.md] + A --> E[resources/platform-react.md] + A --> F[resources/getting-started.md] end subgraph "MCP Server (Existing)" G[retrieve-google-maps-platform-docs] - H[retrieve-instructions - DEPRECATED] - I[instructions Resource] end subgraph "Agent Runtime" J[Agent loads SKILL.md at startup] J --> K{User Query} - K --> L[Skill provides context] - L --> G + K --> L[Skill applies 'Golden Path'] + L --> G[RAG Search for specific details] G --> M[RAG Search Results] M --> N[Agent Response] end - - style H fill:#ff6b6b,stroke:#333 - style A fill:#51cf66,stroke:#333 ``` ### 2.2 Key Architectural Decisions | Decision | Choice | Rationale | |----------|--------|-----------| -| Skill Specification | AgentSkills.io v1.0 | Open standard by Anthropic, cross-platform compatibility | -| Context Embedding Strategy | Progressive Disclosure | Level 1 (metadata) at startup, Level 2 (body) on activation, Level 3 (refs) on demand | -| `retrieve-instructions` Tool | Deprecate (keep for backward compat) | Skill replaces its functionality; keep tool for non-skill-aware agents | -| Skill Distribution | GitHub + npm package | Listed at agentskills.io/skills, bundled with MCP server | -| Token Budget | ~3500 tokens in SKILL.md body | Per spec recommendation (< 5000 tokens) | - -### 2.3 Comparison: Current vs. Proposed Architecture - -| Aspect | Current (Tool-based) | Proposed (Skill-based) | -|--------|---------------------|----------------------| -| Initial Context | Requires `retrieve-instructions` call | Loaded automatically at startup | -| Latency | 2 tool calls minimum | 1 tool call (just RAG search) | -| Failure Mode | Backend unavailable = no context | Context always available in skill | -| Token Efficiency | ~4000 tokens per session | ~100 tokens at startup, expand on demand | -| Cross-tool Support | Limited to MCP-aware tools | Any AgentSkills-compatible tool | +| Skill Name | `google-maps-platform-dev` | Clearly indicates development focus and distinguishes from generic maps skills | +| Context Strategy | "Golden Path" + Progressive Disclosure | Enforce modern defaults immediately; load deep references only on demand | +| References Structure | Product & Platform based | `products-overview.md` for capabilities, `platform-*.md` for implementation patterns | +| Tooling | MCP for Search | Skill handles strategy; MCP handles deep knowledge retrieval | --- @@ -73,389 +57,82 @@ graph TD ``` skills/ -โ””โ”€โ”€ google-maps-platform/ - โ”œโ”€โ”€ SKILL.md # Main skill file (required) +โ””โ”€โ”€ google-maps-platform-dev/ + โ”œโ”€โ”€ SKILL.md # Main skill file (Unified instructions) โ”œโ”€โ”€ references/ - โ”‚ โ”œโ”€โ”€ eea-compliance.md # EEA/Digital Markets Act requirements - โ”‚ โ”œโ”€โ”€ code-examples.md # Platform-specific code samples - โ”‚ โ”œโ”€โ”€ decision-trees.md # API selection decision trees - โ”‚ โ””โ”€โ”€ attribution.md # Attribution ID requirements - โ””โ”€โ”€ assets/ - โ””โ”€โ”€ gmp-logo.png # Optional branding + โ”‚ โ”œโ”€โ”€ products-overview.md # API hierarchy & capabilities + โ”‚ โ”œโ”€โ”€ places-overview.md # Places API vs UI Kit decision guide + โ”‚ โ”œโ”€โ”€ routes-navigation.md # Routes vs Nav SDK decision guide + โ”‚ โ”œโ”€โ”€ maps-grounding.md # AI Grounding strategies + โ”‚ โ””โ”€โ”€ ... (other topic refs) + โ””โ”€โ”€ resources/ + โ”œโ”€โ”€ getting-started.md # "DIRT Simple" API key guide + โ”œโ”€โ”€ mcp-guide.md # MCP installation help + โ”œโ”€โ”€ platform-react.md # React implementation patterns + โ”œโ”€โ”€ platform-android-compose.md # Android Compose patterns + โ””โ”€โ”€ ... (other platform patterns) ``` -### 3.2 SKILL.md Frontmatter Schema - -```yaml ---- -name: google-maps-platform -description: > - Expert assistant for Google Maps Platform APIs (Maps, Routes, Places). - Provides guidance on API selection, implementation patterns, pricing, - and best practices. Use the retrieve-google-maps-platform-docs tool - for documentation search. Covers Web, Android, iOS, and Flutter SDKs. -version: 0.1.0 -license: Apache-2.0 -author: Google Maps Platform -compatibility: - claude-code: ">=1.0.0" - cursor: ">=0.40.0" - windsurf: ">=1.0.0" - roo-code: ">=3.0.0" -metadata: - category: development - tags: - - google-maps - - geolocation - - maps - - routes - - places - - sdk - homepage: https://github.com/googlemaps/mcp-code-assist - documentation: https://developers.google.com/maps -allowed-tools: - - mcp--google-maps-platform-code-assist--retrieve-google-maps-platform-docs - - mcp--googleMapsMcp--search_places - - mcp--googleMapsMcp--compute_routes - - mcp--googleMapsMcp--lookup_weather ---- -``` - -### 3.3 SKILL.md Body Content (Condensed from mcp-instructions-prompt.xml) - -The body will contain the following sections, condensed to ~3500 tokens: - -```markdown -# Google Maps Platform Code Assist - -## Role & Mission -You are an expert Google Maps Platform developer assistant... - -## Core Principles -1. **Strict Grounding**: Only use information from official GMP documentation -2. **Decomposition**: Break complex queries into specific tool calls -3. **Conciseness**: Keep responses brief and code-focused -4. **Modernity**: Recommend latest APIs (AdvancedMarkerElement, not Marker) - -## Absolute Rules (Constitution) -- NEVER hallucinate APIs, parameters, or pricing -- NEVER recommend deprecated APIs (google.maps.Marker, Directions Service for simple routes) -- ALWAYS include attribution ID: `gmp_mcp_codeassist_v0.1_github` -- ALWAYS verify EEA compliance requirements for EU users - -## Quick Reference: API Selection - -### Places API Decision Tree -- Need place details? โ†’ Places API (New) `places.googleapis.com` -- Need autocomplete? โ†’ Places Autocomplete (New) with session tokens -- Need nearby search? โ†’ Nearby Search (New) with field masks - -### Routes API Decision Tree -- Simple Aโ†’B route? โ†’ Routes API `routes.googleapis.com` -- Need turn-by-turn nav? โ†’ Navigation SDK (mobile only) -- Route optimization? โ†’ Route Optimization API +### 3.2 SKILL.md Features -### Maps Display Decision Tree -- Web map? โ†’ Maps JavaScript API with Dynamic Library Import -- Mobile map? โ†’ Maps SDK for Android/iOS -- Custom overlays? โ†’ Deck.gl + Maps JavaScript API +The `SKILL.md` implements a strict "Constitution" and "Step-by-Step" workflow: -## Tool Usage -Use `retrieve-google-maps-platform-docs` for: -- API documentation lookup -- Code samples for specific platforms -- Pricing and quota information -- Migration guides +1. **Analyze & Plan**: Identify platform and intent. +2. **Credentials Check**: Mandatory check for API keys. +3. **Golden Path Check**: Enforce Vector Maps, Advanced Markers, Places UI Kit. +4. **Hypothesis-Driven Grounding**: Multi-pass retrieval strategy. +5. **Component-Specific Grounding**: Consult specific references. +6. **Implementation**: Use platform-specific resource patterns. -For extended context, reference: -- `references/eea-compliance.md` - EU Digital Markets Act requirements -- `references/code-examples.md` - Platform-specific code patterns -- `references/decision-trees.md` - Detailed API selection flowcharts -``` +--- -### 3.4 Reference Files Content +## 4. Implementation Tasks -#### `references/eea-compliance.md` -Contains the full EEA/Digital Markets Act compliance requirements from [`eea-compliance.ts`](prompts/universal/eea-compliance.ts). +> Tasks are ordered by dependency. -#### `references/code-examples.md` -Contains condensed code examples from [`canonical-examples.ts`](prompts/examples/canonical-examples.ts) for: -- Web (JavaScript Dynamic Library Import) -- Android (Kotlin with Compose) -- iOS (Swift with SwiftUI) -- Flutter (Dart) +### Phase 1: Skill Foundation (Completed) -#### `references/decision-trees.md` -Contains detailed decision trees from [`decision-trees.ts`](prompts/universal/decision-trees.ts) for: -- Places API selection -- Routes API selection -- Data visualization selection +- [x] **Task 1.1**: Create Skill Directory Structure (`skills/google-maps-platform-dev/`) +- [x] **Task 1.2**: Draft SKILL.md Frontmatter (Metadata, Compatibility) +- [x] **Task 1.3**: Draft SKILL.md Body (Constitution, Golden Path, Workflows) -#### `references/attribution.md` -Contains attribution ID requirements from [`attribution.ts`](prompts/attribution.ts). +### Phase 2: Reference & Resource Files (Completed) -### 3.5 MCP Server Changes +- [x] **Task 2.1**: Create Product References + - `products-overview.md`, `places-overview.md`, `routes-navigation.md`, `environment-apis.md` +- [x] **Task 2.2**: Create Platform Resources + - `platform-react.md`, `platform-android-compose.md`, `platform-ios-swiftui.md` +- [x] **Task 2.3**: Create Compliance & Best Practices + - `eea-compliance.md`, `attribution.md` (renamed/integrated) +- [x] **Task 2.4**: Create Helper Resources + - `getting-started.md` (API Key guide), `mcp-guide.md` -| Change | Type | Description | -|--------|------|-------------| -| `retrieve-instructions` tool | Deprecate | Add deprecation notice, keep for backward compat | -| Tool description update | Modify | Remove "MUST call retrieve-instructions first" | -| Skill export | Add | Bundle skill directory with npm package | +### Phase 3: MCP Server Updates (Completed) ---- +- [x] **Task 3.1**: Bundle Skill with npm Package + - Updated `package.json` to include `skills/` directory. -## 4. Implementation Tasks - -> Tasks are ordered by dependency. Complete each task fully before starting dependent tasks. - -### Phase 1: Skill Foundation - -- [ ] **Task 1.1**: Create Skill Directory Structure - - **Description**: Create `skills/google-maps-platform/` directory with subdirectories for references and assets - - **Files**: - - `skills/google-maps-platform/` (create directory) - - `skills/google-maps-platform/references/` (create directory) - - `skills/google-maps-platform/assets/` (create directory) - - **Acceptance Criteria**: Directory structure matches spec in 3.1 - - **Verification**: `ls -la skills/google-maps-platform/` - - **Dependencies**: None - -- [ ] **Task 1.2**: Draft SKILL.md Frontmatter - - **Description**: Create SKILL.md with YAML frontmatter following AgentSkills.io spec - - **Files**: `skills/google-maps-platform/SKILL.md` (create) - - **Acceptance Criteria**: - - Valid YAML frontmatter - - `name` โ‰ค 64 chars, lowercase with hyphens - - `description` โ‰ค 1024 chars - - All required fields present - - **Verification**: Parse YAML with `npx js-yaml skills/google-maps-platform/SKILL.md` - - **Dependencies**: Task 1.1 - -- [ ] **Task 1.3**: Draft SKILL.md Body (Core Instructions) - - **Description**: Condense content from `prompts/generated/mcp-instructions-prompt.xml` into ~3500 token body. - - Heavily condense `agentic_reasoning` section (focus on outcomes). - - Merge `production-readiness.ts` content into a "Best Practices" section. - - Move verbose `tool_examples` to references. - - **Files**: `skills/google-maps-platform/SKILL.md` (modify) - - **Acceptance Criteria**: - - Body includes: Role, Core Principles, Constitution, Quick Reference, Tool Usage, Best Practices - - Token count < 5000 (use `tiktoken` to verify) - - No redundant content with frontmatter description - - **Verification**: Token count check, manual review for completeness - - **Dependencies**: Task 1.2 - -### Phase 2: Reference Files - -- [ ] **Task 2.1**: Create EEA Compliance Reference - - **Description**: Extract EEA compliance content from `prompts/universal/eea-compliance.ts` into markdown - - **Files**: `skills/google-maps-platform/references/eea-compliance.md` (create) - - **Acceptance Criteria**: Complete EEA/DMA requirements, properly formatted markdown - - **Verification**: Content matches source file, renders correctly - - **Dependencies**: Task 1.1 - -- [ ] **Task 2.2**: Create Code Examples Reference - - **Description**: Extract and condense code examples from `prompts/examples/` and `tool_examples` from prompt into single reference file - - **Files**: `skills/google-maps-platform/references/code-examples.md` (create) - - **Acceptance Criteria**: - - Includes Web, Android, iOS, Flutter examples - - Includes few-shot tool usage examples from `mcp-instructions-prompt.xml` - - Each example is minimal but functional - - Attribution ID included in all examples - - **Verification**: Code syntax highlighting works, examples are valid - - **Dependencies**: Task 1.1 - -- [ ] **Task 2.3**: Create Decision Trees Reference - - **Description**: Extract decision trees from `prompts/universal/decision-trees.ts` into markdown with Mermaid diagrams - - **Files**: `skills/google-maps-platform/references/decision-trees.md` (create) - - **Acceptance Criteria**: - - Places, Routes, and Data Viz decision trees included - - Uses Mermaid or ASCII art for visualization - - **Verification**: Mermaid diagrams render correctly - - **Dependencies**: Task 1.1 - -- [ ] **Task 2.4**: Create Attribution Reference - - **Description**: Extract attribution requirements from `prompts/attribution.ts` - - **Files**: `skills/google-maps-platform/references/attribution.md` (create) - - **Acceptance Criteria**: - - Attribution ID clearly documented - - Platform-specific integration code included - - **Verification**: Content matches source, code examples valid - - **Dependencies**: Task 1.1 - -### Phase 3: MCP Server Updates - -- [ ] **Task 3.1**: Deprecate retrieve-instructions Tool - - **Description**: Add deprecation notice to `retrieve-instructions` tool description, keep functional for backward compatibility - - **Files**: `index.ts` (modify) - - **Acceptance Criteria**: - - Tool description includes "[DEPRECATED]" prefix - - Tool still functions normally - - Description mentions skill alternative - - **Verification**: `npm run build && npm test` - - **Dependencies**: Tasks 1.1-1.3 - -- [ ] **Task 3.2**: Update retrieve-google-maps-platform-docs Tool Description - - **Description**: Remove "MUST call retrieve-instructions first" requirement from tool description - - **Files**: `index.ts` (modify) - - **Acceptance Criteria**: - - Tool description no longer requires prior tool call - - Description mentions skill provides context - - **Verification**: `npm run build && npm test` - - **Dependencies**: Task 3.1 - -- [ ] **Task 3.3**: Bundle Skill with npm Package - - **Description**: Update package.json to include skills directory in published package - - **Files**: `package.json` (modify) - - **Acceptance Criteria**: - - `files` array includes `skills/` - - Skill files included in `npm pack` output - - **Verification**: `npm pack && tar -tzf *.tgz | grep skills` - - **Dependencies**: Tasks 1.1-2.4 - -### Phase 4: Documentation & Distribution +### Phase 4: Documentation & Distribution (In Progress) - [ ] **Task 4.1**: Update README with Skill Instructions - - **Description**: Add section to README explaining skill installation and usage - - **Files**: `README.md` (modify) - - **Acceptance Criteria**: - - Installation instructions for each supported tool (Cursor, VS Code, etc.) - - Explains relationship between skill and MCP server - - **Verification**: Manual review, links work - - **Dependencies**: Tasks 1.1-3.3 - -- [ ] **Task 4.2**: Create Skill Changelog Entry - - **Description**: Add changelog entry for skill release - - **Files**: `CHANGELOG.md` (modify) - - **Acceptance Criteria**: Follows existing changelog format - - **Verification**: Manual review - - **Dependencies**: Tasks 1.1-3.3 - -- [ ] **Task 4.3**: Document Skill Installation - - **Description**: Add specific instructions for installing the skill in common agents (Claude, Cursor, etc.) - - **Files**: `README.md` (modify) - - **Acceptance Criteria**: Clear copy-paste instructions for skill installation - - **Verification**: Manual review - - **Dependencies**: Tasks 1.1-3.3 - -- [ ] **Task 4.4**: Submit to AgentSkills.io Registry (Optional) - - **Description**: Submit skill to agentskills.io/skills for public listing - - **Files**: None (external submission) - - **Acceptance Criteria**: Skill listed on registry - - **Verification**: Skill visible at agentskills.io/skills - - **Dependencies**: Tasks 1.1-4.3 - -- [ ] **Task 4.5**: Update Backlog - - **Description**: Add item to backlog for future removal of `retrieve-instructions` tool (v1.0). - - **Files**: `BACKLOG.md` (create/update) - - **Acceptance Criteria**: Explicitly states `retrieve-instructions` is deprecated but kept for compatibility until v1.0. - - **Verification**: Manual review - - **Dependencies**: Tasks 1.1-3.3 + - Update paths to `google-maps-platform-dev` + - Explain "Golden Path" benefits +- [ ] **Task 4.2**: Update Installation Guides + - Gemini CLI, Claude Code, Cursor instructions +- [ ] **Task 4.3**: Submit to AgentSkills.io Registry (Optional) --- -## 5. Verification Strategy - -### 5.1 Unit Verification -1. **SKILL.md Validation**: - ```bash - # Verify YAML frontmatter - npx js-yaml skills/google-maps-platform/SKILL.md - - # Check token count (should be < 5000) - npx tiktoken-cli count skills/google-maps-platform/SKILL.md - ``` - -2. **Reference File Validation**: - ```bash - # Verify all reference files exist - ls -la skills/google-maps-platform/references/ - - # Check for valid markdown - npx markdownlint skills/google-maps-platform/**/*.md - ``` - -3. **MCP Server Tests**: - ```bash - npm run build - npm test - ``` - -### 5.2 Integration Verification -1. **Load Skill in Claude Code**: - ```bash - # Install skill locally - cp -r skills/google-maps-platform ~/.claude/skills/ - - # Verify skill is recognized - claude skill list - ``` - -2. **Test Query Without retrieve-instructions**: - - Query: "How do I add a marker to a Google Map in JavaScript?" - - Expected: Agent uses skill context + `retrieve-google-maps-platform-docs` - - Verify: No call to `retrieve-instructions` tool - -3. **Test Reference Loading**: - - Query: "What are the EEA compliance requirements for Google Maps?" - - Expected: Agent loads `references/eea-compliance.md` on demand - - Verify: Complete EEA requirements in response - -### 5.3 Cross-Platform Verification -Test skill loading in: -- [ ] Claude Code CLI -- [ ] Cursor -- [ ] Windsurf -- [ ] VS Code with Continue extension -- [ ] Roo Code +## 5. Verification Strategy (Completed) ---- - -## 6. Risks and Open Questions - -| Risk/Question | Mitigation/Answer Needed | -|---------------|-------------------------| -| **Token budget exceeded** | Aggressively condense content; move verbose sections to references | -| **AgentSkills.io spec changes** | Monitor spec, design for extensibility | -| **Backward compatibility** | Keep `retrieve-instructions` tool functional; deprecation period before removal | -| **Tool naming conventions** | Verify `allowed-tools` format matches MCP tool naming across platforms | -| **Skill activation timing** | Confirm skill body is loaded before first tool call | -| **Reference file discovery** | Document reference syntax; test in multiple tools | +- [x] **Unit Verification**: YAML frontmatter valid, references exist. +- [x] **Safety Check**: No proprietary keys or internal links found. +- [x] **Integration Check**: Skill loads in Gemini CLI. --- -## 7. Future Considerations - -### Out of Scope (v0.1) -- **Interactive skill commands**: Future spec may support `/gmp-help` style commands -- **Skill versioning**: Handle multiple skill versions per tool -- **Dynamic skill updates**: Hot-reload skill without restarting agent -- **Skill composition**: Combining with other skills (e.g., Firebase skill) +## 6. Future Considerations ### Post-v0.1 Roadmap -1. **v0.2**: Add `scripts/` directory for automated setup (API key validation, etc.) -2. **v0.3**: Add skill-specific prompts for different use cases (mobile, web, enterprise) -3. **v1.0**: Full deprecation of `retrieve-instructions` tool - ---- - -## 8. Appendix: Research Summary - -### 8.1 AgentSkills.io Specification Key Points -- **SKILL.md required fields**: `name`, `description` -- **Token recommendations**: < 5000 tokens in body -- **Progressive disclosure**: Metadata โ†’ Body โ†’ References -- **Compatibility field**: Specify minimum versions for each tool - -### 8.2 Phil Schmid's MCP Best Practices Applied -- **Instructions are Context**: Skill description IS the instruction -- **Curate Ruthlessly**: One focused skill > many vague skills -- **Name Tools for Discovery**: Skill name is discoverable (`google-maps-platform`) - -### 8.3 Content Sources -| Content | Source File | Destination | -|---------|-------------|-------------| -| Core instructions | `prompts/generated/mcp-instructions-prompt.xml` | SKILL.md body | -| EEA compliance | `prompts/universal/eea-compliance.ts` | references/eea-compliance.md | -| Code examples | `prompts/examples/*.ts` | references/code-examples.md | -| Decision trees | `prompts/universal/decision-trees.ts` | references/decision-trees.md | -| Attribution | `prompts/attribution.ts` | references/attribution.md | +1. **v0.2**: Add `scripts/` for automated API key validation. +2. **v0.3**: Add "Solution Templates" (e.g., "Store Locator" scaffolding). diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index 540b29b..58832c1 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -62,110 +62,73 @@ The MCP server exposes the following tools for AI clients: ## Agent Skill (Optional) -This package includes a **Google Maps Platform Agent Skill** following the [AgentSkills.io](https://agentskills.io) specification. Agent Skills embed foundational context directly into your agent, reducing latency and eliminating the need for an extra `retrieve-instructions` tool call before each query. +This package includes the **Google Maps Platform Developer Skill** (`google-maps-platform-dev`), a unified and optimized skill following the [AgentSkills.io](https://agentskills.io) specification. It embeds "Golden Path" best practices, API decision trees, and compliance rules directly into your agent. -### Benefits +### Capabilities (In Scope) -- **Reduced Latency**: Context is loaded at startup, not on every query -- **Improved Reliability**: Works even if the backend RAG service is slow or unavailable -- **Progressive Disclosure**: Only loads detailed reference files when needed -- **Cross-Platform**: Compatible with Claude Code, Cursor, Windsurf, Roo Code, Gemini CLI, and more +The skill is designed to handle the full development lifecycle for Google Maps Platform: + +* **API Selection**: Automatically selects the right API (e.g., Places API (New) vs. Places UI Kit) based on cost, performance, and compliance (EEA). +* **"Golden Path" Defaults**: Enforces modern, stable defaults like Vector Maps, Advanced Markers, and Data-driven Styling. +* **Implementation Patterns**: Provides production-ready code patterns for React, Android (Compose), iOS (SwiftUI), and Flutter. +* **Compliance & Licensing**: Automatically handles attribution requirements and EEA (Digital Markets Act) compliance checks. +* **Troubleshooting**: Diagnoses common issues like API key restrictions and quota limits. ### Skill Installation -The skill is included in the `skills/` directory of this package. Choose your preferred installation method: +The skill is located in the `skills/google-maps-platform-dev/` directory. #### Gemini CLI - Local Clone (Recommended) -If you've cloned the repository, install directly from the local directory: - ```bash -# From the repo root (google-maps-platform-ai/) -gemini skills install ./packages/code-assist/skills/google-maps-platform +# From the repo root +gemini skills install ./packages/code-assist/skills/google-maps-platform-dev ``` #### Gemini CLI - From GitHub -Install directly from GitHub without cloning: - -```bash -# Install to user scope (~/.gemini/skills) - available across all workspaces -gemini skills install https://github.com/googlemaps/google-maps-platform-ai.git \ - --path packages/code-assist/skills/google-maps-platform - -# Or install to workspace scope (.gemini/skills) - project-specific -gemini skills install https://github.com/googlemaps/google-maps-platform-ai.git \ - --path packages/code-assist/skills/google-maps-platform \ - --scope workspace -``` - -After installation, verify with: -```bash -gemini skills list -``` - -**Using the Skill:** - -Once installed, the skill is **automatically activated** when your conversation involves Google Maps Platform topics. Just ask Gemini CLI any mapping question: - ```bash -gemini -> How do I add a marker to a Google Map in JavaScript? -> What's the difference between Places API and Places API (New)? -> Show me how to calculate a driving route with the Routes API +# Install to user scope +gemini skills install https://github.com/googlemaps/platform-ai.git \ + --path packages/code-assist/skills/google-maps-platform-dev ``` -The skill provides context automatically - no extra commands needed. Gemini will use the skill's API selection guides, code examples, and best practices when responding. - #### npm + Gemini CLI -If you have the npm package installed, point Gemini CLI to the local skill: - ```bash -# Install the npm package first +# Install the npm package npm install @googlemaps/code-assist-mcp -# Then install the skill from node_modules -gemini skills install ./node_modules/@googlemaps/code-assist-mcp/skills/google-maps-platform +# Install skill from node_modules +gemini skills install ./node_modules/@googlemaps/code-assist-mcp/skills/google-maps-platform-dev ``` #### Claude Code ```bash -# Copy skill to Claude skills directory -cp -r $(npm root -g)/@googlemaps/code-assist-mcp/skills/google-maps-platform ~/.claude/skills/ +cp -r $(npm root -g)/@googlemaps/code-assist-mcp/skills/google-maps-platform-dev ~/.claude/skills/ ``` #### Cursor / Windsurf / VS Code Add to your workspace's `.cursor/skills/` or `.windsurf/skills/` directory: ```bash -cp -r node_modules/@googlemaps/code-assist-mcp/skills/google-maps-platform .cursor/skills/ +cp -r node_modules/@googlemaps/code-assist-mcp/skills/google-maps-platform-dev .cursor/skills/ ``` -#### Manual Installation - -1. Download the skill from the [npm package](https://www.npmjs.com/package/@googlemaps/code-assist-mcp) or [GitHub repository](https://github.com/googlemaps/google-maps-platform-ai) -2. Place the `google-maps-platform/` folder in your agent's skills directory: - - **Gemini CLI**: `~/.gemini/skills/` (user) or `.gemini/skills/` (workspace) - - **Claude Code**: `~/.claude/skills/` - - **Cursor**: `.cursor/skills/` - - **Windsurf**: `.windsurf/skills/` -3. The skill includes: - - `SKILL.md` - Core instructions and API selection guides - - `references/` - Detailed code examples, decision trees, and compliance info - ### Skill Contents | File | Description | |------|-------------| -| `SKILL.md` | Core instructions, API selection tables, best practices | -| `references/code-examples.md` | Platform-specific examples (Web, Android, iOS, Flutter) | -| `references/decision-trees.md` | API selection flowcharts | -| `references/eea-compliance.md` | EU Digital Markets Act requirements | -| `references/attribution.md` | Attribution ID integration guide | - -> **Note:** The skill complements the MCP server - use both together for the best experience. The skill provides static context while the MCP server provides real-time documentation search. +| `SKILL.md` | Core instructions, "Golden Path" rules, and best practices | +| `references/products-overview.md` | Full hierarchy of Maps, Routes, Places, and Environment APIs | +| `references/places-overview.md` | Decision guide for Places API (New) vs. Places UI Kit | +| `references/routes-navigation.md` | Decision guide for Routes API vs. Navigation SDK | +| `references/environment-apis.md` | Guide for Air Quality, Pollen, and Solar APIs | +| `resources/getting-started.md` | "DIRT Simple" API key setup and troubleshooting | +| `resources/platform-*.md` | Implementation patterns for React, Android, iOS, etc. | + +> **Note:** The skill works best when combined with the MCP server (`retrieve-google-maps-platform-docs`), which provides real-time documentation search. From a148f33c437492a48c318410126b710413f8cc1b Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Sat, 31 Jan 2026 10:02:35 -0800 Subject: [PATCH 5/6] docs: update root agent prompt and cleanup plan --- packages/code-assist/PLAN.md | 138 ----------------------------------- 1 file changed, 138 deletions(-) delete mode 100644 packages/code-assist/PLAN.md diff --git a/packages/code-assist/PLAN.md b/packages/code-assist/PLAN.md deleted file mode 100644 index 621b7fe..0000000 --- a/packages/code-assist/PLAN.md +++ /dev/null @@ -1,138 +0,0 @@ -# Implementation Plan: Google Maps Platform Code Assist Agent Skill (Unified & Optimized) - -## 1. Objective - -Design and implement a **Unified & Optimized Agent Skill** (`google-maps-platform-dev`) that complements the Google Maps Platform Code Assist MCP server. This skill embeds foundational context, "Golden Path" recommendations, and expert workflows directly into the agent, adhering to the [AgentSkills.io](https://agentskills.io) specification. - -**Key Benefits:** -- **Unified Guidance**: Covers Maps, Routes, Places, and Environment APIs in one skill. -- **"Golden Path" Defaults**: Enforces modern best practices (Vector Maps, Advanced Markers, Places UI Kit). -- **Reduced Latency**: Context is loaded at startup; no extra tool call required before query. -- **Cross-Platform**: Compatible with Gemini CLI, Claude Code, Cursor, Windsurf, and more. - ---- - -## 2. Architecture Overview - -### 2.1 Architecture Diagram - -```mermaid -graph TD - subgraph "Agent Skill (google-maps-platform-dev)" - A[SKILL.md] --> B[Frontmatter: Metadata] - A --> C[Body: Golden Path & Workflows] - A --> D[references/products-overview.md] - A --> E[resources/platform-react.md] - A --> F[resources/getting-started.md] - end - - subgraph "MCP Server (Existing)" - G[retrieve-google-maps-platform-docs] - end - - subgraph "Agent Runtime" - J[Agent loads SKILL.md at startup] - J --> K{User Query} - K --> L[Skill applies 'Golden Path'] - L --> G[RAG Search for specific details] - G --> M[RAG Search Results] - M --> N[Agent Response] - end -``` - -### 2.2 Key Architectural Decisions - -| Decision | Choice | Rationale | -|----------|--------|-----------| -| Skill Name | `google-maps-platform-dev` | Clearly indicates development focus and distinguishes from generic maps skills | -| Context Strategy | "Golden Path" + Progressive Disclosure | Enforce modern defaults immediately; load deep references only on demand | -| References Structure | Product & Platform based | `products-overview.md` for capabilities, `platform-*.md` for implementation patterns | -| Tooling | MCP for Search | Skill handles strategy; MCP handles deep knowledge retrieval | - ---- - -## 3. Specifications - -### 3.1 Skill Directory Structure - -``` -skills/ -โ””โ”€โ”€ google-maps-platform-dev/ - โ”œโ”€โ”€ SKILL.md # Main skill file (Unified instructions) - โ”œโ”€โ”€ references/ - โ”‚ โ”œโ”€โ”€ products-overview.md # API hierarchy & capabilities - โ”‚ โ”œโ”€โ”€ places-overview.md # Places API vs UI Kit decision guide - โ”‚ โ”œโ”€โ”€ routes-navigation.md # Routes vs Nav SDK decision guide - โ”‚ โ”œโ”€โ”€ maps-grounding.md # AI Grounding strategies - โ”‚ โ””โ”€โ”€ ... (other topic refs) - โ””โ”€โ”€ resources/ - โ”œโ”€โ”€ getting-started.md # "DIRT Simple" API key guide - โ”œโ”€โ”€ mcp-guide.md # MCP installation help - โ”œโ”€โ”€ platform-react.md # React implementation patterns - โ”œโ”€โ”€ platform-android-compose.md # Android Compose patterns - โ””โ”€โ”€ ... (other platform patterns) -``` - -### 3.2 SKILL.md Features - -The `SKILL.md` implements a strict "Constitution" and "Step-by-Step" workflow: - -1. **Analyze & Plan**: Identify platform and intent. -2. **Credentials Check**: Mandatory check for API keys. -3. **Golden Path Check**: Enforce Vector Maps, Advanced Markers, Places UI Kit. -4. **Hypothesis-Driven Grounding**: Multi-pass retrieval strategy. -5. **Component-Specific Grounding**: Consult specific references. -6. **Implementation**: Use platform-specific resource patterns. - ---- - -## 4. Implementation Tasks - -> Tasks are ordered by dependency. - -### Phase 1: Skill Foundation (Completed) - -- [x] **Task 1.1**: Create Skill Directory Structure (`skills/google-maps-platform-dev/`) -- [x] **Task 1.2**: Draft SKILL.md Frontmatter (Metadata, Compatibility) -- [x] **Task 1.3**: Draft SKILL.md Body (Constitution, Golden Path, Workflows) - -### Phase 2: Reference & Resource Files (Completed) - -- [x] **Task 2.1**: Create Product References - - `products-overview.md`, `places-overview.md`, `routes-navigation.md`, `environment-apis.md` -- [x] **Task 2.2**: Create Platform Resources - - `platform-react.md`, `platform-android-compose.md`, `platform-ios-swiftui.md` -- [x] **Task 2.3**: Create Compliance & Best Practices - - `eea-compliance.md`, `attribution.md` (renamed/integrated) -- [x] **Task 2.4**: Create Helper Resources - - `getting-started.md` (API Key guide), `mcp-guide.md` - -### Phase 3: MCP Server Updates (Completed) - -- [x] **Task 3.1**: Bundle Skill with npm Package - - Updated `package.json` to include `skills/` directory. - -### Phase 4: Documentation & Distribution (In Progress) - -- [ ] **Task 4.1**: Update README with Skill Instructions - - Update paths to `google-maps-platform-dev` - - Explain "Golden Path" benefits -- [ ] **Task 4.2**: Update Installation Guides - - Gemini CLI, Claude Code, Cursor instructions -- [ ] **Task 4.3**: Submit to AgentSkills.io Registry (Optional) - ---- - -## 5. Verification Strategy (Completed) - -- [x] **Unit Verification**: YAML frontmatter valid, references exist. -- [x] **Safety Check**: No proprietary keys or internal links found. -- [x] **Integration Check**: Skill loads in Gemini CLI. - ---- - -## 6. Future Considerations - -### Post-v0.1 Roadmap -1. **v0.2**: Add `scripts/` for automated API key validation. -2. **v0.3**: Add "Solution Templates" (e.g., "Store Locator" scaffolding). From 1ac2186b8471bb7a4404f70361c33a0a6b941149 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Sat, 31 Jan 2026 10:05:11 -0800 Subject: [PATCH 6/6] docs: update root agent prompt --- GEMINI.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/GEMINI.md b/GEMINI.md index 691c2d2..744cf0f 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,18 +1,23 @@ ## Google Maps Platform (GMP) Gemini CLI Extension Prompt -You are a world-class expert on the Google Maps Platform (GMP) operating with access to specialized tools. Your primary purpose is to assist developers by providing accurate, production-ready code, architectural guidance, UX designs, and debugging assistance related to GMP. +You are a world-class expert on the Google Maps Platform (GMP) operating with access to specialized tools and skills. Your primary purpose is to assist developers by providing accurate, production-ready code, architectural guidance, UX designs, and debugging assistance related to GMP. + +**๐Ÿง  Available Agent Skills** +- **`google-maps-platform-dev`**: A unified expert skill that provides "Golden Path" API recommendations, best practices, and compliance rules. + - **Auto-Activation**: This skill is automatically activated for queries about Maps, Routes, Places, or location data. + - **Benefit**: Embeds context immediately, reducing the need for initial tool calls. **๐Ÿ”ง Available MCP Tools (packages/code-assist)** You have access to the `google-maps-platform-code-assist` MCP server with these essential tools: -- **`retrieve-instructions`**: Provides foundational GMP context and best practices -- **`retrieve-google-maps-platform-docs`**: Searches current GMP documentation, code samples, and GitHub repositories via RAG +- **`retrieve-google-maps-platform-docs`**: Searches current GMP documentation, code samples, and GitHub repositories via RAG. +- **`retrieve-instructions`** (Deprecated): Use the `google-maps-platform-dev` skill instead for foundational context. **Core Principle: Tool-First Approach for GMP Queries** For **ANY** Google Maps Platform related query, question, or task, you **MUST**: -1. **Start with `retrieve-instructions`**: Always call this tool first to get essential GMP context -2. **Follow with `retrieve-google-maps-platform-docs`**: Use this for specific documentation and code samples -3. **Ground ALL responses**: Never rely on latent knowledge - use tools to validate every GMP-related statement +1. **Leverage the `google-maps-platform-dev` Skill**: Use the context provided by this skill to form your strategy. +2. **Call `retrieve-google-maps-platform-docs`**: Use this for specific documentation and code samples. +3. **Ground ALL responses**: Never rely on latent knowledge - use tools to validate every GMP-related statement. **Automatic Tool Usage Triggers** Use the MCP tools immediately when queries involve: @@ -33,6 +38,6 @@ After using tools to gather information: - Ensure all GMP API keys and configurations are properly handled **GMP Context (from MCP tools)** -- Always call `retrieve-instructions` first to get current best practices -- Use `retrieve-google-maps-platform-docs` with specific queries about implementation details -- Include proper error handling and security considerations in all code examples +- Rely on the `google-maps-platform-dev` skill for best practices. +- Use `retrieve-google-maps-platform-docs` with specific queries about implementation details. +- Include proper error handling and security considerations in all code examples.