feat!: move to MCP TypeScript SDK v2

CHANGELOG.md

@@ -18,6 +18,15 @@
 
 ### Breaking Changes
 
+- **MCP TypeScript SDK v2 (#142, same move as mapbox/mcp-server#296).** The server and the `@mapbox/mcp-devkit-server/tools`, `/resources` and `/prompts` exports now use the v2 SDK packages (`@modelcontextprotocol/server` and `@modelcontextprotocol/core`, 2.3.1) instead of `@modelcontextprotocol/sdk` 1.x, and `@modelcontextprotocol/ext-apps` moves from 1.x to 2.0.3. v2 is where new MCP features land.
+  - **For code that imports our tools:** `installTo(server)` needs a v2 `McpServer`; a v1 server from `@modelcontextprotocol/sdk` won't work. The hosted server builds its own server, so it has to move to v2 in the same release as this and mcp-server. Tool and resource handlers now get the v2 context, so the access token is at `ctx.http.authInfo.token` instead of `extra.authInfo.token`.
+  - **Clients:** nothing changes. It still negotiates 2025-11-25 with current clients, and the MCP Apps wire protocol is the same in ext-apps 2.x, so the preview and comparison UIs work as before.
+  - **No more SDK patch:** the v1 SDK was patched so a tool's `structuredContent` that didn't match its output schema, or was missing, logged a warning instead of failing the call. v2 takes any Standard Schema as an output schema, so `lenientOutputSchema` wraps each tool's Zod schema: `tools/list` publishes the real JSON Schema (now 2020-12, from v2) and validation only warns. A tool with an output schema that returns only text gets `structuredContent: {}` instead of an error. `patches/` is now empty.
+  - **Prompts:** argument schemas are registered as a `z.object(...)`, since v2 deprecates raw Zod shapes there.
+  - **Codemod:** most of the change is `npx @modelcontextprotocol/codemod v1-to-v2 .` (import paths, `RequestHandlerExtra` to `ServerContext`, `extra.authInfo` to `ctx.http?.authInfo`). `@modelcontextprotocol/client` is a dev dependency, used only by tests.
+  - **Still on v1 transitively:** `@mcp-ui/server` (6.1.0, the latest) depends on `@modelcontextprotocol/sdk` 1.x, so a copy stays in `node_modules`. We only call its `createUIResource()`, which builds a plain content object, so nothing crosses between the two SDKs.
+  - **Testing:** new tests make a real `tools/call` through `McpServer` for mismatched, missing and matching `structuredContent`, and fail without the wrapper. Tests that built a request context by hand used the v1 `{ authInfo }` shape, so the token never reached the code under test (including the path-traversal checks on usernames from the token and the map preview's token checks); they now use `{ http: { authInfo } }`.
+
 - **Consolidated `GeojsonPreviewUIResource` and `PreviewStyleUIResource` into a single `MapPreviewUIResource`.** Both were near-identical hand-written MCP Apps templates — the same postMessage handshake, fullscreen/open-link controls, and resize handling copy-pasted across ~650 lines, differing only in what they drew on the map once a tool result arrived (a GeoJSON overlay on the default Standard style vs. swapping to an arbitrary preview style). `geojson_preview_tool` and `preview_style_tool` now both declare `_meta.ui.resourceUri: 'ui://mapbox/map-preview/index.html'`, served by the merged resource, which dispatches on the shape of the tool-result URL it receives (a `geojson.io` URL vs. a Styles API `.html?access_token=...` preview URL) rather than assuming a fixed mode. Neither tool's own input/output contract changed.
   - The public resource exports change: `previewStyleUI`/`geojsonPreviewUI` (from `@mapbox/mcp-devkit-server/resources`) are replaced by a single `mapPreviewUI`. `GeojsonPreviewUIResource`/`PreviewStyleUIResource` class exports are removed in favor of `MapPreviewUIResource`.
   - `style_comparison_tool`'s `StyleComparisonUIResource` is untouched and stays separate — it renders two synced `mapboxgl.Map` instances under a swipe/compare slider, a genuinely different UI shape from "one map, different content," not just another mode to fold in.

CLAUDE.md

@@ -33,7 +33,7 @@ The codebase organizes into:
 
 **Resource System:** Static reference data exposed as MCP resources using URI pattern `resource://mapbox-*`, including style layer specs, Streets v8 field definitions, and token scope documentation.
 
-**Token Management:** Tools receive `MAPBOX_ACCESS_TOKEN` via `extra.authInfo.token` or environment variable. Token scope validation is critical—most tool failures stem from insufficient scopes (see `README.md` for per-tool requirements).
+**Token Management:** Tools receive `MAPBOX_ACCESS_TOKEN` via `ctx.http.authInfo.token` (SDK v2 `ServerContext`) or environment variable. Token scope validation is critical—most tool failures stem from insufficient scopes (see `README.md` for per-tool requirements).
 
 **Tool Registry:** Tools are auto-discovered via `src/tools/toolRegistry.ts` exports. No manual registration required—just export from registry.
 

docs/engineering_standards.md

@@ -72,7 +72,7 @@ This approach supports dependency injection and maintains testability. See `src/
 
 All Mapbox API tools require `MAPBOX_ACCESS_TOKEN` with specific scopes:
 
-- Tools receive tokens via `extra.authInfo.token` or `process.env.MAPBOX_ACCESS_TOKEN`
+- Tools receive tokens via `ctx.http.authInfo.token` or `process.env.MAPBOX_ACCESS_TOKEN`
 - Document required scopes in `README.md` for each tool
 - Token scope mismatches are the primary failure mode
 - Use `VERBOSE_ERRORS=true` for debugging authentication issues

package.json

@@ -51,8 +51,9 @@
   "dependencies": {
     "@mapbox/mapbox-gl-style-spec": "^14.26.0",
     "@mcp-ui/server": "^6.1.0",
-    "@modelcontextprotocol/ext-apps": "^1.1.1",
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/core": "^2.3.1",
+    "@modelcontextprotocol/ext-apps": "^2.0.3",
+    "@modelcontextprotocol/server": "^2.3.1",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/auto-instrumentations-node": "^0.74.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.216.0",
@@ -65,6 +66,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.27.0",
+    "@modelcontextprotocol/client": "^2.3.1",
     "@types/geojson": "^7946.0.16",
     "@types/node": "^22.0.0",
     "@typescript-eslint/eslint-plugin": "^8.58.2",