Repository navigation
chore(mcp): upgrade MCP SDK to 1.30.0 with coherent dependency graph - #6086
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughChangesDependency, documentation, and build updates
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🧹 Preview Cleanup CompleteThe following preview resources have been cleaned up:
Thank you for your contribution! 🎉 |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 5 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="package.json">
<violation number="1" location="package.json:66">
P2: The new `overrides: { zod: 4.3.6 }` entry applies globally to every `zod` resolution in the tree, not just `@modelcontextprotocol/sdk`. The lockfile contains several transitive consumers that only support zod v3 — `@langchain/core` (`"zod": "^3.25.32"`), `@langchain/openai` (`"zod": "^3.22.4"`), `@expo/mcp-tunnel` (`"zod": "^3.25.76"`), and `@ai-sdk/ui-utils-v5` (peer `"zod": "^3.23.8"`). With a global override these all get coerced to v4.3.6, which is outside their declared ranges and can surface as runtime breaks in code paths that rely on v3 zod APIs. The override only needed to pin the SDK's own `zod` copy to restore schema type identity, but as written it is broader than necessary. Worth a quick typecheck/install verification that the v3-only transitive consumers still behave correctly with zod forced to 4.3.6 (and, if any break, scoping the override or pinning those packages to a v3-compatible zod instead).</violation>
</file>
Architecture diagram
sequenceDiagram
participant Client as MCP Client (Claude)
participant DocsRoute as Docs MCP Route
participant MCPPackage as MCP Package
participant SDK as @modelcontextprotocol/sdk 1.30.0
participant Zod as zod 4.3.6
participant ServerCard as Server-Card Route
participant InMemory as InMemoryTransport
Note over Client,InMemory: Runtime Architecture after SDK bump + zod override
Client->>DocsRoute: HTTP /mcp request
DocsRoute->>SDK: Initialize MCP server
SDK->>Zod: CHANGED: Uses overridden 4.3.6 (single instance)
Zod-->>SDK: Schema type identity preserved
SDK-->>DocsRoute: Server instance
alt Server-Card Route (/.well-known/mcp/server-card.json)
ServerCard->>MCPPackage: Instantiate real server
MCPPackage->>SDK: Create server with tools
ServerCard->>InMemory: Create transport pair
InMemory->>SDK: Connect server over in-memory
ServerCard->>SDK: Send tools/list request
SDK->>MCPPackage: List registered tools
MCPPackage-->>SDK: Tool definitions
SDK-->>ServerCard: tools/list response
ServerCard-->>Client: JSON server card
else Direct MCP Connection
Client->>SDK: claude mcp add --transport http <preview>/mcp
SDK->>SDK: NEW: ToolTaskHandler available for Phase 5
Note over SDK: Tasks support unlocked (tool handler)
alt List results caching (future A2)
SDK-->>Client: No ttlMs/cacheScope yet (requires later SDK)
end
end
Note over Client,InMemory: Key: single zod instance across all consumers prevents type mismatch in docs route
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| "rollup": "4.62.3", | ||
| "shell-quote": "1.9.0" | ||
| "shell-quote": "1.9.0", | ||
| "zod": "4.3.6" |
There was a problem hiding this comment.
P2: The new overrides: { zod: 4.3.6 } entry applies globally to every zod resolution in the tree, not just @modelcontextprotocol/sdk. The lockfile contains several transitive consumers that only support zod v3 — @langchain/core ("zod": "^3.25.32"), @langchain/openai ("zod": "^3.22.4"), @expo/mcp-tunnel ("zod": "^3.25.76"), and @ai-sdk/ui-utils-v5 (peer "zod": "^3.23.8"). With a global override these all get coerced to v4.3.6, which is outside their declared ranges and can surface as runtime breaks in code paths that rely on v3 zod APIs. The override only needed to pin the SDK's own zod copy to restore schema type identity, but as written it is broader than necessary. Worth a quick typecheck/install verification that the v3-only transitive consumers still behave correctly with zod forced to 4.3.6 (and, if any break, scoping the override or pinning those packages to a v3-compatible zod instead).
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At package.json, line 66:
<comment>The new `overrides: { zod: 4.3.6 }` entry applies globally to every `zod` resolution in the tree, not just `@modelcontextprotocol/sdk`. The lockfile contains several transitive consumers that only support zod v3 — `@langchain/core` (`"zod": "^3.25.32"`), `@langchain/openai` (`"zod": "^3.22.4"`), `@expo/mcp-tunnel` (`"zod": "^3.25.76"`), and `@ai-sdk/ui-utils-v5` (peer `"zod": "^3.23.8"`). With a global override these all get coerced to v4.3.6, which is outside their declared ranges and can surface as runtime breaks in code paths that rely on v3 zod APIs. The override only needed to pin the SDK's own `zod` copy to restore schema type identity, but as written it is broader than necessary. Worth a quick typecheck/install verification that the v3-only transitive consumers still behave correctly with zod forced to 4.3.6 (and, if any break, scoping the override or pinning those packages to a v3-compatible zod instead).</comment>
<file context>
@@ -62,7 +62,8 @@
"rollup": "4.62.3",
- "shell-quote": "1.9.0"
+ "shell-quote": "1.9.0",
+ "zod": "4.3.6"
},
"trustedDependencies": [
</file context>
f86262b to
e10143e
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
packages/mcp/src/define-tool.ts (1)
106-114: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick winPreserve the MCP SDK registration contract across both compatibility bridges.
Both adapters solve the Zod type-identity problem by erasing the
registerToolcontract. Keep the casts narrow, preserve schema-handler type linkage, and verify runtime schema generation and invalid-input rejection.
packages/mcp/src/define-tool.ts#L106-L114: replace the whole-configas nevercast with a narrow compatibility wrapper.apps/docs/src/app/mcp/route.ts#L17-L27: derive callback arguments from the local schema instead of using broadRecord<string, unknown>andany.apps/docs/src/app/mcp/route.ts#L36-L40: preserve SDK checks outside the unavoidable Zod boundary.As per coding guidelines, avoid
anyunless it is necessary; keep the bridge limited to the smallest unavoidable boundary.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/mcp/src/define-tool.ts` around lines 106 - 114, Preserve the MCP SDK registration contract across both adapters: in packages/mcp/src/define-tool.ts lines 106-114, replace the whole-config as never cast with the narrowest compatibility wrapper while retaining input/output schema-handler type linkage; in apps/docs/src/app/mcp/route.ts lines 17-27, derive callback arguments from the local schema instead of broad Record<string, unknown> and any; and in lines 36-40, keep SDK validation checks outside the unavoidable Zod compatibility boundary. Verify runtime schema generation and invalid-input rejection remain enforced.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@packages/mcp/src/define-tool.ts`:
- Around line 106-114: Preserve the MCP SDK registration contract across both
adapters: in packages/mcp/src/define-tool.ts lines 106-114, replace the
whole-config as never cast with the narrowest compatibility wrapper while
retaining input/output schema-handler type linkage; in
apps/docs/src/app/mcp/route.ts lines 17-27, derive callback arguments from the
local schema instead of broad Record<string, unknown> and any; and in lines
36-40, keep SDK validation checks outside the unavoidable Zod compatibility
boundary. Verify runtime schema generation and invalid-input rejection remain
enforced.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: f7a3fc51-01a6-4382-b62e-b2a0b10f268e
⛔ Files ignored due to path filters (1)
bun.lockis excluded by!**/*.lock
📒 Files selected for processing (5)
apps/api/package.jsonapps/docs/package.jsonapps/docs/src/app/mcp/route.tspackages/mcp/package.jsonpackages/mcp/src/define-tool.ts
🚧 Files skipped from review as they are similar to previous changes (3)
- packages/mcp/package.json
- apps/api/package.json
- apps/docs/package.json
SDK 1.28.0 -> 1.30.0 across packages/mcp, apps/api, apps/docs. The SDK's zod peer forced confronting a latent graph problem: bun creates one store copy per peer-resolution context, and nominally-typed packages (#private classes, branded schemas) cannot span copies, so a partial zod migration is structurally impossible. This lands the coherent graph instead: zod 4.4.3 workspace-wide, fumadocs 16.13.0 / fumadocs-mdx 15.2.0 (old versions break typegen under zod 4.4; forked docs layout components migrated off removed internals), ai 6.0.235 (exact 6.0.141 pins violated the Mastra chain's ^6.0.176, splitting @mastra/core and breaking host-service declaration emit), a @types/hast 3.0.5 override (shiki vs hast-util split), and a regenerated lockfile. No casts, no overrides beyond @types/hast, no Mastra version changes. Claude-Session: https://claude.ai/code/session_01Kub4p3Eim9pc1qaRRmGea2
e10143e to
6cd761d
Compare
saddlepaddle
changed the title
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
packages/mcp/docs/ROADMAP.md (1)
64-64: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick winClarify the pagination contract.
MCP list operations use opaque
cursorandnextCursorvalues. Clients must not assume numbered pages or fixed page sizes. Iflimit/offsetapplies only to custom tool arguments, state that explicitly. Otherwise use MCP cursor pagination. (modelcontextprotocol.io)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/mcp/docs/ROADMAP.md` at line 64, Clarify the pagination contract in the roadmap entry mentioning uniform limit/offset pagination: state that MCP list operations use opaque cursor and nextCursor values without numbered-page or fixed-size assumptions, and specify whether limit/offset is restricted to custom tool arguments; otherwise describe the operations using MCP cursor pagination.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/mcp/docs/ROADMAP.md`:
- Around line 69-76: The roadmap table’s tool count does not match its “target
~24” claim. Update the target count in the table header to reflect the 27 listed
tools, or remove three tool entries so the table totals approximately 24 before
the parity manifest is generated.
- Around line 62-64: Update the migration plan’s sequencing to explicitly
include the superset://guide resource: register it, advertise resource
capability, authorize access, and cover resources/read handling. If this
resource is not part of the intended target contract, remove its reference from
the Principles statement instead.
- Around line 85-86: Define the compatibility behavior for removed tool names at
the REGISTRARS registration/dispatch boundary: add stubs or alias routing that
returns a descriptive “use X instead” error instead of the default unknown-tool
response, and explicitly document whether these legacy names remain in
tools/list.
- Around line 12-18: Update the roadmap references around ToolTaskHandler and
the affected task entries to describe the 2026 Tasks extension using standard
extension negotiation and its tasks/get, tasks/update, and tasks/cancel methods.
Remove legacy ToolTaskHandler framing, and keep tasks_list explicitly mapped as
a named tool separate from the io.modelcontextprotocol/tasks capability contract
across all referenced sections.
- Around line 28-34: Update the SDK v2 roadmap entry to remove the “mostly
mechanical” characterization and state explicit migration gates: retain the
stateless transport requirement, add per-request metadata/state handling, adopt
standard routing and discovery behavior, and migrate to the stable SDK
entrypoint. Keep the migration scheduled after the toolset rework.
---
Nitpick comments:
In `@packages/mcp/docs/ROADMAP.md`:
- Line 64: Clarify the pagination contract in the roadmap entry mentioning
uniform limit/offset pagination: state that MCP list operations use opaque
cursor and nextCursor values without numbered-page or fixed-size assumptions,
and specify whether limit/offset is restricted to custom tool arguments;
otherwise describe the operations using MCP cursor pagination.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: ad305ed9-1116-4876-9437-a4d5b6b14e29
📒 Files selected for processing (1)
packages/mcp/docs/ROADMAP.md
| - **Tasks extension** (`io.modelcontextprotocol/tasks`) — `ToolTaskHandler` | ||
| ships in 1.30. This is the centerpiece for agent ergonomics: `agents_run` | ||
| and `automations_run` return a task handle; clients drive `tasks/get` for | ||
| status + transcript and `tasks/update` for follow-up input. Replaces | ||
| polling `terminals_read` to follow an agent. Server-side only until major | ||
| clients declare the capability at initialize; keep synchronous shapes as | ||
| the fallback path. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== locate ROADMAP =="
fd -a 'ROADMAP.md' . || true
echo "== relevant file excerpt =="
if [ -f packages/mcp/docs/ROADMAP.md ]; then
nl -ba packages/mcp/docs/ROADMAP.md | sed -n '1,110p'
fi
echo "== task-related identifiers in repo =="
rg -n "ToolTaskHandler|registerToolTask|tasks/get|tasks/update|tasks/cancel|tasks_list|capabilities|Tasks extension|io\.modelcontextprotocol/tasks|tasks" -S . --glob '!node_modules' --glob '!dist' --glob '!build' | head -n 200Repository: superset-sh/superset
Length of output: 295
🌐 Web query:
ts.sdk.modelcontextprotocol.io v2 migration ToolTaskHandler registerToolTask removed tasks cancel get update capabilities
💡 Result:
In the Model Context Protocol (MCP) TypeScript SDK v2, the registerToolTask method and its associated ToolTaskHandler interface remain available as experimental features [1][2]. While there was a significant bug fix in v2 that ensured custom getTask and getTaskResult handlers are correctly invoked [3], these methods were not removed, but their signatures were updated [3]. Key points regarding the v2 migration and registerToolTask: 1. Handler Signature Changes: A breaking change occurred where the args parameter is no longer passed to getTask or getTaskResult handlers; these now only accept the extra argument [3]. Previously, these handlers were often bypassed or unused, but they are now correctly integrated into the task lifecycle [3]. 2. Migration Process: To upgrade from v1 to v2, you should use the provided codemod (npx @modelcontextprotocol/codemod@latest v1-to-v2 .) to handle mechanical renames [4][5][6]. However, because registerToolTask and other task-related features are experimental, you must manually review and adapt your implementation to accommodate API signature changes that the codemod cannot automate [5][6]. 3. Experimental Status: The tasks API is still marked as experimental [1][2]. Ensure you are following the latest SDK documentation and checking your specific project implementation, as experimental features can undergo changes without notice [2]. For complete guidance on the broader migration, refer to the official migration documentation, which details the architectural shifts between v1 and v2, including the transition to multiple packages (@modelcontextprotocol/client, @modelcontextprotocol/server, etc.) and support for newer protocol revisions [4][5][7].
Citations:
- 1: https://github.com/modelcontextprotocol/typescript-sdk/blob/327243ce/packages/server/src/experimental/tasks/mcpServer.ts
- 2: https://github.com/modelcontextprotocol/typescript-sdk/blob/2c0c481c/docs/server.md
- 3: [v2] Fix registerToolTask's getTask and getTaskResult handlers not being invoked modelcontextprotocol/typescript-sdk#1332
- 4: https://ts.sdk.modelcontextprotocol.io/v2/migration/upgrade-to-v2.html
- 5: https://ts.sdk.modelcontextprotocol.io/v2/migration/
- 6: https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/README.md
- 7: https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28.md
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== roadmap excerpt using awk =="
awk '{ printf "%5d\t%s\n", NR, $0 }' packages/mcp/docs/ROADMAP.md | sed -n '1,120p'
echo "== task-related identifiers in repo excerpt =="
rg -n "ToolTaskHandler|registerToolTask|tasks/get|tasks/update|tasks/cancel|tasks_list|capabilities|Tasks extension|io\.modelcontextprotocol/tasks|tasks" -S packages/mcp --glob '!node_modules' --glob '!dist' --glob '!build' | head -n 200
echo "== package/task dependency/version references =="
rg -n "`@modelcontextprotocol`|tool_context|tasks/get|tasks/update|tasks/cancel|ToolTaskHandler|registerToolTask" -S . --glob '!node_modules' --glob '!dist' --glob '!build' | head -n 200Repository: superset-sh/superset
Length of output: 22265
🌐 Web query:
2026 MCP tasks extension tasks/cancel tasks/get tasks/update capabilities initialize tasks_list
💡 Result:
As of August 2026, the Model Context Protocol (MCP) has moved the Tasks feature out of the core specification and into an official, opt-in extension [1][2]. The authoritative documentation and specification for this functionality are now maintained in the extension-specific repository and documentation site [3][4]. Key aspects of the 2026 Tasks extension (SEP-2663) include: Capabilities and Initialization The Tasks extension uses the standard MCP extension negotiation mechanism [3]. Rather than being a top-level capability in the core protocol, support is advertised via the extensions field in the capabilities object [3][2]. Servers advertise their support for io.modelcontextprotocol/tasks in the capabilities returned by server/discover, and clients signal their support in the clientCapabilities they include in request metadata (_meta) [3]. Core Operations The extension defines three primary methods for managing asynchronous, long-running operations: 1. tasks/get: Used by clients to poll for the status of a task, retrieve progress, or access final results [1][4]. This method consolidates the lifecycle management, replacing older approaches that required separate result-fetching methods [5]. 2. tasks/update: Used by clients to provide mid-flight input when a task transitions to an input_required status [1][4][5]. 3. tasks/cancel: Used by clients to signal an intent to cancel a task [1][4]. Task Lifecycle Tasks are server-directed: when a tool is called, the server decides on a per-request basis whether to materialize a task [1]. If it does, it returns a task handle rather than the final result, allowing the client to poll for completion asynchronously [3][1]. The extension also supports server-pushed updates via notifications (e.g., notifications/tasks) if the client has subscribed to them [4][5]. This design supersedes the previous implementation (from the 2025-11-25 specification) which treated tasks as core protocol utilities with top-level capability flags like tasks.list or tasks.cancel [1][6][7]. Implementers are advised to consult the current extension documentation for modern integration requirements [3][1].
Citations:
- 1: https://modelcontextprotocol.io/seps/2663-tasks-extension
- 2: https://modelcontextprotocol.io/specification/2026-07-28
- 3: https://modelcontextprotocol.io/extensions/tasks/overview
- 4: https://tasks.extensions.modelcontextprotocol.io/
- 5: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f61/seps/2663-tasks-extension.md
- 6: https://modelcontextprotocol.io/seps/1686-tasks
- 7: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks
Align the task roadmap with the MCP Tasks extension contract.
ToolTaskHandler is the legacy experimental task API, while the 2026 Tasks extension uses standard extension negotiation and defines tasks/get, tasks/update, and tasks/cancel. tasks_list is a named tool, not an extension method; keep that tool mapping separate from the io.modelcontextprotocol/tasks capability contract.
Also applies to: lines 72, 91-93
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/mcp/docs/ROADMAP.md` around lines 12 - 18, Update the roadmap
references around ToolTaskHandler and the affected task entries to describe the
2026 Tasks extension using standard extension negotiation and its tasks/get,
tasks/update, and tasks/cancel methods. Remove legacy ToolTaskHandler framing,
and keep tasks_list explicitly mapped as a named tool separate from the
io.modelcontextprotocol/tasks capability contract across all referenced
sections.
| - **SDK v2 (stateless core)** — beta only; migrate when a stable tag ships. | ||
| We are already stateless (no `sessionIdGenerator`), so the migration is | ||
| mostly mechanical: initialize handshake retired in favor of self-contained | ||
| requests (`_meta` carries version/identity/capabilities), optional | ||
| `server/discover`, and header-based routing (`Mcp-Method`/`Mcp-Name`) that | ||
| lets gateways rate-limit per tool without parsing bodies. Do this after | ||
| the toolset rework so the surface migrates once. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Repo files around ROADMAP:"
git ls-files | rg '(^|/)ROADMAP\.md$|packages/mcp|package\.json$' | head -200
echo
echo "Relevant ROADMAP lines:"
if [ -f packages/mcp/docs/ROADMAP.md ]; then
nl -ba packages/mcp/docs/ROADMAP.md | sed -n '1,120p'
fi
echo
echo "Search sessionIdGenerator and v2/migration references:"
rg -n "sessionIdGenerator|SDK v2|sdk-v2|2026|protocol-era|server/discover|Mcp-Method|Mcp-Name|_meta|migration" packages packages/mcp 2>/dev/null | head -300 || true
echo
echo "Package files:"
fd -a 'package\.json' packages 2>/dev/null | head -100Repository: superset-sh/superset
Length of output: 3014
🌐 Web query:
modelcontextprotocol typescript-sdk docs migration support 2026-07-28 sessionIdGenerator
💡 Result:
In the MCP TypeScript SDK v2, the sessionIdGenerator option is used to control session state for transports, specifically within the 2025-era protocol model [1][2]. With the release of the 2026-07-28 protocol revision, the architecture has shifted toward a stateless, per-request model [3][4][5]. Key points regarding sessionIdGenerator and the 2026-07-28 migration: 1. Protocol Shift: The 2026-07-28 revision is fundamentally stateless [3][4]. Unlike the 2025-era sessions that relied on Mcp-Session-Id headers and sessionIdGenerator to maintain long-lived state in memory, the 2026 revision operates per request [1][3][4]. 2. Role of sessionIdGenerator: - Stateful Mode (2025-era): If you provide a sessionIdGenerator (e.g., () => randomUUID()), the transport enters stateful mode [1][6][7]. It will generate a session ID, include it in response headers (Mcp-Session-Id), and reject requests that arrive without a valid session [1][6]. - Stateless Mode (2026-era default): If sessionIdGenerator is left undefined (or explicitly set to undefined), the transport operates in stateless mode [1][6][7]. This is the required configuration for the modern 2026-07-28 path [3][4]. 3. Migration to 2026-07-28: - Modern Handler: The new createMcpHandler entry point is designed for the 2026-07-28 revision and is stateless by default [3][4][8]. - Handling State: If your previous v1/v2 alpha server relied on session IDs to persist state, you should migrate to using requestState [3][4]. This allows the server to return an opaque string with inputRequired(...), which the client then echoes back on subsequent requests [3][4]. - Legacy Support: For applications needing to support both 2025-era and 2026-era clients, you can route requests in front of a strict entry point, using isLegacyRequest(request) to differentiate traffic [3][4]. For detailed implementation, refer to the official migration guide at docs/migration/support-2026-07-28.md in the SDK repository or the equivalent v2 documentation site [3][4][5].
Citations:
- 1: https://ts.sdk.modelcontextprotocol.io/v2/serving/sessions-state-scaling.html
- 2: https://ts.sdk.modelcontextprotocol.io/v2/interfaces/_modelcontextprotocol_server.server_streamableHttp.WebStandardStreamableHTTPServerTransportOptions.html
- 3: https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration/support-2026-07-28.md
- 4: https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28.md
- 5: https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28
- 6: https://ts.sdk.modelcontextprotocol.io/v2/classes/_modelcontextprotocol_node.streamableHttp.NodeStreamableHTTPServerTransport.html
- 7: https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md
- 8: https://blog.modelcontextprotocol.io/posts/sdk-betas-2026-07-28/
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "packages/mcp/docs/ROADMAP.md first 140 lines:"
awk '{printf "%4d %s\n", NR, $0}' packages/mcp/docs/ROADMAP.md | sed -n '1,140p'
echo
echo "packages/mcp source: outline and key symbols:"
for f in packages/mcp/src/*.ts; do
echo "--- $f"
wc -l "$f"
rg -n "sessionIdGenerator|createMcpHandler|createServer|ServerTransport|HTTP|Mcp-|discover|_meta|requestState|legacy|createHandler|version" "$f" || true
done
echo
echo "packages/mcp package metadata:"
python3 - <<'PY'
import json
from pathlib import Path
p = Path('packages/mcp/package.json')
data = json.loads(p.read_text())
for k in ['name','version','main','module','exports','dependencies','peerDependencies','scripts']:
if k in data:
print(f'{k}: {data[k]}')
PY
echo
echo "Search all tracked files for MCP SDK migration docs/references:"
rg -n "support-2026-07-28|isLegacyRequest|createMcpHandler|requestState|webStandardStreamableHttp|SdkV2|SDK v2|sessionIdGenerator|Mcp-Method|Mcp-Name|_meta|server/discover" . --glob '!node_modules' --glob '!dist' --glob '!build' | head -400 || trueRepository: superset-sh/superset
Length of output: 27140
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "apps/api/src/app/mcp/route.ts:"
awk '{printf "%4d %s\n", NR, $0}' apps/api/src/app/mcp/route.ts | sed -n '1,240p'
echo
echo "apps/docs/src/app/mcp/route.ts:"
awk '{printf "%4d %s\n", NR, $0}' apps/docs/src/app/mcp/route.ts | sed -n '1,240p'
echo
echo "packages/mcp/src/server.ts:"
awk '{printf "%4d %s\n", NR, $0}' packages/mcp/src/server.ts | sed -n '1,220p'
echo
echo "packages/mcp/src/in-memory.ts relevant:"
awk '{printf "%4d %s\n", NR, $0}' packages/mcp/src/in-memory.ts | sed -n '1,140p'
echo
echo "packages/mcp/src defineTool relevant:"
awk '{printf "%4d %s\n", NR, $0}' packages/mcp/src/define-tool.ts | sed -n '1,220p'Repository: superset-sh/superset
Length of output: 17163
🌐 Web query:
GitHub modelcontextprotocol typescript-sdk support-2026-07-28.md requestState createMcpHandler Mcp-Method Mcp-Name
💡 Result:
In the Model Context Protocol (MCP) TypeScript SDK, the createMcpHandler function and requestState mechanism are key components introduced for the 2026-07-28 protocol revision [1][2]. createMcpHandler createMcpHandler is the v2 HTTP entry point from @modelcontextprotocol/server designed to serve the 2026-07-28 protocol revision on a per-request basis [1][2]. It creates a fresh server instance for each request, eliminating the need for a persistent Mcp-Session-Id and enabling stateless operation [1]. It also supports 2025-era traffic via a legacy stateless fallback [3][1]. requestState Because the 2026-07-28 revision is per-request, the requestState mechanism was introduced to manage state across multi-round-trip operations [1]. It allows the server to pass an opaque string to the client, which the client then echoes back on subsequent retries [1]. - Accessing State: Developers can read this state within a handler using the typed accessor ctx.mcpReq.requestState() [1]. - Verification: Since requestState is untrusted, servers should integrity-protect it (e.g., using HMAC). You can configure a verification hook via ServerOptions.requestState.verify, which runs before the handler [1][4]. The createRequestStateCodec helper is available to generate mint and verify functions for this purpose [1]. Mcp-Method and Mcp-Name These terms relate to the header-based parameter mirroring introduced in the 2026-07-28 draft [5][6]. - Mechanism: When a tool's inputSchema includes an x-mcp-header annotation, conforming clients mirror that argument into an Mcp-Param-{Name} HTTP request header [5][6]. - Server Handling: createMcpHandler validates these headers before dispatch. If headers are missing, malformed, or conflict with the body, the server rejects the request with a 400 Bad Request and JSON-RPC error -32020 (HeaderMismatch) [6]. For detailed implementation patterns, refer to the examples/mrtr/server.ts file in the repository, which demonstrates multi-round-trip handling [7][1]. [3][1][6]
Citations:
- 1: https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration/support-2026-07-28.md
- 2: https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28
- 3: https://github.com/modelcontextprotocol/typescript-sdk/blob/cc4b4161/packages/server/src/index.ts
- 4: https://github.com/modelcontextprotocol/typescript-sdk/blob/cc4b4161/packages/server/src/server/server.ts
- 5: https://github.com/modelcontextprotocol/TypeScript-sdk/blob/main/docs/client.md
- 6: https://github.com/modelcontextprotocol/TypeScript-sdk/blob/main/docs/server.md
- 7: https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/mrtr/server.ts
Replace “mostly mechanical” with explicit SDK v2 migration acceptance criteria.
No sessionIdGenerator only means the current transport is stateless v1. The 2026 SDK path still requires per-request metadata/state handling, standard routing/discovery changes, and the stable SDK entrypoint. Add those migration gates instead of implying the migration is mostly mechanical.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/mcp/docs/ROADMAP.md` around lines 28 - 34, Update the SDK v2 roadmap
entry to remove the “mostly mechanical” characterization and state explicit
migration gates: retain the stateless transport requirement, add per-request
metadata/state handling, adopt standard routing and discovery behavior, and
migrate to the stable SDK entrypoint. Keep the migration scheduled after the
toolset rework.
| Principles: one-sentence tool descriptions (orchestration protocol lives in | ||
| server `instructions` + a `superset://guide` resource), `outputSchema` on | ||
| every tool, uniform `limit`/`offset` pagination, structured error codes, |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Add the superset://guide resource to the migration plan.
The current state is tools-only, but the target instructions require superset://guide. Add resource registration, capability advertisement, authorization, and resources/read coverage to the sequencing. Otherwise remove the resource from the target contract.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/mcp/docs/ROADMAP.md` around lines 62 - 64, Update the migration
plan’s sequencing to explicitly include the superset://guide resource: register
it, advertise resource capability, authorize access, and cover resources/read
handling. If this resource is not part of the intended target contract, remove
its reference from the Principles statement instead.
| | Toolset | Exposure | Tools (target ~24) | | ||
| |---|---|---| | ||
| | Discovery | default | `hosts_list`, `projects_list`, `org_members_list` | | ||
| | Tasks | default | `tasks_list` (full CLI filter parity), `tasks_get`, `tasks_create`, `tasks_update`, `tasks_delete`, `tasks_statuses_list` | | ||
| | Workspaces | default | `workspaces_list` (+project/search filters), `workspaces_get` (new; embeds running agents + terminals), `workspaces_create`, `workspaces_update` (+taskId set/clear), `workspaces_delete` (MRTR confirm) | | ||
| | Agents | default | `agents_run` (start; returns task handle), `agents_send` (follow-up) — splits today's overloaded `agents_create` | | ||
| | Terminals | opt-in | `terminals_create`, `terminals_send`, `terminals_read`, `terminals_close` (`terminals_list` folds into `workspaces_get`) | | ||
| | Automations | opt-in | `automations_list`, `automations_get` (incl. prompt), `automations_create`, `automations_update` (incl. prompt + `enabled`, absorbing pause/resume), `automations_delete`, `automations_run` (task handle), `automations_logs` | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Reconcile the target tool count.
The table lists 27 tools: 3 + 6 + 5 + 2 + 4 + 7. Update the ~24 claim or remove three entries before generating the parity manifest.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/mcp/docs/ROADMAP.md` around lines 69 - 76, The roadmap table’s tool
count does not match its “target ~24” claim. Update the target count in the
table header to reflect the 27 listed tools, or remove three tool entries so the
table totals approximately 24 before the parity manifest is generated.
| Breaking changes ship as a clean break behind the same endpoint with one | ||
| changelog entry; removed tools return a descriptive "use X instead" error. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Define the compatibility path for removed tool names.
The current registrar boundary installs tools from REGISTRARS. If removed tools leave that list, direct calls will receive the default unknown-tool error, not "use X instead". Add compatibility stubs or alias dispatch, and specify whether old names remain in tools/list.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/mcp/docs/ROADMAP.md` around lines 85 - 86, Define the compatibility
behavior for removed tool names at the REGISTRARS registration/dispatch
boundary: add stubs or alias routing that returns a descriptive “use X instead”
error instead of the default unknown-tool response, and explicitly document
whether these legacy names remain in tools/list.
There was a problem hiding this comment.
3 issues found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="packages/mcp/docs/ROADMAP.md">
<violation number="1" location="packages/mcp/docs/ROADMAP.md:12">
P3: This bullet conflates the legacy `ToolTaskHandler` API with the 2026 Tasks extension's negotiated methods (`tasks/get`, `tasks/update`, `tasks/cancel`). Since these are different mechanisms (tool-level handler vs. capability-negotiated extension), the roadmap should distinguish them explicitly, and clarify that `tasks_list` remains a named tool rather than an extension method.</violation>
<violation number="2" location="packages/mcp/docs/ROADMAP.md:63">
P3: The target layout references a `superset://guide` resource, but current capabilities are tools-only (per the intro) and the sequencing plan doesn't mention resource registration, capability advertisement, authorization, or `resources/read` support needed to deliver it. Either add these to the migration plan or drop the resource from the target contract.</violation>
<violation number="3" location="packages/mcp/docs/ROADMAP.md:69">
P3: The table header claims 'target ~24' tools, but summing the listed tools per toolset (Discovery 3 + Tasks 6 + Workspaces 5 + Agents 2 + Terminals 4 + Automations 7) yields 27. Reconcile the stated target count with the actual tool list before this feeds a parity manifest.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
|
|
||
| ### Now usable (SDK 1.30.0) | ||
|
|
||
| - **Tasks extension** (`io.modelcontextprotocol/tasks`) — `ToolTaskHandler` |
There was a problem hiding this comment.
P3: This bullet conflates the legacy ToolTaskHandler API with the 2026 Tasks extension's negotiated methods (tasks/get, tasks/update, tasks/cancel). Since these are different mechanisms (tool-level handler vs. capability-negotiated extension), the roadmap should distinguish them explicitly, and clarify that tasks_list remains a named tool rather than an extension method.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/mcp/docs/ROADMAP.md, line 12:
<comment>This bullet conflates the legacy `ToolTaskHandler` API with the 2026 Tasks extension's negotiated methods (`tasks/get`, `tasks/update`, `tasks/cancel`). Since these are different mechanisms (tool-level handler vs. capability-negotiated extension), the roadmap should distinguish them explicitly, and clarify that `tasks_list` remains a named tool rather than an extension method.</comment>
<file context>
@@ -0,0 +1,93 @@
+
+### Now usable (SDK 1.30.0)
+
+- **Tasks extension** (`io.modelcontextprotocol/tasks`) — `ToolTaskHandler`
+ ships in 1.30. This is the centerpiece for agent ergonomics: `agents_run`
+ and `automations_run` return a task handle; clients drive `tasks/get` for
</file context>
| handle embedding `host:workspace`; hosts stay explicit — no cross-host | ||
| fan-outs), and toolsets with a lean default exposure. | ||
|
|
||
| | Toolset | Exposure | Tools (target ~24) | |
There was a problem hiding this comment.
P3: The table header claims 'target ~24' tools, but summing the listed tools per toolset (Discovery 3 + Tasks 6 + Workspaces 5 + Agents 2 + Terminals 4 + Automations 7) yields 27. Reconcile the stated target count with the actual tool list before this feeds a parity manifest.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/mcp/docs/ROADMAP.md, line 69:
<comment>The table header claims 'target ~24' tools, but summing the listed tools per toolset (Discovery 3 + Tasks 6 + Workspaces 5 + Agents 2 + Terminals 4 + Automations 7) yields 27. Reconcile the stated target count with the actual tool list before this feeds a parity manifest.</comment>
<file context>
@@ -0,0 +1,93 @@
+handle embedding `host:workspace`; hosts stay explicit — no cross-host
+fan-outs), and toolsets with a lean default exposure.
+
+| Toolset | Exposure | Tools (target ~24) |
+|---|---|---|
+| Discovery | default | `hosts_list`, `projects_list`, `org_members_list` |
</file context>
| | Toolset | Exposure | Tools (target ~24) | | |
| | Toolset | Exposure | Tools (target ~27) | |
| ## Target API layout | ||
|
|
||
| Principles: one-sentence tool descriptions (orchestration protocol lives in | ||
| server `instructions` + a `superset://guide` resource), `outputSchema` on |
There was a problem hiding this comment.
P3: The target layout references a superset://guide resource, but current capabilities are tools-only (per the intro) and the sequencing plan doesn't mention resource registration, capability advertisement, authorization, or resources/read support needed to deliver it. Either add these to the migration plan or drop the resource from the target contract.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/mcp/docs/ROADMAP.md, line 63:
<comment>The target layout references a `superset://guide` resource, but current capabilities are tools-only (per the intro) and the sequencing plan doesn't mention resource registration, capability advertisement, authorization, or `resources/read` support needed to deliver it. Either add these to the migration plan or drop the resource from the target contract.</comment>
<file context>
@@ -0,0 +1,93 @@
+## Target API layout
+
+Principles: one-sentence tool descriptions (orchestration protocol lives in
+server `instructions` + a `superset://guide` resource), `outputSchema` on
+every tool, uniform `limit`/`offset` pagination, structured error codes,
+opaque handles instead of ID ceremony (list tools return a `workspace`
</file context>
…ndle The regenerated lockfile materializes webdriverio's optional puppeteer-core peer, whose lazy chromium-bidi deep requires break the CLI dist bundle. The browser-driver path never executes at runtime, so both join the existing external list. Claude-Session: https://claude.ai/code/session_01Kub4p3Eim9pc1qaRRmGea2
Phase 1 (A1) of the MCP rework, expanded per review discussion: the SDK bump plus the dependency-graph unification that makes it cast-free.
Root phenomenon (discovered while chasing why the SDK bump needed
any/adapter casts): bun materializes one store copy of a package per peer-resolution context, and nominally-typed packages —#privateclasses (@mastra/core), branded schemas (zod) — cannot span copies even at identical versions. A partial zod migration is therefore structurally impossible; the only coherent states are "everything moves together" or "nothing moves." This PR moves everything together:@modelcontextprotocol/sdk1.28.0 → 1.30.0 (packages/mcp,apps/api,apps/docs) — zero source changes in the MCP registration path, no castsminimum-release-ageguard) — 16.4.7'sPageDatatypegen breaks under zod 4.4; 4 forked docs layout components migrated off removed internals (React 19.2's nativeuseEffectEvent, inlined single-locale strings for the removed i18n text API, widened page-tree types)ai→ 6.0.235 (apps/desktop,packages/ui,packages/chat) — the exact 6.0.141 pins violated the Mastra chain's^6.0.176, forcing dualai→ splitchat@4.35.0→ split@mastra/core→ host-service declaration-emit failure (TS2883)@types/hast3.0.5 override — post-refresh shiki/hast-util disagreementbun.lock— required for graph coherence; ~1,100 transitive entries re-resolve within their declared rangesUnchanged on purpose: mastracode 0.18.1, @mastra/memory 1.18.0 (version bumps proved unnecessary once the graph was coherent).
Full clean-install monorepo typecheck 34/34; lint clean.
Review focus: the lock refresh +
aipatch-level bump touch real runtime, especially desktop — CI's full matrix, the test suite, and a desktop smoke carry more weight than usual here. Verify on preview:/.well-known/mcp/server-card.json(live tools/list via SDK 1.30 — expect 31 tools), docs MCPtools/list, and an eyeball of the docs site layout (TOC header, prev/next footer, "Last updated on").https://claude.ai/code/session_01Kub4p3Eim9pc1qaRRmGea2
Summary by CodeRabbit
Documentation
Chores
Also adds
packages/mcp/docs/ROADMAP.md: the durable reference for what we adopt from the 2026-07-28 spec / SDK v2 line (tasks extension, MRTR, cacheable lists, stateless v2 migration, auth train, explicit non-adoptions) and the target ~24-tool API layout with toolsets, handles, and the usage data backing the consolidation.