placeguide

placeguide

placeguide 是一个小型本地桥接服务，连接到托管的 itsnum places MCP 服务。它是一个覆盖 119 个旅行目的地的 经过验证的地点目录。你可以询问在普吉岛哪里用餐、洛杉矶哪些 地点此刻营业、某个场所自行发布的菜单是什么样，或其经过验证的 顾客如何评价它；答案均来自该目录自行维护的列表——目录中 没有记录的地点绝不会被编造出来填补空缺。

该软件包不维护自己的目录。它会在本地回答工具列表，内容与从 实时端点捕获的一致，并将每次工具调用转发到上游，原样返回 收到的内容。部分上游响应包含 attribution 字符串； 无论在哪里展示这些结果，都要按照捕获的工具描述要求显示该字符串。

九个工具中有三个由上游标记为免费，属于不收费的免费层级： get_menu、get_reviews 和 directory_feed。此接口中的任何 功能都不会进行预订、向任何人收费或开设账户。booking_link 会返回场所自有平台上的预订页面，其中已填好人数、日期和时间—— 旅客需在该页面完成预订，且响应始终会显示 booked: false。

工具

• search_places — 查找目的地中真实且目前仍在营业的场所：餐厅、酒吧、海滩、水疗中心、观景点、寺庙。必填：destination（slug 或城市名称）。可选：category、near（"lat,lng" 坐标对，用于查找约 5 公里范围内按距离排序的结果；或用于按区域筛选的街区名称）、query（自由文本）和 limit（1–20，默认值为 8）。结果按质量排序（评分按评论数加权）；提供坐标时，则按质量和距离的综合指标排序。返回名称、类别、区域、评分、评论数、电话、地址，以及已知情况下的营业时间。
• concierge_answer — 像旅行者一样提出旅行问题（“今晚 Kata 附近去哪儿吃饭好？”），即可获得基于已核验目录的简短回答，以及以结构化数据形式提供的场所名称。必填：question。可选：destination、near 和 language（BCP-47 标签；默认使用问题所用语言）。回答只针对所询问的地点，不会换成其他城市；如果没有相关覆盖，会明确说明，而不会猜测。
• list_destinations — 列出目录涵盖的目的地，以及每个目的地中已核验场所的数量。无需参数。不确定某座城市是否受支持时，请先调用此工具。
• place_details — 根据 search_places 返回的 place_id，获取某个场所的全部信息。必填：place_id。返回该场所在其自有列表中发布的联系信息、营业时间、评分、评论数、区域、类别、菜系、场所自己的简短介绍、坐标、根据目的地时区计算的 open_now（null 表示营业时间未经核验，并非表示已关闭）、预订平台，以及仅在已核验的所有者选择了预订页面时才提供的场所自有预订页面；如有，还会返回近期读取到的已发布价格信息，以及各自带有归属信息的照片。
• open_places — 根据目的地自身时区，查找目的地中当前营业的场所。必填：destination。可选：category、near、bookable_only 和 limit（1–50，默认值为 20）。只有营业时间已核验的场所才会出现在结果中，因此列表较短表示营业时间覆盖有限，并不意味着这座城市没有场所。
• booking_link — 返回已填入人数、日期和时间的某个场所预订页面。必填：place_id。可选：party（1–20）、date（YYYY-MM-DD）和 time（HH:MM，24 小时制，使用场所当地时间）。此工具不会创建预订，也不会保留桌位；响应始终包含 booked: false 和 mode: "deeplink"。如果场所没有预订平台，响应会说明这一点并返回电话号码。
• get_menu — 获取场所自行发布的菜单或服务项目列表，按场所的分区及其原有顺序分组。必填：place_id。价格完全按照场所设定，以其使用的货币显示；没有价格的项目会显示 price: null。如果没有已发布的菜单，则 sections 为空，且 note 会说明原因。免费。
• get_reviews — 获取某个场所的评分摘要。必填：place_id。返回 external（列表中显示的公开评分和评论数，以及其来源）和 num_verified（已核验客人的平均评分、数量及 1–5 星分布）。绝不提供评论文本或评论者身份信息；已核验评分少于 5 条时，所有已核验评分数据均为 null，且 note 会说明原因。免费。
• directory_feed — 对某个目的地中列出的所有场所进行批量分页同步，每次调用最多 200 个场所，按 place_id 排序。必填：destination。可选：cursor（传回返回的 next_cursor，直到其值为 null）和 limit（提供合作伙伴密钥时为 1–200，默认值为 100；不提供密钥时最多为 50）。每个条目包含 search_places 的字段，以及菜系、坐标和预订平台；不包含菜单、评论或照片。免费。

配置

• ITSNUM_MCP_URL（可选）— 覆盖上游端点。默认为 https://app.itsnum.com/api/partner/mcp。（此重建版自带标注的 覆盖机制。）
• ITSNUM_PARTNER_KEY（可选）— 设置后，每个上游请求都会携带 X-Partner-Key: <value> 标头，其中包含调用方自己的合作伙伴密钥。未设置时， 不会发送密钥标头，但工具仍可正常响应——工具列表是在未提供密钥的情况下捕获的， 且有多个工具注明免费使用，无需密钥。（原始版本的注册记录指定了秘密 X-Partner-Key 标头，因此标头名称已确定；但该记录未指定包的环境变量名称， 所以从此环境变量转发密钥是本重建版自带的标注机制。） 根据捕获的描述，提供密钥后，directory_feed 的页面大小上限会从 50 提高到 200。

转发机制

首次调用工具时，客户端会在上游打开一个可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26，clientInfo 名称为 placeguide），然后发送 notifications/initialized 通知，最后发送携带调用方参数的 tools/call 请求，参数保持不变。当上游在 initialize 响应中返回 Mcp-Session-Id 标头时，该值会附加到此会话的所有后续请求中；此会话会在 进程运行期间重复使用。响应可能是普通 JSON，也可能是服务器发送事件；两种格式都会读取。

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

CLI

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

npx @reneturcios/placeguide search_places '{"destination":"phuket","category":"restaurant"}'
npx @reneturcios/placeguide list_destinations '{}'
npx @reneturcios/placeguide get_menu '{"place_id":"..."}'
npx @reneturcios/placeguide --version

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

MCP 服务

npx -y @reneturcios/placeguide mcp

MCP 客户端配置：

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

Docker

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

容器的默认命令为 mcp，因此第一种形式是 stdio MCP 服务；其他参数会照常传递给 CLI。

开发

npm install
npm run build
npm test
npm run dev

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

许可证

MIT — 参见 LICENSE。