feat: add @kepler.gl/mcp package and demo-app MCP harness bridge

[lixun910]

Extracts the AI assistant's map surface into a publishable, dependency-light @kepler.gl/mcp workspace at src/mcp/, so any AI harness (Claude Code / Codex / sqlrooms) can drive kepler.gl's map without going through kepler-assistant.

@kepler.gl/mcp (src/mcp/)

• map. commands* — get-boundary, get-dataset-context, load-data, add-layer, update-layer-color, set-basemap, add-time-filter, toggle-time-filter, split-view, plus table ops (create-table, add-column, save-data) — each with a zod inputSchema, risk metadata, and human-facing data.details results
• Structural types only: local RoomCommand / RoomCommandResult / KeplerContext replace @sqlrooms/room-store and redux imports; the DuckDB connector slice is typed against apache-arrow so the real @sqlrooms/duckdb connector still satisfies it
• Glue helpers move here and are re-exported: getValuesFromDataset (+ vector-tile branch), isObjectColumn, stringifyObjectColumn, restoreObjectColumns, buildAddColumnPayload
• kepler skill/kepler ships with the package (files: ["dist", "skill"]); build files modeled on src/duckdb; jest spec ported from the vitest one

Demo-app

MCP server based on @kepler.gl/mcp

• esbuild alias resolves @kepler.gl/mcp to source
• kepler-mcp-bridge.tsx — opt-in WebSocket client (reverse-connect, token-gated) that connects out to a local kepler-mcp-demo process, advertises the DuckDB-free command subset with JSON-Schema-converted input schemas, and executes commands against the demo's own redux store. Auto-connects via ?mcp=<token>, or via the status chip (bottom-left)

Codex/Claude -> kepler-mcp-demo-server -> https://deploy-preview-3678--keplergl.netlify.app/

webMCP based on @kepler.gl/mcp

Codex -> https://deploy-preview-3678--keplergl.netlify.app/

webMCP-demo-1-x3.mp4

Verification

• jest: yarn jest src/mcp
• End-to-end with a local kepler-mcp-demo harness against the rendered demo map: bridge connect → map.get-boundary → generate 10k points within the viewport → map.load-data from the harness's /files URL → map.add-layer (points, color-by-value breaks) → map.update-layer-color → screenshot-confirmed render
• End-to-end with Codex to connect to webMCP at https://deploy-preview-3678--keplergl.netlify.app/ and ask to generate 10k points within the viewport

Out of scope

• npm publish of @kepler.gl/mcp (separate step once imports are proven)
• kepler-assistant consuming the package (local repo, separate PR)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR introduces a new workspace package, @kepler.gl/mcp (src/mcp/), intended to externalize kepler.gl’s “map surface” (the map.* command/tool contract + implementations) into a dependency-light module that can be consumed by AI harnesses. It also wires an opt-in WebSocket “reverse-connect” bridge into the demo-app so a local MCP harness process can execute a DuckDB-free subset of those map.* commands against the demo page’s Redux store.

Changes:

• Adds the new @kepler.gl/mcp workspace with contract types (MapContract, tool IDs), command implementations, shared helpers, and a packaged skill/kepler.
• Adds a demo-app MCP bridge component that advertises available commands (DuckDB-free subset) and executes them via WebSocket messages.
• Updates monorepo workspace configuration and lockfile to include the new package and its dependencies (notably zod).

Reviewed changes

Copilot reviewed 30 out of 31 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
yarn.lock	Adds @kepler.gl/mcp workspace entry and zod@^4.4.0 lock entry.
src/mcp/tsconfig.production.json	Adds production TS config for generating declaration files.
src/mcp/src/types.ts	Introduces shared map-surface contract types and MAP_TOOL_IDS.
src/mcp/src/map-contract.ts	Introduces MapContract interface and re-exports tool IDs/types.
src/mcp/src/index.ts	Barrel export for contract + types + commands.
src/mcp/src/commands/utils.ts	Adds shared helpers for Arrow conversion, dataset value extraction, and LLM formatting.
src/mcp/src/commands/types.ts	Defines local structural RoomCommand/KeplerContext/DuckDB connector types.
src/mcp/src/commands/toggle-time-filter-command.ts	Adds map.toggle-time-filter command.
src/mcp/src/commands/time-filter-command.ts	Adds map.add-time-filter command + interval detection logic.
src/mcp/src/commands/table-command.ts	Adds map.create-table command using DuckDB + Arrow round-trips.
src/mcp/src/commands/split-view-command.ts	Adds map.split-view command.
src/mcp/src/commands/save-data-command.ts	Adds map.save-data command for loading DuckDB tables into kepler.
src/mcp/src/commands/load-data-command.ts	Adds map.load-data command for URL-based dataset loading.
src/mcp/src/commands/layer-style-command.ts	Adds map.update-layer-color command.
src/mcp/src/commands/layer-style-command.spec.ts	Adds Jest tests for map.update-layer-color.
src/mcp/src/commands/layer-creation-command.ts	Adds map.add-layer command with default-layer guessing + color config.
src/mcp/src/commands/index.ts	Registers/builds the command catalog and re-exports helpers.
src/mcp/src/commands/dataset-context-command.ts	Adds map.get-dataset-context command.
src/mcp/src/commands/command-wrappers.ts	Adds generic wrapper to adapt existing tools into RoomCommands.
src/mcp/src/commands/boundary-command.ts	Adds map.get-boundary command.
src/mcp/src/commands/basemap-command.ts	Adds map.set-basemap command.
src/mcp/src/commands/add-column-command.ts	Adds map.add-column command for in-place column appends via DuckDB.
src/mcp/skill/kepler/skill.yaml	Adds packaged skill metadata for the map surface.
src/mcp/skill/kepler/SKILL.md	Adds detailed skill documentation and command guidance.
src/mcp/package.json	Defines the new package build, exports, and dependencies.
src/mcp/babel.config.js	Adds Babel build config (mirrors other workspaces’ patterns).
package.json	Adds ./src/mcp to monorepo workspaces list.
examples/demo-app/src/kepler-mcp-bridge.tsx	Adds the opt-in WebSocket bridge exposing DuckDB-free commands.
examples/demo-app/src/app.tsx	Mounts KeplerMcpBridge into the demo app.
examples/demo-app/esbuild.config.mjs	Adds mcp workspace alias for local-source resolution.
examples/demo-app/docs/NEXT_PLAN.md	Removes now-outdated “vendored map surface” planning doc.

Suppressed comments (1)

src/mcp/src/commands/time-filter-command.ts:10

• KeplerContext is type-only. Because the ESM build preserves imports, importing it as a value can throw at module load time. Use import type here.

import {KeplerContext} from './types';

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 38 changed files in this pull request and generated 2 comments.

Suppressed comments (3)

Previously missed (3) — in code that hasn't changed since the last review.

src/mcp/src/commands/types.ts:131

• ToolDescriptor is referenced by the demo-app (toDescriptor(...): ToolDescriptor) but isn’t defined in this package. Adding a shared descriptor type here keeps the map surface contract self-contained.
  src/mcp/src/commands/utils.ts:183
• getValuesFromVectorTileLayer stops collecting values on the first null, which can truncate results if the field legitimately contains nulls. Vector-tile accessors can return null for missing values, so this should not break the loop.
  examples/demo-app/src/kepler-mcp-bridge.tsx:82
• getUrlConfig() supports mcpHost, but the WebSocket URL always uses WSHost() (localhost), so the mcpHost query param is ignored.

      setError(null);

      const wsUrl = `ws://${WSHost()}:${port}/ws?token=${encodeURIComponent(useToken)}`;
      const ws = new WebSocket(wsUrl);

[Copilot]

Pull request overview

Copilot reviewed 36 out of 38 changed files in this pull request and generated no new comments.

Suppressed comments (4)

Previously missed (4) — in code that hasn't changed since the last review.

examples/demo-app/src/kepler-mcp-bridge.tsx:81

• getUrlConfig() reads mcpHost, but the WebSocket URL always uses WSHost() (localhost). This makes the ?mcpHost= parameter ineffective and can be confusing when debugging or running the harness on a different host.

      const wsUrl = `ws://${WSHost()}:${port}/ws?token=${encodeURIComponent(useToken)}`;
      const ws = new WebSocket(wsUrl);

examples/demo-app/src/kepler-mcp-bridge.tsx:92

• ws.onmessage assumes every incoming message is valid JSON. If the server sends a non-JSON frame (or a partial message), JSON.parse will throw and break the message handler for the lifetime of the socket.

      ws.onmessage = async ev => {
        const msg = JSON.parse(String(ev.data));
        if (msg?.type !== 'call') return;

src/mcp/src/commands/time-filter-command.ts:185

• When interval is omitted, the command iterates every row in the dataset to infer an interval (for (let i = 0; i < rows; i++)). For large datasets this can freeze the UI thread; sampling a bounded number of rows is enough for a reasonable interval estimate.

            if (fieldIdx >= 0 && dataset.dataContainer) {
              const rows = dataset.dataContainer.numRows();
              mappedValues = [];
              for (let i = 0; i < rows; i++) {
                const val = dataset.dataContainer.valueAt(i, fieldIdx);
                if (val != null) {
                  const ts = typeof val === 'number' ? val : new Date(val as any).getTime();
                  if (!isNaN(ts)) mappedValues.push(ts);
                }
              }

src/mcp/src/commands/layer-creation-command.ts:260

• The datasetName schema description says “do NOT use the datasetId”, but the implementation accepts either datasets[dataId].label === datasetName or dataId === datasetName. This mismatch can mislead tool callers.

    inputSchema: z.object({
      datasetName: z.string().describe('The name of the dataset. Note: do NOT use the datasetId.'),
      latitudeColumn: z.string().optional(),

[Copilot]

Pull request overview

Copilot reviewed 36 out of 38 changed files in this pull request and generated 2 comments.

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

src/mcp/src/commands/load-data-command.ts:67

• readFileInBatches() can legally yield zero batches (or the first next() can be done: true). In that case parsedData stays empty, but the command still dispatches addDataToMap and returns success: true, which is a broken/false-positive load. Also fileName = url.split('/').pop() will include query strings (e.g. data.csv?x=1). Prefer consuming the async generator like loadExternallyHostedDataset does and erroring when nothing was produced, and derive fileName from new URL(url).pathname.

        const blob = await response.blob();
        const fileName = url.split('/').pop() || 'data';
        const file = new File([blob], fileName);

        const batches = await readFileInBatches({
          file,
          fileCache: [],
          loaders: visState.loaders ?? [],
          loadOptions: visState.loadOptions ?? {}
        });

examples/demo-app/src/kepler-webmcp.tsx:82

• The initial enabled state reads window.localStorage.getItem(...) without a try/catch. In private mode or locked-down storage environments this can throw during render and break the whole WebMCP surface. Mirror the guarded access you already use in setPersistedEnabled.

  const modelContext = useMemo(getModelContext, []);
  const [enabled, setEnabled] = useState(
    () => (typeof window === 'undefined' ? true : window.localStorage.getItem(ENABLED_KEY) !== 'false')
  );
  const [status, setStatus] = useState<WebMcpStatus>('idle');

examples/demo-app/src/kepler-mcp-bridge.tsx:80

• connect() writes the token with localStorage.setItem(...) without guarding for storage failures (private mode / blocked third-party storage). Since a storage exception aborts the connect path, wrap this in try/catch so the bridge can still function without persistence.

      if (!useToken) {
        setError('No token. Paste the one printed by kepler-mcp-demo.');
        setStatus('error');
        return;
      }
      localStorage.setItem('kepler-mcp-token', useToken);
      setStatus('connecting');
      setError(null);

[Copilot]

Pull request overview

Copilot reviewed 36 out of 38 changed files in this pull request and generated no new comments.

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

src/mcp/src/commands/split-view-command.ts:59

• In the disable branch, toggleSplitMap(0) closes map 0 and keeps map 1 (see closeSpecificMapAtIndex: it merges visibility from 1 - payload). Since this command’s API calls the panels map0 (left) and map1 (right), disabling split view should keep the left panel by closing index 1 instead, otherwise layer visibility can unexpectedly flip to whatever map 1 had configured.

        if (action === 'disable') {
          if (isSplit) {
            ctx.dispatch(toggleSplitMap(0));
          }
          return {
            success: true,
            commandId: splitViewCommandId,
            data: {details: 'Split map view disabled. Returned to single map view.'}

src/mcp/src/commands/split-view-command.ts:88

• toggleLayerForMapUpdater treats a missing splitMaps[i].layers[layerId] entry as false and toggles it to true (see reducer comment: “if layerId not in layers, set it to visible”). Here const isVisible = map0Layers[layerId]; yields undefined for missing keys, so layers that are already hidden can get toggled on when shouldBeVisible is false. Coerce to boolean before comparing.

This issue also appears on line 93 of the same file.

              const map0Layers = splitMaps[0]?.layers || {};
              const desiredSet0 = new Set(layerIdsForMap0);
              for (const layerId of allLayerIds) {
                const isVisible = map0Layers[layerId];
                const shouldBeVisible = desiredSet0.has(layerId);
                if (isVisible !== shouldBeVisible) {
                  ctx.dispatch(toggleLayerForMap(0, layerId));
                }
              }

src/mcp/src/commands/split-view-command.ts:101

• Same issue for the right panel: map1Layers[layerId] can be undefined for hidden layers, but toggleLayerForMapUpdater interprets missing as false and will toggle it to true. Use Boolean(map1Layers[layerId]) so that layers not listed in layerIdsForMap1 remain hidden.

              const map1Layers = freshSplitMaps?.[1]?.layers || {};
              const desiredSet1 = new Set(layerIdsForMap1);
              for (const layerId of allLayerIds) {
                const isVisible = map1Layers[layerId];
                const shouldBeVisible = desiredSet1.has(layerId);
                if (isVisible !== shouldBeVisible) {
                  ctx.dispatch(toggleLayerForMap(1, layerId));
                }
              }

[Copilot]

Pull request overview

Copilot reviewed 36 out of 38 changed files in this pull request and generated no new comments.

Suppressed comments (4)

Previously missed (4) — in code that hasn't changed since the last review.

src/mcp/src/commands/layer-creation-command.ts:176

• The categorical colorMap validation builds a Set of every value in the column (Array.from({length: dataset.length}...)), which can be very expensive and freeze the UI on large datasets. You can validate that all provided colorMap values exist without materializing the full column by scanning rows and deleting matches from a small wanted set (early-exit when all are found), while still collecting a small sample for the error message.

    if (colorType !== 'breaks' && providedColorMap) {
      const actualValues = new Set(
        Array.from({length: dataset.length}, (_, i) => dataset.getValue(colorBy, i))
      );
      const missing = providedColorMap.filter(c => !actualValues.has(c.value)).map(c => c.value);

src/mcp/src/commands/save-data-command.ts:50

• In the error path, the error string interpolates the caught value directly (${error}), which often becomes Error: ... or [object Object] and can leak non-string objects. Other commands in this package normalize errors to error.message / String(error); align this one so the message is predictable.

        return {
          success: false,
          commandId: saveDataCommandId,
          error: `Cannot save data to kepler.gl: ${error}`
        };

examples/demo-app/src/kepler-mcp-shared.ts:63

• getMapboxToken reads localStorage without a try/catch. In some browser contexts (private mode, blocked storage, sandboxed iframes) this can throw and break all command execution. Other localStorage reads in the demo bridge are guarded; this one should be too.

    getMapboxToken: () =>
      typeof window !== 'undefined' ? (localStorage.getItem('mapbox-token') ?? undefined) : undefined,
    dispatch: (action: any) => reduxStore?.dispatch(action),

src/mcp/src/commands/load-data-command.ts:50

• When loading a URL, the created File loses the original source URL, so processFileData will generate the dataset id from fileName only. That can cause collisions/overwrites if two different URLs share the same filename, and it also prevents externally-hosted metadata from being attached. Set file.keplerSourceUrl so the processors can hash by URL and persist source metadata.

        // Derive the filename from the URL pathname so query strings (e.g.
        // `data.csv?x=1`) don't end up in the dataset name.
        const fileName = new URL(url).pathname.split('/').pop() || 'data';
        const file = new File([blob], fileName);

[Copilot]

Pull request overview

Copilot reviewed 36 out of 38 changed files in this pull request and generated no new comments.

Suppressed comments (3)

Previously missed (3) — in code that hasn't changed since the last review.

src/mcp/src/map-contract.ts:34

• MapContract.callTool redefines a result shape that already exists as ToolResult in ./types. Duplicating this contract increases the risk of the two drifting (e.g., adding a field to ToolResult but forgetting MapContract). Reuse ToolResult directly for callTool’s return type and import it from ./types.
  src/mcp/src/commands/dataset-context-command.ts:31
• map.get-dataset-context currently assumes ctx.getDatasetContext() returns a two-part string (a human line + JSON), and blindly JSON.parse()s everything after the first newline. Since KeplerContext is meant to be a reusable host seam, this is brittle (a host returning pure JSON, or a slightly different preface, will make this tool fail). Consider parsing both formats: accept pure JSON (starting with '[' / '{') and otherwise fall back to stripping the first line.

        const datasets = JSON.parse(context.split('\n').slice(1).join('\n'));
        return {

src/mcp/src/commands/utils.ts:71

• The comment claims the decimal conversion is “exact for any scale”, but the implementation ultimately coerces the decimal string into a JS Number. That coercion can still lose precision (or overflow) for large Decimal128 values, so the comment is misleading.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 38 changed files in this pull request and generated 2 comments.

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

src/mcp/src/commands/utils.ts:185

• getValuesFromVectorTileLayer stops iterating the tileSet when it encounters a null value. In kepler's own vector-tile TileDataset iteration, nulls are treated as “skip this row” rather than “end of data”, so breaking here can truncate the returned values array and misalign downstream logic.
  examples/demo-app/src/kepler-mcp-shared.ts:43
• buildKeplerContext declares getVisState: () => VisState (per KeplerContext), but currently returns readMap()?.visState, which can be undefined before the map is initialized. That leads to confusing downstream errors like "Cannot read properties of undefined" inside commands.

    getVisState: () => readMap()?.visState,

[Copilot]

Pull request overview

Copilot reviewed 36 out of 38 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

examples/demo-app/src/kepler-webmcp.tsx:149

• WebMCP tool execution ignores the caller-provided AbortSignal (2nd argument to execute). This prevents agents from cancelling long-running commands and also drops cancellation semantics expected by the WebMCP API.

            execute: async input => {
              try {
                const result = await cmd.execute(
                  {store: undefined, getState: () => undefined, invocation: {surface: 'webmcp'}} as any,
                  input ?? {}
                );
                return formatResult(result as any);