Back to Details

carto-preview-builder-map

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

carto-preview-builder-map

carto-preview-builder-map

Renders a lightweight inline preview of an existing saved CARTO Builder map via the CARTO MCP server's 
load_builder_map
tool. The user references the map (by URL, ID, or name); the agent locates it and loads it inline.
Tool contract. This skill consumes the 
load_builder_map
and 
list_maps
tools exposed by the CARTO MCP server. The tools' input shapes and access-control rules (the user must own, be shared on, or have public access to the map) are documented in the tool's own MCP description — read it via the MCP host's tool-inspector or by calling 
tools/list
. This skill stays focused on routing, name → ID resolution, and setting expectations on the lightweight preview; it does NOT duplicate the tool's spec.
This skill assumes the CARTO MCP server is attached (the 
load_builder_map
and 
list_maps
tools are in your tool list) AND the host supports MCP Apps (Claude.ai, Claude Desktop, ChatGPT). If either is missing, see "Step 1 — detect what's available" below.
通过CARTO MCP服务器的
load_builder_map
工具，渲染已保存的CARTO Builder地图的轻量级内嵌预览。用户通过URL、ID或名称引用地图；Agent定位地图并将其内嵌加载。
工具约定。此技能使用CARTO MCP服务器提供的
load_builder_map
和
list_maps
工具。工具的输入格式和访问控制规则（用户必须拥有地图权限、被共享权限或地图为公开访问）记录在工具自身的MCP描述中——可通过MCP主机的工具检查器或调用
tools/list
查看。此技能专注于路由、名称→ID解析及明确轻量级预览的预期；不会重复工具的规格说明。
此技能假设已连接CARTO MCP服务器（工具列表中包含
load_builder_map
和
list_maps
工具）且主机支持MCP应用（Claude.ai、Claude Desktop、ChatGPT）。若缺少任一条件，请参阅下方“步骤1——检测可用资源”。

Step 1 — detect what's available

步骤1——检测可用资源

CheckHow
load_builder_map
and 
list_maps
are callable		Both tool names appear in your tool list.
Host renders MCP AppsHosts that DO: Claude.ai, Claude Desktop, ChatGPT. Hosts that DON'T (Gemini CLI, Codex CLI, plain MCP Inspector, current MCPJam) execute the tool but only show a text confirmation — no map widget.
SetupWhat to do
Tools present + host rendersProceed normally.
Tools present + host doesn't renderTell the user the host can't render maps inline; suggest opening the Builder URL directly.
Tools not presentThe MCP server isn't attached. Tell the user; don't try to reconstruct the saved map from scratch.
检查项检测方式
load_builder_map
和
list_maps
可调用		两个工具名称均出现在工具列表中。
主机可渲染MCP应用支持的主机：Claude.ai、Claude Desktop、ChatGPT。不支持的主机（Gemini CLI、Codex CLI、普通MCP检查器、当前MCPJam）会执行工具，但仅显示文本确认——无地图小部件。
配置情况操作建议
工具存在 + 主机可渲染正常执行。
工具存在 + 主机不可渲染告知用户该主机无法内嵌渲染地图；建议直接打开Builder URL。
工具不存在未连接MCP服务器。告知用户；不要尝试从头重建已保存的地图。

Resolution rules (URL / ID / name)

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

User inputWhat to do
Builder URL 
https://<workspace>.app.carto.com/builder/<mapId>
Extract 
<mapId>
from the URL; call 
load_builder_map({ mapId })
directly.
Bare UUIDCall 
load_builder_map({ mapId })
directly.
Name / topic ("the retail-stores map", "my last week's accidents analysis")Call 
list_maps({ search: "<topic>" })
first, then load by ID. See match handling below.
For name-based lookup, use 
mine_only: true
if the user said "my map". Default sort is 
updated_at desc
— most recently edited first.
用户输入操作方式
Builder URL 
https://<workspace>.app.carto.com/builder/<mapId>
从URL中提取
<mapId>
；直接调用
load_builder_map({ mapId })
。
纯UUID直接调用
load_builder_map({ mapId })
。
名称/主题（“零售门店地图”、“我上周的事故分析地图”）先调用
list_maps({ search: "<topic>" })
，再通过ID加载。请参阅下方的匹配处理规则。
对于基于名称的查找，若用户提到“我的地图”，请使用
mine_only: true
。默认排序为
updated_at desc
——最近编辑的地图优先。

Match handling (after 
list_maps
)

匹配处理（调用
list_maps
后）

ResultAction
1 match
load_builder_map({ mapId: <id> })
. Confirm to the user which map you're loading by name.
>1 matchesList names + dates + thumbnails. Ask the user to pick. Don't guess.
0 matchesTell the user no saved map matches. Offer 
carto-render-inline-map
(
view_map
) as an ad-hoc alternative for the same data.
结果操作
1个匹配项调用
load_builder_map({ mapId: <id> })
。向用户确认正在加载的地图名称。
多个匹配项列出名称+日期+缩略图。请用户选择。不要猜测。
无匹配项告知用户没有匹配的已保存地图。提供
carto-render-inline-map
（
view_map
）作为相同数据的临时替代方案。

Set expectations on the preview (always)

明确预览的预期（始终执行）

The preview is lightweight:
  • ✓ Layers, basemap, viewport, popups, legend — exactly as configured in Builder.
  • ✗ Widgets, SQL parameters, map description, AI agent configuration, and other Builder-only features are NOT included.
After loading, tell the user: "Loaded [name] as a lightweight preview. Widgets, SQL parameters, and the map description aren't included — click 'Open in Builder' in the rendered widget for the full experience." Set this expectation BEFORE the user asks why the preview looks different from the live Builder map.
预览为轻量级：
  • ✓ 图层、底图、视口、弹窗、图例——与Builder中的配置完全一致。
  • ✗ 不包含小部件、SQL参数、地图描述、AI Agent配置及其他仅Builder具备的功能。
加载完成后，告知用户：“已加载[地图名称]的轻量级预览。小部件、SQL参数和地图描述未包含在内——点击渲染部件中的‘在Builder中打开’以获得完整体验。” 在用户询问预览为何与Builder中的实时地图不同之前，就明确此预期。

Post-CLI-creation preview workflow

CLI创建后的预览流程

When the user creates a permanent map via 
carto maps create
(from 
carto-create-builder-maps
), the response is a 
mapId
+ Builder URL. With the MCP server attached, preview inline immediately:
undefined
当用户通过
carto maps create
（来自
carto-create-builder-maps
）创建永久地图时，响应会包含
mapId
和Builder URL。连接MCP服务器后，立即内嵌预览：
undefined

carto maps create returned { mapId: "abc-123", ... }

carto maps create返回 { mapId: "abc-123", ... }

load_builder_map({ mapId: "abc-123" })

This is the fastest authoring loop: edit, save via CLI, preview inline via MCP, repeat. Especially useful for styling iterations.

Caveat: still the lightweight preview. If the user is debugging widgets or SQL parameters, they need the full Builder experience.
load_builder_map({ mapId: "abc-123" })

这是最快的创作循环：编辑、通过CLI保存、通过MCP内嵌预览、重复操作。对样式迭代尤其有用。

注意：仍为轻量级预览。若用户调试小部件或SQL参数，需使用完整的Builder体验。

When to pick a different skill

何时选择其他技能

  • Ad-hoc visualization, no saved map exists → 
    carto-render-inline-map
    (
    view_map
    ).
  • Authoring / editing a permanent map → 
    carto-create-builder-maps
    (CLI).
  • Building a from-scratch deck.gl app → 
    carto-develop-app
    .
  • 临时可视化，无已保存地图 → 
    carto-render-inline-map
    （
    view_map
    ）。
  • 创作/编辑永久地图 → 
    carto-create-builder-maps
    （CLI）。
  • 从头构建deck.gl应用 → 
    carto-develop-app
    。

Anti-patterns to avoid

需要避免的反模式

  • Reconstructing a saved map via 
    view_map
    instead of 
    load_builder_map
    .     If the user references an existing map, ALWAYS try 
    list_maps
    + 
    load_builder_map
    first. Re-rendering loses fidelity (saved layers, popups, legend) AND it's slower.
  • Skipping 
    list_maps
    when the user references a map by name.     Don't guess the ID. Search first.
  • Promising widgets, SQL parameters, or map description in the preview. They're not rendered. Set expectations upfront.
  • Picking the most-recent match silently when 
    list_maps
    returns multiple.     Surface the choices and let the user pick.
  • 通过
    view_map
    重建已保存地图而非使用
    load_builder_map
    。若用户引用现有地图，始终优先尝试
    list_maps
    + 
    load_builder_map
    。重新渲染会丢失保真度（已保存的图层、弹窗、图例）且速度更慢。
  • 用户通过名称引用地图时跳过
    list_maps
    。不要猜测ID。先搜索。
  • 承诺预览包含小部件、SQL参数或地图描述。这些内容不会被渲染。提前明确预期。
  • 当
    list_maps
    返回多个匹配项时，静默选择最近的匹配项    。列出选项并让用户选择。",