carto-preview-builder-map

carto-preview-builder-map

CARTO MCP サーバーを介して、既存の保存済み CARTO Builder マップの軽量なインラインプレビューを表示します。ユーザーがマップを URL、ID、名前のいずれかで指定すると、エージェントは 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 を描画できる必要があります。トークンと OAuth： トークンを使った 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 で読み込みます。名前を挙げて、どのマップを読み込むかユーザーに確認します。
2 件以上一致	名前、日付、サムネイルを一覧表示します。ユーザーに選んでもらってください。推測してはいけません。
0 件一致	条件に一致する保存済みマップがないことをユーザーに伝えます。同じデータに対する代替手段として carto-render-inline-map（アドホックな view_map 仕様）を提案します。

プレビューについての事前説明（常に行う）

プレビューは軽量です。

• ✓ レイヤー、ベースマップ、表示範囲、ポップアップ、凡例。線のスタイル（破線／点線、ポリゴンの境界線）を含め、Builder での設定がそのまま反映されます。
• ✗ ウィジェット、SQL パラメーター、マップの説明、AI エージェントの設定、その他 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 が複数の候補を返した際、最新の候補を黙って選ぶこと。 候補を提示し、ユーザーに選んでもらってください。