Repository navigation
fix(ai-mcp): follow the final MCP Events webhook spec #2221
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| '@tanstack/ai-mcp': patch | ||
| --- | ||
|
|
||
| MCP Events follows the final text of SEP-3415 for webhook delivery. `events/subscribe` and `events/unsubscribe` send `Mcp-Name` and `Mcp-Param-*` on HTTP, SSE, and a Streamable HTTP transport instance. An event type whose `x-mcp-header` annotation breaks the transport rules is left out of `events/list`. A control message with no cursor is accepted, and `onGap` can receive `cursor: null`. Webhook signatures use the raw `webhook-timestamp` header, so a timestamp with a leading zero still verifies. Event occurrences keep a JSON object `_meta`. A HeaderMismatch (`-32020`) makes the client list events again and retry that request once. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -29,6 +29,10 @@ function rethrowEvents(err: unknown): never { | |
| throw toMCPEventRequestError(err) | ||
| } | ||
|
|
||
| function isHeaderMismatch(err: unknown): boolean { | ||
| return err instanceof MCPEventRequestError && err.kind === 'header-mismatch' | ||
| } | ||
|
|
||
| function assertWebhookMode(mode: string) { | ||
| if (mode !== 'webhook') { | ||
| throw new MCPEventConfigError('delivery.mode must be webhook') | ||
|
|
@@ -101,7 +105,10 @@ export function createDirectMCPEvents( | |
| if (!ctx.supportsEvents) throw new MCPEventsUnsupportedError() | ||
| } | ||
|
|
||
| async function send(record: MCPEventSubscription, signal?: AbortSignal) { | ||
| async function subscribeOnce( | ||
| record: MCPEventSubscription, | ||
| signal?: AbortSignal, | ||
| ): Promise<SubscribeEventsResult> { | ||
| try { | ||
| return await ctx.request( | ||
| 'events/subscribe', | ||
|
|
@@ -114,6 +121,44 @@ export function createDirectMCPEvents( | |
| } | ||
| } | ||
|
|
||
| async function send(record: MCPEventSubscription, signal?: AbortSignal) { | ||
| try { | ||
| return await subscribeOnce(record, signal) | ||
| } catch (err) { | ||
| if (!isHeaderMismatch(err)) throw err | ||
| } | ||
| // The remembered inputSchema was stale. List once, then retry once. | ||
| await listEventDefinitions(ctx, signal) | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Keep the stored definition current after a
Persist the matching definition from the relist result with the subscription before the record becomes
|
||
| return await subscribeOnce(record, signal) | ||
| } | ||
|
|
||
| async function unsubscribeOnce( | ||
| record: MCPEventSubscription, | ||
| signal?: AbortSignal, | ||
| ) { | ||
| try { | ||
| await ctx.request( | ||
| 'events/unsubscribe', | ||
| { | ||
| name: record.name, | ||
| arguments: record.arguments, | ||
| delivery: { mode: 'webhook', url: record.delivery.url }, | ||
| }, | ||
| emptyResult, | ||
| signal, | ||
| ) | ||
| } catch (err) { | ||
| const mapped = toMCPEventRequestError(err) | ||
| if ( | ||
| mapped instanceof MCPEventRequestError && | ||
| mapped.kind === 'not-found' | ||
| ) { | ||
| return | ||
| } | ||
| throw mapped | ||
| } | ||
| } | ||
|
|
||
| async function save( | ||
| key: string, | ||
| result: SubscribeEventsResult, | ||
|
|
@@ -189,24 +234,11 @@ export function createDirectMCPEvents( | |
| assertReady() | ||
| const record = await resolveRecord(store, ref) | ||
| try { | ||
| await ctx.request( | ||
| 'events/unsubscribe', | ||
| { | ||
| name: record.name, | ||
| arguments: record.arguments, | ||
| delivery: { mode: 'webhook', url: record.delivery.url }, | ||
| }, | ||
| emptyResult, | ||
| ref.signal, | ||
| ) | ||
| await unsubscribeOnce(record, ref.signal) | ||
| } catch (err) { | ||
| const mapped = toMCPEventRequestError(err) | ||
| if ( | ||
| !(mapped instanceof MCPEventRequestError) || | ||
| mapped.kind !== 'not-found' | ||
| ) { | ||
| throw mapped | ||
| } | ||
| if (!isHeaderMismatch(err)) throw err | ||
| await listEventDefinitions(ctx, ref.signal) | ||
| await unsubscribeOnce(record, ref.signal) | ||
| } | ||
| await store.delete(record.key) | ||
| }, | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,7 @@ | ||
| import { listPages } from '../list-pages' | ||
| import { MCPEventsUnsupportedError } from '../errors' | ||
| import { isMethodNotFound, toMCPEventRequestError } from './errors-map' | ||
| import { eventHeaderFault } from './param-headers' | ||
| import type { MCPEventDefinition, MCPEventsContext } from './types' | ||
| import { listEventsResult } from './wire' | ||
|
|
||
|
|
@@ -13,8 +14,9 @@ export async function listEventDefinitions( | |
| ): Promise<Array<MCPEventDefinition>> { | ||
| ctx.assertOpen() | ||
| if (!ctx.supportsEvents) throw new MCPEventsUnsupportedError() | ||
| let events: Array<MCPEventDefinition> | ||
| try { | ||
| return await listPages(async (cursor) => { | ||
| events = await listPages(async (cursor) => { | ||
| const page = await ctx.request( | ||
| 'events/list', | ||
| cursor === undefined ? {} : { cursor }, | ||
|
|
@@ -27,4 +29,12 @@ export async function listEventDefinitions( | |
| if (isMethodNotFound(err)) throw new MCPEventsUnsupportedError() | ||
| throw toMCPEventRequestError(err) | ||
| } | ||
| const kept = events.filter((event) => { | ||
| const fault = eventHeaderFault(event.inputSchema) | ||
| if (fault === undefined) return true | ||
| console.warn(`MCP events: left ${event.name} out of events/list. ${fault}`) | ||
| return false | ||
| }) | ||
| ctx.noteEventSchemas?.(kept) | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Stop older event listings from overwriting newer header schemas.
The retry runs only once, so the subscribe fails again with Apply only the schemas from the most recently started listing. Track a listing generation and skip
|
||
| return kept | ||
| } | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Declare the breaking type changes as a
majorrelease.Two exported declarations change in a type-breaking way.
verifyMCPEventSignaturenow requirestimestampas astring, so existing number callers no longer compile.onGapnow typesgap.cursorasstring | null, so callers that treat it asstringno longer compile. Apatchrelease signals a compatible fix. Consumers on a caret range can therefore take this update and fail to build. The@experimentaltag does not change this, because the package follows themajorconvention for breaking changes in 1.x releases.Use a
majorbump. If the breaking type changes are reverted, keeppatch. That is the only other compatible option.Suggested fix
Committable suggestion