mcpField
C
carto-render-inline-map

carto-render-inline-map

github.com/cartodb数据与数据库653 次安装1 周前更新
代码仓库

关于 carto-render-inline-map

carto-render-inline-map 指导 Agent 通过 CARTO MCP 在聊天中生成交互式地图预览，适用于临时可视化数据。它强调先探索数据、遵循制图规范，并在地图后提供图例；预览不会保存为可分享地图。

主要功能

  1. 01通过 `view_map` 渲染聊天内地图
  2. 02基于数据探索选择图层与字段
  3. 03按制图参考配置地图样式
  4. 04地图渲染后补充图例
  5. 05区分临时预览与已保存地图

适用场景

  1. 01在聊天中快速查看地理数据
  2. 02探索数值字段并选择分级阈值
  3. 03为临时地图结果提供图例
  4. 04将持久地图请求转交专用技能

MCP 相关

该技能专用于 CARTO MCP 的 `view_map` 工具，使用 `@deck.gl/json` 描述地图并在支持 MCP Apps 的主机内渲染。它也通过 `explore_data` 工具发现连接、表和字段信息。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cartodb/agent-skills --skill carto-render-inline-map

安装后在 Claude Code 中输入/carto-render-inline-map确认已加载。

附带文件references/cartography.md

详细介绍

carto-render-inline-map

通过 CARTO MCP 服务的 view_map 工具，在聊天中内嵌渲染临时交互式地图。Agent 会生成一个 @deck.gl/json 声明式规范；渲染器负责处理凭据、底图和工具提示。用户无需离开聊天即可查看地图。

每次渲染后都必须显示图例。 view_map 渲染器不会自动显示图例。调用 view_map 后，通过宿主的组件界面渲染图例（例如 Claude.ai / Claude Desktop 中的 show_widget）——这是唯一可用的可视化传输方式。所有主流宿主的渲染器都会转义聊天消息中的 HTML，并将其显示为原始文本——请勿在聊天回复中输出 HTML。如果宿主没有组件工具，则回退为纯文本图例（使用带有 Emoji 色块的 Markdown 项目符号表示各分桶，并在括号中注明十六进制代码）。完整的 HTML 模板、样式规则和各辅助函数的变体（colorBins 色块、colorContinuous 渐变条、colorCategories 各类别，以及栅格三元分桶 + 无数据值）位于 view_map 工具描述的 LEGEND 部分。此规则仅适用于临时 view_map 规范；内嵌加载的已保存 Builder 地图（参见 carto-preview-builder-map）自带 Builder 原生图例。

工具约定。 此技能使用 CARTO MCP 服务提供的 view_map 工具。工具的输入结构（deckglProps）、图层源兼容性、aggregationExp 要求和 @@= 表达式求值限制，均记录在工具自身的 MCP 描述中——请通过 MCP 宿主的工具检查器或调用 tools/list 阅读。此技能专注于路由、制图和 Agent 的回复，不会重复工具规范。

此技能仅适用于 MCP：view_map 只能在 CARTO MCP 服务上内嵌渲染，且仅支持 MCP Apps 的宿主可用（Claude.ai、Claude Desktop、ChatGPT）。没有用于内嵌渲染的 CLI 对应方案。OAuth 和令牌 MCP 会话均提供 view_map。

步骤 1 — 检查可用项

关于检测信号和宿主支持情况，请参见 carto-basics/references/access-paths.md。快速检查：view_map 必须出现在工具列表中，且宿主必须能够渲染 MCP Apps。

设置操作
存在 view_map + 宿主支持渲染正常继续。
存在 view_map + 宿主不支持渲染（Gemini CLI、Codex CLI、MCP Inspector、MCPJam — 纯文本）告知用户该宿主无法内嵌渲染地图；建议切换宿主，或在可使用 shell 的情况下，使用 carto-create-builder-maps + carto maps screenshot 生成 PNG。
不存在 view_mapMCP 服务未连接。告知用户；不要回退到通用可视化组件。

何时选择其他技能

  • 永久保存 / 可分享的地图 → carto-create-builder-maps（通过 MCP 使用 create_map，或使用 carto maps CLI）。view_map 规范不会保存，也无法通过 URL 分享；它们仅存在于聊天中。
  • 按名称 / URL / ID 打开现有已保存地图 → carto-preview-builder-map。该技能通过 read_maps 查找已保存的地图并内嵌渲染。
  • 从零编写 TypeScript/JavaScript 应用 → carto-develop-app。运行时不同（JS 中使用完整的 deck.gl 功能），制图规则也不同。

编写规范前的发现流程

发现通过 explore_data MCP 工具进行。其方法在制图参考中以裸名称 list_connections、search、list_resources、describe 表示。这些方法均可通过 OAuth 使用；在 token 会话中，list_connections / search / list_resources 只需要 MCP Server 作用域，但 describe 需要 Maps API——没有该 API，下面的统计步骤就没有可用数据，因此请改用 carto connections describe CLI（或通过 OAuth 重新连接）。

  1. explore_data（list_connections）→ 找到合适的连接（通常是 carto_dw）。
  2. explore_data（按名称使用 search，或按 FQN 使用 list_resources）→ 找到表。
  3. 对于任何要用于分箱的陌生数值列，务必通过 explore_data（describe，stats 模式）获取列统计数据——分位数、最小值、最大值、类别。跳过此步骤并硬编码 colorBins 阈值，是最常见的样式失败原因。
  4. 编写 view_map 规范。

编写要点

关于完整的 deck.gl 声明式规范——图层与数据源的兼容性、aggregationExp 规则、mapStyle URL、@@function 形状、expression-eval 限制——请直接阅读 view_map 工具说明。本技能专注于路由和制图决策。

有关规范的制图决策（调色板、比例尺、底图、描边、绘制顺序、层级、拾取、反模式、示例配方），请阅读 references/cartography.md。编写任何带样式的规范前必须阅读。

路由反模式

  • 在 view_map 可用时退回到通用可视化组件。 如果工具列表中有它，就使用它。
  • 为按名称引用的已保存地图手动构建规范。 切换到 carto-preview-builder-map，并先通过 read_maps 查找。
  • 把内联预览当作已保存／可分享的地图。 它不是——规范保存在聊天中。如果用户想保留它，请路由到 carto-create-builder-maps。

（规范编写反模式——瓦片方案不匹配、通用图层、硬编码分箱——见 references/cartography.md §9。）

创建后的预览

通过 carto-create-builder-maps 创建永久地图后（通过 MCP 调用 create_map，或在 CLI 上运行 carto maps create），请通过其 mapId 加载已保存地图（carto-preview-builder-map）并在内联预览中验证——不要使用重新渲染的临时规范。

评论

支持 Markdown