mapbox / mapbox/mcp-docs-server

Track migration to MCP spec 2026-07-28 (stateless model)

Open
#40 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
1
Forks
1
Avg merge
9h 5m
Merged PRs (30d)
2

Description

## Summary

The MCP spec released a new revision on 2026-07-28 (announced at https://blog.modelcontextprotocol.io/posts/2026-07-28/) that moves from the stateful bidirectional protocol to a stateless request/response model — eliminating the `initialize`/`initialized` handshake and session IDs, replacing server-initiated elicitation with "Multi Round-Trip Requests" (MRTR), and deprecating Sampling, Roots, and Logging (12-month minimum deprecation window).

As of this issue, `@modelcontextprotocol/sdk` on npm is still on the `1.x` line (`1.30.0` latest) — no separate `2.0.0` package exists. The spec appears to be supported via 1.x releases.

## Why this is lower-priority here than in the other Mapbox MCP servers

Verified (`grep -rn "elicitInput\|createMessage" src/`): this repo uses **neither elicitation nor sampling** anywhere. Unlike `mcp-server` (mapbox/mcp-server#245) and `mcp-devkit-server` (mapbox/mcp-devkit-server#130), there's no elicitation-based or sampling-based UX here that the spec's deprecations would force a redesign of. The remaining relevant surface is just the stateless request/response transport model itself.

## What to check before starting

- [ ] Confirm real client support for the new stateless model (Claude Desktop, Claude Code, VS Code Copilot).
- [ ] Read the SDK's actual migration guide for the TypeScript SDK version(s) implementing 2026-07-28 support.
- [ ] Check whether anything in this server's transport/session handling assumes the old stateful handshake.

## Non-goals for now

- No urgency given the 12-month deprecation window.
- The routine SDK dependency bump (`1.29.0` → `1.30.0`) is handled separately and does not itself adopt the new spec — see the corresponding PR.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by inspecting the transport and session-handling code under src/ and confirm the current SDK version and migration guidance for the 2026-07-28 specification. Check real client support and whether the server assumes the stateful handshake; done means the required migration scope is identified and any necessary transport changes are completed or clearly documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, backend
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.