mapsdata

mapsdata

mapsdata 是一个小型本地桥接程序，连接托管的 HasData Google Maps MCP 服务，以 JSON 格式返回 Google Maps 数据。 按关键词搜索地点——也可指定 GPS 坐标附近——并获取包含评分、 营业时间、电话和网站的本地信息；然后通过 placeId 获取完整的 地点详情、评价、照片集以及最新帖子和优惠信息。第六个工具会列出 一位 Local Guide 贡献者撰写的所有评价，可用于检查评价者资料和 可信度。

该桥接程序不保存任何地点数据。它会在本地提供上游服务的工具列表， 与从在线端点捕获的内容完全一致，并将每次工具调用转发到上游，原样 返回结果。所有功能均为只读，只涉及 Google Maps 上公开显示的地点和 评价者数据：不提供发帖、消息或预订工具。

工具

• hasdata_google_maps_search_performMapSearch — 执行 Google Maps 搜索。必需参数：q。可选参数： domain、gl、hl、start（偏移分页）和 ll（GPS 坐标，格式为 @lat,lng,zoomz；存在 start 时必需）。返回包含 placeId、名称、地址、坐标、 评分、评价数、价格等级、类别、电话、网站、营业时间和 缩略图的本地信息列表。
• hasdata_google_maps_place_getPlaceDetails — 获取 一个地点的完整信息。必需参数：placeId。可选参数： domain、hl 和 fetchWebResults（同时返回地点面板中的 网络结果）。返回名称、地址、坐标、电话、网站、类别、 营业时间、评分、评价数、价格等级、照片、属性和 plus code。
• hasdata_google_maps_reviews_getMapReviews — 获取一个地点的分页评价，可通过 dataId 或 placeId 指定。可选参数：hl、sortBy（mostRelevant、 newestFirst、ratingHigh、ratingLow）、topicId 筛选条件和 nextPageToken。返回作者、评分、文本、日期、 点赞数、商家回复、照片和 Local Guide 标记。
• hasdata_google_maps_photos_getMapPhotos — 获取 一个地点的照片集，可通过 dataId 或 placeId 指定， 使用 nextPageToken 分页，并可按 categoryId 筛选。 返回每张照片的图片 URL 和缩略图。
• hasdata_google_maps_posts_getMapPosts — 获取 一个地点最新的 Google Maps 帖子（优惠、活动、 公告），可通过 dataId 或 placeId 指定，并可使用 hl 设置目标语言。返回每篇帖子的标题、描述、图片、 发布日期、链接和商家名称。
• hasdata_google_maps_contributor_reviews_getMapReviews — 获取一位 Local Guide 撰写的所有评价。 必需参数：contributorId。可选参数：hl、gl、 num（每页 10–200 条）和 nextPageToken。 返回每条评价的评分、文本、日期、地点名称和地址、 照片以及商家回复。

配置

• HASDATA_GOOGLE_MAPS_MCP_URL（可选）— 覆盖 上游端点。默认值为 https://mcp.hasdata.com/mcp?apis=google_maps（查询 字符串是固定 URL 的一部分）。（此覆盖入口是本次重建中 明确标注的还原内容。）
• HASDATA_API_KEY（可选）— 设置后，每个 上游请求都会携带 x-api-key: <key> 标头，使用调用者自己的 HasData API 密钥。未设置时， 不会发送密钥标头。（标头名称和环境变量名称由原始项目的 注册记录固定；从此环境变量转发密钥是明确标注的还原内容—— 原始功能界面是在不带密钥的情况下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立一个可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26， clientInfo name mapsdata），然后发送 notifications/initialized 通知，最后发送携带调用方参数 且不作更改的 tools/call 请求。上游通过 initialize 返回 Mcp-Session-Id 标头后，该值会随 此会话的每个后续请求一同发送；此会话会在整个进程运行期间复用。 回复可能是纯 JSON，也可能是服务器发送的事件；两种格式都会读取。

上游的成功结果会原样传递，包括上游设置的任何 isError 标记。失败情况——JSON-RPC 错误、非 2xx 状态、 无法读取的响应，或无法完成的请求——会以 isError 结果返回，其文本以 mapsdata error: 开头 （此呈现方式是本次重建自行标注的还原结果）。

命令行界面

每个工具也可作为子命令使用，并接受一个 JSON 参数字符串：

npx @reneturcios/mapsdata hasdata_google_maps_search_performMapSearch '{"q":"coffee near Union Square","hl":"en"}'
npx @reneturcios/mapsdata hasdata_google_maps_place_getPlaceDetails '{"placeId":"ChIJN1t_tDeuEmsRUsoyG83frY4"}'
npx @reneturcios/mapsdata --version

退出代码：成功时为 0，isError 结果时为 1， 用法错误时为 2。

MCP 服务

npx -y @reneturcios/mapsdata mcp

MCP 客户端配置：

{
  "mcpServers": {
    "mapsdata": {
      "command": "npx",
      "args": ["-y", "@reneturcios/mapsdata", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/mapsdata
docker run --rm ghcr.io/cloudcorprecords/mapsdata --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他参数会按常规方式传递给命令行界面。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全针对桩接的 JSON-RPC 上游运行，不会发起实时网络调用。

许可证

MIT — 参见 LICENSE。