Repository navigation
feat: Tasks extension for server and client (ext/tasks subpaths) - #2782
mattzcarey wants to merge 24 commits into
Conversation
🦋 Changeset detectedLatest commit: fb0d953 The changes in this PR will be included in the next version bump. This PR includes changesets to release 6 packages
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 |
@modelcontextprotocol/client
@modelcontextprotocol/codemod
@modelcontextprotocol/core
@modelcontextprotocol/server
@modelcontextprotocol/server-legacy
@modelcontextprotocol/express
@modelcontextprotocol/fastify
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
774c3f9 to
b04649e
Compare
46c22c6 to
b6f148b
Compare
b6f148b to
100decd
Compare
100decd to
92e5587
Compare
92e5587 to
1e5cffb
Compare
There was a problem hiding this comment.
2 optional notes from this repository's REVIEW.md or CLAUDE.md checks were not posted as comments, over this review's limit for such notes; they are on this commit's check card.
Findings marked 🟡 are optional suggestions and need no follow-up push.
There was a problem hiding this comment.
3 optional suggestions (nits or notes on pre-existing code) were found and not posted.
Still open from earlier reviews (10):
- 🔴
docs/servers/tasks.md:41—Operators following the documented task pattern get a server process crash when a client cancels a task that is waiting… - 🔴
packages/client/src/ext/tasks/tasksClientExtension.ts:68—Hosts that install TasksClientExtension but still use plain client.callTool get a silent empty result when a tool answe… - 🔴
packages/client/src/ext/tasks/tasksClientExtension.ts:81—Clients calling tools through tasks.callTool lose what client.callTool provides: Mcp-Param-* header mirroring, HEADER_M… - 🔴
packages/client/src/ext/tasks/tasksClientExtension.ts:113—Client users following the documented waitFor pattern are prompted again on every poll while a task waits for input, so… - 🔴
packages/server/src/ext/tasks/inMemoryStore.ts:107—Operators who set a task retention longer than about 24.8 days get the task purged about 1 ms after creation instead of… - 🔴
packages/server/src/ext/tasks/tasksExtension.ts:79—Users who share an OAuth client can read, answer and cancel each other's tasks once this merges, which the base cannot… - 🔴
packages/server/src/ext/tasks/tasksExtension.ts:142—Clients whose tasks/update answers are discarded by the protocol lift get a success ack while the task stays stuck in i… - Also unresolved: 3 minor or pre-existing.
If you have decided not to act on one of these findings, resolve its thread (a reply alone leaves it open) and the next review stops counting it. To review this commit again now, use Re-run on its "Claude Code Review" check.
1e5cffb to
ff1836d
Compare
There was a problem hiding this comment.
Code review found no new issues
No new issues were found in this update; 8 findings from earlier reviews are still open above.
5 optional suggestions (nits or notes on pre-existing code) were found and not posted.
Still open from earlier reviews (8):
- 🔴
packages/client/src/ext/tasks/tasksClientExtension.ts:113—Clients calling tools through tasks.callTool lose what client.callTool provides: Mcp-Param-* header mirroring, HEADER_M… - 🔴
packages/server/src/ext/tasks/tasksExtension.ts:179—Clients that never declared elicitation, sampling or roots can be handed those requests through a task and the task the… - 🔴
packages/server/src/ext/tasks/tasksExtension.ts:181—Servers that declare an outputSchema on a task-returning tool send clients an isError tool result instead of the task h… - Also unresolved: 4 minor or pre-existing, 1 blocking on lines changed since (possibly already fixed).
If you have decided not to act on one of these findings, resolve its thread (a reply alone leaves it open) and the next review stops counting it. To review this commit again now, use Re-run on its "Claude Code Review" check.
@modelcontextprotocol/server/ext/tasks adds TasksExtension(store): it advertises io.modelcontextprotocol/tasks, serves tasks/get, tasks/update and tasks/cancel, refuses requests that did not declare the extension (-32021), and gives a tool handler tasks.create(ctx) to answer tools/call with a task handle. TaskStore is the four-method interface a server implements over its own task state; InMemoryTaskStore is the in-process reference, with a writer handle (status, requireInput, complete, fail, signal). @modelcontextprotocol/client/ext/tasks adds TasksClientExtension: callTool, get, update, cancel and waitFor, which polls tasks/get until a terminal status. Wire types and schemas live at @modelcontextprotocol/core-internal/ext/tasks. examples/ext-tasks is a minimal in-process server and client: a bake_cake tool on TasksExtension over an InMemoryTaskStore reports progress, asks for input (input_required) and honours cancellation; the client follows it with TasksClientExtension.waitFor, answers through tasks.update, and cancels a second task.
InMemoryTaskStore passed ttlMs straight to setTimeout, which fires almost at once for any delay above 2^31-1 ms (about 24.8 days), so such a task was purged right after creation and its signal aborted. Wait the TTL out in steps of at most that delay.
handle.complete and handle.fail left an outstanding requireInput promise pending until the TTL purge, or forever with ttlMs: null, and a second requireInput replaced the first wait so the first never settled. Reject the pending wait when the task settles, refuse a second concurrent wait, and drop the abort listener once a wait resolves.
- TasksExtension goes in McpServerOptions.extensions; ServerOptions has no extensions option. - The requester half ships in this PR as TasksClientExtension from @modelcontextprotocol/client/ext/tasks, not @modelcontextprotocol/ext-tasks. - The server example fired the work with void and no catch; requireInput rejects on cancel or purge, so that crashed Node with an unhandled rejection. Settle failures on the task instead, here and in the TSDoc. - The schema header pointed at a vendored test fixture that does not exist.
The client guide answers input_required inside an async onUpdate, but waitFor called it without awaiting. Polling went on at the task's interval while the user was being asked, so the same unanswered input request came back and was asked again on every poll, and a rejection from the callback was unhandled. Await the callback before the next poll and let its rejection reject waitFor.
@modelcontextprotocol/core-internal is private, so users cannot import the wire types from it; they come from the server and client ext/tasks subpaths.
…6-07-28 only The task principal was the OAuth client id, so every user of a shared or public client could read, answer and cancel the others' tasks. The default is now the client id plus the token subject at authInfo.extra.sub when the verifier sets one, and TasksExtensionOptions.principal picks any identity. On 2025-11-25 the capability was advertised, then every tasks call failed with -32021 asking for an envelope that era cannot carry, and the core legacy tasks/get and tasks/cancel got the extension's handlers. The extension's methods now answer -32601 there, and tasks.create refuses with a -32021 that names the era.
everythingServer now installs TasksExtension over one in-memory store shared by the per-request servers, and registers the tools the tasks-* scenarios call by name: greet, slow_compute, failing_job, protocol_error_job, confirm_delete, multi_input and test_tool_with_task. All nine tasks-* server scenarios pass, so they leave the expected-failures baseline.
…ndles - tasks/update acked a request whose inputResponses the protocol dropped as not bare results, or that had none, leaving the task waiting. It now answers -32602 naming the refused keys, or the missing field; an empty object is still a valid partial update. - The tools/call middleware refused a task handle minted outside create after the task was already running, so the task leaked until its TTL, or forever with ttlMs: null. It now cancels the task before refusing.
TTL expiry and close() aborted the same signal as tasks/cancel with no reason, and a pending requireInput rejected with "was cancelled" in every case. The signal now carries an Error naming cancellation, expiry or store close, and the wait rejects with it.
…-type headers The TasksClientExtension example built a client on the default legacy handshake, where tasks.callTool is refused with -32021. It now negotiates, and the header says the extension needs a 2026-07-28 connection. The wire-type and schema headers keep provenance only.
…ol/core/ext/tasks
The Tasks schemas, types and constants lived in the private core-internal,
so code implementing either side without the SDK's server or client had no
published import, and the changeset had pointed at a private package. They
now live in core/ext/tasks, like core/ext/skills: the zod schemas and
constants move unchanged, and the types are inferred from the schemas, so
there is one definition. core-internal/ext/tasks is gone.
The core types describe inputRequests structurally ({ method, params }), as
core cannot import the SDK's MRTR unions. The server and client subpaths
re-export core's definitions, plus the precise InputRequest(s) and
InputResponse(s) types that requireInput and update take.
…RPC error The spec says a server MUST answer a request that needs an undeclared client capability with MissingRequiredClientCapabilityError (-32021) carrying requiredCapabilities. McpServer wrapped it as an isError tool result, like any other throw; it now passes it through, as it does UrlElicitationRequiredError.
…docs say what a tool can propagate docs/servers/errors.md said the SDK converts anything a tool throws and that UrlElicitationRequiredError is the only error a tool can propagate.
…nt ids They ran on one transport inside packages/server, which needed a dev dependency on the client and four tsconfig paths. They are now tasks:* and typescript:tasks:* requirements, with new cases for an outputSchema tool, the input-request capability check and tasks/update answer validation.
…l answer with a task - A task may only request input the creating request's client capabilities cover: tasks.create records them and InMemoryTaskStore.requireInput rejects a request that needs more, as the in-band input_required gate does. - InMemoryTaskStore.update validates each answer against the request it answers and refuses a bad one with -32602, keeping nothing from that update. - McpServer skips outputSchema validation for a result of another kind, such as a task handle; before, the client got an isError result and the work ran on unseen. - tasks.create's refusal no longer names tools/call as the tool. - Docs and changeset: tasks.callTool's limits, and that task access is by principal, not by scope.
…nd client subpaths Nothing in the SDK used them, and the three result schemas require a resultType that client.request strips before a caller's schema runs. They stay in core/ext/tasks, as the Skills subpaths do it.
…pability their task asks for
b9b2ddf to
f54eff4
Compare
2025-11-25 does not define the code, so there the tool error stays as it was, the way the -32042 passthrough is gated to its own era. errors.md says which era each exception applies to.
Adds the Tasks extension (
io.modelcontextprotocol/tasks, SEP-2663) as@modelcontextprotocol/server/ext/tasksand@modelcontextprotocol/client/ext/tasks, with the wire schemas and types in@modelcontextprotocol/core/ext/tasks. A tool answers with a task handle, and the client polls it to a result. Stacked on #3066; it also carries #3202's commits until that merges.The SDK handles the wire protocol; running the work is the server's:
TasksExtensionadvertises the capability, servestasks/get,tasks/updateandtasks/cancel, and refuses a request that did not declare the extension (-32021). It is served on 2026-07-28 only: on 2025-11-25 the methods answer-32601.TaskStoreis four methods (create,get,update,cancel) over the server's own state.InMemoryTaskStoreis the in-process reference, with a writerhandlefor status, input requests and settling.authInfo.extra.sub, or theprincipaloption. Another principal gets "Task not found". Access is by principal only; a tool'sscopeChallengeis not re-run ontasks/*.tasks/updateanswer that is not a valid result for its request is refused with-32602.TasksClientExtensionwrapscallTool,get,updateandcancel, and addswaitFor. ItscallToolsendstools/calldirectly, withoutclient.callTool'sMcp-Param-*header mirroring oroutputSchemavalidation.McpServerno longer validates a result of another kind, such as a task handle, against the tool'soutputSchema.ext/taskssubpaths is@experimental: it may change in a minor release while the extensions SEPs settle.notifications/tasks(subscriptions/listen cannot carry extension notifications (blocks notifications/tasks) #2569), so clients poll. Refs Implement SEP-2663: Tasks Extension #2189, v2: extension methods shadowed by legacy spec-method registry — custom tasks/get & tasks/cancel handlers unreachable (-32601 before handler lookup) #2598.pnpm check:all, the build and the unit, integration and e2e suites ran on Node 24, and the ninetasks-*conformance scenarios pass. The e2e requirementstasks:*andtypescript:tasks:*cover the flow on thecreateMcpHandlerentry, andexamples/ext-tasksruns end to end over stdio.