v2 - RFC Extract Tasks out of protocol.ts into TaskManager

[KKonstantinov]

Based on #1449

Extract all task orchestration logic (creation, polling, queuing, routing) from the monolithic Protocol class into a dedicated TaskManager class that implements a new ProtocolModule interface. TaskManager is only instantiated when capabilities.tasks is declared, keeping Protocol lean for non-task use cases.

Motivation and Context

The Protocol class had grown to ~1800 lines, with roughly half dedicated to task management. This made it difficult to reason about, test, and extend independently. Extracting tasks into TaskManager achieves:

• Separation of concerns: Protocol handles JSON-RPC message routing; TaskManager handles task lifecycle
• Conditional initialization: Task infrastructure is only created when tasks capability is declared
• Extensibility: The new ProtocolModule interface allows future modules to hook into request/response/notification lifecycle without modifying Protocol
• Consolidated task context: Handler extra/ctx task fields are grouped under a single task object instead of scattered top-level properties

How Has This Been Tested?

• All 1239 tests pass across all packages (pnpm test:all)
• pnpm typecheck:all passes (except a pre-existing unrelated type error in examples/client)
• Core protocol tests refactored to test TaskManager independently
• Integration tests updated to properly declare tasks capability when using experimental.tasks.* APIs
• Task-augmented request flows (elicitation, sampling) tested with InMemoryTaskStore on both client and server

Breaking Changes

Before	After
ProtocolOptions.taskStore	capabilities.tasks.taskStore (on ClientOptions / ServerOptions)
ProtocolOptions.taskMessageQueue	capabilities.tasks.taskMessageQueue (on ClientOptions / ServerOptions)
Protocol.assertTaskCapability() (abstract)	Removed — passed as callback in TaskManagerOptions
Protocol.assertTaskHandlerCapability() (abstract)	Removed — passed as callback in TaskManagerOptions

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

New files:

• packages/core/src/shared/taskManager.ts — TaskManager class implementing ProtocolModule
• packages/core/src/shared/protocolModule.ts — ProtocolModule interface and lifecycle types

Architecture: Protocol now maintains a _modules array. During request/response/notification processing, it delegates to each registered module in order. TaskManager is the first (and currently only) module. The interface is designed so additional modules can be added without further changes to Protocol.

Test fixes: Integration tests for createMessageStream and elicitInputStream were updated to declare tasks capability on the server, since experimental.tasks.* methods correctly require it. The createMessageStream task-related tests were also restructured with shared beforeEach/afterEach to eliminate repeated inline server creation.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3b7c0fd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@modelcontextprotocol/core	Minor
@modelcontextprotocol/client	Minor
@modelcontextprotocol/server	Minor
@modelcontextprotocol/node	Major
@modelcontextprotocol/express	Major
@modelcontextprotocol/hono	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1673

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1673

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1673

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1673

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1673

commit: 5e86b5d

[KKonstantinov]

Just leaving this thought process here. I wonder if looping through _modules just to support multiple modules (where we have only one right now) is premature abstraction/generalization here. This could fall back to direct calling of the task module now (while keeping it running only if the task capability is declared), and if additional modules are added in the future, this could probably be done in a 15 minute change/iteration. Wondering if it is worth the indirection today - probably not. Any new "module" I imagine would be a significant feature coming from the protocol spec and not a random SDK-level feature. Thus, it would have to be carefully implemented and reviewed anyway; and the looping of the _modules etc. could be added at that point.

The real two benefits would be - tasks code runs runtime only if tasks is declared as a capability; ProtocolModule interface and Protocol Module could still exist if we removed the multi-module speculative abstraction; Still holds value in defining the contract, but Protocol would call the module directly rather than looping. Right now reading through the loop of _modules and seems like added cognitive complexity - but wanted to see how it'd look like.

Leaving it as-is right now, but happy to remove that