modelcontextprotocol/ext-apps
Watch
1
0
Fork
You've already forked ext-apps
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

refactor: use MCP resource types for ui/download-file params

Browse source 
Replace custom {filename, content, mimeType, encoding} params with
standard MCP resource types: EmbeddedResource for inline content and
ResourceLink for host-resolved references.

New params shape:
  params: { contents: (EmbeddedResource | ResourceLink)[] }

This reuses existing MCP primitives instead of inventing new ones,
and enables hosts to show resource 'bubbles' or resolve ResourceLink
URIs via resources/read on the MCP server.
This commit is contained in:
Anton Pidkuiko MacBook 2026-02-20 12:00:35 +00:00
commit 3757271641
No known key found for this signature in database
1 changed files with 366 additions and 125 deletions
Download patch file Download diff file Expand all files Collapse all files

42
specification/draft/apps.mdx
View file

@ -1018,16 +1018,39 @@ Host SHOULD open the URL in the user's default browser or a new tab.
`ui/download-file` - Request host to download a file
```typescript
// Request
// Request (EmbeddedResource — inline content)
{
jsonrpc: "2.0",
id: 1,
method: "ui/download-file",
params: {
filename: string, // Suggested filename
content: string, // File content (text or base64-encoded)
mimeType: string, // MIME type (e.g. "image/svg+xml", "application/json")
encoding?: "utf-8" | "base64" // Content encoding, defaults to "utf-8"
contents: [
{
type: "resource",
resource: {
uri: "file:///export.json", // Used for suggested filename
mimeType: "application/json",
text: "{ ... }" // Text content (or `blob` for base64 binary)
}
}
]
}
}
// Request (ResourceLink — host fetches)
{
jsonrpc: "2.0",
id: 1,
method: "ui/download-file",
params: {
contents: [
{
type: "resource_link",
uri: "https://api.example.com/reports/q4.pdf",
name: "Q4 Report",
mimeType: "application/pdf"
}
]
}
}
@ -1051,12 +1074,15 @@ Host SHOULD open the URL in the user's default browser or a new tab.
MCP Apps run in sandboxed iframes where direct file downloads are blocked (`allow-downloads` is not set). `ui/download-file` provides a host-mediated mechanism for apps to offer file exports — useful for visualization tools (SVG/PNG export), document editors, data analysis tools, and any app that produces downloadable artifacts.
The `contents` array uses standard MCP resource types (`EmbeddedResource` and `ResourceLink`), avoiding custom content formats. For `EmbeddedResource`, content is inline via `text` (UTF-8) or `blob` (base64). For `ResourceLink`, the host can retrieve the content directly from the URI.
Host behavior:
* Host SHOULD show a confirmation dialog before initiating the download.
* Host SHOULD use the `filename` as the suggested filename for the download.
* For `encoding: "base64"`, host MUST decode the content from base64 before creating the file.
* For `EmbeddedResource`, host SHOULD derive the filename from the last segment of `resource.uri`.
* For `EmbeddedResource` with `blob`, host MUST decode the content from base64 before creating the file.
* For `ResourceLink`, host MAY fetch the resource on behalf of the app or open the URI directly.
* Host MAY reject the download based on security policy, file size limits, or user preferences.
* Host SHOULD sanitize the filename to prevent path traversal.
* Host SHOULD sanitize filenames to prevent path traversal.
`ui/message` - Send message content to the host's chat interface