Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
// SPDX-License-Identifier: MIT
// Copyright contributors to the kepler.gl project
/**
* Shared plumbing for the demo-app's agent surfaces over the `@kepler.gl/mcp`
* map.* commands:
*
* - `kepler-webmcp.tsx` — native WebMCP registration (`document.modelContext`)
* for harnesses with a built-in browser (Chrome's agent, Claude Desktop's
* browser, ...)
* - `kepler-mcp-bridge.tsx` — WebSocket reverse-connect for harnesses without
* WebMCP (Codex, Claude Code), opted in with the ?mcp=<token> URL printed by
* the local `kepler-mcp` server
*
* Both surfaces execute commands against the demo's own redux store through
* `buildKeplerContext` and serve the same DuckDB-free catalog.
*/
import {getKeplerCommands, getValuesFromDataset} from '@kepler.gl/mcp';
import type {
KeplerContext,
RoomCommandExecuteOutput,
RoomCommandResult,
ToolDescriptor
} from '@kepler.gl/mcp';
import {WebMercatorViewport} from '@deck.gl/core';
import {z} from 'zod';
// The skill markdown ships with the @kepler.gl/mcp package (subpath export), so
// the demo-app folder stays self-contained — no relative path reaching outside
// it into the monorepo layout.
import mapSkillMarkdown from '@kepler.gl/mcp/skill/kepler/SKILL.md';
// map.* commands that need a DuckDB connector / the kepler-app glue
// (`loadTableToKepler`, `loadTableIntoDuckDB`, `getConnector`). The demo
// surfaces (mapping-only bridge / webMCP) do not serve them.
export const DUCKDB_REQUIRED = new Set(['map.create-table', 'map.add-column', 'map.save-data']);
// Mutating map.* commands every agent will reach for without reading the
// skill. Each gets a pointer to kepler.get-map-skill appended to its
// description so the reader tool is impossible to miss.
const SKILL_REQUIRED = new Set([
'map.add-layer',
'map.update-layer-color',
'map.add-time-filter',
'map.toggle-time-filter',
'map.split-view',
'map.load-data',
'map.set-basemap'
]);
const SKILL_HINT = `\nREAD THE MAP SKILL FIRST: call kepler.get-map-skill before using this command — it explains layer-type selection, color rules, and the workflow.`;
// The skill markdown is served verbatim, but this demo catalog filters out the
// DuckDB-backed commands. Prepend a note so agents don't get stuck trying
// tools that aren't actually served on the bridge/WebMCP surfaces.
const DUCKDB_UNAVAILABLE_NOTE = `> NOTE: this demo surface does NOT serve the DuckDB-backed commands ${[
...DUCKDB_REQUIRED
].join(', ')} — they are filtered out of the catalog. Use the available map.* commands only.`;
/** Live accessors into the demo's own redux store — no kepler-assistant needed. */
export function buildKeplerContext(reduxStore: any): KeplerContext {
const readMap = () => reduxStore?.getState()?.demo?.keplerGl?.map;
return {
getVisState: () => {
const visState = readMap()?.visState;
if (!visState) {
throw new Error('kepler.gl map is not initialized yet.');
}
return visState;
},
getMapBoundary: () => {
// Recompute the current viewport corners from the live mapState (same
// WebMercatorViewport math the app's onViewStateChange uses). Fall back
// to the assistant slice's stored boundary if mapState lacks a size.
const mapState = readMap()?.mapState;
if (mapState?.width && mapState?.height) {
try {
const viewport = new WebMercatorViewport(mapState);
const nw = viewport.unproject([0, 0]);
const se = viewport.unproject([viewport.width, viewport.height]);
return {nw: [nw[0], nw[1]], se: [se[0], se[1]]};
} catch {
/* fall through to stored boundary */
}
}
// Coerce null → undefined: the assistant slice may hold null, but
// KeplerContext.getMapBoundary is typed to return the boundary object or
// undefined only — returning null would break the contract for strict
// consumers.
return reduxStore?.getState()?.demo?.aiAssistant?.keplerGl?.mapBoundary ?? undefined;
},
getMapboxToken: () => {
if (typeof window === 'undefined') return undefined;
try {
return localStorage.getItem('mapbox-token') ?? undefined;
} catch {
// private mode / blocked storage — no token
return undefined;
}
},
dispatch: (action: any) => reduxStore?.dispatch(action),
getValuesFromDataset: (datasetName, variableName) => {
const visState = readMap()?.visState;
if (!visState) return [];
return getValuesFromDataset(visState.datasets, visState.layers, datasetName, variableName);
},
getDatasetContext: () => {
// Shape required by map.get-dataset-context: a human line, then a JSON
// array of {datasetName, datasetId, fields, layers} descriptors.
const visState = readMap()?.visState;
const datasets = visState?.datasets;
const layers = visState?.layers ?? [];
if (!datasets) return '';
const context =
'Please remember the following datasets and layers for answering the user question:';
const dataMeta = Object.values(datasets).map((ds: any) => ({
datasetName: ds?.label ?? ds?.id,
datasetId: ds?.id,
// Field name→type mappings as a single object ({colA: typeA, ...}),
// matching the "field name→type mappings" shape map.get-dataset-context
// describes — not an array of single-key objects.
fields: Object.fromEntries((ds?.fields ?? []).map((f: any) => [f.name, f.type])),
layers: layers
.filter((layer: any) => layer?.config?.dataId === ds?.id)
.map((layer: any) => ({
id: layer.id,
label: layer.config.label,
type: layer.type,
geometryMode: layer.config.columnMode,
geometryColumns: Object.fromEntries(
Object.entries(layer.config.columns)
.filter(([, value]) => value !== null)
.map(([key, value]) => [
key,
typeof value === 'object' && value !== null
? Object.fromEntries(Object.entries(value).filter(([, v]) => v !== null))
: value
])
)
}))
}));
return `${context}\n${JSON.stringify(dataMeta)}`;
},
loadTableToKepler: async () => ({
success: false,
error: 'map.save-data / loadTableToKepler is not available in the mapping-only bridge.'
}),
loadTableIntoDuckDB: async () => {
throw new Error('DuckDB operations are not available in the mapping-only bridge.');
},
getConnector: async () => {
throw new Error('DuckDB operations are not available in the mapping-only bridge.');
}
};
}
/** The DuckDB-free map.* commands this page serves to agents, plus the map skill reader. */
export function buildCatalog(ctx: KeplerContext) {
const commands = Object.values(getKeplerCommands(ctx)).filter(c => !DUCKDB_REQUIRED.has(c.id));
return [getMapSkillCommand(), ...commands.map(c => withSkillHint(c))];
}
/**
* Read-only tool that serves the kepler.gl map-management skill verbatim. First
* in the catalog so it is the first tool any surface advertises; every mutating
* command's description also points at it (see `withSkillHint`).
*/
function getMapSkillCommand() {
return {
id: 'kepler.get-map-skill',
name: 'Read map skill',
group: 'Map',
description: `READ THE MAP SKILL FIRST — the kepler.gl map-management skill, served verbatim from src/mcp/skill/kepler/SKILL.md.
Call this command BEFORE any other map command. It explains how to choose a layer type (point, arc, line, grid, hexagon, cluster, heatmap, geojson, h3, trip, s2, flow), how to color layers (case-sensitive colorBy, breaks vs unique colorMaps), time animation, split view, and the complete add-layer workflow with JSON examples.
When the user asks for a flow map, "OD flows", "a map of movements" → this skill maps that to layerType "flow" (use "arc" only for straight great-circle lines between un-clustered points).`,
keywords: ['skill', 'map', 'workflow', 'guide', 'read-me-first'],
metadata: {readOnly: true, idempotent: true, riskLevel: 'low'},
execute: async () => ({
success: true,
commandId: 'kepler.get-map-skill',
data: {details: `${DUCKDB_UNAVAILABLE_NOTE}\n\n${mapSkillMarkdown}`}
})
};
}
function withSkillHint(cmd: ReturnType<typeof getKeplerCommands>[string]) {
if (SKILL_REQUIRED.has(cmd.id) && cmd.description) {
return {...cmd, description: `${cmd.description}${SKILL_HINT}`};
}
return cmd;
}
export function toDescriptor(cmd: {
id: string;
name: string;
description?: string;
group?: string;
keywords?: string[];
metadata?: {
readOnly?: boolean;
idempotent?: boolean;
riskLevel?: string;
requiresConfirmation?: boolean;
};
inputSchema?: any;
}): ToolDescriptor {
let inputSchema: Record<string, unknown> = {type: 'object'};
if (cmd.inputSchema) {
try {
// zod v4 -> JSON Schema. Static import (not require): the demo-app
// bundles for platform 'browser' / format 'iife', where `require` is
// undefined — a runtime require would throw and silently fall back to
// {type: 'object'}, losing tool discoverability and validation.
inputSchema = (z.toJSONSchema(cmd.inputSchema) ?? {type: 'object'}) as Record<
string,
unknown
>;
} catch {
inputSchema = {type: 'object'};
}
}
return {
id: cmd.id,
name: cmd.name,
description: cmd.description,
group: cmd.group,
keywords: cmd.keywords,
inputSchema,
metadata: cmd.metadata as ToolDescriptor['metadata']
};
}
export function formatResult(result: RoomCommandExecuteOutput): string {
// A command may return a bare payload (TData) or void, not just a
// RoomCommandResult — handle those instead of assuming the result shape.
if (result && typeof result === 'object' && 'success' in result) {
const r = result as RoomCommandResult;
// A structured failure may carry `error` or a `message` field, or neither
// — treat success:false as a failure regardless so it can't be formatted
// as a ✓ success and mask the failure in bridge/WebMCP logs.
if (r.success === false || r.error) {
const reason = r.error ?? (r as {message?: string}).message ?? 'failed';
return `✗ ${r.commandId}: ${reason}`;
}
const data = r.data as {details?: string} | undefined;
return data?.details ? `✓ ${data.details}` : `✓ ${r.commandId} ok`;
}
return result == null
? '✓ ok'
: `✓ ${typeof result === 'string' ? result : JSON.stringify(result)}`;
}