carto-basics

carto-basics

CARTO 可通过两条并行的访问路径使用，大多数 Agent 配置会使用其中一条或两条：

• CARTO MCP Server — 在基于聊天的 Agent 宿主（Claude.ai、Claude Desktop、ChatGPT 和其他 MCP 客户端）中进行对话内操作的主要路径。连接后，它会提供广泛且统一的工具集：探索数据、创建和编辑 Builder 地图、编写和运行 Workflows、运行 SQL、导入/导出以及组织管理。在支持 MCP Apps 的宿主中，可内嵌渲染地图，并动态将用户发布的 Workflows 注册为 MCP 工具。它可满足大多数交互式请求。
• CARTO CLI（@carto/carto-cli）— 用于脚本编写、CI/CD、无头环境、批量和跨组织操作、更深入的管理与审计（例如，对使用日志运行 SQL），以及使用最完整命令集的路径。本目录中的许多平台技能都会使用它；如果未连接 MCP 服务，则将其用作备用方案。

在使用任何其他 CARTO 技能之前，请先使用此技能 — 本技能介绍如何检测并选择这两条访问路径，还包括 CLI 安装、身份验证、配置文件，以及 CLI 驱动的技能所依赖的全局标志。

何时使用此技能

• 在新机器上首次设置 CLI。
• 用户报告身份验证错误（auth status 失败、令牌过期）。
• 用户希望在不同组织或环境之间切换。
• 下游技能需要使用 --profile、--json、--token 或 --base-url，而你还不清楚这些选项的用法。

预检 — 在执行任何 CLI 操作前运行

使用 CLI 的技能都假设 carto CLI 已正常运行并完成身份验证。如果已连接的 MCP 服务 足以处理该请求（在聊天宿主中探索数据、创建地图、运行 Workflows），则无需使用 CLI — 通过 MCP 执行即可。首次调用 CLI 前，请运行以下检查，并在每项任务开始时重新运行 — 临时沙盒（例如 Claude Code Cowork 任务）会在任务之间清除 CLI。相比之下，已连接的 MCP 服务会在账户级别保持连接（见下文）。

1. 是否已安装 CLI？ 运行 carto --version。如果显示 command not found，请自行安装 — 告知用户你正在安装，然后执行安装；不要推脱说“请在自己的机器上运行此命令”。沙盒所需的 npm 命令以及 EACCES / 可写前缀回退方法见 references/installation.md。
2. 是否已完成身份验证？ 运行 carto auth status。如果尚未完成，请使用无头流程 carto auth login --no-launch-browser — Agent 无法完成浏览器 OAuth。切勿打开或等待浏览器，也切勿改为向用户索要 M2M / API 令牌（见 references/authentication.md）。

如果无法完成安装或身份验证，请说明情况并停止 — 切勿静默改用 Python / SQL / deck.gl 或其他非 CARTO 工具。

此技能包含的内容

主题	参考文档
安装 CLI（npm、版本验证）	references/installation.md
身份验证：浏览器、无头 --no-launch-browser、API 令牌、SSO	references/authentication.md
配置文件：管理多个组织 / 环境	references/profiles.md
全局标志：--json、--debug、--yes、--token、--base-url、--profile、环境变量	references/global-options.md
访问路径：CLI 与 MCP 路由、检测、宿主支持	references/access-paths.md

访问路径：MCP 服务与 CLI

MCP 服务和 CLI 面向不同的使用场景——有些工作流会结合两者。连接了 MCP 服务时，交互式请求应优先使用它（探索数据、创建和编辑地图、构建和运行工作流）；脚本编写、CI/CD、无界面运行、批量或跨组织工作，以及更深入的管理和审计（例如查询使用日志）则应使用 CLI；未连接 MCP 服务时也应使用 CLI。如果某个使用场景适用于 MCP，但 MCP 服务未连接（或宿主环境无法渲染 MCP Apps），则在适用时回退到 CLI，或说明缺少相应功能——不要悄悄改用手工制作的地图。CLI 在临时沙盒中每项任务结束后都会清除；已连接的 MCP 服务则会在账户级别持久存在。完整的路由表、检测信号和依赖身份验证的工具可用性，请参阅：references/access-paths.md。

始终适用的指南

• 绝不悄悄降级。 对 CARTO 的请求必须使用 CARTO 工具。如果无法安装或完成 CLI 身份验证（或未连接所需的 MCP 路由），请说明阻碍并停止——不要改用 Python、SQL、deck.gl 或其他通用地理空间解决方案，也不要用 M2M 令牌替代 carto auth login --no-launch-browser。
• 需要机器可读的输出时，始终传入 --json。 CLI 的文本输出面向人工，且可能发生变化。
• 地图 URL 使用 auth status 返回的租户域名，而不是通用工作区 URL。私有地图的地址为 https://{tenant_domain}/builder/{map_id}；公开或共享地图的地址为 https://{tenant_domain}/map/{map_id}。绝不要为地图拼接 workspace-{region}.app.carto.com URL。托管应用（carto app deploy）是唯一例外：它们只通过 https://workspace-{tenant_id}.app.carto.com/app/{slug}/ 提供服务，在租户域名下使用相同路径会失败。请参阅 carto-develop-app。
• API 基础 URL 为 https://{tenant_id}.api.carto.com，其中 auth status --json 返回的 tenant_id 表示区域（例如 gcp-us-east1）。tenant_domain 中不包含区域。
• 确认提示：maps delete 等破坏性命令会要求输入字面值 "delete"。非交互式使用时，请传入 --yes（或 --json）。
• 异步作业：默认情况下，import 和 sql job 会轮询直至完成。传入 --async（受支持时）可立即返回，并单独进行轮询。