Add addEventListener/removeEventListener with DOM-model on* semantics

[ochafik]

Adds DOM-model event semantics to on* setters and introduces addEventListener/removeEventListener for multi-listener support. The on* setters now have replace semantics (like el.onclick) with getters, and coexist with addEventListener listeners — both fire on dispatch.

• Fixes useHostStyles internals override each other #551 (useHostStyles broken: fonts handler clobbers theme/CSS variables)
• Fixes bug: app.onhostcontextchanged handlers silently overwrite each other #225 (user onhostcontextchanged and SDK hooks are mutually exclusive)
• Makes getHostContext() robust (context merge now happens unconditionally in onEventDispatch, not in a replaceable setter wrapper)

How it works

New ProtocolWithEvents base class between Protocol and App/AppBridge. Each notification event gets a slot with two independent channels:

Feature	on* setter	addEventListener
Semantics	Replace (single slot)	Append (listener array)
Clear	app.ontoolinput = undefined	removeEventListener(event, fn)
Getter	app.ontoolinput returns handler	N/A

Dispatch order: onEventDispatch() (side-effects) → on* handler → addEventListener listeners.

Other changes

• Getters for all on* properties on both App and AppBridge
• replaceRequestHandler for request-handler on* setters (replace semantics, no double-set throw)
• Reentrancy-safe dispatch (listener array snapshot-copied)
• useHostStyleVariables and useHostFonts now use addEventListener with proper cleanup

Test plan

• Build + all unit tests pass
• All examples build
• on* replace semantics, coexistence with addEventListener, getters, clearing
• Double-set protection on direct setRequestHandler/setNotificationHandler
• E2E tests

🤖 Generated with Claude Code

[github-actions]

Preview

Preview deployments for this PR have been cleaned up.

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/ext-apps

npm i https://pkg.pr.new/@modelcontextprotocol/ext-apps@573

@modelcontextprotocol/server-basic-preact

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-preact@573

@modelcontextprotocol/server-basic-react

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-react@573

@modelcontextprotocol/server-basic-solid

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-solid@573

@modelcontextprotocol/server-basic-svelte

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-svelte@573

@modelcontextprotocol/server-basic-vanillajs

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vanillajs@573

@modelcontextprotocol/server-basic-vue

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vue@573

@modelcontextprotocol/server-budget-allocator

npm i https://pkg.pr.new/@modelcontextprotocol/server-budget-allocator@573

@modelcontextprotocol/server-cohort-heatmap

npm i https://pkg.pr.new/@modelcontextprotocol/server-cohort-heatmap@573

@modelcontextprotocol/server-customer-segmentation

npm i https://pkg.pr.new/@modelcontextprotocol/server-customer-segmentation@573

@modelcontextprotocol/server-debug

npm i https://pkg.pr.new/@modelcontextprotocol/server-debug@573

@modelcontextprotocol/server-map

npm i https://pkg.pr.new/@modelcontextprotocol/server-map@573

@modelcontextprotocol/server-pdf

npm i https://pkg.pr.new/@modelcontextprotocol/server-pdf@573

@modelcontextprotocol/server-scenario-modeler

npm i https://pkg.pr.new/@modelcontextprotocol/server-scenario-modeler@573

@modelcontextprotocol/server-shadertoy

npm i https://pkg.pr.new/@modelcontextprotocol/server-shadertoy@573

@modelcontextprotocol/server-sheet-music

npm i https://pkg.pr.new/@modelcontextprotocol/server-sheet-music@573

@modelcontextprotocol/server-system-monitor

npm i https://pkg.pr.new/@modelcontextprotocol/server-system-monitor@573

@modelcontextprotocol/server-threejs

npm i https://pkg.pr.new/@modelcontextprotocol/server-threejs@573

@modelcontextprotocol/server-transcript

npm i https://pkg.pr.new/@modelcontextprotocol/server-transcript@573

@modelcontextprotocol/server-video-resource

npm i https://pkg.pr.new/@modelcontextprotocol/server-video-resource@573

@modelcontextprotocol/server-wiki-explorer

npm i https://pkg.pr.new/@modelcontextprotocol/server-wiki-explorer@573

commit: d64adb8

[antonpk1]

love it! I think we should keep app.onhostcontextchanged as deprecated to avoid surprises with backward compatibility for folks who update

[mel-anthropic]

love it! I think we should keep app.onhostcontextchanged as deprecated to avoid surprises with backward compatibility for folks who update

If we keep the old handler, would it be possible to add a console warning when it's being overwritten and that it's deprecated?

[localden]

Any issues with this being undefined? Wouldn't if (callback) skip on undefined?

[ochafik]

Good catch — fixed. The closure now reads from the backing field (this._onteardown) at call time instead of capturing callback. When cleared with undefined, the backing field is undefined and the next request throws "No onteardown handler set". The old callback is never called again.

set onteardown(callback: ... | undefined) {
  this._onteardown = callback;
  this.replaceRequestHandler(Schema, (request, extra) => {
    if (!this._onteardown) throw new Error("No onteardown handler set");
    return this._onteardown(request.params, extra);
  });
}

Same pattern applied to all 13 request handler setters.

[localden]

Previous implementations like this would break, right?

app.onlisttools = () => ({ tools: ["foo"]})

Do we need to document this?

[ochafik]

Yes, app.onlisttools = () => ({ tools: ["foo"]}) would be a TypeScript error with the new type. The old type Promise<{ tools: string[] }> was incorrect though — tools/list returns Tool objects (with name, inputSchema, etc.), not strings. This fixes the type to match the MCP protocol. Will mention as a type fix in the changelog.

[ochafik]

Done in latest push:

• Notification on* setters deprecated — all 10 (5 on App, 5 on AppBridge) now have @deprecated JSDoc directing users to addEventListener.
• Replacement warning — console.warn fires when an on* handler replaces a previously-set one (both notification events via setEventHandler and request handlers via warnIfRequestHandlerReplaced). Helps catch accidental overwrites at dev time.
• Request handler clearing fixed — closures now read from the backing field at call time instead of capturing the callback, so app.onteardown = undefined truly prevents the old handler from being called.
• Bot test fix — added getter assertion in the clearing test so the first assignment is observed.