carto-render-inline-map

carto-render-inline-map

CARTO MCP サーバーの view_map ツールを使って、チャット内にその場でインタラクティブな地図を表示します。エージェントが @deck.gl/json の宣言的な仕様を出力し、レンダラーが認証情報、ベースマップ、ツールチップを処理します。ユーザーはチャットを離れずに地図を確認できます。

レンダリングのたびに凡例が必要です。 view_map レンダラーは自動凡例を表示しません。view_map の呼び出し後、ホストのウィジェット機能（例：Claude.ai／Claude Desktop の show_widget）を使って凡例を表示してください。これが機能する唯一の視覚的な表示方法です。主要なホストのレンダラーはすべてチャットメッセージ内の HTML をエスケープするため、生のテキストとして表示されます。チャットの返信に HTML を出力しないでください。ホストにウィジェットツールがない場合は、プレーンテキストの凡例（バケットごとに絵文字の色付き四角形を使った Markdown の箇条書き、括弧内に 16 進コード）を使用してください。HTML テンプレート全体、スタイル規則、および各ヘルパーのバリエーション（colorBins のスウォッチ、colorContinuous のグラデーションバー、colorCategories のカテゴリ別表示、ラスターの 3 値バケットと nodata）は、view_map ツールの説明にある LEGEND セクションに記載されています。これはその場で作成する view_map の仕様にのみ適用されます。インラインで読み込んだ保存済みの Builder マップ（carto-preview-builder-map を参照）には、Builder 独自の凡例が含まれています。

ツールの仕様。 このスキルは、CARTO MCP サーバーが提供する view_map ツールを使用します。ツールの入力形式（deckglProps）、レイヤーソースの互換性、aggregationExp の要件、および @@= の式評価に関する制限は、ツール自身の MCP 説明に記載されています。MCP ホストのツールインスペクターを使うか、tools/list を呼び出して確認してください。このスキルはルーティング、地図表現、およびエージェントの返信に重点を置いており、ツールの仕様を重複して記載するものではありません。

このスキルは MCP 専用です。view_map がインラインで地図を表示するのは、CARTO MCP サーバー上で、かつ MCP Apps に対応したホスト（Claude.ai、Claude Desktop、ChatGPT）に限られます。インライン表示に相当する CLI はありません。view_map は OAuth とトークンの両方の MCP セッションで利用できます。

Step 1 — 利用可能な機能を検出する

検出の手がかりとホストの対応状況については、carto-basics/references/access-paths.md を参照してください。簡単な確認方法：ツール一覧に view_map があり、ホストが MCP Apps をレンダリングできる必要があります。

セットアップ	対応方法
view_map があり、ホストがレンダリングに対応	通常どおり進めます。
view_map があるが、ホストがレンダリングに非対応（Gemini CLI、Codex CLI、MCP Inspector、MCPJam — テキストのみ）	ホストでは地図をインライン表示できないことをユーザーに伝え、ホストの切り替え、またはシェルを利用できる場合は PNG を作成するために carto-create-builder-maps と carto maps screenshot を使うことを提案します。
view_map がない	MCP サーバーが接続されていません。ユーザーに伝え、汎用の可視化ウィジェットで代用しないでください。

別のスキルを選ぶ場合

• 恒久的に保存・共有できる地図 → 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。実行環境（JavaScript で利用できる deck.gl の全機能）と地図表現のルールが異なります。

仕様を作成する前のデータ探索フロー

データ探索は explore_data MCP ツールを通じて行います。そのメソッドは、カートグラフィーのリファレンスで list_connections、search、list_resources、describe とだけ記載されているものです。すべて OAuth 経由で利用できます。トークンセッションでは、list_connections／search／list_resources に必要なのは MCP Server スコープだけですが、describe には Maps 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）、インラインで確認してください。再レンダリングした場当たり的な仕様を使ってはいけません。