Google Maps Platform 代码辅助工具包

Alpha 版本

描述

Google Maps Platform 代码辅助工具包是一个模型上下文协议（MCP）服务器，通过将大型语言模型（LLMs）的响应基于最新的官方文档和代码示例来增强这些模型在开发 Google Maps Platform 应用程序时的响应。

由于 MCP 服务器在模型被提示时访问内容，因此 LLM 关于 Google Maps Platform 的上下文不必局限于模型训练日期时可用的数据。

MCP 服务器可以访问的 Google Maps Platform 资源包括：

• Google Maps Platform 文档
• Google Maps Platform 服务条款
• Google Maps Platform 信任中心
• Google Maps Platform 官方 GitHub 组织中的代码仓库

开发者

• 🪄 让您最喜欢的 AI 助手或 IDE 成为 Google Maps Platform 专家。借助代码辅助功能，像 Gemini CLI、Claude Code 和 Cursor 这样的 AI 代理可以直接在您的开发工作流中生成代码并回答基于最新官方 Google Maps Platform 文档和代码示例的开发者问题。

• 🚀 无论您是在进行精确的 AI 辅助代码更改还是在编写新的应用程序原型 - 代码辅助都可以帮助您更快更轻松地完成任务。

以下是一个安装了代码辅助 MCP 后的 MCP 客户端对用户问题的响应示例：

[!NOTE]
这是提供通过 RAG 服务访问 Google Maps Platform 文档的 MCP 服务器的仓库。它不是 Google Maps Platform 核心服务。

---

🔧 提供的工具

MCP 服务器为 AI 客户端提供了以下工具：

1. retrieve-instructions: 一个辅助工具，客户端使用它来获取关于如何最好地理解用户意图并有效调用 retrieve-google-maps-platform-docs 工具的关键系统指令。
2. retrieve-google-maps-platform-docs: 主要工具。它接受自然语言查询，并将其提交给托管的检索增强生成（RAG）引擎。RAG 引擎搜索最新的官方 Google Maps Platform 文档、教程和代码示例，并返回相关上下文以供 AI 生成准确的响应。

---

🛠️ 支持的 MCP 传输方式

该服务器支持两种标准的 MCP 通信协议：

• stdio: 当客户端通过 command 调用服务器时，默认使用此传输方式。它通过标准输入/输出流进行通信，非常适合本地命令行执行。
• Streamable HTTP: 服务器暴露了一个 /mcp 端点，接受 POST 请求。这是通过 url 连接的客户端使用的，也是远程服务器连接的标准。我们的实现支持流式处理，以便实时交互响应。

---

🚀 使用方法您可以将 Code Assist MCP 服务器运行在本地开发机器上，也可以远程运行在 Google Cloud Run 上。

要求

为了使用 Google Maps Platform Code Assist 工具包，您需要一个安装了 Node.js（推荐使用 LTS 版本）和 npm 的环境，以便克隆和运行服务器，同时还需要一个 MCP 客户端来访问该服务器。

将 Code Assist 作为本地 MCP 服务器使用 stdio 传输（推荐）

在本地机器上运行服务器，并使用 stdio 协议连接客户端，以供 AI 辅助的 IDE（如 VS Code、Android Studio、Cursor）或桌面 AI 应用程序（如 Gemini CLI）使用。这是最简单且最常见的设置。

配置您的客户端

将服务器添加到您首选的 AI 客户端的 MCP 配置文件中。请根据您的客户端找到具体的、经过验证的说明。

1. Gemini Code Assist & Gemini CLI

   • 选项 1 - 直接从命令行添加服务器（假设您已经安装了 Gemini CLI）：
     bash
     gemini mcp add google-maps-platform-code-assist npx -y @googlemaps/code-assist-mcp@latest

     • 通过运行 gemini mcp list 来验证安装。

   • 选项 2 - 作为带有静态前言、MCP 工具和基本 Google 地图主题的 Gemini CLI 扩展安装 Code Assist：
     bash
     gemini extensions install https://github.com/googlemaps/platform-ai.git

   • 选项 3 - 手动将 MCP 服务器配置添加到您的 ~/.gemini/settings.json 文件中。
     json
     {
     "mcpServers": {
     "google-maps-platform-code-assist": {
     "command": "npx",
     "args": ["-y", "@googlemaps/code-assist-mcp@latest"]
     }
     }
     }

2. Claude Code

   • 选项 1 - 直接从命令行添加服务器（假设您已经安装了 Claude Code）：
     bash
     claude mcp add google-maps-platform-code-assist -- npx -y @googlemaps/code-assist-mcp@latest

     • 通过运行 claude mcp list 来验证安装。
     • Windows 用户： 在原生 Windows（非 WSL）上，必须使用 cmd /c 包装器才能使 npx 命令正确工作。
       bash
       claude mcp add google-maps-platform-code-assist -- cmd /c "npx -y @googlemaps/code-assist-mcp@latest"

   • 选项 2 - 手动将服务器添加到您的 Claude 配置文件 ~/.claude.json 中
     json
     "mcpServers": {
     "google-maps-platform-code-assist": {
     "command": "npx",
     "args": [
     "-y", "@googlemaps/code-assist-mcp@latest"
     ]
     }
     }

3. Cursor

   • <-- 如果您已经安装了 Cursor，请点击此处直接安装 Google Maps Platform Code Assist MCP。
   • 否则，将其添加到您的工作区的 .cursor-settings/mcp.json 文件中。
     json
     {
     "mcpServers": {
     "google-maps-platform-code-assist": {
     "command": "npx",
     "args": ["-y", "@googlemaps/code-assist-mcp@latest"]
     }
     }
     }

4. Firebase Studio

   • with Code Assist MCP installed
   • 将其添加到您的 Firebase Studio 工作区中的 .idx 文件夹内的 mcp.json 文件中
     json
     {
     "mcpServers": {
     "google-maps-platform-code-assist": {
     "command": "npx",
     "args": ["-y", "@googlemaps/code-assist-mcp@latest"]
     }
     }
     }

5. Android Studio* 创建一个 mcp.json 文件并将其放置在 Android Studio 的 配置目录 中。将 Code Assist 服务器添加到列表中：
   json
   {
   "mcpServers": {
   "google-maps-platform-code-assist": {
   "command": "npx",
   "args": ["-y", "@googlemaps/code-assist-mcp@latest"]
   }
   }
   }

6. Cline

   • 选项 1：使用 Cline MCP GUI 安装
   • 选项 2：手动/编程方式安装，使用 Cline MCP 配置文件。配置文件位于：
     • 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
     • 在 cline_mcp_settings.json 中添加以下内容到您的 MCP 配置中：
       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

   • 选项 1：使用 Roo MCP GUI 安装
   • 选项 2：手动/编程方式安装，使用 Roo Code 配置文件。配置文件位于：
     • 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
     • 在 mcp_settings.json 中添加以下内容到您的 MCP 配置中：
       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

   • 当处于代理模式时，点击“工具”，然后在顶部标题栏中点击“配置工具”，再点击“从 NPM 包名称安装”（见下图）

   • 输入包名 @googlemaps/code-assist-mcp 并按回车键，接受安装并使用默认端口 3000，最后再次按回车键确认更改

9. Windsurf

   • 类似于上面的 Cursor 指南。

10. Kilo Code

    • 类似于上面的 Cline 和 Roo Code 指南。

---

⚙️ 可用设置

端口配置默认情况下，服务器运行在端口 3000 上。你可以使用 --port 标志或 PORT 环境变量指定不同的端口。--port 标志优先。

示例：使用端口 5000

在你的 mcp.json 中：

json
"google-maps-platform-code-assist": {
"command": "npx",
"args": ["-y", "@googlemaps/code-assist-mcp@latest", "--port", "5000"]
}

或者使用环境变量：

json
"google-maps-platform-code-assist": {
"command": "npx",
"args": ["-y", "@googlemaps/code-assist-mcp@latest"],
"env": {
"PORT": "5000"
}
}

如果指定的端口不可用，服务器将自动找到并启动在一个随机可用端口上。

---

🌐 本地可流式 HTTP 指南

对于需要在其本地机器上使用 可流式 HTTP 传输集成 Google Maps Platform 代码辅助 MCP 服务器的开发者，本指南提供了设置说明和测试步骤。

何时使用本地可流式 HTTP

在以下情况下使用本地可流式 HTTP 传输：

• 你的客户端需要基于 URL 的连接而不是命令执行
• 你的本地开发环境需要基于 HTTP 的通信
• 你正在构建和测试通过 HTTP 通信的自定义集成

本地可流式 HTTP 设置

1. 启动服务器

在本地运行 MCP 服务器，并指定一个端口：

bash
npx -y @googlemaps/code-assist-mcp@latest --port 3215

服务器将在 http://localhost:3215/mcp 可用。

2. 配置你的客户端

更新你的客户端 MCP 配置以连接到本地服务器 URL。

注意： 确保你的 MCP 配置中的 type 参数正确设置为你的特定客户端。例如，Roo Code 使用 "type": "streamable-http"，而 Cline 使用 "type": "streamableHttp"。

Roo Code (VS Code 扩展)

添加到 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 扩展)

添加到 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"
]
}
}
}

使用 cURL 测试你的本地设置

通过发送 initialize 请求来验证你的服务器是否正常工作：

bash

测试服务器初始化

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"}
}
}'

预期响应：
服务器将以包含其功能的 SSE 事件响应。
json
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"}}}

---

在 Cloud Run 上使用可流式 HTTP 作为远程 MCP 服务器

在 Google Cloud Run 上运行服务器，并从你的本地机器连接到它。如果你的客户端需要一个远程托管的、可流式 HTTP 端点，这将非常有用。

[!WARNING]
这些说明确保只有你才能通过适当的应用程序 IAM 角色访问该服务器，MCP 客户端或代理。1. 前提条件

安装Google Cloud SDK 并验证您的账户：

bash
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

2. 部署到 Cloud Run

此命令从该仓库的源代码部署服务器，并确保它不公开访问。

bash
gcloud run deploy google-maps-code-assist-mcp --source . --no-allow-unauthenticated

当提示时，选择一个区域（例如 us-central1）。

3. 安全连接

在本地机器上运行 Cloud Run 代理。这将创建一个从本地端口到远程服务器的安全隧道，并使用您的 gcloud 身份进行身份验证。

bash
gcloud run services proxy google-maps-code-assist-mcp --port=8999 --region=YOUR_REGION

现在，您机器上的 http://localhost:8999 将安全地连接到您的 Cloud Run 服务。

4. 配置客户端

更新客户端的 MCP 配置以指向本地代理。

• 使用 url 属性通过 Streamable HTTP 连接：

  json
  "google-maps-platform-code-assist": {
  "url": "http://localhost:8999/mcp",
  "type": //根据您的 MCP 客户端，可以是 "streamableHttp" 或 "streamable-http"
  }

5. 连接 GCP 服务（替代本地代理）

要将另一个 GCP 服务连接到远程部署的 Cloud Run MCP 服务器，例如 Agent Development Kit (ADK) 代理或 Vertex AI Agent Engine，您可以直接通过 Streamable HTTP 连接到远程 MCP 服务，使用以下 IAM 角色：

bash

授予 Cloud Run Invoker 角色给服务账号

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

现在，您的 GCP 托管应用或代理可以直接通过 Streamable HTTP 连接到远程托管的 MCP 服务器 URL。

6. 健康检查端点

此服务器实现包括一个标准的 /health 端点。这是部署在像 Cloud Run 这样的平台上的服务的最佳实践，用于检查服务器的操作状态。

• HTTP /health 端点：对此端点的简单 GET 请求（例如 https://your-service-url/health）将在服务器运行时返回 200 OK 状态和包含服务器状态、活动会话数量和时间戳的 JSON 负载。这用于基础设施级别的健康检查。
• MCP ping 工具：这与 MCP 规范中定义的协议内 ping 工具不同。ping 工具是在会话建立后发送的 JSON-RPC 请求，用于检查协议连接的活跃性，而 /health 端点则检查HTTP 服务器本身的活跃性。

---

服务条款

此工具包提供了描述 Google Maps Platform 服务使用的工具。使用 Google Maps Platform 服务受 Google Maps Platform 服务条款 的约束，但是，如果您的账单地址位于欧洲经济区，则 Google Maps Platform EEA 服务条款 将适用于您对服务的使用。功能因地区而异。了解更多。

此工具包不是 Google Maps Platform 核心服务。因此，Google Maps Platform 服务条款（例如技术支持服务、服务水平协议和弃用政策）不适用于此仓库中的代码或由其调用的 RAG 服务。

支持

如果您发现错误或有功能请求，请在 GitHub 上提交问题。如果您希望从其他 Google Maps Platform 开发者那里获得技术问题的答案，请通过我们的开发者社区渠道之一提问。如果您想贡献代码，请查阅贡献指南。

您还可以在我们的Discord 服务器上讨论此工具包。