feat: directions_tool renders as a live GL JS map (MCP Apps + MCP-UI)

CHANGELOG.md

@@ -18,6 +18,13 @@
 
 ### New Features
 
+- **`directions_tool` now renders as a live Mapbox GL JS map** for both the MCP Apps spec and legacy MCP-UI clients:
+  - **MCP Apps**: the tool declares `_meta.ui.resourceUri` pointing to a new `DirectionsAppUIResource` (`ui://mapbox/directions-app/index.html`). MCP App–capable hosts (Claude Desktop, VS Code, Cursor) render the route via postMessage handoff.
+  - **MCP-UI**: when `geometries=geojson` is requested and the response carries a renderable LineString, an inline `rawHtml` UIResource is added to the tool's `content[]` (gated by the existing `ENABLE_MCP_UI`/`--disable-mcp-ui` flag, like `static_map_image_tool`).
+  - **One source of truth**: both pathways render the same HTML produced by `renderDirectionsAppHtml` — for MCP Apps the resource serves a generic version and the iframe receives the tool result via postMessage; for MCP-UI the tool bakes the route geometry into the HTML before returning. No more "GL JS map for one client, static image for the other."
+  - **Public token**: resolved server-side via `GET /tokens/v2/{user}?default=true` (requires `tokens:read` on the `sk.*` token) with `MAPBOX_PUBLIC_TOKEN` env var fallback. Non-MCP-App hosts that also have MCP-UI disabled ignore both UI hints and consume the existing text/structuredContent payload unchanged.
+  - **Graceful degradation**: responses without renderable geometry (>50KB temporary-resource path, `geometries=none`, `geometries=polyline*`) skip the inline rawHtml block and show a "no geometry to render" message in the MCP App iframe.
+  - **CSP**: `_meta.ui.csp.workerDomains: ['blob:']` so MCP App hosts grant Mapbox GL JS the iframe sandbox permissions it needs.
 - **MCP Completions capability**: Add auto-completion support for prompt arguments per MCP spec (2025-11-25). Clients can now suggest values when users fill in prompt parameters (#176)
   - `category` argument on `find-places-nearby` — 482 Mapbox Search API categories
   - `mode` argument on `get-directions`, `search-along-route`, `show-reachable-areas` — driving, driving-traffic, walking, cycling

docs/importing-tools.md

@@ -116,7 +116,7 @@ import {
   centroid,
   distance,
   midpoint,
-  pointInPolygon,
+  pointsWithinPolygon,
   simplify,
 
   // API tools (HTTP pre-configured)
@@ -149,7 +149,7 @@ import {
   CentroidTool,
   DistanceTool,
   MidpointTool,
-  PointInPolygonTool,
+  PointsWithinPolygonTool,
   SimplifyTool,
 
   // API tools

src/resources/resourceRegistry.ts

@@ -5,6 +5,7 @@
 import { CategoryListResource } from './category-list/CategoryListResource.js';
 import { TemporaryDataResource } from './temporary/TemporaryDataResource.js';
 import { StaticMapUIResource } from './ui-apps/StaticMapUIResource.js';
+import { DirectionsAppUIResource } from './ui-apps/DirectionsAppUIResource.js';
 import { VersionResource } from './version/VersionResource.js';
 import { httpRequest } from '../utils/httpPipeline.js';
 
@@ -14,6 +15,7 @@ export const ALL_RESOURCES = [
   new CategoryListResource({ httpRequest }),
   new TemporaryDataResource(),
   new StaticMapUIResource(),
+  new DirectionsAppUIResource({ httpRequest }),
   new VersionResource()
 ] as const;
 

src/resources/ui-apps/DirectionsAppUIResource.ts

@@ -0,0 +1,89 @@
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type {
+  ReadResourceResult,
+  ServerNotification,
+  ServerRequest
+} from '@modelcontextprotocol/sdk/types.js';
+import { RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
+import { BaseResource } from '../BaseResource.js';
+import type { HttpRequest } from '../../utils/types.js';
+import { resolveMapboxPublicToken } from '../../utils/mapboxPublicToken.js';
+import { renderDirectionsAppHtml } from './directionsAppHtml.js';
+
+/**
+ * MCP Apps resource for `directions_tool` — serves the HTML at
+ * `ui://mapbox/directions-app/index.html`. The iframe waits for the host to
+ * deliver the tool result via the `ui/notifications/tool-result` postMessage
+ * event and renders the route from `structuredContent.routes[0]`.
+ *
+ * The legacy MCP-UI pathway (inline `rawHtml` on the tool result) uses the
+ * same HTML template via `renderDirectionsAppHtml` with geometry baked in at
+ * tool-execute time.
+ */
+export class DirectionsAppUIResource extends BaseResource {
+  readonly name = 'Directions App UI';
+  readonly uri = 'ui://mapbox/directions-app/index.html';
+  readonly description =
+    'Interactive UI for visualizing a Mapbox directions route with Mapbox GL JS (MCP Apps)';
+  readonly mimeType = RESOURCE_MIME_TYPE;
+
+  private readonly httpRequest: HttpRequest;
+  private readonly apiEndpoint: () => string;
+
+  constructor(params: {
+    httpRequest: HttpRequest;
+    apiEndpoint?: () => string;
+  }) {
+    super();
+    this.httpRequest = params.httpRequest;
+    this.apiEndpoint =
+      params.apiEndpoint ??
+      (() => process.env.MAPBOX_API_ENDPOINT || 'https://api.mapbox.com/');
+  }
+
+  async read(
+    _uri: string,
+    extra?: RequestHandlerExtra<ServerRequest, ServerNotification>
+  ): Promise<ReadResourceResult> {
+    const accessToken =
+      (extra?.authInfo?.token as string | undefined) ||
+      process.env.MAPBOX_ACCESS_TOKEN ||
+      '';
+
+    const publicToken = await resolveMapboxPublicToken({
+      accessToken,
+      apiEndpoint: this.apiEndpoint(),
+      httpRequest: this.httpRequest
+    });
+
+    const html = renderDirectionsAppHtml({
+      publicToken: publicToken ?? ''
+    });
+
+    return {
+      contents: [
+        {
+          uri: this.uri,
+          mimeType: RESOURCE_MIME_TYPE,
+          text: html,
+          _meta: {
+            ui: {
+              csp: {
+                connectDomains: [
+                  'https://*.mapbox.com',
+                  'https://events.mapbox.com'
+                ],
+                resourceDomains: ['https://api.mapbox.com'],
+                workerDomains: ['blob:']
+              },
+              preferredSize: { width: 1000, height: 600 }
+            }
+          }
+        }
+      ]
+    };
+  }
+}