mcp-dashboards 2.0.0 → 2.1.0

package/dist/preview-server.d.ts

@@ -0,0 +1,8 @@
+import http from "node:http";
+export interface PreviewUrls {
+    httpUrl: string;
+    fileUrl: string;
+}
+export declare function getPreviewUrls(data: any): Promise<PreviewUrls | null>;
+export declare function getPreviewServer(): http.Server | null;
+//# sourceMappingURL=preview-server.d.ts.map

package/dist/preview-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-server.d.ts","sourceRoot":"","sources":["../preview-server.ts"],"names":[],"mappings":"AAEA,OAAO,IAAI,MAAM,WAAW,CAAC;AAyG7B,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAiB3E;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,CAErD"}

package/dist/preview-server.js

@@ -0,0 +1,115 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DIST_DIR = __filename.endsWith(".ts") ? path.join(__dirname, "dist") : __dirname;
+const MAX_CHARTS = 50;
+const TEMP_DIR = path.join(os.tmpdir(), "mcp-dashboards");
+const chartStore = new Map();
+let cachedHtml = null;
+let httpServer = null;
+let serverPort = null;
+async function loadHtml() {
+    if (cachedHtml)
+        return cachedHtml;
+    const htmlPath = path.join(DIST_DIR, "mcp-app.html");
+    cachedHtml = await fs.readFile(htmlPath, "utf-8");
+    return cachedHtml;
+}
+function injectChartData(html, data) {
+    const payload = JSON.stringify(data).replace(/<\//g, "<\\/");
+    return html.replace("</head>", `<script>window.__CHART_DATA__=${payload};</script></head>`);
+}
+function storeChart(data) {
+    const id = crypto.randomBytes(6).toString("hex");
+    chartStore.set(id, data);
+    // Evict oldest if over limit
+    if (chartStore.size > MAX_CHARTS) {
+        const firstKey = chartStore.keys().next().value;
+        if (firstKey)
+            chartStore.delete(firstKey);
+    }
+    return id;
+}
+async function ensurePreviewServer() {
+    if (serverPort !== null)
+        return serverPort;
+    return new Promise((resolve, reject) => {
+        const server = http.createServer(async (req, res) => {
+            try {
+                if (!req.url) {
+                    res.writeHead(404);
+                    res.end("Not Found");
+                    return;
+                }
+                const match = req.url.match(/^\/chart\/([a-f0-9]+)/);
+                if (!match) {
+                    res.writeHead(404);
+                    res.end("Not Found");
+                    return;
+                }
+                const data = chartStore.get(match[1]);
+                if (!data) {
+                    res.writeHead(404, { "Content-Type": "text/html" });
+                    res.end("<h1>Chart not found</h1><p>It may have been evicted or never existed.</p>");
+                    return;
+                }
+                const html = await loadHtml();
+                const injected = injectChartData(html, data);
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(injected);
+            }
+            catch (err) {
+                res.writeHead(500);
+                res.end(`Server error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (typeof addr === "object" && addr) {
+                serverPort = addr.port;
+                httpServer = server;
+                process.stderr.write(`[mcp-dashboards] Preview server ready at http://localhost:${serverPort}\n`);
+                process.on("exit", () => server.close());
+                resolve(serverPort);
+            }
+            else {
+                reject(new Error("Failed to bind preview server"));
+            }
+        });
+        server.on("error", reject);
+    });
+}
+async function writeTempHtml(id, data) {
+    await fs.mkdir(TEMP_DIR, { recursive: true });
+    const filePath = path.join(TEMP_DIR, `chart-${id}.html`);
+    const html = await loadHtml();
+    const injected = injectChartData(html, data);
+    await fs.writeFile(filePath, injected, "utf-8");
+    return pathToFileURL(filePath).href;
+}
+export async function getPreviewUrls(data) {
+    if (process.env.MCP_DASHBOARDS_DISABLE_PREVIEW === "1")
+        return null;
+    try {
+        const id = storeChart(data);
+        const port = await ensurePreviewServer();
+        const fileUrl = await writeTempHtml(id, data);
+        return {
+            httpUrl: `http://localhost:${port}/chart/${id}`,
+            fileUrl,
+        };
+    }
+    catch (err) {
+        process.stderr.write(`[mcp-dashboards] Preview unavailable: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+export function getPreviewServer() {
+    return httpServer;
+}
+//# sourceMappingURL=preview-server.js.map

package/dist/preview-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-server.js","sourceRoot":"","sources":["../preview-server.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../server.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoNpE;;GAEG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAm5CxC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../server.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoPpE;;GAEG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAs2CxC"}

package/dist/server.js

@@ -1,10 +1,11 @@
-import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import { getUiCapability, registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { getPreviewUrls } from "./preview-server.js";
 // Works both from source (server.ts) and compiled (dist/server.js)
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -154,6 +155,7 @@ function _registerChartTool(server, name, meta, inputSchema, buildResult, summar
             effects: EffectsParam,
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         const chartData = {
             ...buildResult(args),
@@ -162,15 +164,39 @@ function _registerChartTool(server, name, meta, inputSchema, buildResult, summar
             typography: args.typography,
             effects: args.effects,
         };
-        return {
-            content: [
-                { type: "text", text: summarize(args) },
-                { type: "text", text: JSON.stringify(chartData) },
-            ],
-            structuredContent: chartData,
-        };
+        return await _buildChartResult(server, chartData, summarize(args));
     });
 }
+// Tracks whether each server's connected client supports MCP Apps inline rendering.
+// Set via oninitialized callback in createServer.
+const _clientSupportsInline = new WeakMap();
+// Builds the standard tool response. If the client doesn't support MCP Apps
+// inline rendering, appends browser preview links (localhost HTTP + standalone file)
+// to the text content. MCP Apps clients only get the structuredContent - they
+// already render the chart inline, so preview URLs would be redundant clutter.
+async function _buildChartResult(server, chartData, summary) {
+    const content = [
+        { type: "text", text: summary },
+    ];
+    if (!_clientSupportsInline.get(server)) {
+        const urls = await getPreviewUrls(chartData);
+        if (urls) {
+            content.push({
+                type: "text",
+                text: `\n## View this chart\n` +
+                    `Your AI client doesn't render MCP Apps inline, so use one of these links to see the interactive chart in your browser:\n\n` +
+                    `**Click to open (recommended):** ${urls.httpUrl}\n` +
+                    `  - Opens instantly in your default browser\n` +
+                    `  - Only works while this MCP server is running\n\n` +
+                    `**Save or share:** ${urls.fileUrl}\n` +
+                    `  - Self-contained HTML file on your disk\n` +
+                    `  - Works offline, survives server restart, can be emailed or archived\n`,
+            });
+        }
+    }
+    content.push({ type: "text", text: JSON.stringify(chartData) });
+    return { content, structuredContent: chartData };
+}
 /**
  * Creates a new MCP Dashboards server instance.
  */
@@ -179,6 +205,12 @@ export function createServer() {
         name: "MCP Dashboards",
         version: "2.0.0",
     });
+    // After initialize handshake, detect if client supports MCP Apps inline rendering.
+    // Clients that do will see the interactive chart; those that don't get preview URLs.
+    server.server.oninitialized = () => {
+        const caps = server.server.getClientCapabilities?.();
+        _clientSupportsInline.set(server, !!getUiCapability(caps));
+    };
     // -- Shared HTML resource --
     registerAppResource(server, RESOURCE_URI, RESOURCE_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => {
         const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");
@@ -200,6 +232,7 @@ export function createServer() {
             effects: EffectsParam,
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         const chartData = {
             type: "pie",
@@ -215,13 +248,7 @@ export function createServer() {
         const summary = args.data
             .map((d) => `${d.label}: ${d.value} (${total > 0 ? ((d.value / total) * 100).toFixed(1) : "0.0"}%)`)
             .join(", ");
-        return {
-            content: [
-                { type: "text", text: `${args.title}: ${summary}` },
-                { type: "text", text: JSON.stringify(chartData) },
-            ],
-            structuredContent: chartData,
-        };
+        return await _buildChartResult(server, chartData, `${args.title}: ${summary}`);
     });
     // -- Tool: render_bar_chart --
     registerAppTool(server, "render_bar_chart", {
@@ -238,6 +265,7 @@ export function createServer() {
             effects: EffectsParam,
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         const chartData = {
             type: "bar",
@@ -253,13 +281,7 @@ export function createServer() {
         const summary = args.datasets
             .map((ds) => `${ds.label}: [${ds.data.join(", ")}]`)
             .join("; ");
-        return {
-            content: [
-                { type: "text", text: `${args.title} - ${summary}` },
-                { type: "text", text: JSON.stringify(chartData) },
-            ],
-            structuredContent: chartData,
-        };
+        return await _buildChartResult(server, chartData, `${args.title} - ${summary}`);
     });
     // -- Tool: render_line_chart --
     registerAppTool(server, "render_line_chart", {
@@ -276,6 +298,7 @@ export function createServer() {
             effects: EffectsParam,
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         const chartData = {
             type: "line",
@@ -291,13 +314,7 @@ export function createServer() {
         const summary = args.datasets
             .map((ds) => `${ds.label}: [${ds.data.join(", ")}]`)
             .join("; ");
-        return {
-            content: [
-                { type: "text", text: `${args.title} - ${summary}` },
-                { type: "text", text: JSON.stringify(chartData) },
-            ],
-            structuredContent: chartData,
-        };
+        return await _buildChartResult(server, chartData, `${args.title} - ${summary}`);
     });
     // -- Tool: render_hero_metric --
     const GemTypeEnum = z.enum([
@@ -397,6 +414,7 @@ export function createServer() {
             effects: EffectsParam,
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         const chartData = {
             type: "hero_metric",
@@ -404,13 +422,7 @@ export function createServer() {
         };
         const variant = args.variant || "big_number";
         const summary = `${args.title}: [${variant}] ${args.value ?? ""}${args.unit ? " " + args.unit : ""}`;
-        return {
-            content: [
-                { type: "text", text: summary },
-                { type: "text", text: JSON.stringify(chartData) },
-            ],
-            structuredContent: chartData,
-        };
+        return await _buildChartResult(server, chartData, summary);
     });
     // -- Tool: render_dashboard --
     const HeroSchema = z.object({
@@ -457,6 +469,7 @@ export function createServer() {
             layout: z.enum(["default", "hero-center", "kpi-top"]).optional().describe("Layout variant: default (hero above KPIs), hero-center (hero prominent), kpi-top (KPIs first)"),
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         const chartData = {
             type: "dashboard",
@@ -483,13 +496,7 @@ export function createServer() {
             const heroCount = Array.isArray(args.hero) ? args.hero.length : 1;
             parts.push(`Hero: ${heroCount} widget${heroCount > 1 ? "s" : ""}`);
         }
-        return {
-            content: [
-                { type: "text", text: parts.join(" | ") },
-                { type: "text", text: JSON.stringify(chartData) },
-            ],
-            structuredContent: chartData,
-        };
+        return await _buildChartResult(server, chartData, parts.join(" | "));
     });
     // -- Tool: render_chart_catalog --
     registerAppTool(server, "render_chart_catalog", {
@@ -499,6 +506,7 @@ export function createServer() {
             theme: ThemeParam,
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         // CSS-delegated charts spread c.data into the payload, so array data
         // must be wrapped as { data: [...] } to land on payload.data correctly.
@@ -595,20 +603,15 @@ export function createServer() {
             theme: args.theme,
             footer: { text: "mcp-dashboards", lastUpdated: "Also available: render_table, render_from_json, render_from_url, render_live_chart, poll_http" },
         };
-        return {
-            content: [
-                { type: "text", text: "Chart Catalog: 22 visual previews of every embeddable chart type. Click any card to ask about it. Standalone-only tools (table, live, auto, URL) listed in footer." },
-                { type: "text", text: JSON.stringify(chartData) },
-            ],
-            structuredContent: chartData,
-        };
+        return await _buildChartResult(server, chartData, "Chart Catalog: 22 visual previews of every embeddable chart type. Click any card to ask about it. Standalone-only tools (table, live, auto, URL) listed in footer.");
     });
     // -- Tool: render_theme_catalog --
     registerAppTool(server, "render_theme_catalog", {
         title: "Theme Catalog",
-        description: "Show a visual catalog of all 20 available themes. Each card previews the theme's colors, typography, and effects. Click any card to use that theme.",
+        description: "Show a visual catalog of all 21 available themes. Each card previews the theme's colors, typography, and effects. Click any card to use that theme.",
         inputSchema: {},
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async () => {
         return {
             content: [
@@ -789,6 +792,7 @@ export function createServer() {
             effects: EffectsParam,
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         const chartData = {
             type: "scatter",
@@ -803,13 +807,7 @@ export function createServer() {
         const summary = args.datasets
             .map((ds) => `${ds.label}: ${ds.data.length} points`)
             .join("; ");
-        return {
-            content: [
-                { type: "text", text: `${args.title} - ${summary}` },
-                { type: "text", text: JSON.stringify(chartData) },
-            ],
-            structuredContent: chartData,
-        };
+        return await _buildChartResult(server, chartData, `${args.title} - ${summary}`);
     });
     // -- Tool: render_candlestick_chart --
     registerAppTool(server, "render_candlestick_chart", {
@@ -825,6 +823,7 @@ export function createServer() {
             effects: EffectsParam,
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         const chartData = {
             type: "candlestick",
@@ -839,13 +838,7 @@ export function createServer() {
         const first = args.data[0];
         const last = args.data[args.data.length - 1];
         const change = last ? ((last.c - first.o) / first.o * 100).toFixed(2) : "0";
-        return {
-            content: [
-                { type: "text", text: `${args.title}: ${args.data.length} bars, ${first?.date ?? "?"} to ${last?.date ?? "?"}, change: ${change}%` },
-                { type: "text", text: JSON.stringify(chartData) },
-            ],
-            structuredContent: chartData,
-        };
+        return await _buildChartResult(server, chartData, `${args.title}: ${args.data.length} bars, ${first?.date ?? "?"} to ${last?.date ?? "?"}, change: ${change}%`);
     });
     // -- Tool: render_table --
     registerAppTool(server, "render_table", {
@@ -865,6 +858,7 @@ export function createServer() {
             effects: EffectsParam,
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         const chartData = {
             type: "table",
@@ -877,13 +871,7 @@ export function createServer() {
             typography: args.typography,
             effects: args.effects,
         };
-        return {
-            content: [
-                { type: "text", text: `${args.title}: ${args.rows.length} rows, ${args.columns.length} columns` },
-                { type: "text", text: JSON.stringify(chartData) },
-            ],
-            structuredContent: chartData,
-        };
+        return await _buildChartResult(server, chartData, `${args.title}: ${args.rows.length} rows, ${args.columns.length} columns`);
     });
     // -- Tool: render_from_json --
     registerAppTool(server, "render_from_json", {
@@ -897,6 +885,7 @@ export function createServer() {
             }).optional(),
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         const chartData = {
             type: "auto",
@@ -904,13 +893,7 @@ export function createServer() {
             data: args.data,
             options: args.options ?? {},
         };
-        return {
-            content: [
-                { type: "text", text: `Auto-visualizing: ${args.title}` },
-                { type: "text", text: JSON.stringify(chartData) },
-            ],
-            structuredContent: chartData,
-        };
+        return await _buildChartResult(server, chartData, `Auto-visualizing: ${args.title}`);
     });
     // -- Tool: render_from_url --
     registerAppTool(server, "render_from_url", {
@@ -924,6 +907,7 @@ export function createServer() {
             }).optional(),
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     }, async (args) => {
         try {
             const response = await fetch(args.url, {
@@ -943,13 +927,7 @@ export function createServer() {
                 data,
                 options: args.options ?? {},
             };
-            return {
-                content: [
-                    { type: "text", text: `Fetched and visualizing: ${args.title} (from ${args.url})` },
-                    { type: "text", text: JSON.stringify(chartData) },
-                ],
-                structuredContent: chartData,
-            };
+            return await _buildChartResult(server, chartData, `Fetched and visualizing: ${args.title} (from ${args.url})`);
         }
         catch (err) {
             return {
@@ -964,7 +942,7 @@ export function createServer() {
         filename: z.string().describe("Filename with extension (e.g. chart.png)"),
         data: z.string().describe("File contents: base64-encoded binary or plain text"),
         encoding: z.enum(["base64", "utf-8"]).describe("How data is encoded"),
-    }, async (args) => {
+    }, { readOnlyHint: false, destructiveHint: false, idempotentHint: true }, async (args) => {
         try {
             const sanitized = path.basename(args.filename);
             const downloadsDir = path.join(os.homedir(), "Downloads");
@@ -1341,7 +1319,7 @@ export function createServer() {
         headers: z.record(z.string(), z.string()).optional().describe("Extra HTTP headers (public APIs only - NEVER put API keys here)"),
         method: z.enum(["GET", "POST"]).optional().describe("HTTP method. Default: GET"),
         body: z.string().optional().describe("Request body for POST requests"),
-    }, async (args) => {
+    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async (args) => {
         try {
             let fetchUrl;
             let fetchHeaders = {};