feat: add ui/update-model-context

[idosal]

This new message allows the UI to update the Host's model context without triggering a follow-up action.

`ui/update-model-context` - Update the Host's model context

// Request
{
  jsonrpc: "2.0",
  id: 3,
  method: "ui/update-model-context",
  params: {
    role: "user",
    content: ContentBlock[]
  }
}

Guest UI MAY send this request to inform the agent about app state changes that should be added to the model's context for future reasoning. This event serves a different use case from `notifications/message` (logging) and `ui/message` (which also trigger followups).

Host behavior:
- SHOULD provide the context to the model in future turns
- SHOULD overwrite the previous model context with the new update
- MAY display context updates to the user

notifications/message remains another message type with MCP's original intent.

Addresses #61.

Note: the params's type (content: ContentBlock[]) may be problematic for the MVP. It's subject to the same decision as #119 (comment)

[pkg-pr-new]

Open in StackBlitz

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

commit: a809478

[Copilot]

Pull request overview

This PR introduces the ui/update-context request to allow Guest UI applications to inform the host agent about app state changes that should be stored in the conversation context for future reasoning, without triggering follow-up actions. This addresses the need to distinguish between logging messages (notifications/message), interactive messages that expect follow-ups (ui/message), and context updates that inform the agent's reasoning.

Key changes:

• Added ui/update-context request type with role and ContentBlock[] parameters
• Extended host capabilities to include optional context capability for negotiation
• Implemented sendContext() method in App class and oncontext handler in AppBridge class

Reviewed changes

Copilot reviewed 6 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/types.ts	Re-exports new McpUiUpdateContextRequest/Result types and schemas
src/spec.types.ts	Defines TypeScript interfaces for update-context request/result and adds context capability to McpUiHostCapabilities
src/generated/schema.ts	Adds Zod schemas for validating update-context requests and results
src/generated/schema.test.ts	Adds type inference tests to verify schema/type compatibility
src/generated/schema.json	Contains JSON schema definitions for update-context with full ContentBlock support
src/app.ts	Implements sendContext() method for Guest UI to send context updates to host
src/app-bridge.ts	Implements oncontext handler for Host to receive context updates from Guest UI
src/app-bridge.test.ts	Adds integration tests covering basic sendContext functionality with single and multiple content blocks
specification/draft/apps.mdx	Documents ui/update-context in the protocol specification with examples and host behavior guidelines

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 9 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 9 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ochafik]

Something to discuss: I wonder if we want to go full multimedia on this one.
Also, in OAI Apps SDK the updates are essentially structuredContent, and text might also often be the most useful kind of update, so both would place us in the territory of Pick<CallToolResult, 'content' | 'structuredContent' | 'isError'> more than a message content block array

[ochafik]

We probably also need to mention that the host MAY defer sending the context to the model, and it MAY dedupe identical ui/update-context calls.

Potentially we could add a boolean that says it replaces / purges any previously pending

[idosal]

1. How about SHOULD provide the context to the model in future turns?
2. We always replace now

[ochafik]

And should this be ui/update-semantic-state?

[idosal]

I think semantic-state isn't as self-documenting as model-context

[antonpk1]

Thanks for the proposal! I think we should design the state that only the last 'context-update' is used, and all past context updates are disregarded.

Here's a specific example: imagine a text-editor app. The user can write and edit text and wants to be able to ask the agent to help/reflect/act on the current text state.

Problem with the current proposal: if we send a 'context-update' with full text on every character change, it will quickly pollute the entire context window and won't work well.

At the same time, if an app wants to share context with a chronological history of events like in current proposal, nothing prevents them from accumulating an array and passing that as a 'context-update'.

[idosal]

Thanks for the proposal! I think we should design the state that only the last 'context-update' is used, and all past context updates are disregarded.

Here's a specific example: imagine a text-editor app. The user can write and edit text and wants to be able to ask the agent to help/reflect/act on the current text state.

Problem with the current proposal: if we send a 'context-update' with full text on every character change, it will quickly pollute the entire context window and won't work well.

At the same time, if an app wants to share context with a chronological history of events like in current proposal, nothing prevents them from accumulating an array and passing that as a 'context-update'.

After further discussions, for the MVP, we propose clarifying that ui/update-model-context will overwrite the previous state. In the future, following community feedback and requirements, we can extend it to enable maintaining history and other enhancements.

[idosal]

Something to discuss: I wonder if we want to go full multimedia on this one. Also, in OAI Apps SDK the updates are essentially structuredContent, and text might also often be the most useful kind of update, so both would place us in the territory of Pick<CallToolResult, 'content' | 'structuredContent' | 'isError'> more than a message content block array

I think this is the last open item. I can see value in pushing non-textual information (like images) into context. Thoughts?