使用说明

项目简介

本项目 'genkit-mcp-google-maps-sample' 是一个示例项目，展示了如何将 Google Maps API 集成到 Genkit 应用中，并通过 Model Context Protocol (MCP) 提供给大型语言模型 (LLM) 使用。它充当一个 MCP 服务器，允许 LLM 客户端调用 Google Maps 的各种地理位置服务功能。

主要功能点

地理编码 (Geocoding): 将地址转换为地理坐标 (经纬度)。
逆地理编码 (Reverse Geocoding): 将地理坐标转换为地址。
地点搜索 (Place Search): 搜索附近的地点，例如餐厅、酒店等。
地点详情 (Place Details): 获取特定地点的详细信息，例如营业时间、评价等。
距离矩阵 (Distance Matrix): 计算多个起点和终点之间的距离和行驶时间。
海拔查询 (Elevation): 获取指定位置的海拔高度。
路线规划 (Directions): 获取两点之间的驾车、步行等路线规划。

核心特点： 本项目作为一个 MCP 服务器，其主要功能是桥接 LLM 和 Google Maps API。它将 Google Maps API 的各种功能封装成 MCP 工具 (Tools)，使得 LLM 可以通过标准的 MCP 协议调用这些工具，从而扩展 LLM 在地理位置信息处理方面的能力。

安装步骤

克隆仓库:

git clone https://github.com/nozomi-koborinai/genkit-mcp-google-maps-sample
cd genkit-mcp-google-maps-sample

安装依赖:

npm install
npm install --save-dev genkit-cli@latest

配置环境变量: 你需要拥有 Google Cloud (Firebase) 项目，并启用 Google Maps Platform API 和 Google AI API。在 Firebase Secret Manager 中设置以下密钥：
- 'GOOGLE_GENAI_API_KEY': 你的 Google AI API 密钥
- 'GOOGLE_MAPS_API_KEY': 你的 Google Maps API 密钥
或者，你也可以在本地环境中设置环境变量 (仅用于本地开发):
```
export GOOGLE_GENAI_API_KEY=your_genai_api_key
export GOOGLE_MAPS_API_KEY=your_maps_api_key
```

服务器配置 (MCP 客户端配置)

MCP 客户端需要配置以下信息来连接到此 MCP 服务器。此配置描述了如何启动和连接到 'mapsClient' 定义的 MCP 服务器。

{
  "serverName": "maps",
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-google-maps"
  ],
  "env": {
    "GOOGLE_MAPS_API_KEY": "<你的 Google Maps API 密钥>"
  }
}

配置参数说明:

serverName: 服务器名称，这里定义为 "maps"。客户端需要使用此名称来引用该服务器提供的工具。
command: 启动服务器进程的命令，这里使用 'npx' 来运行 npm 包。
args: 传递给 'command' 的参数，'-y' 表示跳过 npm 包安装确认，'@modelcontextprotocol/server-google-maps' 是 Google Maps MCP 服务器的 npm 包名称，会被 'npx' 执行。
env: 传递给服务器进程的环境变量。'GOOGLE_MAPS_API_KEY' 用于配置 Google Maps API 密钥，请务必替换 '<你的 Google Maps API 密钥>' 为实际的 API 密钥。这个环境变量会被传递给 '@modelcontextprotocol/server-google-maps' 服务进程。

注意: MCP 客户端在配置 'args' 时，需要确保 '@modelcontextprotocol/server-google-maps' 这个 npm 包可以被 'npx' 找到并执行。通常 'npx' 会自动下载并执行该包。

基本使用方法

本地开发运行:

打开 Genkit Developer UI 并启动本地开发服务器：

npx genkit start -o -- tsx --watch src/index.ts

部署到 Firebase (可选):

如果你想将此 MCP 服务器部署到云端，可以使用 Firebase Functions:
```
firebase deploy --only functions
```
部署后，你需要配置你的 MCP 客户端连接到部署后的云端 Function URL (具体 URL 会在 Firebase 部署完成后给出)。但通常来说，对于 MCP 模式，更常见的是客户端直接连接到本地或者可访问的网络位置运行的 MCP 服务器进程，而不是通过 Function URL 间接调用。本示例更侧重于演示本地开发和集成 MCP 服务器的方式。
在 Genkit Flow 中使用:

在 'src/google-maps-flow.ts' 文件中，你可以看到如何定义一个 Genkit Flow ('googleMapsFlow')，并在 'ai.generate' 中通过 'tools' 数组指定要使用的 MCP 工具，例如 ''maps/maps_geocode''。你可以根据需要启用或禁用不同的 Google Maps 工具。然后在你的 Genkit 应用中调用 'googleMapsFlow'，即可利用 Google Maps 的功能。

例如:

在 'google-maps-flow.ts' 中，当前只启用了 'maps/maps_geocode' 工具。你可以取消注释其他工具的注册，例如 ''maps/maps_reverse_geocode''，来启用更多 Google Maps 功能。

  tools: [
    'maps/maps_geocode',
    // ↓ Register tools as needed below ↓
    // 'maps/maps_reverse_geocode',
    // 'maps/maps_search_places',
    // 'maps/maps_place_details',
    // 'maps/maps_distance_matrix',
    // 'maps/maps_elevation',
    // 'maps/maps_directions',
  ]

然后在你的 Genkit 应用中，你可以这样调用 'googleMapsFlow':

import { googleMapsFlow } from './google-maps-flow';

async function main() {
  const result = await googleMapsFlow("北京市朝阳区");
  console.log(result);
}

main();

这段代码会调用 'googleMapsFlow'，并使用 'maps/maps_geocode' 工具将 "北京市朝阳区" 这个地址转换为地理坐标，最终结果会包含坐标信息。

关键词