mapport

mapport

mapport 可将关于地点的普通问题转化为来自 Google Maps Platform 的答案：地址可转换为坐标，坐标可转换为地址，文本查询可转换为地点列表，任意两点可得出距离、耗时或逐步路线。它还会报告某个地点的海拔高度。一个二进制文件同时提供供脚本使用的命令行界面和供 Agent 使用的 stdio MCP 服务，两种接口共用相同的请求逻辑。

需要 Google Maps Platform API 密钥。请将密钥放入 GOOGLE_MAPS_API_KEY 环境变量；每次请求都会将其作为 key 查询参数发送给 Google，且不会出现在输出中。如果未设置该变量，所有调用都会在发出请求前失败，并显示包含该变量名称的错误。

安装

npx @reneturcios/mapport geocode "1600 Amphitheatre Parkway"

也可以运行容器镜像：

docker run -i -e GOOGLE_MAPS_API_KEY ghcr.io/cloudcorprecords/mapport

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

export GOOGLE_MAPS_API_KEY="your API key"

mapport geocode "1600 Amphitheatre Parkway, Mountain View"
mapport reverse 37.422 -122.084
mapport search "coffee near the ferry building" --lat 37.7955 --lng -122.3937 --radius 1500
mapport details ChIJ2eUgeAK6j4ARbn5u_wAGqWA
mapport distance "San Francisco" "Oakland" --to "Berkeley" --mode driving
mapport elevation 37.422,-122.084 40.0,-70.0
mapport directions "San Francisco" "San Jose" --mode transit

mapport --version

每条命令都会输出上游 JSON 负载。退出码：成功时为 0，调用失败时为 1（包括缺少 GOOGLE_MAPS_API_KEY 或 API 错误），用法错误时为 2。

MCP 服务

一个二进制文件同时提供两种接口。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/mapport mcp

MCP 客户端配置：

{
  "mcpServers": {
    "mapport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/mapport", "mcp"],
      "env": { "GOOGLE_MAPS_API_KEY": "your API key" }
    }
  }
}

工具

工具	输入	返回内容
maps_geocode	address（字符串，必填）	匹配的地点及其坐标、格式化地址和地点 ID。
maps_reverse_geocode	latitude（数字，必填）、longitude（数字，必填）	这些坐标对应的最近地址及其组成部分。
maps_search_places	query（字符串，必填）、location（对象，可选）、radius（数字，可选）	与查询匹配的地点及其名称、地址和位置。
maps_place_details	place_id（字符串，必填）	某个地点的完整详情：联系信息、评分、评论和营业时间。
maps_distance_matrix	origins（字符串数组，必填）、destinations（字符串数组，必填）、mode（字符串，可选）	距离和出行时长矩阵。
maps_elevation	locations（由 {latitude, longitude} 构成的数组，必填）	每个地点的海拔，单位为米。
maps_directions	origin（字符串，必填）、destination（字符串，必填）、mode（字符串，可选）	包含路段、步骤、距离和耗时的路线。

Google 会将大多数 API 失败信息放在 HTTP 200 负载的顶层 status 字段中。对于任何状态不是 OK 或 ZERO_RESULTS 的响应，mapport 都会将其作为工具错误返回，并显示状态和 Google 提供的错误消息；ZERO_RESULTS 则会作为如实的空结果返回。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。