@mapbox/mcp-server 0.12.7 → 0.13.0-dev

package/dist/commonjs/utils/mapAppPayload.d.ts

@@ -0,0 +1,206 @@
+import { z } from 'zod';
+/**
+ * Payload format for the generic Mapbox MCP App (`ui://mapbox/map-app/...`).
+ *
+ * Tools that want to render their result on a live Mapbox GL JS map produce
+ * a `MapAppPayload` and attach it to the tool result at `_meta.ui.payload`.
+ * The shared iframe template reads it and translates each entry into
+ * `map.addSource`/`map.addLayer`/`new mapboxgl.Marker` calls.
+ *
+ * The payload is intentionally a thin pass-through to Mapbox Style spec
+ * `paint` and `layout` objects rather than its own DSL — the iframe just
+ * forwards them to GL JS. That keeps the spec surface small and avoids
+ * reinventing a chunk of the style spec over postMessage.
+ */
+export type Geometry = {
+    type: 'Point';
+    coordinates: [number, number];
+} | {
+    type: 'LineString';
+    coordinates: [number, number][];
+} | {
+    type: 'Polygon';
+    coordinates: [number, number][][];
+} | {
+    type: 'MultiPolygon';
+    coordinates: [number, number][][][];
+};
+export type Feature = {
+    type: 'Feature';
+    geometry: Geometry;
+    properties?: Record<string, unknown>;
+};
+export type FeatureCollection = {
+    type: 'FeatureCollection';
+    features: Feature[];
+};
+export interface MapAppLayer {
+    /** Unique within the payload — used as both source id and layer id. */
+    id: string;
+    type: 'fill' | 'line' | 'circle' | 'symbol';
+    data: Feature | FeatureCollection;
+    /** Mapbox Style spec paint object, passed through to addLayer. */
+    paint?: Record<string, unknown>;
+    /** Mapbox Style spec layout object, passed through to addLayer. */
+    layout?: Record<string, unknown>;
+}
+export interface MapAppMarker {
+    coordinates: [number, number];
+    /**
+     * Visual style:
+     *   - `pin`: default Mapbox marker
+     *   - `numbered`: circular badge containing `label` (e.g. visit order)
+     *   - `start`/`end`: green/red circular badge (route endpoints)
+     */
+    style?: 'pin' | 'numbered' | 'start' | 'end';
+    /** Required when style === 'numbered'. */
+    label?: string;
+    /** Optional CSS color override; defaults are style-derived. */
+    color?: string;
+    /** Popup text (optional). */
+    popup?: string;
+}
+export interface MapAppLegendEntry {
+    label: string;
+    color: string;
+    opacity?: number;
+}
+export interface MapAppCamera {
+    center?: [number, number];
+    zoom?: number;
+    /** If set, takes precedence over center/zoom and over auto-fit. */
+    bounds?: [[number, number], [number, number]];
+}
+/**
+ * For responses >50KB where the geometry is offloaded to a temp resource:
+ * the iframe will fetch this URI via `resources/read` (host bridge) and
+ * merge the returned GeoJSON into the named layer.
+ */
+export interface MapAppDeferredLayer {
+    resourceUri: string;
+    layerId: string;
+}
+/**
+ * A layer the iframe must fetch and build *itself*, directly from the
+ * Mapbox API using its own public token — rather than server-computed
+ * geometry passed through a ref. Used by tools whose geometry is a single
+ * Mapbox API call away from the tool's own input params (e.g. directions,
+ * isochrone, map matching, search, category search, trip optimization),
+ * so the map preview never depends on server-side storage that a process
+ * restart or a conversation rehydration could invalidate. See
+ * `src/utils/selfFetchRef.ts` and the `selffetch` handling in
+ * `mapAppHtml.ts`.
+ */
+export interface MapAppSelfFetch {
+    tool: 'directions' | 'isochrone' | 'map_matching' | 'search' | 'category_search' | 'optimization' | 'ground_location';
+    params: Record<string, unknown>;
+}
+export interface MapAppPayload {
+    /** Short header chip shown in the top-left of the iframe. */
+    summary?: string;
+    /** Layers to add to the map (in order). */
+    layers: MapAppLayer[];
+    markers?: MapAppMarker[];
+    /** Bottom-left legend rows (color swatch + label). */
+    legend?: MapAppLegendEntry[];
+    /** Optional initial camera; otherwise auto-fits to the union of all data. */
+    camera?: MapAppCamera;
+    /** Optional fetch-on-render hook for large geometries. */
+    defer?: MapAppDeferredLayer;
+    /** Layers the iframe fetches and builds itself, post-initial-render. */
+    selfFetch?: MapAppSelfFetch[];
+}
+export declare const MapAppPayloadSchema: z.ZodObject<{
+    summary: z.ZodOptional<z.ZodString>;
+    layers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<{
+            symbol: "symbol";
+            fill: "fill";
+            line: "line";
+            circle: "circle";
+        }>;
+        data: z.ZodUnion<readonly [z.ZodObject<{
+            type: z.ZodLiteral<"Feature">;
+            geometry: z.ZodObject<{
+                type: z.ZodEnum<{
+                    Point: "Point";
+                    LineString: "LineString";
+                    Polygon: "Polygon";
+                    MultiPolygon: "MultiPolygon";
+                }>;
+                coordinates: z.ZodUnknown;
+            }, z.core.$strip>;
+            properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"FeatureCollection">;
+            features: z.ZodArray<z.ZodObject<{
+                type: z.ZodLiteral<"Feature">;
+                geometry: z.ZodObject<{
+                    type: z.ZodEnum<{
+                        Point: "Point";
+                        LineString: "LineString";
+                        Polygon: "Polygon";
+                        MultiPolygon: "MultiPolygon";
+                    }>;
+                    coordinates: z.ZodUnknown;
+                }, z.core.$strip>;
+                properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>]>;
+        paint: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        layout: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    markers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        coordinates: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        style: z.ZodOptional<z.ZodEnum<{
+            start: "start";
+            pin: "pin";
+            numbered: "numbered";
+            end: "end";
+        }>>;
+        label: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+        popup: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    legend: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        color: z.ZodString;
+        opacity: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    camera: z.ZodOptional<z.ZodObject<{
+        center: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        zoom: z.ZodOptional<z.ZodNumber>;
+        bounds: z.ZodOptional<z.ZodTuple<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>], null>>;
+    }, z.core.$strip>>;
+    selfFetch: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        tool: z.ZodEnum<{
+            search: "search";
+            directions: "directions";
+            isochrone: "isochrone";
+            map_matching: "map_matching";
+            category_search: "category_search";
+            optimization: "optimization";
+            ground_location: "ground_location";
+        }>;
+        params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * Decode a Mapbox polyline string (precision 5 by default) to a GeoJSON
+ * LineString. Used tool-side so the iframe never has to do this — the
+ * generic renderer only ever sees GeoJSON.
+ *
+ * Returns null if the decoded coordinates fall outside lng/lat bounds,
+ * which can happen if the precision is wrong (the Directions API can emit
+ * polyline6 when `geometries=polyline6`). Callers should try precision 6
+ * as a fallback.
+ */
+export declare function decodePolyline(str: string, precision?: number): [number, number][] | null;
+/**
+ * Convenience: decode polyline with precision-5 then precision-6 fallback.
+ * If both produce out-of-range coordinates, returns null and the caller
+ * should skip emitting a map-app payload (the geometry can't be drawn).
+ */
+export declare function decodePolylineWithFallback(str: string): [number, number][] | null;
+//# sourceMappingURL=mapAppPayload.d.ts.map

package/dist/commonjs/utils/mapAppPayload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapAppPayload.d.ts","sourceRoot":"","sources":["../../../src/utils/mapAppPayload.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/utils/mapAppPayload.js

@@ -0,0 +1,129 @@
+"use strict";
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapAppPayloadSchema = void 0;
+exports.decodePolyline = decodePolyline;
+exports.decodePolylineWithFallback = decodePolylineWithFallback;
+const zod_1 = require("zod");
+// Zod mirror of MapAppPayload, kept loose on paint/layout/geometry internals
+// (those are already validated by construction in the payload builders) -
+// this exists so `render_map_tool` can declare the inline payload shape on
+// its output schema without a strict validator stripping it. See
+// RenderMapTool.output.schema.ts for why the inline copy matters.
+const GeometrySchema = zod_1.z.object({
+    type: zod_1.z.enum(['Point', 'LineString', 'Polygon', 'MultiPolygon']),
+    coordinates: zod_1.z.unknown()
+});
+const FeatureSchema = zod_1.z.object({
+    type: zod_1.z.literal('Feature'),
+    geometry: GeometrySchema,
+    properties: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional()
+});
+const FeatureCollectionSchema = zod_1.z.object({
+    type: zod_1.z.literal('FeatureCollection'),
+    features: zod_1.z.array(FeatureSchema)
+});
+const MapAppLayerSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    type: zod_1.z.enum(['fill', 'line', 'circle', 'symbol']),
+    data: zod_1.z.union([FeatureSchema, FeatureCollectionSchema]),
+    paint: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    layout: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional()
+});
+const MapAppMarkerSchema = zod_1.z.object({
+    coordinates: zod_1.z.tuple([zod_1.z.number(), zod_1.z.number()]),
+    style: zod_1.z.enum(['pin', 'numbered', 'start', 'end']).optional(),
+    label: zod_1.z.string().optional(),
+    color: zod_1.z.string().optional(),
+    popup: zod_1.z.string().optional()
+});
+const MapAppLegendEntrySchema = zod_1.z.object({
+    label: zod_1.z.string(),
+    color: zod_1.z.string(),
+    opacity: zod_1.z.number().optional()
+});
+const MapAppCameraSchema = zod_1.z.object({
+    center: zod_1.z.tuple([zod_1.z.number(), zod_1.z.number()]).optional(),
+    zoom: zod_1.z.number().optional(),
+    bounds: zod_1.z
+        .tuple([
+        zod_1.z.tuple([zod_1.z.number(), zod_1.z.number()]),
+        zod_1.z.tuple([zod_1.z.number(), zod_1.z.number()])
+    ])
+        .optional()
+});
+const MapAppSelfFetchSchema = zod_1.z.object({
+    tool: zod_1.z.enum([
+        'directions',
+        'isochrone',
+        'map_matching',
+        'search',
+        'category_search',
+        'optimization',
+        'ground_location'
+    ]),
+    params: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown())
+});
+exports.MapAppPayloadSchema = zod_1.z.object({
+    summary: zod_1.z.string().optional(),
+    layers: zod_1.z.array(MapAppLayerSchema),
+    markers: zod_1.z.array(MapAppMarkerSchema).optional(),
+    legend: zod_1.z.array(MapAppLegendEntrySchema).optional(),
+    camera: MapAppCameraSchema.optional(),
+    selfFetch: zod_1.z.array(MapAppSelfFetchSchema).optional()
+});
+/**
+ * Decode a Mapbox polyline string (precision 5 by default) to a GeoJSON
+ * LineString. Used tool-side so the iframe never has to do this — the
+ * generic renderer only ever sees GeoJSON.
+ *
+ * Returns null if the decoded coordinates fall outside lng/lat bounds,
+ * which can happen if the precision is wrong (the Directions API can emit
+ * polyline6 when `geometries=polyline6`). Callers should try precision 6
+ * as a fallback.
+ */
+function decodePolyline(str, precision = 5) {
+    if (!str || typeof str !== 'string')
+        return null;
+    const factor = Math.pow(10, precision);
+    const coords = [];
+    let lat = 0;
+    let lng = 0;
+    let i = 0;
+    while (i < str.length) {
+        let shift = 0;
+        let result = 0;
+        let b;
+        do {
+            b = str.charCodeAt(i++) - 63;
+            result |= (b & 0x1f) << shift;
+            shift += 5;
+        } while (b >= 0x20 && i < str.length);
+        lat += result & 1 ? ~(result >> 1) : result >> 1;
+        shift = 0;
+        result = 0;
+        do {
+            b = str.charCodeAt(i++) - 63;
+            result |= (b & 0x1f) << shift;
+            shift += 5;
+        } while (b >= 0x20 && i < str.length);
+        lng += result & 1 ? ~(result >> 1) : result >> 1;
+        const lngOut = lng / factor;
+        const latOut = lat / factor;
+        if (lngOut < -180 || lngOut > 180 || latOut < -90 || latOut > 90) {
+            return null;
+        }
+        coords.push([lngOut, latOut]);
+    }
+    return coords;
+}
+/**
+ * Convenience: decode polyline with precision-5 then precision-6 fallback.
+ * If both produce out-of-range coordinates, returns null and the caller
+ * should skip emitting a map-app payload (the geometry can't be drawn).
+ */
+function decodePolylineWithFallback(str) {
+    return decodePolyline(str, 5) ?? decodePolyline(str, 6);
+}
+//# sourceMappingURL=mapAppPayload.js.map

package/dist/commonjs/utils/mapAppPayload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapAppPayload.js","sourceRoot":"","sources":["../../../src/utils/mapAppPayload.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/utils/selfFetchRef.d.ts

@@ -0,0 +1,25 @@
+import type { MapAppPayload, MapAppSelfFetch } from './mapAppPayload.js';
+export type SelfFetchTool = MapAppSelfFetch['tool'];
+/**
+ * Build a ref for a tool whose map preview is fetched by the iframe itself,
+ * directly from the Mapbox API using its own public token — rather than
+ * server-computed geometry stashed behind an opaque UUID.
+ *
+ * `params` is the tool's own call arguments (already visible to the LLM —
+ * nothing new is exposed), base64'd into the URI. Unlike `mapbox://temp/`
+ * refs, there is nothing server-side to lose on a restart: resolving this
+ * ref just unwraps the params back into a `MapAppPayload.selfFetch` entry
+ * for the iframe to act on, with no I/O and no store involved.
+ */
+export declare function buildSelfFetchRef(tool: SelfFetchTool, params: Record<string, unknown>): string;
+export declare function isSelfFetchRef(uri: string): boolean;
+/**
+ * Unwrap a `mapbox://selffetch/...` ref back into a minimal `MapAppPayload`
+ * carrying only a `selfFetch` entry — no layers/markers of its own. The
+ * iframe resolves the actual geometry client-side after the initial render
+ * (see the `selffetch` handling in `mapAppHtml.ts`). Returns null if the ref
+ * isn't a self-fetch ref, names an unrecognized tool, or its data doesn't
+ * decode.
+ */
+export declare function resolveSelfFetchRef(uri: string): MapAppPayload | null;
+//# sourceMappingURL=selfFetchRef.d.ts.map

package/dist/commonjs/utils/selfFetchRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfFetchRef.d.ts","sourceRoot":"","sources":["../../../src/utils/selfFetchRef.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAIzE,MAAM,MAAM,aAAa,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;AAYpD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAKR;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CA2BrE"}

package/dist/commonjs/utils/selfFetchRef.js

@@ -0,0 +1,75 @@
+"use strict";
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSelfFetchRef = buildSelfFetchRef;
+exports.isSelfFetchRef = isSelfFetchRef;
+exports.resolveSelfFetchRef = resolveSelfFetchRef;
+const SELF_FETCH_URI_PREFIX = 'mapbox://selffetch/';
+const SELF_FETCH_TOOLS = [
+    'directions',
+    'isochrone',
+    'map_matching',
+    'search',
+    'category_search',
+    'optimization',
+    'ground_location'
+];
+/**
+ * Build a ref for a tool whose map preview is fetched by the iframe itself,
+ * directly from the Mapbox API using its own public token — rather than
+ * server-computed geometry stashed behind an opaque UUID.
+ *
+ * `params` is the tool's own call arguments (already visible to the LLM —
+ * nothing new is exposed), base64'd into the URI. Unlike `mapbox://temp/`
+ * refs, there is nothing server-side to lose on a restart: resolving this
+ * ref just unwraps the params back into a `MapAppPayload.selfFetch` entry
+ * for the iframe to act on, with no I/O and no store involved.
+ */
+function buildSelfFetchRef(tool, params) {
+    const data = Buffer.from(JSON.stringify(params), 'utf8').toString('base64url');
+    return `${SELF_FETCH_URI_PREFIX}${tool}?data=${data}`;
+}
+function isSelfFetchRef(uri) {
+    return uri.startsWith(SELF_FETCH_URI_PREFIX);
+}
+/**
+ * Unwrap a `mapbox://selffetch/...` ref back into a minimal `MapAppPayload`
+ * carrying only a `selfFetch` entry — no layers/markers of its own. The
+ * iframe resolves the actual geometry client-side after the initial render
+ * (see the `selffetch` handling in `mapAppHtml.ts`). Returns null if the ref
+ * isn't a self-fetch ref, names an unrecognized tool, or its data doesn't
+ * decode.
+ */
+function resolveSelfFetchRef(uri) {
+    if (!isSelfFetchRef(uri))
+        return null;
+    let tool;
+    let encoded;
+    try {
+        const parsed = new URL(uri);
+        tool = parsed.pathname.replace(/^\//, '');
+        encoded = parsed.searchParams.get('data');
+    }
+    catch {
+        return null;
+    }
+    if (!encoded)
+        return null;
+    if (!SELF_FETCH_TOOLS.includes(tool))
+        return null;
+    let params;
+    try {
+        params = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!params || typeof params !== 'object')
+        return null;
+    return {
+        layers: [],
+        selfFetch: [{ tool: tool, params }]
+    };
+}
+//# sourceMappingURL=selfFetchRef.js.map

package/dist/commonjs/utils/selfFetchRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfFetchRef.js","sourceRoot":"","sources":["../../../src/utils/selfFetchRef.ts"],"names":[],"mappings":";AAAA,6BAA6B;AAC7B,kCAAkC;;AA6BlC,8CAQC;AAED,wCAEC;AAUD,kDA2BC;AA1ED,MAAM,qBAAqB,GAAG,qBAAqB,CAAC;AAIpD,MAAM,gBAAgB,GAA6B;IACjD,YAAY;IACZ,WAAW;IACX,cAAc;IACd,QAAQ;IACR,iBAAiB;IACjB,cAAc;IACd,iBAAiB;CAClB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,SAAgB,iBAAiB,CAC/B,IAAmB,EACnB,MAA+B;IAE/B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,QAAQ,CAC/D,WAAW,CACZ,CAAC;IACF,OAAO,GAAG,qBAAqB,GAAG,IAAI,SAAS,IAAI,EAAE,CAAC;AACxD,CAAC;AAED,SAAgB,cAAc,CAAC,GAAW;IACxC,OAAO,GAAG,CAAC,UAAU,CAAC,qBAAqB,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,mBAAmB,CAAC,GAAW;IAC7C,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,IAAI,IAAY,CAAC;IACjB,IAAI,OAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1C,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAqB,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnE,IAAI,MAA+B,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEvD,OAAO;QACL,MAAM,EAAE,EAAE;QACV,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,IAAqB,EAAE,MAAM,EAAE,CAAC;KACrD,CAAC;AACJ,CAAC"}

package/dist/commonjs/utils/storeMapPayload.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import type { MapAppPayload } from './mapAppPayload.js';
+export declare const MAX_INLINE_PAYLOAD_BYTES: number;
+/**
+ * Schema for the `mapboxRender` field that data tools attach to their
+ * structuredContent. Each tool declares this on its output schema so
+ * Claude Desktop (and any other host that strictly validates tool results
+ * against the published output schema) doesn't flag the response.
+ */
+export declare const MapAppRefSchema: z.ZodObject<{
+    ref: z.ZodString;
+}, z.core.$strip>;
+export type MapAppRef = z.infer<typeof MapAppRefSchema>;
+/**
+ * Stash a `MapAppPayload` server-side and return a short reference the LLM
+ * can pass to `render_map_tool` instead of inlining the whole payload as
+ * tool-call arguments. With detailed geometry (a directions polyline can
+ * easily be 5–50 KB), having the LLM emit the payload token-by-token costs
+ * 20–30 seconds per render and risks Anthropic API timeouts on big
+ * payloads (e.g. polygon-op chains). Passing a ref instead keeps the LLM's
+ * emission down to a few tokens.
+ *
+ * `owner` must be the same account identifier (`getUserNameFromToken`) the
+ * caller resolves for its own token — `TemporaryDataResource.read()` fails
+ * closed on an unowned resource, so omitting this makes the ref permanently
+ * unreadable via the real `resources/read` path the render iframe uses (it
+ * always 404s), even though callers that read the manager directly (like
+ * `resolveMapPayloadRef`) wouldn't notice anything wrong.
+ */
+export declare function storeMapPayload(payload: MapAppPayload, owner?: string): string;
+/**
+ * Build the `mapboxRender` field for `render_map_tool`'s own structuredContent
+ * - the one tool result the iframe actually reads. Includes the resolved
+ * payload inline (in addition to `ref`) when it's small enough, because
+ * ChatGPT's MCP Apps bridge delivers `structuredContent` to the iframe intact
+ * but has no `resources/read` equivalent at all - the ref alone is
+ * permanently unusable there. Claude Desktop strips `structuredContent`
+ * before it reaches the iframe, so it's unaffected either way and keeps
+ * using the ref (via the sentinel-tagged text) + `resources/read`.
+ *
+ * Only `render_map_tool` needs this: it's the only tool that declares
+ * `_meta.ui.resourceUri`, so it's the only tool result the iframe ever sees.
+ */
+export declare function buildMapboxRenderField(ref: string, payload: MapAppPayload): {
+    ref: string;
+} & Partial<MapAppPayload>;
+/**
+ * One-line render hint that data tools append to their text output. Tells the
+ * LLM the EXACT shape of the next call so it doesn't hallucinate a ref URI.
+ * (Seen in the wild: Sonnet inventing `mapbox-isochrone-tool-result://0` when
+ * only structuredContent.mapboxRender.ref had the real `mapbox://temp/map-payload-…`
+ * URI — including the literal string in the visible text fixes that.)
+ */
+export declare function renderHint(ref: string): string;
+/**
+ * Resolve a `mapbox://temp/map-payload-...` ref back to its `MapAppPayload`.
+ * Returns null if the ref is unknown, expired, or owned by a different
+ * account than `owner` — this is the same account-scoping enforced by
+ * `TemporaryDataResource.read()` (a caller passing another account's ref
+ * would otherwise have it silently merged and re-served under their own
+ * ref, bypassing the read-side check entirely since this goes straight to
+ * the manager rather than through `resources/read`).
+ */
+export declare function resolveMapPayloadRef(ref: string, owner: string | undefined): MapAppPayload | null;
+/**
+ * Merge multiple `MapAppPayload`s into one. Layer/marker IDs are
+ * deduplicated by appending an index suffix when collisions happen.
+ * Summaries are joined with " · ". Legends are concatenated.
+ */
+export declare function mergeMapPayloads(payloads: MapAppPayload[]): MapAppPayload;
+//# sourceMappingURL=storeMapPayload.d.ts.map

package/dist/commonjs/utils/storeMapPayload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storeMapPayload.d.ts","sourceRoot":"","sources":["../../../src/utils/storeMapPayload.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMxD,eAAO,MAAM,wBAAwB,QAAY,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;iBAUzB,CAAC;AAEJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAIxD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,aAAa,EACtB,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAcR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,aAAa,GACrB;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAM1C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,aAAa,GAAG,IAAI,CAMtB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,aAAa,CA8BzE"}