From c4d7c3d25d3b944c03ce6a27ef3275128e3ee8a1 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 13:21:45 -0800 Subject: [PATCH 01/16] docs: switch MCP to remote SSE and update marketplace integrations --- base64.txt | 1 + found_words.txt | 25 ++ gemini-extension.json | 10 +- ls_out.txt | 4 + packages/code-assist/README.md | 391 ++---------------- .../skills/google-maps-platform-dev/SKILL.md | 40 ++ 6 files changed, 108 insertions(+), 363 deletions(-) create mode 100644 base64.txt create mode 100644 found_words.txt create mode 100644 ls_out.txt create mode 100644 packages/code-assist/skills/google-maps-platform-dev/SKILL.md diff --git a/base64.txt b/base64.txt new file mode 100644 index 0000000..f25639a --- /dev/null +++ b/base64.txt @@ -0,0 +1 @@ +eyJ0eXBlIjoic3NlIiwidXJsIjoiaHR0cHM6Ly9tYXBzY29kZWFzc2lzdC5nb29nbGVhcGlzLmNvbS9tY3AifQ== diff --git a/found_words.txt b/found_words.txt new file mode 100644 index 0000000..45a18c3 --- /dev/null +++ b/found_words.txt @@ -0,0 +1,25 @@ + + alt="Try in Firebase Studio" + src="https://cdn.firebasestudio.dev/btn/try_dark_32.svg"> +4. **[Firebase Studio](https://firebase.google.com/docs/studio/customize-workspace)** + * Try in Firebase Studio with Code Assist MCP installed + * Add to your project's `mcp.json` file in the `.idx` folder in your Firebase Studio workspace +6. **[Cline](https://docs.cline.bot/mcp/configuring-mcp-servers)** + * Option 1: install using the [Cline MCP GUI](https://docs.cline.bot/mcp/configuring-mcp-servers) + * Option 2: manually / programatically install using the Cline MCP config file. The config file is located at: + * **macOS:** `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` + * **Windows:** `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` + * **Linux:** `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` + * Add the following to your MCP configuration in `cline_mcp_settings.json`: +7. **[Roo Code](https://docs.roocode.com/features/mcp/using-mcp-in-roo)** + * Option 1: install using the [Roo MCP GUI](https://docs.roocode.com/features/mcp/using-mcp-in-roo) + * Option 2: manually / programatically install using the Roo Code config file. The config file is located at: + * **macOS:** `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` + * **Windows:** `%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json` + * **Linux:** `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` +10. **[Kilo Code](https://kilocode.ai/docs/features/mcp/using-mcp-in-kilo-code)** + * Similar to the Cline and Roo Code instructions above +**Note:** Check that the `type` parameter in your MCP configuration is set correctly for your specific client. For example, Roo Code uses `"type": "streamable-http"`, while Cline uses `"type": "streamableHttp"`. +**Roo Code (VS Code Extension)** +**Cline (VS Code Extension)** +Add to `cline_mcp_settings.json`: diff --git a/gemini-extension.json b/gemini-extension.json index 0783afd..7241b08 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -3,13 +3,13 @@ "version": "0.1.0", "description": "Ground agents on fresh, official Google Maps Platform documentation and code samples for optimal geo-related developer guidance and code", "contextFileName": "GEMINI.md", + "skills": { + "google-maps-platform-dev": "packages/code-assist/skills/google-maps-platform-dev" + }, "mcpServers": { "google-maps-platform-code-assist": { - "command": "npx", - "args": [ - "-y", - "@googlemaps/code-assist-mcp@latest" - ] + "type": "sse", + "url": "https://mapscodeassist.googleapis.com/mcp" } }, "theme": "gmp-theme.json" diff --git a/ls_out.txt b/ls_out.txt new file mode 100644 index 0000000..feebac5 --- /dev/null +++ b/ls_out.txt @@ -0,0 +1,4 @@ +total 24 +drwxr-xr-x@ 3 ryanbaumann primarygroup 96 Mar 6 13:08 . +drwxr-xr-x@ 4 ryanbaumann primarygroup 128 Jan 31 09:52 .. +-rw-r--r-- 1 ryanbaumann primarygroup 10244 Jan 28 14:59 .DS_Store diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index 419f45d..fdca66d 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -1,15 +1,7 @@ -[![npm](https://img.shields.io/npm/v/@googlemaps/code-assist-mcp)][npm-pkg] ![Alpha](https://img.shields.io/badge/release-alpha-orange) [![License](https://img.shields.io/github/license/googlemaps/platform-ai?color=blue)][license] [![Discord](https://img.shields.io/discord/676948200904589322?color=6A7EC2&logo=discord&logoColor=ffffff)][Discord server] -[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=google-maps-platform&config=eyJjb21tYW5kIjoibnB4IC15IEBnb29nbGVtYXBzL2NvZGUtYXNzaXN0LW1jcCJ9) - - Try in Firebase Studio - - +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=google-maps-platform&config=eyJ0eXBlIjoic3NlIiwidXJsIjoiaHR0cHM6Ly9tYXBzY29kZWFzc2lzdC5nb29nbGVhcGlzLmNvbS9tY3AifQ==) # Google Maps Platform Logo Google Maps Platform Code Assist Toolkit *Alpha version* @@ -32,7 +24,7 @@ Google Maps Platform resources that the MCP server can access include: ## Benefits -- Make your favorite AI assistant or IDE a Google Maps Platform expert. With Code Assist, AI Agents like Gemini CLI, Claude Code, and Cursor can generate code and answer developer questions grounded in up-to-date, official Google Maps Platform documentation and code samples -- directly in your dev workflow. +- Make your favorite AI assistant or IDE an expert on the Google Maps Platform. With Code Assist, AI Agents like Gemini CLI, Claude Code, and Cursor can generate code and answer developer questions grounded in up-to-date, official Google Maps Platform documentation and code samples -- directly in your dev workflow. - Whether you are making precision AI-Assisted code changes or vibecoding a new app prototype - Code Assist can help you accomplish your task faster and easier. @@ -63,404 +55,90 @@ The MCP server exposes the following tools for AI clients: ## Supported MCP Transports -This server supports two standard MCP communication protocols: +This remote server supports standard MCP communication protocols: - * **`stdio`**: This is the default transport used when a client invokes the server via a `command`. It communicates over the standard input/output streams, making it ideal for local command-line execution. - * **`Streamable HTTP`**: The server exposes a `/mcp` endpoint that accepts POST requests. This is used by clients that connect via a `url` and is the standard for remote server connections. Our implementation supports streaming for real-time, interactive responses. + * **`Streamable HTTP`**: The server exposes a `/mcp` endpoint that accepts POST requests over the HTTPS protocol. This is used by clients that connect via a `url` and is the standard for remote server connections. Our implementation supports Server-Sent Events (SSE) for real-time, interactive responses. ----- - + ## Usage -You can run the Code Assist MCP server either on your local development machine or remotely on Google Cloud Run. - -### Requirements - -In order to use the Google Maps Platform Code Assist toolkit, you need an environment with [Node.js](https://nodejs.org/en/download/) (LTS version recommended) and npm installed in order to clone and run the server, as well as an MCP client to access the server. - -### Use Code Assist as a Local MCP Server with `stdio` transport (Recommended) - -Run the server on your local machine and connect clients using `stdio` protocol for use with AI-assisted IDEs (like VS Code, Android Studio, Cursor) or desktop AI applications (like Gemini CLI). This is the simplest and most common setup. +The Code Assist MCP server is securely hosted by Google. To use it, you must configure your AI client to connect to the remote URL via Server-Sent Events (SSE). -#### Configure Your Client +### Configure Your Client -Add the server to your preferred AI client's MCP configuration file. Find your client below for specific, verified instructions. +Add the remote server URL to your preferred AI client's MCP configuration file or settings UI. Find your client below for specific, verified instructions. -1. **[Gemini Code Assist & Gemini CLI](https://developers.google.com/gemini-code-assist/docs/use-agentic-chat-pair-programmer#configure-mcp-servers)** - * Option 1 - Add the server directly from your command line (assuming you have Gemini CLI already installed): - ```bash - gemini mcp add google-maps-platform-code-assist npx -y @googlemaps/code-assist-mcp@latest - ``` - * Verify the installation by running `gemini mcp list`. - * Option 2 - Install Code Assist MCP server as a Gemini CLI extension: +1. **Gemini CLI** + * Option 1 - Install the Code Assist MCP server as a Gemini CLI extension. This provides the most complete experience, including specialized developer skills: ```bash gemini extensions install https://github.com/googlemaps/platform-ai.git ``` - * Option 3 - Add the MCP server config manually to your `~/.gemini/settings.json` file. + * Option 2 - Add the MCP server config manually to your `~/.gemini/servers.json` file. ```json { "mcpServers": { "google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"] + "type": "sse", + "url": "https://mapscodeassist.googleapis.com/mcp" } } } ``` -2. **[Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp)** - * Option 1 - Add the server directly from your command line (assuming you have Claude Code already installed): - ```bash - claude mcp add google-maps-platform-code-assist -- npx -y @googlemaps/code-assist-mcp@latest - ``` - * Verify the installation by running `claude mcp list`. - * **Windows Users:** On native Windows (not WSL), you must use the `cmd /c` wrapper for `npx` commands to work correctly. - ```bash - claude mcp add google-maps-platform-code-assist -- cmd /c "npx -y @googlemaps/code-assist-mcp@latest" - ``` - * Option 2 - Add the sever manually to your Claude config file `~/.claude.json` +2. **Claude Code** + * Add the server manually to your Claude config file `~/.claude.json`: ```json "mcpServers": { "google-maps-platform-code-assist": { - "command": "npx", - "args": [ - "-y", "@googlemaps/code-assist-mcp@latest" - ] + "type": "sse", + "url": "https://mapscodeassist.googleapis.com/mcp" } } ``` -3. **[Cursor](https://docs.cursor.com/en/context/mcp)** - * [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=google-maps-platform&config=eyJjb21tYW5kIjoibnB4IC15IEBnb29nbGVtYXBzL2NvZGUtYXNzaXN0LW1jcCJ9) <-- If you already have Cursor installed, click here to install Google Maps Platform Code Assist MCP directly. - * Otherwise, add it to your workspace's `.cursor-settings/mcp.json` file. +3. **Cursor** + * [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=google-maps-platform&config=eyJ0eXBlIjoic3NlIiwidXJsIjoiaHR0cHM6Ly9tYXBzY29kZWFzc2lzdC5nb29nbGVhcGlzLmNvbS9tY3AifQ==) <-- If you already have Cursor installed, click here to install the Google Maps Platform Code Assist MCP directly. + * Otherwise, add it to your workspace's `.cursor/mcp.json` file. ```json { "mcpServers": { "google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"] + "type": "sse", + "url": "https://mapscodeassist.googleapis.com/mcp" } } } ``` -4. **[Firebase Studio](https://firebase.google.com/docs/studio/customize-workspace)** - * Try in Firebase Studio with Code Assist MCP installed - * Add to your project's `mcp.json` file in the `.idx` folder in your Firebase Studio workspace +4. **Codex** + * Add the following to your Codex configuration to enable the remote MCP server: ```json { "mcpServers": { "google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"] + "type": "sse", + "url": "https://mapscodeassist.googleapis.com/mcp" } } } ``` -5. **[Android Studio](https://developer.android.com/studio/gemini/add-mcp-server)** - * Create a `mcp.json` file and place it in the [configuration directory](https://developer.android.com/studio/troubleshoot#directories) of Android Studio. Add the Code Assist server to the list: +5. **Antigravity** + * In your Antigravity configuration or workspace settings, add the streamable HTTP endpoint: ```json { "mcpServers": { "google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"] + "type": "sse", + "url": "https://mapscodeassist.googleapis.com/mcp" } } } ``` -6. **[Cline](https://docs.cline.bot/mcp/configuring-mcp-servers)** - * Option 1: install using the [Cline MCP GUI](https://docs.cline.bot/mcp/configuring-mcp-servers) - * Option 2: manually / programatically install using the Cline MCP config file. The config file is located at: - * **macOS:** `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - * **Windows:** `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - * **Linux:** `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - * Add the following to your MCP configuration in `cline_mcp_settings.json`: - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"], - "alwaysAllow": [ - "retrieve-instructions", - "retrieve-google-maps-platform-docs" - ] - } - } - } - ``` -7. **[Roo Code](https://docs.roocode.com/features/mcp/using-mcp-in-roo)** - * Option 1: install using the [Roo MCP GUI](https://docs.roocode.com/features/mcp/using-mcp-in-roo) - * Option 2: manually / programatically install using the Roo Code config file. The config file is located at: - * **macOS:** `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` - * **Windows:** `%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json` - * **Linux:** `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` - * Add the following to your MCP configuration in `mcp_settings.json`: - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"], - "alwaysAllow": [ - "retrieve-instructions", - "retrieve-google-maps-platform-docs" - ] - } - } - } - ``` - -8. **[Microsoft Copilot](https://learn.microsoft.com/en-us/microsoft-copilot-studio/agent-extend-action-mcp)** - * When in Agent mode, Click "Tools" and then in the top header "Configure Tools" then "Install from an NPM package name" (See screenshots below) - * image - - * image - * image - * Enter pacakge name `@googlemaps/code-assist-mcp` and ENTER, accepting the install and using the default port 3000, then ENTER one last time to confirm the change - * image - - -9. **[Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp)** - * Similar to Cursor instructions above. - -10. **[Kilo Code](https://kilocode.ai/docs/features/mcp/using-mcp-in-kilo-code)** - * Similar to the Cline and Roo Code instructions above - - - ------ - - - -## Available Settings - -### Port Configuration - -By default, the server runs on port `3000`. You can specify a different port using the `--port` flag or a `PORT` environment variable. The `--port` flag takes precedence. - -**Example: Use port `5000`** - -In your `mcp.json`: - -```json -"google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest", "--port", "5000"] -} -``` - -Or with an environment variable: - -```json -"google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"], - "env": { - "PORT": "5000" - } -} -``` - -If the specified port is unavailable, the server will automatically find and start on a random available port. - -### Source Configuration - -You can specify a `SOURCE` environment variable to track the origin of the requests. The default value is `github`. - -**Example: Set source to `my_company_name`** - -In your `mcp.json`: - -```json -"google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"], - "env": { - "SOURCE": "my_company_name" - } -} -``` - - - ------ - - - -## Local Streamable HTTP Guide - -For developers who need to integrate the Google Maps Platform Code Assist MCP server using the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport on their local machine, this guide provides setup instructions and testing steps. - -### When to Use Local Streamable HTTP - -Use the local Streamable HTTP transport when: -- Your client requires a URL-based connection instead of command execution -- Your local development environment requires HTTP-based communication -- You're building and testing custom integrations that communicate over HTTP - -### Local Streamable HTTP Setup - -**1. Start the Server** - -Run the MCP server locally, specifying a port: - -```bash -npx -y @googlemaps/code-assist-mcp@latest --port 3215 -``` - -The server will be available at `http://localhost:3215/mcp`. - -**2. Configure Your Client** - -Update your client's MCP configuration to connect to the local server URL. - -**Note:** Check that the `type` parameter in your MCP configuration is set correctly for your specific client. For example, Roo Code uses `"type": "streamable-http"`, while Cline uses `"type": "streamableHttp"`. - -**Roo Code (VS Code Extension)** - -Add to `mcp_settings.json`: -```json -{ - "mcpServers": { - "google-maps-platform-code-assist": { - "type": "streamable-http", - "url": "http://localhost:3215/mcp", - "alwaysAllow": [ - "retrieve-instructions", - "retrieve-google-maps-platform-docs" - ] - } - } -} -``` - -**Cline (VS Code Extension)** - -Add to `cline_mcp_settings.json`: -```json -{ - "mcpServers": { - "google-maps-platform-code-assist": { - "type": "streamableHttp", - "url": "http://localhost:3215/mcp", - "alwaysAllow": [ - "retrieve-instructions", - "retrieve-google-maps-platform-docs" - ] - } - } -} -``` - -### Testing Your Local Setup with cURL - -Verify your server is working correctly by sending an `initialize` request: - -```bash -# Test server initialization -curl -X POST http://localhost:3215/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -d '{ - "jsonrpc": "2.0", - "id": 1, - "method": "initialize", - "params": { - "protocolVersion": "2025-03-26", - "capabilities": {}, - "clientInfo": {"name": "test-client", "version": "1.0.0"} - } - }' -``` - -**Expected Response:** -The server will respond with an SSE event containing its capabilities. -``` -event: message -data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","capabilities":{"tools":{},"logging":{},"resources":{}},"serverInfo":{"name":"code-assist-mcp","version":"0.1.3"}}} -``` - - - ------ - - - -### Use as a Remote MCP Server on Cloud Run with Streamable HTTP - -Run the server on Google Cloud Run and connect to it from your local machine. This is useful if your client requires a remotely-hosted, streamable HTTP endpoint. - -> [\!WARNING] -> These instructions secure the server so only you can access it with the proper IAM roles for your applications, MCP Clients, or Agents. - -**1. Prerequisites** - -Install the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install) and authenticate your account: - -```bash -gcloud auth login -gcloud config set project YOUR_PROJECT_ID -``` - -**2. Deploy to Cloud Run** - -This command deploys the server from this repository's source code and ensures it is **not** publicly accessible. - -```bash -gcloud run deploy google-maps-code-assist-mcp --source . --no-allow-unauthenticated -``` - -When prompted, select a region (e.g., `us-central1`). - -**3. Connect Securely** - -Run a Cloud Run proxy on your local machine. This creates a secure tunnel from a local port to your remote server, authenticated with your `gcloud` identity. - -```bash -gcloud run services proxy google-maps-code-assist-mcp --port=8999 --region=YOUR_REGION -``` - -Now, `http://localhost:8999` on your machine securely connects to your Cloud Run service. - -**4. Configure Your Client** - -Update your client's MCP configuration to point to the local proxy. - - * Connect using the `url` attribute over Streamable HTTP: - - ```json - "google-maps-platform-code-assist": { - "url": "http://localhost:8999/mcp", - "type": //Either "streamableHttp" or "streamable-http", depending on your MCP client - } - ``` - -**5. Connect GCP Services (Alternative to Local Proxy)** - -To connect another GCP service to the remotely deployed Cloud Run MCP server, such as an [Agent Development Kit (ADK)](https://google.github.io/adk-docs/) agent on GCP Cloud Run or [Vertex AI Agent Engine](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview), you can connect the client directly to the remote MCP service over Streamable HTTP using the following IAM roles: - -```bash -# Grant Cloud Run Invoker role to the service account -gcloud run services add-iam-policy-binding google-maps-code-assist-mcp \ - --member="serviceAccount:YOUR-SERVICE-ACCOUNT@YOUR-PROJECT.iam.gserviceaccount.com" \ - --role="roles/run.invoker" \ - --region=YOUR_REGION -``` - -Now your GCP hosted app or agent can connect directly to the remotely hosted MCP server URL over Streamable HTTP. - -**6. Health Check Endpoint** - -This server implementation includes a standard `/health` endpoint. This is a best practice for services deployed on platforms like Cloud Run, which use it to check the server's operational status. - -- **HTTP `/health` Endpoint**: A simple `GET` request to this endpoint (e.g., `https://your-service-url/health`) will return a `200 OK` status with a JSON payload containing the server status, number of active sessions, and a timestamp if the server is running. This is used for infrastructure-level health checks. -- **MCP `ping` Utility**: This is different from the in-protocol `ping` utility defined by the MCP specification. The `ping` utility is a JSON-RPC request sent *after* a session is established to check the liveness of the *protocol connection*, whereas the `/health` endpoint checks the liveness of the *HTTP server* itself. @@ -470,9 +148,9 @@ This server implementation includes a standard `/health` endpoint. This is a bes ## **Terms of Service** -This toolkit provides tools to describe the use of Google Maps Platform services. Use of Google Maps Platform services is subject to the Google Maps Platform [Terms of Service](https://cloud.google.com/maps-platform/terms), however, if your billing address is in the European Economic Area, the Google Maps Platform [EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](https://developers.google.com/maps/comms/eea/faq). +This toolkit provides tools to describe the use of Google Maps Platform services. Use of Google Maps Platform services is subject to the Google Maps Platform [Terms of Service](https://cloud.google.com/maps-platform/terms). If your billing address is in the European Economic Area, the Google Maps Platform [EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. -This toolkit is not a Google Maps Platform Core Service. Therefore, the Google Maps Platform Terms of Service (e.g. Technical Support Services, Service Level Agreements, and Deprecation Policy) do not apply to the code in this repository or the RAG service called by it. +This toolkit is not a Google Maps Platform Core Service. Therefore, the Google Maps Platform Terms of Service (such as Technical Support Services, Service Level Agreements, and Deprecation Policy) do not apply to the code in this repository or the RAG service called by it. @@ -486,11 +164,8 @@ If you find a bug, or have a feature request, please [file an issue](https://git You can also discuss this toolkit on our [Discord server](https://discord.gg/hYsWbmk). - -[npm-pkg]: - [Discord server]: https://discord.gg/hYsWbmk [license]: LICENSE - + \ No newline at end of file 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..cdaebca --- /dev/null +++ b/packages/code-assist/skills/google-maps-platform-dev/SKILL.md @@ -0,0 +1,40 @@ + +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. + + + +**🔧 Available MCP Tools (gmp-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. + +**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. + +**Automatic Tool Usage Triggers** +Use the MCP tools immediately when queries involve: +- Maps, mapping, or cartography +- Location services, geocoding, or reverse geocoding +- Places API, Routes API, or Navigation SDK +- Street View, satellite imagery, or terrain data +- Location analytics or geospatial data +- Any Google Maps Platform product or service +- Geographic coordinates, addresses, or points of interest +- Use cases like data visualization, store locator, routing, logistics, delivery, mobility + +**Core Principle: Self-Evaluation & Validation** +After using tools to gather information: +- Validate your code solutions by running them when possible. +- Use the terminal to check for compilation errors. +- For web content, describe how to launch a browser to inspect results. +- 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. + From c34c2830cd667ea85e674ac432f5bb4563f80857 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 13:58:33 -0800 Subject: [PATCH 02/16] docs: refine MCP configuration instructions and CLI commands for clients --- packages/code-assist/README.md | 160 +++++++++++++++++++-------------- 1 file changed, 91 insertions(+), 69 deletions(-) diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index fdca66d..efe134b 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -3,10 +3,12 @@ [![Discord](https://img.shields.io/discord/676948200904589322?color=6A7EC2&logo=discord&logoColor=ffffff)][Discord server] [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=google-maps-platform&config=eyJ0eXBlIjoic3NlIiwidXJsIjoiaHR0cHM6Ly9tYXBzY29kZWFzc2lzdC5nb29nbGVhcGlzLmNvbS9tY3AifQ==) -# Google Maps Platform Logo Google Maps Platform Code Assist Toolkit -*Alpha version* +# Google Maps Platform Logo Google Maps Platform Code Assist Toolkit + +_Alpha version_ + ## Description The Google Maps Platform Code Assist toolkit is a Model Context Protocol (MCP) server that enhances the responses from large language models (LLMs) used for developing applications with the Google Maps Platform by grounding the responses in the official, up-to-date documentation and code samples. @@ -22,6 +24,7 @@ Google Maps Platform resources that the MCP server can access include: + ## Benefits - Make your favorite AI assistant or IDE an expert on the Google Maps Platform. With Code Assist, AI Agents like Gemini CLI, Claude Code, and Cursor can generate code and answer developer questions grounded in up-to-date, official Google Maps Platform documentation and code samples -- directly in your dev workflow. @@ -29,27 +32,30 @@ Google Maps Platform resources that the MCP server can access include: - Whether you are making precision AI-Assisted code changes or vibecoding a new app prototype - Code Assist can help you accomplish your task faster and easier. + Below is an example MCP Client response to a user's question with Code Assist MCP installed: -![](./code-assist-preview.jpg) +![](./code-assist-preview.jpg) > [\!NOTE] > This is the repository for an MCP server that provides access to Google Maps Platform documentation via a RAG service. It is not a Google Maps Platform Core Service. + ------ +--- + ## Tools Provided The MCP server exposes the following tools for AI clients: - 1. **`retrieve-instructions`**: A helper tool used by the client to get crucial system instructions on how to best reason about user intent and formulate effective calls to the `retrieve-google-maps-platform-docs` tool. - 2. **`retrieve-google-maps-platform-docs`**: The primary tool. It takes a natural language query and submits it to a hosted Retrieval Augmented Generation (RAG) engine. The RAG engine searches fresh versions of official Google Maps Platform documentation, tutorials, and code samples, returning relevant context to the AI to generate an accurate response. +1. **`retrieve-instructions`**: A helper tool used by the client to get crucial system instructions on how to best reason about user intent and formulate effective calls to the `retrieve-google-maps-platform-docs` tool. +2. **`retrieve-google-maps-platform-docs`**: The primary tool. It takes a natural language query and submits it to a hosted Retrieval Augmented Generation (RAG) engine. The RAG engine searches fresh versions of official Google Maps Platform documentation, tutorials, and code samples, returning relevant context to the AI to generate an accurate response. ------ +--- @@ -57,13 +63,14 @@ The MCP server exposes the following tools for AI clients: This remote server supports standard MCP communication protocols: - * **`Streamable HTTP`**: The server exposes a `/mcp` endpoint that accepts POST requests over the HTTPS protocol. This is used by clients that connect via a `url` and is the standard for remote server connections. Our implementation supports Server-Sent Events (SSE) for real-time, interactive responses. +- **`streamable HTTP`**: The server exposes a `/mcp` endpoint that accepts POST requests over the HTTPS protocol. This is used by clients that connect via a `url` and is the standard for remote server connections. Our implementation supports Server-Sent Events (SSE) for real-time, interactive responses. ------ +--- + ## Usage The Code Assist MCP server is securely hosted by Google. To use it, you must configure your AI client to connect to the remote URL via Server-Sent Events (SSE). @@ -73,76 +80,90 @@ The Code Assist MCP server is securely hosted by Google. To use it, you must con Add the remote server URL to your preferred AI client's MCP configuration file or settings UI. Find your client below for specific, verified instructions. 1. **Gemini CLI** - * Option 1 - Install the Code Assist MCP server as a Gemini CLI extension. This provides the most complete experience, including specialized developer skills: - ```bash - gemini extensions install https://github.com/googlemaps/platform-ai.git - ``` - * Option 2 - Add the MCP server config manually to your `~/.gemini/servers.json` file. - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "type": "sse", - "url": "https://mapscodeassist.googleapis.com/mcp" - } - } - } - ``` + - Option 1 (Recommended) - Install the Code Assist MCP server as a Gemini CLI extension. This provides the most complete experience, including specialized developer skills: + ```bash + gemini extensions install https://github.com/googlemaps/platform-ai.git + ``` + - Option 2 - Use the `mcp add` CLI command to add the server cleanly: + ```bash + gemini mcp add google-maps-platform-code-assist sse https://mapscodeassist.googleapis.com/mcp + ``` + - Option 3 - Add the MCP server config manually to your `~/.gemini/settings.json` file (or `.gemini/settings.json` in your project root). + + ```json + { + "mcpServers": { + "google-maps-platform-code-assist": { + "type": "sse", + "url": "https://mapscodeassist.googleapis.com/mcp" + } + } + } + ``` 2. **Claude Code** - * Add the server manually to your Claude config file `~/.claude.json`: - ```json - "mcpServers": { - "google-maps-platform-code-assist": { - "type": "sse", - "url": "https://mapscodeassist.googleapis.com/mcp" - } - } - ``` + - The cleanest way to add the remote server is via the `mcp add` CLI command: + ```bash + claude mcp add google-maps-platform-code-assist sse https://mapscodeassist.googleapis.com/mcp + ``` + - Alternatively, add the server manually to your Claude config file `~/.claude.json`: + + ```json + { + "mcpServers": { + "google-maps-platform-code-assist": { + "type": "sse", + "url": "https://mapscodeassist.googleapis.com/mcp" + } + } + } + ``` 3. **Cursor** - * [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=google-maps-platform&config=eyJ0eXBlIjoic3NlIiwidXJsIjoiaHR0cHM6Ly9tYXBzY29kZWFzc2lzdC5nb29nbGVhcGlzLmNvbS9tY3AifQ==) <-- If you already have Cursor installed, click here to install the Google Maps Platform Code Assist MCP directly. - * Otherwise, add it to your workspace's `.cursor/mcp.json` file. - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "type": "sse", - "url": "https://mapscodeassist.googleapis.com/mcp" - } - } - } - ``` + - [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=google-maps-platform&config=eyJ0eXBlIjoic3NlIiwidXJsIjoiaHR0cHM6Ly9tYXBzY29kZWFzc2lzdC5nb29nbGVhcGlzLmNvbS9tY3AifQ==) <-- If you already have Cursor installed, click here to install the Google Maps Platform Code Assist MCP directly. + - Otherwise, add it to your workspace's `.cursor/mcp.json` file. + + ```json + { + "mcpServers": { + "google-maps-platform-code-assist": { + "type": "sse", + "url": "https://mapscodeassist.googleapis.com/mcp" + } + } + } + ``` 4. **Codex** - * Add the following to your Codex configuration to enable the remote MCP server: - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "type": "sse", - "url": "https://mapscodeassist.googleapis.com/mcp" - } - } - } - ``` + - Add the following to your Codex configuration to enable the remote MCP server: + + ```json + { + "mcpServers": { + "google-maps-platform-code-assist": { + "type": "sse", + "url": "https://mapscodeassist.googleapis.com/mcp" + } + } + } + ``` 5. **Antigravity** - * In your Antigravity configuration or workspace settings, add the streamable HTTP endpoint: - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "type": "sse", - "url": "https://mapscodeassist.googleapis.com/mcp" - } - } - } - ``` + - In your Antigravity configuration or workspace settings, add the streamable HTTP endpoint: + ```json + { + "mcpServers": { + "google-maps-platform-code-assist": { + "type": "sse", + "url": "https://mapscodeassist.googleapis.com/mcp" + } + } + } + ``` ------ +--- @@ -165,7 +186,8 @@ If you find a bug, or have a feature request, please [file an issue](https://git You can also discuss this toolkit on our [Discord server](https://discord.gg/hYsWbmk). + [Discord server]: https://discord.gg/hYsWbmk [license]: LICENSE - \ No newline at end of file + From d05be0164dd441f6a6ae4e55c7ee519cc3382326 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 14:01:01 -0800 Subject: [PATCH 03/16] docs: fix Codex TOML MCP configuration and refine Claude Code instructions --- packages/code-assist/README.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index efe134b..6feb29f 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -135,17 +135,15 @@ Add the remote server URL to your preferred AI client's MCP configuration file o ``` 4. **Codex** - - Add the following to your Codex configuration to enable the remote MCP server: + - The easiest way to connect Codex to the remote server is via the CLI: + ```bash + codex mcp add google-maps-platform-code-assist --url https://mapscodeassist.googleapis.com/mcp + ``` + - If you prefer manual configuration, add the following to your `~/.codex/config.toml` or your project's `.codex/config.toml`: - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "type": "sse", - "url": "https://mapscodeassist.googleapis.com/mcp" - } - } - } + ```toml + [mcp_servers.google-maps-platform-code-assist] + url = "https://mapscodeassist.googleapis.com/mcp" ``` 5. **Antigravity** From d6a9b73d6ef5e3aacf461b2ee60bc5bae9d5a4c0 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 14:13:08 -0800 Subject: [PATCH 04/16] docs: fix Gemini CLI MCP transport flags and JSON config --- packages/code-assist/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index 6feb29f..8f27f0e 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -86,7 +86,7 @@ Add the remote server URL to your preferred AI client's MCP configuration file o ``` - Option 2 - Use the `mcp add` CLI command to add the server cleanly: ```bash - gemini mcp add google-maps-platform-code-assist sse https://mapscodeassist.googleapis.com/mcp + gemini mcp add --transport sse google-maps-platform-code-assist https://mapscodeassist.googleapis.com/mcp ``` - Option 3 - Add the MCP server config manually to your `~/.gemini/settings.json` file (or `.gemini/settings.json` in your project root). @@ -94,7 +94,6 @@ Add the remote server URL to your preferred AI client's MCP configuration file o { "mcpServers": { "google-maps-platform-code-assist": { - "type": "sse", "url": "https://mapscodeassist.googleapis.com/mcp" } } From 4213e7f2f041c5828850bffc675a952db414e928 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 14:18:35 -0800 Subject: [PATCH 05/16] chore: align gemini-extension.json and Codex TOML configurations with official schemas --- gemini-extension.json | 1 - packages/code-assist/README.md | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/gemini-extension.json b/gemini-extension.json index 7241b08..6bb6057 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -8,7 +8,6 @@ }, "mcpServers": { "google-maps-platform-code-assist": { - "type": "sse", "url": "https://mapscodeassist.googleapis.com/mcp" } }, diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index 8f27f0e..8f11adc 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -142,6 +142,7 @@ Add the remote server URL to your preferred AI client's MCP configuration file o ```toml [mcp_servers.google-maps-platform-code-assist] + transport = "sse" url = "https://mapscodeassist.googleapis.com/mcp" ``` From 5a15ffd78713671025af65bbcf099d6562d4eed9 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 14:25:33 -0800 Subject: [PATCH 06/16] docs: fix transport terminology across clients to accurately reflect Streamable HTTP --- gemini-extension.json | 2 +- packages/code-assist/README.md | 20 ++++++++++---------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/gemini-extension.json b/gemini-extension.json index 6bb6057..72e92dc 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -8,7 +8,7 @@ }, "mcpServers": { "google-maps-platform-code-assist": { - "url": "https://mapscodeassist.googleapis.com/mcp" + "httpUrl": "https://mapscodeassist.googleapis.com/mcp" } }, "theme": "gmp-theme.json" diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index 8f11adc..2093f59 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -63,7 +63,7 @@ The MCP server exposes the following tools for AI clients: This remote server supports standard MCP communication protocols: -- **`streamable HTTP`**: The server exposes a `/mcp` endpoint that accepts POST requests over the HTTPS protocol. This is used by clients that connect via a `url` and is the standard for remote server connections. Our implementation supports Server-Sent Events (SSE) for real-time, interactive responses. +- **`streamable HTTP`**: The server exposes a `/mcp` endpoint that accepts POST requests over the HTTPS protocol. This is the modern, official standard for remote MCP server connections, replacing legacy HTTP+SSE split endpoints. @@ -73,7 +73,7 @@ This remote server supports standard MCP communication protocols: ## Usage -The Code Assist MCP server is securely hosted by Google. To use it, you must configure your AI client to connect to the remote URL via Server-Sent Events (SSE). +The Code Assist MCP server is securely hosted by Google. To use it, you must configure your AI client to connect to the remote URL via streamable HTTP. ### Configure Your Client @@ -86,7 +86,7 @@ Add the remote server URL to your preferred AI client's MCP configuration file o ``` - Option 2 - Use the `mcp add` CLI command to add the server cleanly: ```bash - gemini mcp add --transport sse google-maps-platform-code-assist https://mapscodeassist.googleapis.com/mcp + gemini mcp add --transport http google-maps-platform-code-assist https://mapscodeassist.googleapis.com/mcp ``` - Option 3 - Add the MCP server config manually to your `~/.gemini/settings.json` file (or `.gemini/settings.json` in your project root). @@ -94,7 +94,7 @@ Add the remote server URL to your preferred AI client's MCP configuration file o { "mcpServers": { "google-maps-platform-code-assist": { - "url": "https://mapscodeassist.googleapis.com/mcp" + "httpUrl": "https://mapscodeassist.googleapis.com/mcp" } } } @@ -103,7 +103,7 @@ Add the remote server URL to your preferred AI client's MCP configuration file o 2. **Claude Code** - The cleanest way to add the remote server is via the `mcp add` CLI command: ```bash - claude mcp add google-maps-platform-code-assist sse https://mapscodeassist.googleapis.com/mcp + claude mcp add google-maps-platform-code-assist http https://mapscodeassist.googleapis.com/mcp ``` - Alternatively, add the server manually to your Claude config file `~/.claude.json`: @@ -111,7 +111,7 @@ Add the remote server URL to your preferred AI client's MCP configuration file o { "mcpServers": { "google-maps-platform-code-assist": { - "type": "sse", + "type": "streamable-http", "url": "https://mapscodeassist.googleapis.com/mcp" } } @@ -119,14 +119,14 @@ Add the remote server URL to your preferred AI client's MCP configuration file o ``` 3. **Cursor** - - [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=google-maps-platform&config=eyJ0eXBlIjoic3NlIiwidXJsIjoiaHR0cHM6Ly9tYXBzY29kZWFzc2lzdC5nb29nbGVhcGlzLmNvbS9tY3AifQ==) <-- If you already have Cursor installed, click here to install the Google Maps Platform Code Assist MCP directly. + - [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=google-maps-platform&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWFwc2NvZGVhc3Npc3QuZ29vZ2xlYXBpcy5jb20vbWNwIn0=) <-- If you already have Cursor installed, click here to install the Google Maps Platform Code Assist MCP directly. - Otherwise, add it to your workspace's `.cursor/mcp.json` file. ```json { "mcpServers": { "google-maps-platform-code-assist": { - "type": "sse", + "type": "http", "url": "https://mapscodeassist.googleapis.com/mcp" } } @@ -142,7 +142,7 @@ Add the remote server URL to your preferred AI client's MCP configuration file o ```toml [mcp_servers.google-maps-platform-code-assist] - transport = "sse" + transport = "http" url = "https://mapscodeassist.googleapis.com/mcp" ``` @@ -152,7 +152,7 @@ Add the remote server URL to your preferred AI client's MCP configuration file o { "mcpServers": { "google-maps-platform-code-assist": { - "type": "sse", + "type": "streamable-http", "url": "https://mapscodeassist.googleapis.com/mcp" } } From ced7e4c00f0cea9c3653d5c49eaae6ef5b8fdaa8 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 14:29:39 -0800 Subject: [PATCH 07/16] docs: append MCP configuration learnings and official client docs to GEMINI.md --- GEMINI.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/GEMINI.md b/GEMINI.md index 691c2d2..c33b049 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -36,3 +36,12 @@ After using tools to gather information: - 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 + +**MCP Client Setup Knowledge & Docs** +When setting up or debugging remote MCP servers (like Code Assist), it's critical to understand that modern implementations use **Streamable HTTP** endpoints (single-connection HTTP POST/GET streams) rather than the legacy two-connection SSE architectures. Keep the following client-specific formats in mind: +- **MCP Spec** ([Docs](https://modelcontextprotocol.io/docs/concepts/transports)): Official reference distinguishing `stdio`, `streamable-http`, and legacy `sse`. +- **Gemini CLI** ([Docs](https://geminicli.com/docs/tools/mcp-server/)): Uses `--transport http` in the CLI. In `settings.json` and `gemini-extension.json`, it uniquely requires the `httpUrl` property instead of the standard `url` and `type` fields. +- **Gemini Extensions** ([Docs](https://geminicli.com/docs/extensions/)): The recommended distribution mechanism is packaging the MCP server config alongside this very `GEMINI.md` and `SKILLS.md` into an extension (installed via `gemini extensions install `). +- **Claude Code** ([Docs](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)): Uses the `claude mcp add http ` CLI command. Manual configs define the `mcpServers` object with `"type": "streamable-http"`. +- **Cursor** ([Docs](https://docs.cursor.com/context/model-context-protocol)): Configured in `~/.cursor/mcp.json`. It expects the conventional `"type": "http"`. Deep links are supported using a base64 encoded config payload. +- **Codex**: Utilizes a TOML configuration file. It requires specifying `transport = "http"` manually in `~/.codex/config.toml`, or simply using `codex mcp add --url `. From 03e8e6fa0764342780c3b45a23b94568ecea6dfe Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 14:29:59 -0800 Subject: [PATCH 08/16] chore: remove orphaned text files --- base64.txt | 1 - found_words.txt | 25 ------------------------- ls_out.txt | 4 ---- 3 files changed, 30 deletions(-) delete mode 100644 base64.txt delete mode 100644 found_words.txt delete mode 100644 ls_out.txt diff --git a/base64.txt b/base64.txt deleted file mode 100644 index f25639a..0000000 --- a/base64.txt +++ /dev/null @@ -1 +0,0 @@ -eyJ0eXBlIjoic3NlIiwidXJsIjoiaHR0cHM6Ly9tYXBzY29kZWFzc2lzdC5nb29nbGVhcGlzLmNvbS9tY3AifQ== diff --git a/found_words.txt b/found_words.txt deleted file mode 100644 index 45a18c3..0000000 --- a/found_words.txt +++ /dev/null @@ -1,25 +0,0 @@ - - alt="Try in Firebase Studio" - src="https://cdn.firebasestudio.dev/btn/try_dark_32.svg"> -4. **[Firebase Studio](https://firebase.google.com/docs/studio/customize-workspace)** - * Try in Firebase Studio with Code Assist MCP installed - * Add to your project's `mcp.json` file in the `.idx` folder in your Firebase Studio workspace -6. **[Cline](https://docs.cline.bot/mcp/configuring-mcp-servers)** - * Option 1: install using the [Cline MCP GUI](https://docs.cline.bot/mcp/configuring-mcp-servers) - * Option 2: manually / programatically install using the Cline MCP config file. The config file is located at: - * **macOS:** `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - * **Windows:** `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - * **Linux:** `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - * Add the following to your MCP configuration in `cline_mcp_settings.json`: -7. **[Roo Code](https://docs.roocode.com/features/mcp/using-mcp-in-roo)** - * Option 1: install using the [Roo MCP GUI](https://docs.roocode.com/features/mcp/using-mcp-in-roo) - * Option 2: manually / programatically install using the Roo Code config file. The config file is located at: - * **macOS:** `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` - * **Windows:** `%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json` - * **Linux:** `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` -10. **[Kilo Code](https://kilocode.ai/docs/features/mcp/using-mcp-in-kilo-code)** - * Similar to the Cline and Roo Code instructions above -**Note:** Check that the `type` parameter in your MCP configuration is set correctly for your specific client. For example, Roo Code uses `"type": "streamable-http"`, while Cline uses `"type": "streamableHttp"`. -**Roo Code (VS Code Extension)** -**Cline (VS Code Extension)** -Add to `cline_mcp_settings.json`: diff --git a/ls_out.txt b/ls_out.txt deleted file mode 100644 index feebac5..0000000 --- a/ls_out.txt +++ /dev/null @@ -1,4 +0,0 @@ -total 24 -drwxr-xr-x@ 3 ryanbaumann primarygroup 96 Mar 6 13:08 . -drwxr-xr-x@ 4 ryanbaumann primarygroup 128 Jan 31 09:52 .. --rw-r--r-- 1 ryanbaumann primarygroup 10244 Jan 28 14:59 .DS_Store From 213c99bfd6f03a09d25ab69f79b9c1f9f55e9f68 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 14:37:24 -0800 Subject: [PATCH 09/16] fix(skills): add missing YAML frontmatter to google-maps-platform-dev SKILL.md for Gemini CLI discovery --- .../code-assist/skills/google-maps-platform-dev/SKILL.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/code-assist/skills/google-maps-platform-dev/SKILL.md b/packages/code-assist/skills/google-maps-platform-dev/SKILL.md index cdaebca..9277037 100644 --- a/packages/code-assist/skills/google-maps-platform-dev/SKILL.md +++ b/packages/code-assist/skills/google-maps-platform-dev/SKILL.md @@ -1,3 +1,8 @@ +--- +name: google-maps-platform-dev +description: Expert assistant for Google Maps Platform development (Maps, Routes, Places, Environment APIs). Use when the user asks to build store locators, visualize maps, search or autocomplete places, perform geocoding, validate addresses, compute routes, add navigation, lookup weather, or perform geospatial analysis. Use for coding, debugging, architecture, and solutioning. +--- + 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. From acf817722fdf9771f2935a6c798b520f2ea0399b Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 14:47:54 -0800 Subject: [PATCH 10/16] docs: add Android Studio setup instructions and clarify marketplace installation paths for Gemini CLI and Antigravity MCPs --- GEMINI.md | 4 +++- packages/code-assist/README.md | 19 ++++++++++++++++++- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/GEMINI.md b/GEMINI.md index c33b049..61e3d48 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -41,7 +41,9 @@ After using tools to gather information: When setting up or debugging remote MCP servers (like Code Assist), it's critical to understand that modern implementations use **Streamable HTTP** endpoints (single-connection HTTP POST/GET streams) rather than the legacy two-connection SSE architectures. Keep the following client-specific formats in mind: - **MCP Spec** ([Docs](https://modelcontextprotocol.io/docs/concepts/transports)): Official reference distinguishing `stdio`, `streamable-http`, and legacy `sse`. - **Gemini CLI** ([Docs](https://geminicli.com/docs/tools/mcp-server/)): Uses `--transport http` in the CLI. In `settings.json` and `gemini-extension.json`, it uniquely requires the `httpUrl` property instead of the standard `url` and `type` fields. -- **Gemini Extensions** ([Docs](https://geminicli.com/docs/extensions/)): The recommended distribution mechanism is packaging the MCP server config alongside this very `GEMINI.md` and `SKILLS.md` into an extension (installed via `gemini extensions install `). +- **Gemini Extensions** ([Docs](https://geminicli.com/docs/extensions/)): The recommended distribution mechanism is packaging the MCP server config alongside this very `GEMINI.md` and `SKILLS.md` into an extension (installed via `gemini extensions install ` or from the marketplace via `gemini extensions install google-maps-platform`). +- **Android Studio** ([Docs](https://developer.android.com/studio/gemini/add-mcp-server)): Enabled via Settings > Tools > AI > MCP Servers. Expects an `httpUrl` property in its internal `mcp.json` exactly like Gemini CLI. +- **Antigravity** ([Docs](https://antigravity.google)): Use the built-in MCP Store in the agent panel, or manually configure the streamable HTTP endpoint in `mcp_config.json`. - **Claude Code** ([Docs](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)): Uses the `claude mcp add http ` CLI command. Manual configs define the `mcpServers` object with `"type": "streamable-http"`. - **Cursor** ([Docs](https://docs.cursor.com/context/model-context-protocol)): Configured in `~/.cursor/mcp.json`. It expects the conventional `"type": "http"`. Deep links are supported using a base64 encoded config payload. - **Codex**: Utilizes a TOML configuration file. It requires specifying `transport = "http"` manually in `~/.codex/config.toml`, or simply using `codex mcp add --url `. diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index 2093f59..f20a277 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -84,6 +84,7 @@ Add the remote server URL to your preferred AI client's MCP configuration file o ```bash gemini extensions install https://github.com/googlemaps/platform-ai.git ``` + *(Alternatively, you can install it directly from the Extension Marketplace using `gemini extensions install google-maps-platform`)* - Option 2 - Use the `mcp add` CLI command to add the server cleanly: ```bash gemini mcp add --transport http google-maps-platform-code-assist https://mapscodeassist.googleapis.com/mcp @@ -147,7 +148,8 @@ Add the remote server URL to your preferred AI client's MCP configuration file o ``` 5. **Antigravity** - - In your Antigravity configuration or workspace settings, add the streamable HTTP endpoint: + - The easiest way to install is via the built-in MCP Store: Open the `...` menu in the agent panel, select **MCP Servers**, find **Google Maps Platform**, and click **Install**. + - Alternatively, add the streamable HTTP endpoint to your `mcp_config.json`: ```json { "mcpServers": { @@ -159,6 +161,21 @@ Add the remote server URL to your preferred AI client's MCP configuration file o } ``` +6. **Android Studio** + - Go to **File** (or Android Studio on macOS) > **Settings** > **Tools** > **AI** > **MCP Servers**. + - Select **Enable MCP Servers**. + - Add the configuration. This will be saved in your Android Studio's `mcp.json` file: + + ```json + { + "mcpServers": { + "google-maps-platform-code-assist": { + "httpUrl": "https://mapscodeassist.googleapis.com/mcp" + } + } + } + ``` + --- From 2af3c4fe8c062442adbb0c14928c59da53471314 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 15:04:12 -0800 Subject: [PATCH 11/16] docs: sync MCP tool definitions, rename to gmp-code-assist, and add deprecation notice Note: This PR is dependent on another upcoming PR that will deprecate all of the old self-hosted version code on NPM. We have added a notice in the README that the NPM version will be deprecated and will no longer be available as of [XX date - to be completed]. Users should use the securely hosted remote version as the primary connection method, as referenced in this README. - Renamed skill and MCP server references to strictly use 'gmp-code-assist' - Updated MCP tools descriptions in READMEs to perfectly match the 'retrieve-google-maps-platform-docs' and 'retrieve-instructions' endpoints. - Removed arbitrary 'vibecoding' language for safer enterprise tone. - Ensured total consistency across root README, package README, GEMINI.md, and skill specs. --- GEMINI.md | 10 ++-- README.md | 46 ++++++++++------ gemini-extension.json | 4 +- packages/code-assist/README.md | 36 +++++++------ .../skills/gmp-code-assist/skill.md | 54 +++++++++++++++++++ .../skills/google-maps-platform-dev/SKILL.md | 45 ---------------- 6 files changed, 112 insertions(+), 83 deletions(-) create mode 100644 packages/code-assist/skills/gmp-code-assist/skill.md delete mode 100644 packages/code-assist/skills/google-maps-platform-dev/SKILL.md diff --git a/GEMINI.md b/GEMINI.md index 61e3d48..a7b997b 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -2,10 +2,12 @@ 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. -**🔧 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 +**🔧 Available MCP Tools (gmp-code-assist)** +You have access to the `gmp-code-assist` MCP server with these essential tools: +- **`retrieve-google-maps-platform-docs`**: Searches Google Maps Platform documentation, code samples, architecture center, and GitHub repositories via RAG. + - *Parameters*: `llmQuery` (Required string query), `filter` (Optional API/product area filter), `source` (Optional string caller identifier up to 64 chars). +- **`retrieve-instructions`**: Retrieves foundational context on Google Maps Platform best practices. + - *Parameters*: `name` (Required string, expected format is simply "instructions"). **Core Principle: Tool-First Approach for GMP Queries** For **ANY** Google Maps Platform related query, question, or task, you **MUST**: diff --git a/README.md b/README.md index 6fa7697..ebe8cc1 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,20 @@ ## **Description** +> [!WARNING] +> We will be deprecating the NPM version of Code Assit, and it will no longer be available as of [XX date - to be completed]. Please use the securely hosted remote MCP version docuemnted in this README as the primary method of connection. + This repository contains the [Google Maps Platform Code Assist toolkit](packages/code-assist/README.md), a Model Context Protocol (MCP) server that enhances the responses from large language models (LLMs) used for developing applications with the Google Maps Platform by grounding them in the official, up-to-date documentation and code samples. +## **🔧 Available MCP Tools (gmp-code-assist)** + +You have access to the `gmp-code-assist` MCP server with these essential tools: + +- **`retrieve-google-maps-platform-docs`**: Searches Google Maps Platform documentation, code samples, architecture center, and GitHub repositories via RAG. + - _Parameters_: `llmQuery` (Required string query), `filter` (Optional API/product area filter), `source` (Optional string caller identifier up to 64 chars). +- **`retrieve-instructions`**: Retrieves foundational context on Google Maps Platform best practices. + - _Parameters_: `name` (Required string, expected format is simply "instructions"). + ## Install the Google Maps Platform Code Assist extension for [Gemini CLI](https://geminicli.com/) 1. Install the Gemini CLI ([alternative installation methods](https://geminicli.com/docs/get-started/deployment/)) @@ -17,23 +29,22 @@ npm install -g @google/gemini-cli ``` 2. Install the Google Maps Platform extension + - Option 1 - Install Code Assist as a Gemini CLI extension with static preamble, the MCP tool, and basic Google Maps theme: + ```bash + gemini extensions install https://github.com/googlemaps/platform-ai.git + ``` - * Option 1 - Install Code Assist as a Gemini CLI extension with static preamble, the MCP tool, and basic Google Maps theme: - ```bash - gemini extensions install https://github.com/googlemaps/platform-ai.git - ``` - * Verify the installation by running `gemini mcp list`. - * Option 2 - Add the MCP server config manually to your `~/.gemini/settings.json` file. - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"] - } - } - } - ``` + - Verify the installation by running `gemini mcp list`. + - Option 2 - Add the MCP server config manually to your `~/.gemini/settings.json` file to securely connect to the Google-hosted remote service: + ```json + { + "mcpServers": { + "gmp-code-assist": { + "httpUrl": "https://mapscodeassist.googleapis.com/mcp" + } + } + } + ``` ## Install the Google Maps Platform Code Assist toolkit for other MCP clients. @@ -50,4 +61,5 @@ Use these example prompts to get started with the Code Assist MCP server or supp - How do I set up billing for Google Maps Platform? -[npm-pkg]: + +[npm-pkg]: https://npmjs.com/package/@googlemaps/code-assist-mcp diff --git a/gemini-extension.json b/gemini-extension.json index 72e92dc..dc386d6 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -4,10 +4,10 @@ "description": "Ground agents on fresh, official Google Maps Platform documentation and code samples for optimal geo-related developer guidance and code", "contextFileName": "GEMINI.md", "skills": { - "google-maps-platform-dev": "packages/code-assist/skills/google-maps-platform-dev" + "gmp-code-assist": "packages/code-assist/skills/gmp-code-assist" }, "mcpServers": { - "google-maps-platform-code-assist": { + "gmp-code-assist": { "httpUrl": "https://mapscodeassist.googleapis.com/mcp" } }, diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index f20a277..8e65e5e 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -29,7 +29,7 @@ Google Maps Platform resources that the MCP server can access include: - Make your favorite AI assistant or IDE an expert on the Google Maps Platform. With Code Assist, AI Agents like Gemini CLI, Claude Code, and Cursor can generate code and answer developer questions grounded in up-to-date, official Google Maps Platform documentation and code samples -- directly in your dev workflow. -- Whether you are making precision AI-Assisted code changes or vibecoding a new app prototype - Code Assist can help you accomplish your task faster and easier. +- Whether you are making precision AI-Assisted code changes or building applications with Google Maps Platform using AI agents - Code Assist can help you accomplish your task faster and easier. @@ -51,9 +51,11 @@ Below is an example MCP Client response to a user's question with Code Assist MC The MCP server exposes the following tools for AI clients: -1. **`retrieve-instructions`**: A helper tool used by the client to get crucial system instructions on how to best reason about user intent and formulate effective calls to the `retrieve-google-maps-platform-docs` tool. -2. **`retrieve-google-maps-platform-docs`**: The primary tool. It takes a natural language query and submits it to a hosted Retrieval Augmented Generation (RAG) engine. The RAG engine searches fresh versions of official Google Maps Platform documentation, tutorials, and code samples, returning relevant context to the AI to generate an accurate response. - +1. **`retrieve-google-maps-platform-docs`**: Searches Google Maps Platform documentation, code samples, architecture center, and GitHub repositories via RAG. + - *Parameters*: `llmQuery` (Required string query), `filter` (Optional API/product area filter), `source` (Optional string caller identifier up to 64 chars). +2. **`retrieve-instructions`**: Retrieves foundational context on Google Maps Platform best practices. + - *Parameters*: `name` (Required string, expected format is simply "instructions"). + --- @@ -73,6 +75,9 @@ This remote server supports standard MCP communication protocols: ## Usage +> [!WARNING] +> We will be deprecating the version of this package on NPM, and it will no longer be available as of [XX date - to be completed]. Please use the securely hosted remote version as the primary method of connection, as documented below. + The Code Assist MCP server is securely hosted by Google. To use it, you must configure your AI client to connect to the remote URL via streamable HTTP. ### Configure Your Client @@ -84,17 +89,17 @@ Add the remote server URL to your preferred AI client's MCP configuration file o ```bash gemini extensions install https://github.com/googlemaps/platform-ai.git ``` - *(Alternatively, you can install it directly from the Extension Marketplace using `gemini extensions install google-maps-platform`)* + _(Alternatively, you can install it directly from the Extension Marketplace using `gemini extensions install google-maps-platform`)_ - Option 2 - Use the `mcp add` CLI command to add the server cleanly: ```bash - gemini mcp add --transport http google-maps-platform-code-assist https://mapscodeassist.googleapis.com/mcp + gemini mcp add --transport http gmp-code-assist https://mapscodeassist.googleapis.com/mcp ``` - Option 3 - Add the MCP server config manually to your `~/.gemini/settings.json` file (or `.gemini/settings.json` in your project root). ```json { "mcpServers": { - "google-maps-platform-code-assist": { + "gmp-code-assist": { "httpUrl": "https://mapscodeassist.googleapis.com/mcp" } } @@ -104,14 +109,14 @@ Add the remote server URL to your preferred AI client's MCP configuration file o 2. **Claude Code** - The cleanest way to add the remote server is via the `mcp add` CLI command: ```bash - claude mcp add google-maps-platform-code-assist http https://mapscodeassist.googleapis.com/mcp + claude mcp add gmp-code-assist http https://mapscodeassist.googleapis.com/mcp ``` - Alternatively, add the server manually to your Claude config file `~/.claude.json`: ```json { "mcpServers": { - "google-maps-platform-code-assist": { + "gmp-code-assist": { "type": "streamable-http", "url": "https://mapscodeassist.googleapis.com/mcp" } @@ -126,7 +131,7 @@ Add the remote server URL to your preferred AI client's MCP configuration file o ```json { "mcpServers": { - "google-maps-platform-code-assist": { + "gmp-code-assist": { "type": "http", "url": "https://mapscodeassist.googleapis.com/mcp" } @@ -137,23 +142,24 @@ Add the remote server URL to your preferred AI client's MCP configuration file o 4. **Codex** - The easiest way to connect Codex to the remote server is via the CLI: ```bash - codex mcp add google-maps-platform-code-assist --url https://mapscodeassist.googleapis.com/mcp + codex mcp add gmp-code-assist --url https://mapscodeassist.googleapis.com/mcp ``` - If you prefer manual configuration, add the following to your `~/.codex/config.toml` or your project's `.codex/config.toml`: ```toml - [mcp_servers.google-maps-platform-code-assist] + [mcp_servers.gmp-code-assist] transport = "http" url = "https://mapscodeassist.googleapis.com/mcp" ``` 5. **Antigravity** - - The easiest way to install is via the built-in MCP Store: Open the `...` menu in the agent panel, select **MCP Servers**, find **Google Maps Platform**, and click **Install**. + - The easiest way to install is via the built-in MCP Store: Open the `...` menu in the agent panel, select **MCP Servers**, find **Google Maps Platform**, and click **Install**. - Alternatively, add the streamable HTTP endpoint to your `mcp_config.json`: + ```json { "mcpServers": { - "google-maps-platform-code-assist": { + "gmp-code-assist": { "type": "streamable-http", "url": "https://mapscodeassist.googleapis.com/mcp" } @@ -169,7 +175,7 @@ Add the remote server URL to your preferred AI client's MCP configuration file o ```json { "mcpServers": { - "google-maps-platform-code-assist": { + "gmp-code-assist": { "httpUrl": "https://mapscodeassist.googleapis.com/mcp" } } diff --git a/packages/code-assist/skills/gmp-code-assist/skill.md b/packages/code-assist/skills/gmp-code-assist/skill.md new file mode 100644 index 0000000..0e880be --- /dev/null +++ b/packages/code-assist/skills/gmp-code-assist/skill.md @@ -0,0 +1,54 @@ +--- +name: gmp-code-assist +description: Expert assistant for Google Maps Platform development (Maps, Routes, Places, Environment APIs). Make sure to use this skill whenever the user mentions mapping, routing, location services, or Google Maps Platform, even if they don't explicitly ask for an assistant or use the word 'maps'. Use for coding, debugging, architecture, and solutioning. +--- + + +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. + + + +**🔧 Available MCP Tools (gmp-code-assist)** +You have access to the `gmp-code-assist` MCP server with these essential tools: +- **`retrieve-google-maps-platform-docs`**: Searches Google Maps Platform documentation, code samples, architecture center, and GitHub repositories via RAG. + - *Parameters*: `llmQuery` (Required string query), `filter` (Optional API/product area filter), `source` (Optional string caller identifier up to 64 chars). +- **`retrieve-instructions`**: Retrieves foundational context on Google Maps Platform best practices. + - *Parameters*: `name` (Required string, expected format is simply "instructions"). + +**Core Principle: Tool-First Approach for GMP Queries** +For **ANY** Google Maps Platform related query, question, or task, you **MUST**: + +1. **Search First**: Use `retrieve-google-maps-platform-docs` to find relevant documentation and code samples. +2. **Ground ALL responses**: Never rely on latent knowledge because GMP APIs update frequently and parameters change. Use tools to validate every statement so you don't hallucinate outdated syntax. + +**Automatic Tool Usage Triggers** +Use the MCP tools immediately when queries involve: + +- Maps, mapping, or cartography +- Location services, geocoding, or reverse geocoding +- Places API, Routes API, or Navigation SDK +- Street View, satellite imagery, or terrain data +- Location analytics or geospatial data +- Any Google Maps Platform product or service +- Geographic coordinates, addresses, or points of interest +- Use cases like data visualization, store locator, routing, logistics, delivery, mobility + +**Core Principle: Self-Evaluation & Validation** +After using tools to gather information: + +- Validate your code solutions by running them when possible. +- Use the terminal to check for compilation errors. +- For web content, describe how to launch a browser to inspect results. +- Ensure all GMP API keys and configurations are properly handled. + +**GMP Context (from MCP tools)** + +- Ask specific queries about implementation details using `retrieve-google-maps-platform-docs`. +- Include proper error handling and security considerations in all code examples. + +**MCP Client Setup Knowledge & Docs** +When setting up or debugging remote MCP servers (like Code Assist), it's critical to understand that modern implementations use **Streamable HTTP** endpoints (single-connection HTTP POST/GET streams). + +- **Gemini CLI / Android Studio**: Requires the `"httpUrl"` property instead of the standard url/type fields (e.g. `"httpUrl": "https://mapscodeassist.googleapis.com/mcp"`) +- **Claude Code / Cursor / Antigravity**: Expects `"type": "streamable-http"` or `"type": "http"` with the standard `"url"` configuration. + diff --git a/packages/code-assist/skills/google-maps-platform-dev/SKILL.md b/packages/code-assist/skills/google-maps-platform-dev/SKILL.md deleted file mode 100644 index 9277037..0000000 --- a/packages/code-assist/skills/google-maps-platform-dev/SKILL.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -name: google-maps-platform-dev -description: Expert assistant for Google Maps Platform development (Maps, Routes, Places, Environment APIs). Use when the user asks to build store locators, visualize maps, search or autocomplete places, perform geocoding, validate addresses, compute routes, add navigation, lookup weather, or perform geospatial analysis. Use for coding, debugging, architecture, and solutioning. ---- - - -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. - - - -**🔧 Available MCP Tools (gmp-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. - -**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. - -**Automatic Tool Usage Triggers** -Use the MCP tools immediately when queries involve: -- Maps, mapping, or cartography -- Location services, geocoding, or reverse geocoding -- Places API, Routes API, or Navigation SDK -- Street View, satellite imagery, or terrain data -- Location analytics or geospatial data -- Any Google Maps Platform product or service -- Geographic coordinates, addresses, or points of interest -- Use cases like data visualization, store locator, routing, logistics, delivery, mobility - -**Core Principle: Self-Evaluation & Validation** -After using tools to gather information: -- Validate your code solutions by running them when possible. -- Use the terminal to check for compilation errors. -- For web content, describe how to launch a browser to inspect results. -- 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. - From 3730c9bc2395410488d50ffa9ce268ef5a37fefe Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 15:06:33 -0800 Subject: [PATCH 12/16] docs: strip redundant MCP schemas from skill.md and focus purely on RAG reasoning strategies --- .../skills/gmp-code-assist/skill.md | 63 ++++++------------- 1 file changed, 19 insertions(+), 44 deletions(-) diff --git a/packages/code-assist/skills/gmp-code-assist/skill.md b/packages/code-assist/skills/gmp-code-assist/skill.md index 0e880be..e3a4d20 100644 --- a/packages/code-assist/skills/gmp-code-assist/skill.md +++ b/packages/code-assist/skills/gmp-code-assist/skill.md @@ -8,47 +8,22 @@ You are a world-class expert on the Google Maps Platform (GMP) operating with ac -**🔧 Available MCP Tools (gmp-code-assist)** -You have access to the `gmp-code-assist` MCP server with these essential tools: -- **`retrieve-google-maps-platform-docs`**: Searches Google Maps Platform documentation, code samples, architecture center, and GitHub repositories via RAG. - - *Parameters*: `llmQuery` (Required string query), `filter` (Optional API/product area filter), `source` (Optional string caller identifier up to 64 chars). -- **`retrieve-instructions`**: Retrieves foundational context on Google Maps Platform best practices. - - *Parameters*: `name` (Required string, expected format is simply "instructions"). - -**Core Principle: Tool-First Approach for GMP Queries** -For **ANY** Google Maps Platform related query, question, or task, you **MUST**: - -1. **Search First**: Use `retrieve-google-maps-platform-docs` to find relevant documentation and code samples. -2. **Ground ALL responses**: Never rely on latent knowledge because GMP APIs update frequently and parameters change. Use tools to validate every statement so you don't hallucinate outdated syntax. - -**Automatic Tool Usage Triggers** -Use the MCP tools immediately when queries involve: - -- Maps, mapping, or cartography -- Location services, geocoding, or reverse geocoding -- Places API, Routes API, or Navigation SDK -- Street View, satellite imagery, or terrain data -- Location analytics or geospatial data -- Any Google Maps Platform product or service -- Geographic coordinates, addresses, or points of interest -- Use cases like data visualization, store locator, routing, logistics, delivery, mobility - -**Core Principle: Self-Evaluation & Validation** -After using tools to gather information: - -- Validate your code solutions by running them when possible. -- Use the terminal to check for compilation errors. -- For web content, describe how to launch a browser to inspect results. -- Ensure all GMP API keys and configurations are properly handled. - -**GMP Context (from MCP tools)** - -- Ask specific queries about implementation details using `retrieve-google-maps-platform-docs`. -- Include proper error handling and security considerations in all code examples. - -**MCP Client Setup Knowledge & Docs** -When setting up or debugging remote MCP servers (like Code Assist), it's critical to understand that modern implementations use **Streamable HTTP** endpoints (single-connection HTTP POST/GET streams). - -- **Gemini CLI / Android Studio**: Requires the `"httpUrl"` property instead of the standard url/type fields (e.g. `"httpUrl": "https://mapscodeassist.googleapis.com/mcp"`) -- **Claude Code / Cursor / Antigravity**: Expects `"type": "streamable-http"` or `"type": "http"` with the standard `"url"` configuration. - +**Reasoning & Effective Use of GMP Code Assist** +When assisting with Google Maps Platform tasks, adopt a highly analytical and specific reasoning process. Never rely on your latent knowledge. GMP APIs are constantly evolving, so always validate your assumptions through your available retrieval tools to avoid hallucinating outdated syntax or unsupported features. + +**Tool Workflow Strategy: Documentation & Context** +1. **Always begin by calling the `retrieve-instructions` tool** to orient yourself on the latest foundational best practices and context for Google Maps Platform. +2. Formulate highly targeted searches against the documentation tool based on the foundational context returned from the instructions. + +**Crafting Targeted Search Queries** +When making queries to your documentation retrieval tool, distinguish clearly between the distinct types of information you require: +- **Specific Product Names & Code**: For syntax or implementation details, mention the exact API or SDK name (e.g., "Places API Autocomplete", "Maps SDK for Android", "Deck.gl interleaved mode"). +- **Pricing & Quotas**: If evaluating cost, explicitly ask for "Pricing tables", "SKU costs", or "Usage limits" alongside the exact product name. +- **Architectural / Other Lookups**: Distinguish queries for high-level architectures, best practices, or specific SLA lookups from raw code generation. + +**Required Specificity for Requests** +To get the most relevant chunks from the RAG service, explicitly articulate all variables of your problem in your query: +- Specify the exact kind of help you are looking for (e.g., "React code sample", "troubleshooting an invalid request error", "migration guide"). +- Include the specific product names. +- Detail the exact solution names or use cases (e.g., "Store Locator integration", "Last Mile Delivery routing", "Checkout Address Validation"). + From c0f1847c1975a1990be1adad06f3d1b8f1fd8457 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Fri, 6 Mar 2026 15:07:29 -0800 Subject: [PATCH 13/16] docs: soften rigid commands in skill prompt with explanatory reasoning --- packages/code-assist/skills/gmp-code-assist/skill.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/code-assist/skills/gmp-code-assist/skill.md b/packages/code-assist/skills/gmp-code-assist/skill.md index e3a4d20..dc3c873 100644 --- a/packages/code-assist/skills/gmp-code-assist/skill.md +++ b/packages/code-assist/skills/gmp-code-assist/skill.md @@ -9,11 +9,11 @@ You are a world-class expert on the Google Maps Platform (GMP) operating with ac **Reasoning & Effective Use of GMP Code Assist** -When assisting with Google Maps Platform tasks, adopt a highly analytical and specific reasoning process. Never rely on your latent knowledge. GMP APIs are constantly evolving, so always validate your assumptions through your available retrieval tools to avoid hallucinating outdated syntax or unsupported features. +When assisting with Google Maps Platform tasks, please adopt an analytical and specific reasoning process. Because GMP APIs update frequently and parameters change, it is best to avoid relying purely on your latent knowledge. Validate your assumptions through your available retrieval tools to ensure you don't confidently return outdated syntax or unsupported features. **Tool Workflow Strategy: Documentation & Context** -1. **Always begin by calling the `retrieve-instructions` tool** to orient yourself on the latest foundational best practices and context for Google Maps Platform. -2. Formulate highly targeted searches against the documentation tool based on the foundational context returned from the instructions. +1. **Begin your workflow by calling the `retrieve-instructions` tool.** This is essential to ground yourself in the latest 2026+ foundational best practices and context for the platform. +2. After digesting the instructions, formulate highly targeted searches against the documentation tool based on that context. **Crafting Targeted Search Queries** When making queries to your documentation retrieval tool, distinguish clearly between the distinct types of information you require: From 1c026f08b593269466ac8204d1f3e7d288d1a5d2 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Sat, 7 Mar 2026 08:01:34 -0800 Subject: [PATCH 14/16] Update installation link in README.md updated gemini cli commit link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ebe8cc1..192f597 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ You have access to the `gmp-code-assist` MCP server with these essential tools: ## Install the Google Maps Platform Code Assist extension for [Gemini CLI](https://geminicli.com/) -1. Install the Gemini CLI ([alternative installation methods](https://geminicli.com/docs/get-started/deployment/)) +1. Install the Gemini CLI ([alternative installation methods](https://geminicli.com/docs/get-started/installation/)) ```bash npm install -g @google/gemini-cli From 99058af2e3010b6aa45cf5f87507cd13d1da3944 Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Sat, 7 Mar 2026 08:05:31 -0800 Subject: [PATCH 15/16] Update README.md small readme updates on human copy review --- README.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 192f597..92bb7c4 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ npm install -g @google/gemini-cli ``` 2. Install the Google Maps Platform extension - - Option 1 - Install Code Assist as a Gemini CLI extension with static preamble, the MCP tool, and basic Google Maps theme: + - Option 1 - Install Code Assist as a Gemini CLI extension with a skill, the Code Assist MCP tool, and a Google Maps Platform CLI theme: ```bash gemini extensions install https://github.com/googlemaps/platform-ai.git ``` @@ -54,12 +54,8 @@ For information about installing and using the toolkit with any MCP client, as w Use these example prompts to get started with the Code Assist MCP server or supported AI agents: -- Show me how to use the Routes API in Node.js. -- What are the authentication options for Google Maps Platform? -- Give me a code sample for displaying a map with markers. -- Explain the difference between Place Autocomplete and Place Search. -- How do I set up billing for Google Maps Platform? - - - -[npm-pkg]: https://npmjs.com/package/@googlemaps/code-assist-mcp +- Show me how to use the Routes API and display it on a Map in React + Typescript. +- I'm upgrading my map from 2D to 3D Phtotorealistic - what are my options and how would I do that with my existing codebase? +- Change my Places API (new) Text Search API implementtaion to use Places UI Kit. Estimate the amount of cost savings per user this change will make. +- Explain the difference between Address Validation and Geocoding. Which one should I apply for my current codebase for an ecommmerce checkout use case and why? +- I need an API key - can you get one and add it to my app envrionment secrets? From 1097f94884f83b81cb3d184e13a040047fd2343c Mon Sep 17 00:00:00 2001 From: Ryan Baumann Date: Sat, 7 Mar 2026 08:13:02 -0800 Subject: [PATCH 16/16] human review: README for clarity and updated usage Updated README.md to improve clarity and remove deprecated information. --- packages/code-assist/README.md | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md index 8e65e5e..51cb736 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -5,17 +5,13 @@ # Google Maps Platform Logo Google Maps Platform Code Assist Toolkit -_Alpha version_ - ## Description -The Google Maps Platform Code Assist toolkit is a Model Context Protocol (MCP) server that enhances the responses from large language models (LLMs) used for developing applications with the Google Maps Platform by grounding the responses in the official, up-to-date documentation and code samples. - -Since the MCP server accesses the content when the model is prompted, the LLM's context regarding Google Maps Platform does not have to be limited to the available data at the model's training date. +Make your Agent a Google Maps Platform development expert. The Google Maps Platform Code Assist is a Model Context Protocol (MCP) server that enhances the responses from large language models (LLMs) used for developing applications with the Google Maps Platform by grounding the responses in the official, up-to-date documentation and code samples. -Google Maps Platform resources that the MCP server can access include: +Google Maps Platform resources that Agents can access with Code Assist MCP include: - Google Maps Platform Documentation - Google Maps Platform Terms of Service @@ -29,7 +25,7 @@ Google Maps Platform resources that the MCP server can access include: - Make your favorite AI assistant or IDE an expert on the Google Maps Platform. With Code Assist, AI Agents like Gemini CLI, Claude Code, and Cursor can generate code and answer developer questions grounded in up-to-date, official Google Maps Platform documentation and code samples -- directly in your dev workflow. -- Whether you are making precision AI-Assisted code changes or building applications with Google Maps Platform using AI agents - Code Assist can help you accomplish your task faster and easier. +- When you are coding with AI Agent assistance, Code Assist can help you accomplish your task faster and easier. @@ -37,9 +33,6 @@ Below is an example MCP Client response to a user's question with Code Assist MC ![](./code-assist-preview.jpg) -> [\!NOTE] -> This is the repository for an MCP server that provides access to Google Maps Platform documentation via a RAG service. It is not a Google Maps Platform Core Service. - @@ -52,9 +45,13 @@ Below is an example MCP Client response to a user's question with Code Assist MC The MCP server exposes the following tools for AI clients: 1. **`retrieve-google-maps-platform-docs`**: Searches Google Maps Platform documentation, code samples, architecture center, and GitHub repositories via RAG. - - *Parameters*: `llmQuery` (Required string query), `filter` (Optional API/product area filter), `source` (Optional string caller identifier up to 64 chars). + - *Parameters*: + - `llmQuery` (Required string query), + - `filter` (Optional API/product area filter) + - `source` (Optional string caller identifier up to 64 chars). 2. **`retrieve-instructions`**: Retrieves foundational context on Google Maps Platform best practices. - - *Parameters*: `name` (Required string, expected format is simply "instructions"). + - *Parameters*: + - `name` (Required string, expected format is simply "instructions"). --- @@ -63,9 +60,7 @@ The MCP server exposes the following tools for AI clients: ## Supported MCP Transports -This remote server supports standard MCP communication protocols: - -- **`streamable HTTP`**: The server exposes a `/mcp` endpoint that accepts POST requests over the HTTPS protocol. This is the modern, official standard for remote MCP server connections, replacing legacy HTTP+SSE split endpoints. +- **`streamable HTTP`**: The server exposes a `/mcp` endpoint that accepts POST requests over the HTTPS protocol. See more details in the [Transports doc of the MCP spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http). @@ -76,9 +71,9 @@ This remote server supports standard MCP communication protocols: ## Usage > [!WARNING] -> We will be deprecating the version of this package on NPM, and it will no longer be available as of [XX date - to be completed]. Please use the securely hosted remote version as the primary method of connection, as documented below. +> We will be deprecating the NPM version of Code Assist. It will no longer be available as of [XX date - to be completed]. Please use the remote streamable HTTP version at `https://mapscodeassist.googleapis.com/mcp`. -The Code Assist MCP server is securely hosted by Google. To use it, you must configure your AI client to connect to the remote URL via streamable HTTP. +The Code Assist MCP server is securely hosted by Google. No authentication is required. To use it, you must configure your AI client to connect to the remote URL via streamable HTTP. ### Configure Your Client