diff --git a/GEMINI.md b/GEMINI.md index 691c2d2..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**: @@ -36,3 +38,14 @@ 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 ` 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/README.md b/README.md index 6fa7697..92bb7c4 100644 --- a/README.md +++ b/README.md @@ -6,34 +6,45 @@ ## **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/)) +1. Install the Gemini CLI ([alternative installation methods](https://geminicli.com/docs/get-started/installation/)) ```bash 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 - ``` - * 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"] - } - } - } - ``` + - 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 + ``` + + - 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. @@ -43,11 +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]: +- 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? diff --git a/gemini-extension.json b/gemini-extension.json index 0783afd..dc386d6 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -3,13 +3,12 @@ "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": { + "gmp-code-assist": "packages/code-assist/skills/gmp-code-assist" + }, "mcpServers": { - "google-maps-platform-code-assist": { - "command": "npx", - "args": [ - "-y", - "@googlemaps/code-assist-mcp@latest" - ] + "gmp-code-assist": { + "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 419f45d..51cb736 100644 --- a/packages/code-assist/README.md +++ b/packages/code-assist/README.md @@ -1,27 +1,17 @@ -[![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* +# Google Maps Platform Logo Google Maps Platform Code Assist Toolkit -## 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. +## Description -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 @@ -30,449 +20,174 @@ 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. +- When you are coding with AI Agent assistance, 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-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"). + ------ +--- ## Supported MCP Transports -This server supports two 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. See more details in the [Transports doc of the MCP spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http). ------ - - -## 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. - -#### Configure Your Client - -Add the server to your preferred AI client's MCP configuration file. 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: - ```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. - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"] - } - } - } - ``` - -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` - ```json - "mcpServers": { - "google-maps-platform-code-assist": { - "command": "npx", - "args": [ - "-y", "@googlemaps/code-assist-mcp@latest" - ] - } - } - ``` - -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. - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"] - } - } - } - ``` - -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 - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"] - } - } - } - ``` - -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: - ```json - { - "mcpServers": { - "google-maps-platform-code-assist": { - "command": "npx", - "args": ["-y", "@googlemaps/code-assist-mcp@latest"] - } - } - } - ``` -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. +## Usage -- **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. +> [!WARNING] +> 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. 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 + +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 (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 + ``` + _(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 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": { + "gmp-code-assist": { + "httpUrl": "https://mapscodeassist.googleapis.com/mcp" + } + } + } + ``` + +2. **Claude Code** + - The cleanest way to add the remote server is via the `mcp add` CLI command: + ```bash + 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": { + "gmp-code-assist": { + "type": "streamable-http", + "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=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": { + "gmp-code-assist": { + "type": "http", + "url": "https://mapscodeassist.googleapis.com/mcp" + } + } + } + ``` + +4. **Codex** + - The easiest way to connect Codex to the remote server is via the CLI: + ```bash + 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.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**. + - Alternatively, add the streamable HTTP endpoint to your `mcp_config.json`: + + ```json + { + "mcpServers": { + "gmp-code-assist": { + "type": "streamable-http", + "url": "https://mapscodeassist.googleapis.com/mcp" + } + } + } + ``` + +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": { + "gmp-code-assist": { + "httpUrl": "https://mapscodeassist.googleapis.com/mcp" + } + } + } + ``` ------ +--- ## **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,10 +201,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 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..dc3c873 --- /dev/null +++ b/packages/code-assist/skills/gmp-code-assist/skill.md @@ -0,0 +1,29 @@ +--- +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. + + + +**Reasoning & Effective Use of GMP Code Assist** +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. **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: +- **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"). +