Migrate to MCP TypeScript SDK v2 (2.0.0-beta.1) - #14
Open
raymondfeng wants to merge 2 commits into
Open
Conversation
v2 splits the monolithic @modelcontextprotocol/sdk into per-role/per-framework
packages. Migrate the 6 MCP packages + testing + hello-mcp off `sdk` onto
@modelcontextprotocol/{core,server,client,node,server-legacy} via the official
codemod (`@modelcontextprotocol/codemod v1-to-v2`) plus hand-fixes:
- keys.ts: RequestHandlerExtra -> ServerContext; the removed SDK `RequestInfo`
type replaced by a stable local `McpRequestInfo` for the REQUEST_INFO binding.
- mcp.server.ts requestContextFor: v2 flattened the per-request "extra" into
`ctx.mcpReq` (id/signal/send/notify/_meta) and `ctx.http` (authInfo/req).
Map authInfo -> http.authInfo, and derive the {headers,url} REQUEST_INFO
contract from the new `http.req` Fetch Request (keeps @agentback/payments
et al. stable). progressFnFor now relays via `mcpReq.notify`.
- tools/list: v2 tightened the result to require `inputSchema.type:"object"`
(always true here); assert at the one boundary via ListToolsResult.
- mcp-connect: v2 Client.callTool dropped the middle resultSchema arg.
- mcp-http OAuth resource-server bearer path stays on the FROZEN
server-legacy/auth copy (functional, behavior-preserving); moving to
@modelcontextprotocol/express is a documented follow-up (verifiers must
throw the v2 OAuthError).
Deps pinned to exact 2.0.0-beta.1 (v2 is beta until the 2026-07-28 stable).
`pnpm verify` green: 2604 passed | 33 skipped.
Known follow-ups (not in this spike):
- Re-point mcp-http bearer auth to @modelcontextprotocol/express.
- @modelcontextprotocol/ext-apps has no v2 build yet -> hello-mcp-apps keeps
sdk@1.29 transitively.
- Prose docs still reference the old `@modelcontextprotocol/sdk` import paths.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…press; drop server-legacy
Completes the v2 migration by removing the deprecated
@modelcontextprotocol/server-legacy dependency from mcp-http, mcp-client,
and mcp-connect entirely.
- index.ts: requireBearerAuth + OAuthTokenVerifier now import from
@modelcontextprotocol/express (the maintained v2 home). The legacy
metadataHandler is dropped: v2's mcpAuthMetadataRouter also serves the
authorization SERVER's RFC 8414 metadata, which AgentBack — a pure resource
server pointing at an external AS — does not own, so we serve the RFC 9728
protected-resource document directly with a one-line route.
- fetch.ts: the edge/fetch bearer mirror consolidates the four legacy error
subclasses (InvalidToken/InsufficientScope/OAuth/ServerError) into v2's
single OAuthError, discriminated by `code` for the HTTP status mapping.
- All 5 integration-test verifiers throw v2 OAuthError.
Dual-package-identity fix: v2's client/server/express each bundle their own
copy of the auth classes (no shared @modelcontextprotocol/core), so
`instanceof` only matches the copy from the same package — a verifier throwing
OAuthError from the wrong package would be misread as a 500. mcp-http now
re-exports the exact OAuthError its middleware recognizes; the mcp-client and
mcp-connect tests dogfood it via `import {OAuthError} from '@agentback/mcp-http'`.
`pnpm verify` green: 2604 passed | 33 skipped. server-legacy no longer a dep.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Migrates AgentBack's MCP stack from the monolithic
@modelcontextprotocol/sdk@1.29to the v2 package split (@modelcontextprotocol/{core,server,client,node,express}@2.0.0-beta.1). Done via the official@modelcontextprotocol/codemod v1-to-v2plus hand-fixes for the semantic changes the codemod flags.Why v2 is a migration, not a bump
@modelcontextprotocol/sdk@2does not exist on npm — v2 shipped as ~9 new packages. Every import moves. The split also mirrors AgentBack's own host-neutralmcpvsmcp-httpdesign (v2's/servervs/nodevs/express).Commit 1 — core migration
keys.ts:RequestHandlerExtra→ServerContext; the removed SDKRequestInfotype replaced by a stable localMcpRequestInfofor theREQUEST_INFObinding.mcp.server.tsrequestContextFor: v2 flattened the per-request "extra" intoctx.mcpReq(id/signal/send/notify/_meta) andctx.http(authInfo/req). MappedauthInfo→http.authInfo, and derive the stable{headers,url}REQUEST_INFOcontract from the newhttp.reqFetchRequest(keeps@agentback/paymentset al. unchanged).progressFnForrelays viamcpReq.notify.tools/list: v2 tightened the result to require a literalinputSchema.type:"object"(always true here); asserted at the one boundary.mcp-connect: v2Client.callTooldropped the middleresultSchemaarg.Commit 2 — OAuth auth to
@modelcontextprotocol/express; dropserver-legacymcp-http/index.ts:requireBearerAuth+OAuthTokenVerifiernow from@modelcontextprotocol/express. LegacymetadataHandlerdropped — v2'smcpAuthMetadataRouteralso serves the authorization server's RFC 8414 metadata, which AgentBack (a pure resource server pointing at an external AS) does not own, so we serve the RFC 9728 protected-resource doc directly.fetch.ts(edge mirror): the four legacy error subclasses consolidated into v2's singleOAuthErrordiscriminated bycode.core), soinstanceofonly matches the same-package copy — a verifier throwingOAuthErrorfrom the wrong package reads as a 500.@agentback/mcp-httpnow re-exports the exactOAuthErrorits middleware recognizes; tests dogfoodimport {OAuthError} from '@agentback/mcp-http'.@modelcontextprotocol/server-legacyis no longer a dependency of any package.Verification
pnpm verify(build + typecheck:client + full test + validate-templates) — exit 0, 2604 passed | 33 skipped (skips are pre-existing env-gated).Known follow-ups (intentionally not in this PR)
@modelcontextprotocol/ext-appshas no v2 build yet →hello-mcp-appskeepssdk@1.29transitively (the only remaining v1 SDK reference; contained to that one example).packages/*/README.md,docs/guides/build-an-mcp-server.md) still show old@modelcontextprotocol/sdk/...import paths — not build-affecting.latest.🤖 Generated with Claude Code