Skip to content

feat(mcp): upgrade generated servers to SDK v2 - #84

Open
ThomasRooney wants to merge 6 commits into
mainfrom
chore/mcp-sdk-upgrade
Open

ThomasRooney wants to merge 6 commits into
mainfrom
chore/mcp-sdk-upgrade

Conversation

@ThomasRooney

@ThomasRooney ThomasRooney commented Oct 7, 2026 •

Copy link
Copy Markdown
Member

Why

Upgrade generated MCP servers to the stable v2 SDK while preserving existing clients, legacy transports, and extension entrypoints.

What changed

  • Use MCP server/client/server-legacy 2.3.1 and Node adapter 2.1.1. Require Node.js 20, or 22.18 for Gram-enabled servers, while preserving stricter custom engine constraints.
  • Keep Node and Cloudflare SSE available. Cloudflare retains stateful legacy Streamable HTTP sessions alongside modern HTTP, including its Durable Object bindings and serve, serveSSE, and mount entrypoints.
  • Allow both compatible Worker-types major versions so clean installs resolve the current Wrangler peer dependency.
  • Preserve session-opening credentials for legacy clients, isolate concurrent request credentials, and keep authenticated Worker props authoritative.
  • Preserve standalone and optional TypeScript extension callback aliases such as extra.signal, v1 resource-template registration, and cancellation guards. Retain SDK 1.32.1 for existing extension imports alongside the v2 server packages. Keep optional MCP SDKs on root Zod 3 while the v2 dependencies use their own Zod 4.
  • Preserve schema defaults, transforms, validation, prompt completions, and Gram/eval integrations. Distinguish schema input and output types, honor JSON Schema dialects, and preserve tuple and recursive-reference constraints. Fix transport-specific setup links, authentication headers, and supported Node HTTP parameter overrides while retaining legacy SSE header aliases, authentication defaults, DELETE preflights, and graceful HTTP shutdown.
  • Keep package metadata, tool declarations, and stdio options compatible with custom edits during regeneration. Create fresh stdio servers when modern discovery falls back to legacy initialization.
  • Add regression coverage, regenerate the MCP review SDK, and include major changesets for the Node runtime requirement.

Testing

  • Standalone MCP primary suite: 336 passed.
  • Optional TypeScript MCP tertiary suite: 414 passed, one skipped.
  • Schema/extension scratch matrix: 185 passed; generated CLI cases also pass in the permanent suite.
  • Real stdio and HTTP clients using legacy and modern protocols, concurrent calls, cancellation, malformed input, and recovery. Both HTTP protocol eras pass the in-flight shutdown regression.
  • Miniflare legacy SSE/session, authentication isolation, and custom Worker entrypoint checks; Node 20 transport checks; Node 22 Gram/eval checks.
  • Clean Cloudflare dependency install and type-check with Wrangler 4.148.0 and Worker types 5.20261007.1.
  • Wrangler deployment dry-run and Gram packaging checks. No deployment performed; physical Worker disconnect behavior still requires deployed verification.
  • Neutral three-way merge checks preserve custom package metadata, tool annotations, and stdio options. Both generated CLIs cover modern discovery followed by legacy initialization; custom stdio options and startup hooks survive the regeneration merge.
  • Full repository lint and git diff --check passed.
  • Generated MCP and TypeScript snapshot outputs reviewed; no unrelated production model or SDK method changes were found. Earlier package metadata, tool annotation, Zod, and stdio regeneration regressions now pass their snapshots.
  • One customized snapshot retains explicit SDK dependency pins and an adjacent custom import that conflict with this upgrade. That snapshot requires manual reconciliation in package.json and src/mcp-server/cli/serve/impl.ts; aggregate CI success does not establish compile success for it. Isolated copies pass type-checking, lint, bundling, stdio initialization/tool discovery, HTTP initialization, and the custom route after resolving only those conflict blocks. Existing baseline failures were checked against their actual diagnostics. A separate stale running indicator was verified as a successful compile/lint from the job log.

Public-safety check

  • This change contains no credentials, customer documents, private repository URLs, private filesystem paths, or unredacted private logs.
  • Title, body, comments, and commit messages name no customers or customer-derived identifiers, private paths or trackers, or workflow provenance, and are understandable without private context (.claude/skills/public-repo-communication/SKILL.md).
  • Generated fixtures and review SDK changes are public-safe.
  • I reviewed git diff --check.

BREAKING CHANGE: MCP servers require Node 20 (22.18 with Gram).
Custom extensions use v2 ServerContext. Cloudflare serves stateless
HTTP at /mcp and retires /sse; Node legacy SSE remains supported.
@ThomasRooney
ThomasRooney requested a review from a team as a code owner October 7, 2026 13:28
@ThomasRooney ThomasRooney added mcp-typescript Trigger (16) snapshot tests for mcp-typescript typescript Trigger (168) snapshot tests for typescript labels Oct 7, 2026
@ThomasRooney
ThomasRooney requested a review from 2ynn October 7, 2026 13:28
@ThomasRooney ThomasRooney added the typescript Trigger (168) snapshot tests for typescript label Oct 7, 2026
@cubic-dev-ai

cubic-dev-ai Bot commented Oct 7, 2026

Copy link
Copy Markdown

We detected this is a high-risk PR and are running a free ultrareview. An ultrareview is a deeper, multi-pass review that catches hard-to-find bugs a standard review can miss. We'll post the findings when it completes.

This PR appears to move logic across many files, where a missed bug can hide in interactions a single-pass review does not trace, so a deeper multi-pass review is worth running.

Want an ultrareview on every high-risk PR? Set up automated ultrareviews.

@speakeasy-generator-bot

speakeasy-generator-bot Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

Generator Snapshot Testing

Selector(s) Result Summary
snapshot-mcp-typescript, snapshot-typescript ✅ Snapshot run completed

Snapshot results: https://github.com/speakeasy-api/openapi-generation-snapshots/issues/111#issuecomment-6043600032

Snapshot results are summarized above. Additional run context is linked for maintainers with access.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We detected this is a high-risk PR and ran a free ultrareview. An ultrareview is a deeper, multi-pass review that catches hard-to-find bugs a standard review can miss.

This PR appears to move logic across many files, where a missed bug can hide in interactions a single-pass review does not trace, so a deeper multi-pass review is worth running.

Want an ultrareview on every high-risk PR? Set up automated ultrareviews.

All reported issues were addressed across 101 files

Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread zSDKs/mcp-typescript/src/landing-page.ts Outdated
Comment thread templates/templates/mcp-typescript/mcp-server/gram.ts.stmpl
Comment thread templates/templates/mcp-typescript/mcp-server/gram.ts.stmpl
Comment thread zSDKs/mcp-typescript/src/mcp-server/cli/serve/impl.ts
Comment thread zSDKs/mcp-typescript/src/mcp-server/cli/serve/impl.ts Outdated
Comment thread templates/templates/mcp-typescript/tests/primary/auth_additional.test.ts.stmpl Outdated
Keep OAuth grant credentials authoritative and isolate concurrent
session requests. Preserve legacy transports and extension interfaces
while generated servers move to the v2 SDK.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 104 files

Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread templates/templates/mcp-typescript/readme.stmpl Outdated
Comment thread zSDKs/mcp-typescript/src/landing-page.ts Outdated
Comment thread zSDKs/mcp-typescript/src/mcp-server/shared.ts
Keep optional MCP callback contexts and resource templates compatible
with v1 extensions, and distinguish schema input and output.

Align setup headers with each transport while retaining SSE aliases.
Preserve generated declaration layout around custom metadata.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 21 files (changes from recent commits).

Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread templates/templates/mcp-typescript/includes/templating.ts Outdated
Comment thread zSDKs/mcp-typescript/src/landing-page.ts
Convert tuple schemas and local references to the requested dialect
without changing literal defaults or validation behavior.

Advertise supported global parameters and server variables for Node
HTTP while keeping SSE and Worker setup headers accurate.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 7 files (changes from recent commits).

Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic

Keep optional MCP SDKs on Zod 3 at the package root so existing
schemas retain their types. Preserve stdio option layout during
regeneration while creating fresh servers for protocol fallback.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 7 files (changes from recent commits).

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Shadow auto-approve: would not auto-approve. Auto-approval blocked by 5 unresolved issues from previous reviews.

View guided diff | Turn on auto-fix | Re-trigger cubic

Keep the options object layout stable during regeneration and create
fresh servers for stdio protocol fallback.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 3 files (changes from recent commits).

Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread templates/templates/typescriptv2/mcp-server/cli/start/impl.ts.stmpl
@ThomasRooney

Copy link
Copy Markdown
Member Author

@cubic-dev-ai review this PR

Please reassess the current head (af5ccd13e14db051c7b5a3113138d0c15bc552a9) and refresh the confidence assessment using the code and test evidence in the resolved review replies. The shutdown regression is fixed; the remaining findings have dependency-contract and generated-code explanations. All 14 focused regression/parity checks pass, and CI and snapshot checks are green. Please flag any remaining actionable issues.

@cubic-dev-ai

cubic-dev-ai Bot commented Oct 8, 2026

Copy link
Copy Markdown

@cubic-dev-ai review this PR

Please reassess the current head (af5ccd13e14db051c7b5a3113138d0c15bc552a9) and refresh the confidence assessment using the code and test evidence in the resolved review replies. The shutdown regression is fixed; the remaining findings have dependency-contract and generated-code explanations. All 14 focused regression/parity checks pass, and CI and snapshot checks are green. Please flag any remaining actionable issues.

@ThomasRooney I have started the AI code review. It will take a few minutes to complete.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 108 files

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Shadow auto-approve: would require human review. Major SDK v1→v2 MCP migration: new Cloudflare worker credential isolation, runtime/transport changes, major bumps. Needs human sign-off: deployed disconnect behavior unverified; one customized snapshot still needs manual reconciliation.

View guided diff | Turn on auto-fix | Re-trigger cubic

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

mcp-typescript Trigger (16) snapshot tests for mcp-typescript typescript Trigger (168) snapshot tests for typescript

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants