refactor: rename request methods to remove send prefix (#161)

* refactor: rename request methods to remove send prefix

Following the MCP TS SDK convention where request methods don't have
the "send" prefix (reserved for notifications):

- App.sendMessage() → App.message()
- App.sendOpenLink() → App.openLink()
- AppBridge.sendResourceTeardown() → AppBridge.resourceTeardown()

The old method names are kept as deprecated aliases for backwards
compatibility.

Updated all examples to use the new method names.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* test: add tests for deprecated method aliases

- Update existing tests to use new method names (message, openLink)
- Add tests verifying deprecated aliases are same reference as new methods
- Add tests verifying deprecated aliases still work functionally

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: rename message→sendMessage, resourceTeardown→teardownResource

- App.message() → App.sendMessage() (with deprecated message alias)
- AppBridge.resourceTeardown() → AppBridge.teardownResource() (with deprecated aliases)

This better follows the pattern where methods that send data have 'send' or action verb prefix.

* fix: update examples to use sendMessage instead of message

* fix: update basic-host to use teardownResource

* fix: update threejs-server to use sendMessage

* refactor: remove deprecated app.message alias

The app.message alias was removed since sendMessage is the correct name.
sendResourceTeardown already exists in AppBridge.

* refactor: remove resourceTeardown alias, keep only sendResourceTeardown

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Olivier Chafik 2025-12-16 22:07:06 +00:00 • committed by GitHub
commit 2dd223b611
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
14 changed files with 59 additions and 259 deletions

View file

@ -289,7 +289,7 @@ function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppI
}
log.info("Sending teardown notification to MCP App");
appBridgeRef.current.sendResourceTeardown({})
appBridgeRef.current.teardownResource({})
.catch((err) => {
log.warn("Teardown request failed (app may have already closed):", err);
})

View file

@ -9,7 +9,7 @@ An MCP App example with a React UI.
- Tool registration with a linked UI resource
- React UI using the [`useApp()`](https://modelcontextprotocol.github.io/ext-apps/api/functions/_modelcontextprotocol_ext-apps_react.useApp.html) hook
- App communication APIs: [`callServerTool`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#callservertool), [`sendMessage`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendmessage), [`sendLog`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendlog), [`sendOpenLink`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendopenlink)
- App communication APIs: [`callServerTool`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#callservertool), [`sendMessage`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendmessage), [`sendLog`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendlog), [`openLink`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#openlink)
## Key Files

View file

@ -110,7 +110,7 @@ function GetTimeAppInner({ app, toolResult }: GetTimeAppInnerProps) {
const handleOpenLink = useCallback(async () => {
log.info("Sending open link request to Host:", linkUrl);
const { isError } = await app.sendOpenLink({ url: linkUrl });
const { isError } = await app.openLink({ url: linkUrl });
log.info("Open link request", isError ? "rejected" : "accepted");
}, [app, linkUrl]);

View file

@ -9,7 +9,7 @@ An MCP App example with a vanilla JavaScript UI (no framework).
- Tool registration with a linked UI resource
- Vanilla JS UI using the [`App`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html) class directly
- App communication APIs: [`callServerTool`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#callservertool), [`sendMessage`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendmessage), [`sendLog`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendlog), [`sendOpenLink`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendopenlink)
- App communication APIs: [`callServerTool`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#callservertool), [`sendMessage`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendmessage), [`sendLog`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendlog), [`openLink`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#openlink)
## Key Files

View file

@ -92,7 +92,7 @@ sendLogBtn.addEventListener("click", async () => {
openLinkBtn.addEventListener("click", async () => {
log.info("Sending open link request to Host:", linkUrl.value);
const { isError } = await app.sendOpenLink({ url: linkUrl.value });
const { isError } = await app.openLink({ url: linkUrl.value });
log.info("Open link request", isError ? "rejected" : "accepted");
});

View file

@ -32,7 +32,7 @@ export interface WidgetProps<TToolInput = Record<string, unknown>> {
/** Send a message to the host's chat */
sendMessage: App["sendMessage"];
/** Request the host to open a URL */
sendOpenLink: App["sendOpenLink"];
openLink: App["openLink"];
/** Send log messages to the host */
sendLog: App["sendLog"];
}
@ -81,8 +81,8 @@ function McpAppWrapper() {
(params, options) => app!.sendMessage(params, options),
[app],
);
const sendOpenLink = useCallback<App["sendOpenLink"]>(
(params, options) => app!.sendOpenLink(params, options),
const openLink = useCallback<App["openLink"]>(
(params, options) => app!.openLink(params, options),
[app],
);
const sendLog = useCallback<App["sendLog"]>(
@ -106,7 +106,7 @@ function McpAppWrapper() {
hostContext={hostContext}
callServerTool={callServerTool}
sendMessage={sendMessage}
sendOpenLink={sendOpenLink}
openLink={openLink}
sendLog={sendLog}
/>
);

View file

@ -143,7 +143,7 @@ export default function ThreeJSApp({
hostContext: _hostContext,
callServerTool: _callServerTool,
sendMessage: _sendMessage,
sendOpenLink: _sendOpenLink,
openLink: _openLink,
sendLog: _sendLog,
}: ThreeJSAppProps) {
const [error, setError] = useState<string | null>(null);

View file

@ -270,7 +270,7 @@ resetBtn.addEventListener("click", async () => {
// Open button - opens the Wikipedia page in browser
openBtn.addEventListener("click", async () => {
if (selectedNodeUrl) {
await app.sendOpenLink({ url: selectedNodeUrl });
await app.openLink({ url: selectedNodeUrl });
hidePopup();
}
});

View file

@ -373,7 +373,7 @@ describe("App <-> AppBridge integration", () => {
await newBridgeTransport.close();
});
it("sendResourceTeardown triggers app.onteardown", async () => {
it("teardownResource triggers app.onteardown", async () => {
let teardownCalled = false;
app.onteardown = async () => {
teardownCalled = true;
@ -381,12 +381,12 @@ describe("App <-> AppBridge integration", () => {
};
await app.connect(appTransport);
await bridge.sendResourceTeardown({});
await bridge.teardownResource({});
expect(teardownCalled).toBe(true);
});
it("sendResourceTeardown waits for async cleanup", async () => {
it("teardownResource waits for async cleanup", async () => {
const cleanupSteps: string[] = [];
app.onteardown = async () => {
cleanupSteps.push("start");
@ -396,7 +396,7 @@ describe("App <-> AppBridge integration", () => {
};
await app.connect(appTransport);
await bridge.sendResourceTeardown({});
await bridge.teardownResource({});
expect(cleanupSteps).toEqual(["start", "done"]);
});
@ -481,7 +481,7 @@ describe("App <-> AppBridge integration", () => {
expect(result.isError).toBe(true);
});
it("app.sendOpenLink triggers bridge.onopenlink and returns result", async () => {
it("app.openLink triggers bridge.onopenlink and returns result", async () => {
const receivedLinks: string[] = [];
bridge.onopenlink = async (params) => {
receivedLinks.push(params.url);
@ -489,24 +489,51 @@ describe("App <-> AppBridge integration", () => {
};
await app.connect(appTransport);
const result = await app.sendOpenLink({ url: "https://example.com" });
const result = await app.openLink({ url: "https://example.com" });
expect(receivedLinks).toEqual(["https://example.com"]);
expect(result).toEqual({});
});
it("app.sendOpenLink returns error when host denies", async () => {
it("app.openLink returns error when host denies", async () => {
bridge.onopenlink = async () => {
return { isError: true };
};
await app.connect(appTransport);
const result = await app.sendOpenLink({ url: "https://blocked.com" });
const result = await app.openLink({ url: "https://blocked.com" });
expect(result.isError).toBe(true);
});
});
describe("deprecated method aliases", () => {
beforeEach(async () => {
await bridge.connect(bridgeTransport);
await app.connect(appTransport);
});
it("app.sendOpenLink is an alias for app.openLink", async () => {
expect(app.sendOpenLink).toBe(app.openLink);
});
it("bridge.sendResourceTeardown is a deprecated alias for bridge.teardownResource", () => {
expect(bridge.sendResourceTeardown).toBe(bridge.teardownResource);
});
it("app.sendOpenLink works as deprecated alias", async () => {
const receivedLinks: string[] = [];
bridge.onopenlink = async (params) => {
receivedLinks.push(params.url);
return {};
};
await app.sendOpenLink({ url: "https://example.com" });
expect(receivedLinks).toEqual(["https://example.com"]);
});
});
describe("ping", () => {
it("App responds to ping from bridge", async () => {
await bridge.connect(bridgeTransport);

View file

@ -176,7 +176,7 @@ type RequestHandlerExtra = Parameters<
* 2. **Connect**: Call `connect()` with transport to establish communication
* 3. **Wait for init**: Guest UI sends initialize request, bridge responds
* 4. **Send data**: Call `sendToolInput()`, `sendToolResult()`, etc.
* 5. **Teardown**: Call `sendResourceTeardown()` before unmounting iframe
* 5. **Teardown**: Call `teardownResource()` before unmounting iframe
*
* @example Basic usage
* ```typescript
@ -1219,7 +1219,7 @@ export class AppBridge extends Protocol<
* @example
* ```typescript
* try {
* await bridge.sendResourceTeardown({});
* await bridge.teardownResource({});
* // Guest UI is ready, safe to unmount iframe
* iframe.remove();
* } catch (error) {
@ -1227,7 +1227,7 @@ export class AppBridge extends Protocol<
* }
* ```
*/
sendResourceTeardown(
teardownResource(
params: McpUiResourceTeardownRequest["params"],
options?: RequestOptions,
) {
@ -1241,6 +1241,9 @@ export class AppBridge extends Protocol<
);
}
/** @deprecated Use {@link teardownResource} instead */
sendResourceTeardown: AppBridge["teardownResource"] = this.teardownResource;
/**
* Connect to the Guest UI via transport and optionally set up message forwarding.
*

View file

@ -824,7 +824,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* @example Open documentation link
* ```typescript
* try {
* await app.sendOpenLink({ url: "https://docs.example.com" });
* await app.openLink({ url: "https://docs.example.com" });
* } catch (error) {
* console.error("Failed to open link:", error);
* // Optionally show fallback: display URL for manual copy
@ -833,10 +833,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
*
* @see {@link McpUiOpenLinkRequest} for request structure
*/
sendOpenLink(
params: McpUiOpenLinkRequest["params"],
options?: RequestOptions,
) {
openLink(params: McpUiOpenLinkRequest["params"], options?: RequestOptions) {
return this.request(
<McpUiOpenLinkRequest>{
method: "ui/open-link",
@ -847,6 +844,9 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
);
}
/** @deprecated Use {@link openLink} instead */
sendOpenLink: App["openLink"] = this.openLink;
/**
* Request a change to the display mode.
*

View file

@ -2494,29 +2494,6 @@
"text": {
"type": "string"
},
"annotations": {
"type": "object",
"properties": {
"audience": {
"type": "array",
"items": {
"type": "string",
"enum": ["user", "assistant"]
}
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lastModified": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"_meta": {
"type": "object",
"propertyNames": {
@ -2541,29 +2518,6 @@
"mimeType": {
"type": "string"
},
"annotations": {
"type": "object",
"properties": {
"audience": {
"type": "array",
"items": {
"type": "string",
"enum": ["user", "assistant"]
}
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lastModified": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"_meta": {
"type": "object",
"propertyNames": {
@ -2588,29 +2542,6 @@
"mimeType": {
"type": "string"
},
"annotations": {
"type": "object",
"properties": {
"audience": {
"type": "array",
"items": {
"type": "string",
"enum": ["user", "assistant"]
}
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lastModified": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"_meta": {
"type": "object",
"propertyNames": {
@ -2662,29 +2593,6 @@
"mimeType": {
"type": "string"
},
"annotations": {
"type": "object",
"properties": {
"audience": {
"type": "array",
"items": {
"type": "string",
"enum": ["user", "assistant"]
}
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lastModified": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"_meta": {
"type": "object",
"properties": {},
@ -2755,29 +2663,6 @@
}
]
},
"annotations": {
"type": "object",
"properties": {
"audience": {
"type": "array",
"items": {
"type": "string",
"enum": ["user", "assistant"]
}
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lastModified": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"_meta": {
"type": "object",
"propertyNames": {
@ -3867,29 +3752,6 @@
"text": {
"type": "string"
},
"annotations": {
"type": "object",
"properties": {
"audience": {
"type": "array",
"items": {
"type": "string",
"enum": ["user", "assistant"]
}
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lastModified": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"_meta": {
"type": "object",
"propertyNames": {
@ -3914,29 +3776,6 @@
"mimeType": {
"type": "string"
},
"annotations": {
"type": "object",
"properties": {
"audience": {
"type": "array",
"items": {
"type": "string",
"enum": ["user", "assistant"]
}
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lastModified": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"_meta": {
"type": "object",
"propertyNames": {
@ -3961,29 +3800,6 @@
"mimeType": {
"type": "string"
},
"annotations": {
"type": "object",
"properties": {
"audience": {
"type": "array",
"items": {
"type": "string",
"enum": ["user", "assistant"]
}
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lastModified": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"_meta": {
"type": "object",
"propertyNames": {
@ -4035,29 +3851,6 @@
"mimeType": {
"type": "string"
},
"annotations": {
"type": "object",
"properties": {
"audience": {
"type": "array",
"items": {
"type": "string",
"enum": ["user", "assistant"]
}
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lastModified": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"_meta": {
"type": "object",
"properties": {},
@ -4128,29 +3921,6 @@
}
]
},
"annotations": {
"type": "object",
"properties": {
"audience": {
"type": "array",
"items": {
"type": "string",
"enum": ["user", "assistant"]
}
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lastModified": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"_meta": {
"type": "object",
"propertyNames": {

View file

@ -297,7 +297,7 @@ export const McpUiHostStylesSchema = z.object({
/**
* @description Request for graceful shutdown of the Guest UI (Host -> Guest UI).
* @see {@link app-bridge.AppBridge.sendResourceTeardown} for the host method that sends this
* @see {@link app-bridge.AppBridge.teardownResource} for the host method that sends this
*/
export const McpUiResourceTeardownRequestSchema = z.object({
method: z.literal("ui/resource-teardown"),

View file

@ -364,7 +364,7 @@ export interface McpUiHostContextChangedNotification {
/**
* @description Request for graceful shutdown of the Guest UI (Host -> Guest UI).
* @see {@link app-bridge.AppBridge.sendResourceTeardown} for the host method that sends this
* @see {@link app-bridge.AppBridge.teardownResource} for the host method that sends this
*/
export interface McpUiResourceTeardownRequest {
method: "ui/resource-teardown";