@mastra/mcp-apps-components 0.0.0-breadcrumb-chevrons-20261105145508

package/LICENSE.md

@@ -0,0 +1,32 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named `ee/` within this
+  repository, including but not limited to:
+  - `@mastra/core/auth/ee`
+  - `@mastra/core/agent-builder/ee`
+  - `@mastra/editor/ee`
+
+  is licensed under the license defined in [`ee/LICENSE`](https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE).
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,187 @@
+# @mastra/mcp-apps-components
+
+Prebuilt [MCP Apps](https://mastra.ai/docs/connections/mcp) that render Mastra UI components inside any MCP App host, such as Mastra Studio. Each app ships as a self-contained HTML resource you register on an `MCPServer`, plus a server-side helper to link it to your tools.
+
+The apps never reach the network from their iframe. Each read they make travels as a call to one app-only data tool that you register on the same server.
+
+## Installation
+
+```bash
+npm install @mastra/mcp-apps-components
+```
+
+## Usage
+
+Register the dashboard renderer on an `MCPServer`, then return a dashboard definition from a tool linked to the app's `ui://` URI.
+
+```typescript
+import type { DashboardDefinition } from '@mastra/core/storage/dashboards';
+import { createTool } from '@mastra/core/tools';
+import { MCPServer } from '@mastra/mcp';
+import { dashboardDataTool } from '@mastra/mcp-apps-components/dashboard-data-tool';
+import { dashboardRendererApp, dashboardRendererInputSchema } from '@mastra/mcp-apps-components/dashboard-renderer';
+import { z } from 'zod';
+
+const DASHBOARD_APP_URI = 'ui://mastra/dashboard';
+
+const agentRuns: DashboardDefinition = {
+  schemaVersion: 1,
+  defaults: { datePreset: '7d' },
+  rows: [
+    {
+      widgets: [
+        {
+          id: 'runs',
+          span: 12,
+          kind: 'kpis',
+          views: [
+            {
+              queries: [
+                {
+                  id: 'runs',
+                  source: 'metrics',
+                  request: 'aggregate',
+                  name: ['mastra_agent_duration_ms'],
+                  aggregation: 'count',
+                },
+              ],
+              options: { items: [{ label: 'Agent runs', format: 'count', value: { query: 'runs' } }] },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+const showAgentRuns = createTool({
+  id: 'showAgentRuns',
+  description: 'Shows how many agent runs happened in the last 7 days',
+  inputSchema: z.object({}),
+  outputSchema: dashboardRendererInputSchema,
+  mcp: { _meta: { ui: { resourceUri: DASHBOARD_APP_URI } } },
+  execute: async () => ({ definition: agentRuns, scope: 'project' as const }),
+});
+
+export const dashboardServer = new MCPServer({
+  id: 'dashboard-server',
+  name: 'Dashboard Server',
+  version: '1.0.0',
+  appResources: { [DASHBOARD_APP_URI]: dashboardRendererApp() },
+  tools: { showAgentRuns, dashboardDataTool },
+});
+```
+
+### Data tool
+
+Register `dashboardDataTool`, from `@mastra/mcp-apps-components/dashboard-data-tool`, under that exact key, next to the app. The app calls it by name for every read its dashboard makes, such as `getMetricAggregate`. Without it, each widget fails with a message telling you to register it.
+
+The tool runs the observability route behind each read in-process as the caller, with `invokeRoute()` from `@mastra/server`, so the route's own validation, authentication, permission and FGA checks apply and the app sees the same data the signed-in user can. It only answers the reads in `DASHBOARD_DATA_OPERATIONS`, and it's app-only, so hosts keep it away from the model.
+
+Only the `dashboard-data-tool` entry needs `@mastra/server`, which any Mastra server already has. When the server has authentication configured, reads made over an MCP transport that carries no signed-in user, such as stdio, answer with `401`.
+
+### Answering the data tool yourself
+
+A host that reads observability data its own way, such as one serving several projects, can register its own `dashboardDataTool` instead. Import the contract from `@mastra/mcp-apps-components/dashboard-renderer`, which doesn't load `@mastra/server`: `DASHBOARD_DATA_TOOL_NAME`, `DASHBOARD_DATA_OPERATIONS`, `DASHBOARD_DATA_REQUESTS`, `dashboardDataInputSchema` and `dashboardDataOutputSchema`.
+
+To tell the tool which project to read, set `projectId` in the dashboard's tool result. The app sends it as `projectId` on every data tool call. Mastra's `dashboardDataTool` reads the one project its server holds and ignores it.
+
+### Pinning widgets
+
+Each widget shows a pin button when the host says it can pin. The host owns the pinned widgets; the app only reports which ones the user wants. Everything goes through standard MCP Apps messages.
+
+1. The host sets `mastra.ai/dashboard-pinned-widgets` in its host context to the ids of the widgets it has pinned (`[]` for none) and advertises `updateModelContext.structuredContent`. Without both, no pin buttons show.
+2. When the user clicks a widget's button, the app sends `ui/update-model-context` with the **full list** of widgets the user wants pinned under the same key in `structuredContent`. Each entry is `{ widget, scope, defaults? }`: the widget definition, the dashboard's scope, and the date range and filters the user had on, which together render the pinned widget on its own as the user saw it. Only widgets pinned since the app loaded carry `defaults`; for the rest, keep the defaults you stored. The update also has a short text block describing the pins, so the model sees them too, and a request number under `mastra.ai/dashboard-pin-request`.
+3. The host stores what it accepts and sends back, in its host context, the new list of ids and the request number it handled. Each button follows the host, not the click.
+
+Every model context update replaces the previous one, so each update the dashboard sends carries both its pin state and its last drilldown. An update without the pin key carries no pin state; it never means "nothing pinned".
+
+#### In a React host built on `@mastra/playground-ui`
+
+`useMcpAppHost` from the `@mastra/mcp-apps-components/host` subpath does the parsing and routing. That subpath doesn't include the app's HTML, so it adds nothing heavy to the host bundle.
+
+```tsx
+import { useCallback, useState } from 'react';
+import { McpAppHostProvider } from '@mastra/playground-ui/domains/mcps';
+import { useMcpAppHost } from '@mastra/mcp-apps-components/host';
+import type { McpAppRef, DashboardPinnedWidgetEntry } from '@mastra/mcp-apps-components/host';
+
+function ChatWithPins({ children }: { children: React.ReactNode }) {
+  // Widget ids are only unique within one dashboard, so key them by tool call.
+  const [pins, setPins] = useState<Record<string, string[]>>({});
+
+  const pinnedIds = useCallback(
+    (app: McpAppRef) => (app.resourceUri === DASHBOARD_APP_URI ? (pins[app.toolCallId] ?? []) : undefined),
+    [pins],
+  );
+  const onPinnedChange = async (pinned: DashboardPinnedWidgetEntry[], app: McpAppRef) => {
+    // Full list, not a change: diff it, return the ids you kept. If this throws, the pins count as turned down.
+    const ids = await savePinnedWidgets(app.toolCallId, pinned);
+    setPins(current => ({ ...current, [app.toolCallId]: ids }));
+  };
+
+  const host = useMcpAppHost({ dashboardPins: { pinnedIds, onPinnedChange } });
+  return <McpAppHostProvider value={host}>{children}</McpAppHostProvider>;
+}
+```
+
+`pinnedIds` returns `[]` for none, `null` to turn pinning off for an app, or `undefined` for apps that aren't dashboards. The hook echoes each handled request number back for you once `onPinnedChange` returns or its promise settles, so update `pinnedIds` by then; ids you don't add are pins you turned down. If `onPinnedChange` throws or rejects, the error is logged and the pins count as turned down. Updates from one app instance wait for the previous `onPinnedChange` to settle, so an older save never lands after a newer one. Invalid payloads are dropped and logged, never passed to `onPinnedChange`.
+
+#### With `AppBridge` directly
+
+The params come from the app's iframe, so parse them with `dashboardPinnedWidgetsSchema` before storing or rendering anything.
+
+```typescript
+import { AppBridge } from '@modelcontextprotocol/ext-apps/app-bridge';
+import {
+  DASHBOARD_PIN_REQUEST_CONTEXT_KEY,
+  DASHBOARD_PINNED_WIDGETS_CONTEXT_KEY,
+  dashboardPinnedWidgetsSchema,
+} from '@mastra/mcp-apps-components/dashboard-renderer';
+
+let hostContext = { theme: 'dark' as const, [DASHBOARD_PINNED_WIDGETS_CONTEXT_KEY]: [] as string[] };
+const bridge = new AppBridge(
+  client,
+  hostInfo,
+  { ...capabilities, updateModelContext: { text: {}, structuredContent: {} } },
+  { hostContext },
+);
+
+bridge.onupdatemodelcontext = async ({ structuredContent }) => {
+  if (!structuredContent || !(DASHBOARD_PINNED_WIDGETS_CONTEXT_KEY in structuredContent)) return {};
+  const parsed = dashboardPinnedWidgetsSchema.safeParse(structuredContent[DASHBOARD_PINNED_WIDGETS_CONTEXT_KEY]);
+  if (!parsed.success) return {};
+
+  const ids = await savePinnedWidgets(parsed.data); // full list: diff it, return the ids you kept
+  // setHostContext replaces the whole context, so keep the other fields. Echo the request number,
+  // so the app knows you answered even when you turned a pin down and the ids stay the same.
+  hostContext = {
+    ...hostContext,
+    [DASHBOARD_PINNED_WIDGETS_CONTEXT_KEY]: ids,
+    [DASHBOARD_PIN_REQUEST_CONTEXT_KEY]: structuredContent[DASHBOARD_PIN_REQUEST_CONTEXT_KEY],
+  };
+  bridge.setHostContext(hostContext);
+  return {};
+};
+```
+
+Keep in mind:
+
+- To turn pinning off, set the key to a non-array value such as `null`. Deleting the key does nothing, because `AppBridge` only sends the fields that changed, so the app keeps the last ids it got.
+- Widget ids are only unique within one dashboard definition. Keep pinned ids per bridge (one tool call), not across dashboards.
+- Until the host answers a click, the app applies it on top of the host's ids, so quick clicks don't drop pins. A click is answered once the host echoes a request number at or above the one it was sent with, or once the host's ids already reflect it. A pin the host declines then drops, and the next click doesn't resend it.
+- If the app's model context update fails, its clicks drop, and the buttons show the host's ids again.
+- A widget that no longer parses shows no pin button, so the host owns unpinning it.
+
+## Documentation
+
+- [Build MCP Apps](https://mastra.ai/docs/connections/mcp)
+- [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server)
+
+## Changelog
+
+See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/packages/mcp-apps-components/CHANGELOG.md) for version history and release notes.
+
+## Support
+
+We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.

package/dist/apps/dashboard-renderer/data-tool.d.ts

@@ -0,0 +1,22 @@
+import type { ServerRoute } from '@mastra/server/server-adapter';
+import type { DashboardDataOperation } from './data.js';
+/** The Mastra route that answers each read. */
+export declare const DASHBOARD_DATA_ROUTES: Record<DashboardDataOperation, ServerRoute>;
+/**
+ * The app-only tool the dashboard reads its data through. Register it next to
+ * `dashboardRendererApp` on the MCP server that serves the app. Each read runs its Mastra route
+ * in-process as the caller, with the route's own input validation, authentication, RBAC permission
+ * and FGA checks, so the app sees exactly the data the signed-in user can read over HTTP. It runs
+ * only the routes in `DASHBOARD_DATA_ROUTES`. It reads the one project its server holds, so it
+ * ignores a call's `projectId`.
+ */
+export declare const dashboardDataTool: import("@mastra/core/tools").Tool<{
+    operation: "aggregateSpans" | "aggregateTraces" | "getMetricAggregate" | "getMetricBreakdown" | "getMetricPercentiles" | "getMetricTimeSeries" | "getScoreAggregate" | "getScoreBreakdown" | "getScorePercentiles" | "getScoreTimeSeries" | "listScores";
+    query?: Record<string, string | string[]> | undefined;
+    body?: Record<string, unknown> | undefined;
+    projectId?: string | undefined;
+}, {
+    status: number;
+    body: unknown;
+}, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "dashboardDataTool", unknown>;
+//# sourceMappingURL=data-tool.d.ts.map

package/dist/apps/dashboard-renderer/data-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-tool.d.ts","sourceRoot":"","sources":["../../../src/apps/dashboard-renderer/data-tool.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,OAAO,KAAK,EAAE,sBAAsB,EAAuB,MAAM,QAAQ,CAAC;AAE1E,+CAA+C;AAC/C,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,sBAAsB,EAAE,WAAW,CAY7E,CAAC;AAOF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;gIA0B5B,CAAC"}

package/dist/apps/dashboard-renderer/data.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+/**
+ * The app-only tool the dashboard reads its data through. The app runs in a sandboxed iframe that
+ * hosts may forbid from reaching the server, so each read travels as a call to this tool over the
+ * host's existing MCP connection. An MCP server names a tool by the key it's registered under, so
+ * this matches the export: `tools: { dashboardDataTool }`.
+ */
+export declare const DASHBOARD_DATA_TOOL_NAME = "dashboardDataTool";
+/** Every read the dashboard makes, named after the `MastraClient` method that makes it. */
+export declare const DASHBOARD_DATA_OPERATIONS: readonly ['aggregateTraces', 'aggregateSpans', 'getMetricAggregate', 'getMetricBreakdown', 'getMetricTimeSeries', 'getMetricPercentiles', 'listScores', 'getScoreAggregate', 'getScoreBreakdown', 'getScoreTimeSeries', 'getScorePercentiles'];
+export type DashboardDataOperation = (typeof DASHBOARD_DATA_OPERATIONS)[number];
+/**
+ * The Mastra route behind each read: the request `MastraClient` makes for it, without the server's
+ * API prefix. A server that answers the data tool with its own routes can look them up here.
+ */
+export declare const DASHBOARD_DATA_REQUESTS: {
+    aggregateTraces: string;
+    aggregateSpans: string;
+    getMetricAggregate: string;
+    getMetricBreakdown: string;
+    getMetricTimeSeries: string;
+    getMetricPercentiles: string;
+    listScores: string;
+    getScoreAggregate: string;
+    getScoreBreakdown: string;
+    getScoreTimeSeries: string;
+    getScorePercentiles: string;
+};
+export declare const dashboardDataInputSchema: z.ZodObject<{
+    operation: z.ZodEnum<{
+        aggregateSpans: "aggregateSpans";
+        aggregateTraces: "aggregateTraces";
+        getMetricAggregate: "getMetricAggregate";
+        getMetricBreakdown: "getMetricBreakdown";
+        getMetricPercentiles: "getMetricPercentiles";
+        getMetricTimeSeries: "getMetricTimeSeries";
+        getScoreAggregate: "getScoreAggregate";
+        getScoreBreakdown: "getScoreBreakdown";
+        getScorePercentiles: "getScorePercentiles";
+        getScoreTimeSeries: "getScoreTimeSeries";
+        listScores: "listScores";
+    }>;
+    query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+    body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    projectId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DashboardDataInput = z.output<typeof dashboardDataInputSchema>;
+/** What the tool answers: a status and body, as the matching Mastra route would over HTTP. */
+export declare const dashboardDataOutputSchema: z.ZodObject<{
+    status: z.ZodNumber;
+    body: z.ZodUnknown;
+}, z.core.$strip>;
+export type DashboardDataOutput = z.output<typeof dashboardDataOutputSchema>;
+//# sourceMappingURL=data.d.ts.map

package/dist/apps/dashboard-renderer/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../../src/apps/dashboard-renderer/data.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAE5D,2FAA2F;AAC3F,eAAO,MAAM,yBAAyB,YACpC,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,CACb,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhF;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;CAYc,CAAC;AAInD,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;iBAmBjC,CAAC;AAEL,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAK3E,8FAA8F;AAC9F,eAAO,MAAM,yBAAyB;;;iBAQpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC"}