0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/.mastracode
Marvin Frachet fc182d9c14
feat(mcp-apps-components): pin dashboard widgets through standard MCP Apps model context (#29488)
This makes dashboard widget pinning work with any MCP Apps host, using
only standard MCP Apps messages, and gives React hosts a small hook to
wire it up.

When the user clicks a pin, the app sends `ui/update-model-context` with
the full list of widgets the user wants pinned under
`mastra.ai/dashboard-pinned-widgets` in `structuredContent` (each entry
is `{ widget, scope, defaults }`), plus a short text block so the model
knows too. The host still owns the state: it sends pinned ids back in
host context and the buttons follow that. Pin and drilldown state go in
the same update, so one never wipes the other, and quick clicks build on
each other until the host answers. Pin buttons only show when the host
holds the ids array and advertises
`updateModelContext.structuredContent`. Hosts parse the payload with
`dashboardPinnedWidgetsSchema`.

On the host side, `@mastra/playground-ui/domains/mcps` gets
`McpAppHostProvider`, which lets a chat add host-context keys per app
instance and receive raw model context with the app it came from,
without reloading the iframe. The existing text model-context path is
unchanged, and without the provider nothing changes.
`@mastra/mcp-apps-components/host` adds `useMcpAppHost`, which parses
and routes pin updates; that subpath doesn't pull in the app's HTML (1.6
KB vs 2.1 MB).

```tsx
import { McpAppHostProvider } from '@mastra/playground-ui/domains/mcps';
import { useMcpAppHost } from '@mastra/mcp-apps-components/host';

const host = useMcpAppHost({ dashboardPins: { pinnedIds, onPinnedChange } });
<McpAppHostProvider value={host}>{chat}</McpAppHostProvider>;
```

`@mastra/mcp-apps-components` is also added to the playground-snapshot
publish job so the platform frontend can pick it up with playground-ui.

Tested with the real app over an in-memory AppBridge (pin/unpin round
trip through `useMcpAppHost`, rapid clicks, host declining a pin,
drilldown + pins coexisting, capability gating, invalid payloads) and
MSW-backed tests for `McpAppToolResult`/`McpAppViewer` (host-context
changes reach the running app without reload, raw params reach
`onModelContext`, read-only and no-provider cases). Key behaviors were
mutation-checked. Typecheck, oxlint and builds pass for both packages.


Also checked by hand in Studio against `examples/agent`'s dashboard
agent, with a temporary `useMcpAppHost` provider around the chat: pin →
unpin → pin sends exactly one host update per click (with the widget's
defaults), the iframe never reloads, and the agent correctly names the
pinned widget from model context alone.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## ELI5

The dashboard can now send its pinned widgets to the app that hosts it.
The host can save those choices and send them back, while apps that do
not use the new host support can continue to work.

## What changed

- Added `McpAppHostProvider` to `@mastra/playground-ui/domains/mcps`. It
provides per-app host context and receives raw model-context updates
while the app is running.
- Added the `@mastra/mcp-apps-components/host` export and
`useMcpAppHost` hook. Hosts can provide pinned widget IDs and handle
validated pin updates.
- Changed dashboard pinning to use `ui/update-model-context`. The app
sends the full requested widget list under
`mastra.ai/dashboard-pinned-widgets`, with a text description and
request number. Pin and drilldown state share an update.
- Pin controls require host-provided pin IDs and support for
`updateModelContext.structuredContent`. The host can disable pinning by
setting the pin context value to `null`.
- Removed the dashboard pin notification API. Hosts now use the
pinned-widget schemas and model-context updates.
- Added `@mastra/mcp-apps-components` to the playground snapshot publish
workflow and updated snapshot release guidance. Snapshot checks and
publishing use production dependency filters.

## Compatibility

Apps can continue to work without `McpAppHostProvider`. The former
dashboard pin notification API was removed and replaced with
model-context updates.

## Tests and validation

Added tests for pin and unpin interactions, pending and declined
requests, host-context updates, model-context handling, capability
gating, and invalid pin data. The PR objectives report typecheck,
oxlint, and builds passing for both packages, plus manual Studio checks.
These results were not independently verified.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
History 2026-11-04 17:15:46 -08:00
..
commands docs: strengthen authoring guardrails and prose lint workflow (#28256) 2026-10-23 14:34:31 +02:00
resources docs: add CRITICAL_PATHS.md for AI triage automation (#19091) 2026-07-08 17:39:28 +05:30
skills feat(mcp-apps-components): pin dashboard widgets through standard MCP Apps model context (#29488) 2026-11-04 17:15:46 -08:00