carto-preview-builder-map

carto-preview-builder-map

通过 CARTO MCP 服务渲染现有已保存 CARTO Builder 地图的轻量级内嵌预览。用户通过 URL、ID 或名称引用地图；Agent 使用 read_maps 解析地图，并通过 view_map 在内嵌视图中加载地图。

工具约定。 此技能使用 CARTO MCP 服务提供的 read_maps 和 view_map 工具。工具的输入格式和访问控制规则（用户必须是地图所有者、地图共享对象，或拥有地图的公开访问权限）记录在工具自身的 MCP 描述中——请通过 MCP 主机的工具检查器或调用 tools/list 阅读。此技能专注于路由、名称 → ID 解析，以及说明轻量级预览的预期；不会重复工具规范。

此技能仅适用于 MCP——内嵌渲染没有 CLI 等效方式——并且需要支持 MCP-Apps 的主机（Claude.ai、Claude Desktop、ChatGPT）。检测信号和主机支持情况：carto-basics/references/access-paths.md。

第 1 步 — 检测可用功能

view_map 和 read_maps 都必须出现在工具列表中，并且主机必须能够渲染 MCP Apps。**Token 与 OAuth：**在 Token MCP 会话中，系统会提供 view_map，但不会提供 read_maps——仍可通过明确的 URL/ID 加载地图；按名称搜索则需要 OAuth 会话（或请用户提供地图 URL）。

配置	操作
工具已提供 + 主机支持渲染	正常继续。
工具已提供 + 主机不支持渲染（Gemini CLI、Codex CLI、MCP Inspector、MCPJam——仅支持文本）	告知用户该主机无法内嵌渲染地图；建议直接打开 Builder URL。
未提供 view_map	MCP 服务尚未连接。告知用户；不要尝试从头重建已保存的地图。

解析规则（URL / ID / 名称）

用户输入	操作
Builder URL https://<workspace>.app.carto.com/builder/<mapId>	从 URL 中提取 <mapId>；直接传给 view_map。
单独的 UUID	直接传给 view_map。
名称 / 主题（“零售门店地图”“我上周的事故分析”）	先使用 read_maps 搜索（根据主题提示），再通过 ID 加载。参见下方的匹配处理方式。

按名称查找时，如果用户说“我的地图”，则仅搜索用户自己的地图。默认排序为 updated_at desc——最近编辑的地图排在最前面。

匹配处理方式（调用 read_maps 后）

结果	操作
1 个匹配项	使用匹配项的 ID 通过 view_map 加载。告知用户正在加载哪张地图，并说明地图名称。
>1 个匹配项	列出名称、日期和缩略图。请用户选择。不要猜测。
0 个匹配项	告知用户没有匹配的已保存地图。可提供 carto-render-inline-map（临时 view_map 规格），作为处理相同数据的替代方案。

说明预览效果（始终执行）

预览是轻量级的：

• ✓ 图层、底图、视口、弹出窗口、图例——与在 Builder 中配置的完全一致，包括描边样式（虚线 / 点线和多边形边框）。
• ✗ 不包含组件、SQL 参数、地图说明、AI Agent 配置，以及其他仅限 Builder 的功能。

加载后，告知用户：“已将 [name] 加载为轻量级预览。预览不包含组件、SQL 参数和地图说明——如需完整体验，请点击渲染组件中的‘在 Builder 中打开’。” 在用户询问预览为何与实时 Builder 地图不同时，提前说明这一点。

创建后的预览工作流

通过 carto-create-builder-maps 创建地图后（通过 MCP 调用 create_map，或在 CLI 中运行 carto maps create），将返回的 mapId 传给 view_map，即可内嵌预览——这是样式迭代时最快的编辑 → 保存 → 预览循环。预览仍是轻量级的：调试组件或 SQL 参数需要使用完整的 Builder。

何时选择其他技能

• 临时可视化，且不存在已保存的地图 → carto-render-inline-map（临时 view_map 规范）。
• 创建 / 编辑永久地图 → carto-create-builder-maps（通过 MCP 使用 create_map / update_map，或使用 carto maps CLI）。
• 从零构建 deck.gl 应用 → carto-develop-app。

应避免的反模式

• 不通过 ID 加载已保存地图，而是用手工编写的 deck.gl 规范重新构建地图。 如果用户提到了现有地图，务必通过 read_maps 查找并先加载已保存的地图。重新渲染会损失保真度（已保存的图层、弹出窗口、图例），而且速度更慢。
• 用户按名称提到地图时跳过 read_maps。 不要猜测 ID。先搜索。
• 承诺预览中会显示小组件、SQL 参数或地图描述。 这些内容不会被渲染。请提前说明预期。
• read_maps 返回多个结果时，默默选择最新的匹配项。 列出选项，让用户选择。