carto-render-inline-map

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

carto-render-inline-map

Renders an ad-hoc interactive map inline in the chat via the CARTO MCP server's

view_map

tool. The agent emits a

@deck.gl/json

declarative spec; the renderer handles credentials, basemap, and tooltips. The user sees the map without leaving the chat.

Legend required after every render. The

view_map

renderer does NOT show an auto-legend. After invoking

view_map

, render a legend through the host's widget surface (e.g.,

show_widget

in Claude.ai / Claude Desktop) — that is the ONLY visual transport that works. Chat-message HTML is escaped by every major host's renderer and appears as raw text — DO NOT emit HTML in your chat reply. If the host has no widget tool, fall back to a plain-text legend (markdown bullets with emoji color squares per bucket, hex codes in parentheses). The full HTML template, style rules, and per-helper variants (

colorBins

swatches,

colorContinuous

gradient bar,

colorCategories

per-category, raster ternary-bucket + nodata) live in the

view_map

tool description's LEGEND section. Applies to

view_map

ONLY;

load_builder_map

has its own Builder-native legend.

Tool contract. This skill consumes the

view_map

tool exposed by the CARTO MCP server. The tool's input shape (

deckglProps

), layer-source compatibility,

aggregationExp

requirements, and

@@=

expression-eval restrictions 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, cartography, and the agent's reply; it does NOT duplicate the tool's spec.

This skill assumes the CARTO MCP server is attached (the

view_map

tool is in your tool list) AND the host supports MCP Apps (interactive widgets — Claude.ai, Claude Desktop, ChatGPT). If either is missing, see "Step 1 — detect what's available" below.

通过CARTO MCP服务器的

view_map

工具，在聊天中内嵌渲染临时交互式地图。Agent会生成

@deck.gl/json

声明式规范；渲染器负责处理凭证、底图和提示框。用户无需离开聊天界面即可查看地图。

每次渲染后必须添加图例。

view_map

渲染器不会自动显示图例。调用

view_map

后，需通过宿主的小部件界面渲染图例（例如Claude.ai/Claude Desktop中的

show_widget

）——这是唯一有效的可视化传输方式。所有主流宿主的渲染器都会转义聊天消息中的HTML，使其显示为原始文本——请勿在聊天回复中输出HTML。如果宿主没有小部件工具，则退回到纯文本图例（使用带表情符号颜色方块的Markdown项目符号，括号内标注十六进制代码）。完整的HTML模板、样式规则以及各助手变体（

colorBins

样本、

colorContinuous

渐变条、

colorCategories

分类样式、栅格三元桶+无数据样式）都位于

view_map

工具说明的LEGEND部分。此要求仅适用于

view_map

；

load_builder_map

有其自身的Builder原生图例。

**工具约定。**此技能使用CARTO MCP服务器提供的

view_map

工具。该工具的输入格式（

deckglProps

）、图层源兼容性、

aggregationExp

要求以及

@@=

表达式求值限制都记录在工具自身的MCP说明中——可通过MCP宿主的工具检查器或调用

tools/list

查看。此技能专注于路由、制图和Agent回复；不会重复工具的规范内容。

此技能假设已连接CARTO MCP服务器（工具列表中存在

view_map

工具）且宿主支持MCP应用（交互式小部件——Claude.ai、Claude Desktop、ChatGPT）。如果任一条件不满足，请参阅下方的“步骤1——检测可用资源”。

Step 1 — detect what's available

步骤1——检测可用资源

Check	How
`view_map` is callable	Tool name `view_map` is in your tool list.
Host renders MCP Apps	Hosts 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.

Setup	What to do
Tool present + host renders	Proceed normally.
Tool present + host doesn't render	Tell the user the host can't render maps inline; suggest switching hosts or using `carto-create-builder-maps` (CLI) for a screenshot-based alternative.
Tool not present	The MCP server isn't attached. Tell the user; don't fall back to a generic visualization widget.

检查项	检查方式
`view_map` 可调用	工具列表中存在 `view_map` 工具。
宿主可渲染MCP应用	支持的宿主：Claude.ai、Claude Desktop、ChatGPT。不支持的宿主（Gemini CLI、Codex CLI、普通MCP检查器、当前MCPJam）会执行工具，但仅显示文本确认——不会显示地图小部件。

配置情况	操作方式
工具存在且宿主可渲染	正常执行。
工具存在但宿主不可渲染	告知用户该宿主无法内嵌渲染地图；建议切换宿主或使用 `carto-create-builder-maps` （CLI）作为基于截图的替代方案。
工具不存在	MCP服务器未连接。告知用户；不要退回到通用可视化小部件。

When to pick a different skill

何时选择其他技能

Permanent / shareable map →
```
carto-create-builder-maps
```
(CLI).
```
view_map
```
specs aren't saved or shareable as URLs; they live in the chat.
Open an existing saved map by name/URL/ID →
```
carto-preview-builder-map
```
. That skill uses
```
load_builder_map
```
to render a saved Builder map inline.
Writing a TypeScript/JavaScript app from scratch →
```
carto-develop-app
```
. Different runtime (full deck.gl surface in JS), different cartography rules.

永久/可共享地图 →
```
carto-create-builder-maps
```
（CLI）。
```
view_map
```
规范不会保存为URL或共享；仅存在于聊天中。
按名称/URL/ID打开已保存的现有地图 →
```
carto-preview-builder-map
```
。该技能使用
```
load_builder_map
```
内嵌渲染已保存的Builder地图。
从零开始编写TypeScript/JavaScript应用 →
```
carto-develop-app
```
。运行时不同（JS中的完整deck.gl界面），制图规则也不同。

Discovery flow before composing the spec

编写规范前的探索流程

```
list_connections
```
→ identify the right connection (often
```
carto_dw
```
).
```
search_resources
```
(by name) or
```
list_resources
```
(by FQN) to find the table.
Always call
get_column_stats
for any unfamiliar numeric column you'll bin on — quantiles, min, max, categories. Skipping this and hardcoding
```
colorBins
```
thresholds is the #1 styling failure mode.
Compose the
```
view_map
```
spec.

```
list_connections
```
→ 确定合适的连接（通常为
```
carto_dw
```
）。
```
search_resources
```
（按名称）或
```
list_resources
```
（按FQN）查找表格。
对于任何不熟悉的、将用于分箱的数值列，务必调用
get_column_stats
——获取分位数、最小值、最大值、类别。跳过此步骤并硬编码
```
colorBins
```
阈值是最常见的样式失败原因。
编写
```
view_map
```
规范。

Composition essentials

编写要点

For the full deck.gl declarative spec — layer-source compatibility,

aggregationExp

rules,

mapStyle

URLs,

@@function

shapes, expression-eval restrictions — read the

view_map

tool description directly. This skill stays focused on routing and cartographic decisions.

For cartographic decisions on the spec (palette, scale, basemap, stroke, drawing order, hierarchy, picking, anti-patterns, worked recipes), read

references/cartography.md

. Mandatory before composing any styled spec.

关于完整的deck.gl声明式规范——图层源兼容性、

aggregationExp

规则、

mapStyle

URL、

@@function

格式、表达式求值限制——请直接查看

view_map

工具的说明。此技能专注于路由和制图决策。

关于规范的制图决策（调色板、比例尺、底图、描边、绘制顺序、层级、拾取、反模式、实用方案），请阅读

references/cartography.md

。在编写任何带样式的规范前必须阅读此文档。

Anti-patterns to surface or self-correct

需要指出或自我修正的反模式

Falling back to a generic visualization widget when
view_map
is available. If the tool is in your list, use it.
view_map
for a saved map referenced by name. Switch to
```
carto-preview-builder-map
```
and call
```
list_maps
```
first.
Hardcoded
colorBins
domain values without
get_column_stats
. Always fetch real percentiles for unfamiliar columns.
Mixing tile schemes (e.g.,
```
vectorTableSource
```
→
```
HeatmapTileLayer
```
). Silent empty render. The
```
view_map
```
tool description has the full compatibility matrix.
Generic deck.gl layers (
```
ScatterplotLayer
```
,
```
HexagonLayer
```
,
```
GeoJsonLayer
```
, etc.). The MCP JSON converter only registers CARTO layers — anything else silently produces nothing.
Treating an inline preview as a saved/shareable map. It isn't. If the user wants to keep it, route to
```
carto-create-builder-maps
```
.

当
view_map
可用时退回到通用可视化小部件。如果工具列表中有该工具，请使用它。
使用
view_map
处理按名称引用的已保存地图。切换到
```
carto-preview-builder-map
```
并先调用
```
list_maps
```
。
未调用
get_column_stats
就硬编码
colorBins
域值。对于不熟悉的列，务必获取真实的百分位数。
混合瓦片方案（例如
```
vectorTableSource
```
→
```
HeatmapTileLayer
```
）。会导致静默空渲染。
```
view_map
```
工具说明中有完整的兼容性矩阵。
通用deck.gl图层（
```
ScatterplotLayer
```
、
```
HexagonLayer
```
、
```
GeoJsonLayer
```
等）。MCP JSON转换器仅注册CARTO图层——其他任何图层都会静默无输出。
将内嵌预览视为可保存/共享的地图。它并非如此。如果用户想要保留地图，请引导至
```
carto-create-builder-maps
```
。

Post-CLI-creation preview pattern

CLI创建后的预览模式

When the user creates a permanent map via the CLI (

carto maps create

from

carto-create-builder-maps

), the response is a

mapId

+ Builder URL. The fastest way to verify the result inline is

load_builder_map

(in

carto-preview-builder-map

) — NOT a re-rendered

view_map

. Hand off to that skill rather than reconstructing the spec from scratch.

当用户通过CLI创建永久地图时（来自

carto-create-builder-maps

的

carto maps create

），响应会包含

mapId

和Builder URL。内嵌验证结果的最快方式是使用

load_builder_map

（在

carto-preview-builder-map

中）——而非重新渲染

view_map

。将任务移交至该技能，而非从头重建规范。