mcp-dashboards 2.0.1 → 2.2.0

package/dist/server.js

@@ -5,6 +5,8 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { getPreviewUrls, evictChartFromCache, TEMP_DIR, CHART_FILENAME_RE } from "./preview-server.js";
+import { assertSafeUrl, acquireOutbound, UrlSafetyError } from "./url-safety.js";
 // Works both from source (server.ts) and compiled (dist/server.js)
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -19,7 +21,7 @@ const PieDataItem = z.object({
 });
 const ColorsOption = z.array(z.string()).optional().describe("Custom color palette as hex codes (e.g. ['#FF6384', '#36A2EB']). Uses default palette if omitted.");
 // Shared theme parameters for all chart tools
-const ThemeParam = z.string().optional().describe("Theme preset: boardroom, corporate, sales-floor, golden-treasury, clinical, startup, ops-control, tokyo-midnight, zen-garden, consultant, black-tron, black-elegance, black-matrix, forest-amber, forest-earth, sky-light, sky-ocean, sky-twilight, gray-hf, gray-copilot");
+const ThemeParam = z.string().optional().describe("Theme preset: boardroom, corporate, sales-floor, golden-treasury, clinical, startup, ops-control, tokyo-midnight, zen-garden, consultant, black-tron, black-elegance, black-matrix, forest-amber, forest-earth, sky-light, sky-ocean, sky-twilight, gray-hf, gray-copilot, office-red");
 const PaletteParam = z.string().optional().describe("Override palette only (mix-and-match)");
 const TypographyParam = z.string().optional().describe("Override typography: professional, luxury, cyberpunk, editorial, mono, bold, system, techno");
 const EffectsParam = z.string().optional().describe("Override effects: none, subtle, shimmer, neon, energetic");
@@ -154,6 +156,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,22 +165,64 @@ 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));
     });
 }
+// Builds the standard tool response. Writes a self-contained HTML file for the
+// chart AND lazy-starts a same-machine HTTP server (127.0.0.1, random port) so
+// the chart can be opened, saved, and shared from a browser regardless of
+// which client is in use:
+//
+//   - Apps-aware clients (Claude Code, Claude Desktop, VS Code Insiders):
+//     chart renders inline from structuredContent + _meta.ui.resourceUri.
+//     The localhost URL is still useful for "open in browser to print", save
+//     a permanent copy, or share with a colleague.
+//
+//   - Non-Apps clients (generic LLM IDE plugins, older clients): the URL is
+//     the only way to view the chart at all.
+//
+// Why we always emit URLs (no capability detection): Claude Code v2.1.x does
+// not advertise capabilities.extensions["io.modelcontextprotocol/ui"], so any
+// capability-based detection silently treats it as non-Apps and is therefore
+// dead code. The shareable HTML link is genuinely useful even when the chart
+// renders inline.
+//
+// Opt out entirely with MCP_DASHBOARDS_DISABLE_PREVIEW=1.
+async function _buildChartResult(_server, chartData, summary) {
+    const urls = await getPreviewUrls(chartData);
+    // Mirror preview URLs into structuredContent for clients that surface it
+    // (e.g. Claude Code dumps structuredContent as JSON). Renderers ignore
+    // unknown fields, so MCP Apps clients are unaffected.
+    const enrichedChartData = urls
+        ? { ...chartData, preview: { browser: urls.httpUrl, file: urls.fileUrl } }
+        : chartData;
+    const enrichedSummary = urls
+        ? `${summary}\n\n[Open chart in browser](${urls.httpUrl}) - clickable link to view the interactive chart. AI assistant: please include this link verbatim in your reply so the user can click it. The standalone HTML file at ${urls.fileUrl} can be saved or shared (auto-deleted after 7 days). The user can ask you to delete chart files anytime via the delete_chart_files tool.`
+        : summary;
+    const content = [
+        { type: "text", text: enrichedSummary },
+    ];
+    if (urls) {
+        content.push({
+            type: "text",
+            text: `\n## View this chart\n` +
+                `If the chart renders inline above, you're done. Otherwise click the link below:\n\n` +
+                `**[Open chart in browser](${urls.httpUrl})**\n\n` +
+                `Or save/share the standalone HTML file: ${urls.fileUrl}\n` +
+                `- Auto-deleted after ${process.env.MCP_DASHBOARDS_RETAIN_DAYS ?? "7"} days (configure via MCP_DASHBOARDS_RETAIN_DAYS, 0 disables)\n` +
+                `- Use the chart's download button inside the rendered HTML to save a permanent copy (PNG / PPT / A4)\n`,
+        });
+    }
+    content.push({ type: "text", text: JSON.stringify(enrichedChartData) });
+    return { content, structuredContent: enrichedChartData };
+}
 /**
  * Creates a new MCP Dashboards server instance.
  */
 export function createServer() {
     const server = new McpServer({
         name: "MCP Dashboards",
-        version: "2.0.0",
+        version: "2.2.0",
     });
     // -- Shared HTML resource --
     registerAppResource(server, RESOURCE_URI, RESOURCE_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => {
@@ -186,7 +231,6 @@ export function createServer() {
             contents: [{ uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html }],
         };
     });
-    // -- Tool: render_pie_chart --
     registerAppTool(server, "render_pie_chart", {
         title: "Pie Chart",
         description: "Render an interactive pie or donut chart from key-value data. Provide an array of {label, value} pairs. Supports themes for styled visuals.",
@@ -200,6 +244,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,15 +260,8 @@ 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", {
         title: "Bar Chart",
         description: "Render an interactive bar chart. Supports vertical/horizontal, stacked, multi-series, and click-to-drill-down (options.drilldown). Supports themes for styled visuals.",
@@ -238,6 +276,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,15 +292,8 @@ 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", {
         title: "Line Chart",
         description: "Render an interactive line or area chart. Supports smooth curves, gradient fill, and multiple series. Supports themes for styled visuals.",
@@ -276,6 +308,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,15 +324,8 @@ 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([
         "diamond", "ruby", "sapphire", "emerald",
         "golden_pearl", "white_pearl", "black_pearl", "crystal",
@@ -397,6 +423,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,15 +431,8 @@ 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({
         variant: HeroVariantEnum.optional().describe("Hero variant (default: progress_ring for dashboard)"),
         value: z.union([z.string(), z.number()]).optional().describe("Hero metric value"),
@@ -442,7 +462,7 @@ export function createServer() {
     });
     registerAppTool(server, "render_dashboard", {
         title: "Dashboard",
-        description: "Render a full dashboard with KPI cards, charts, and optional hero metric in a responsive grid. Available themes: boardroom (investors, board decks), corporate (enterprise daily use), sales-floor (quota tracking, leaderboards), golden-treasury (wealth, luxury real estate), clinical (healthcare, compliance - WCAG AAA), startup (SaaS metrics, YC demos), ops-control (DevOps, manufacturing), tokyo-midnight (crypto, trading, gaming), zen-garden (wellness, sustainability), consultant (agency deliverables, presentations). Mix-and-match: set palette + typography + effects independently.",
+        description: "Render a full dashboard with KPI cards, charts, and optional hero metric in a responsive grid. Available themes: boardroom (investors, board decks), corporate (enterprise daily use), sales-floor (quota tracking, leaderboards), golden-treasury (wealth, luxury real estate), clinical (healthcare, compliance - WCAG AAA), startup (SaaS metrics, YC demos), ops-control (DevOps, manufacturing), tokyo-midnight (crypto, trading, gaming), zen-garden (wellness, sustainability), consultant (agency deliverables, presentations), office-red (corporate report-style, Word/PowerPoint aesthetic). Mix-and-match: set palette + typography + effects independently.",
         inputSchema: {
             title: z.string().describe("Dashboard title"),
             kpis: z.array(KpiSchema).optional().describe("KPI cards at the top. Include sparkline[] with 5-20 trend values whenever a metric has a % change - this adds an inline mini chart to the card"),
@@ -457,6 +477,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,22 +504,16 @@ 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", {
         title: "Chart Catalog",
-        description: "Show a visual catalog of every available chart type as a dashboard of mini previews. Click any card to learn more about that chart tool.",
+        description: "Show a visual catalog of every available chart type as a dashboard of mini previews. Click any card to learn more about that chart tool. For a master entry point covering all customization dimensions, see render_catalog.",
         inputSchema: {
             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.
@@ -584,7 +599,7 @@ export function createServer() {
         ];
         const kpis = [
             { label: "Total Chart Tools", value: 31, suffix: " tools" },
-            { label: "Themes", value: 20, suffix: " presets" },
+            { label: "Themes", value: 21, suffix: " presets" },
         ];
         const chartData = {
             type: "dashboard",
@@ -595,30 +610,117 @@ 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: ${charts.length} 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. For a master entry point covering all customization dimensions, see render_catalog.",
         inputSchema: {},
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async () => {
-        return {
-            content: [
-                { type: "text", text: "Theme Catalog: 20 theme previews with color swatches, typography, and effects. Click any card to use it." },
-                { type: "text", text: JSON.stringify({ type: "theme_catalog" }) },
+        return await _buildChartResult(server, { type: "theme_catalog" }, "Theme Catalog: 21 theme previews with color swatches, typography, and effects. Click any card to use it.");
+    });
+    registerAppTool(server, "render_hero_catalog", {
+        title: "Hero Variant Catalog",
+        description: "Show all 11 hero metric variants in a single dashboard - big_number, progress_ring, status, comparison, rank, countdown, threshold, breakdown, nps, orb, gem. Each card is a working preview with sample data. Click any card to learn about that variant.",
+        inputSchema: { theme: ThemeParam },
+        _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    }, async (args) => {
+        const charts = [
+            { type: "hero", title: "Big number", data: { variant: "big_number", value: 47200, unit: "$", label: "MRR", change: 12.4, changePeriod: "vs last month", sparkline: [38, 39, 41, 40, 42, 43, 45, 46, 47] } },
+            { type: "hero", title: "Progress ring", data: { variant: "progress_ring", value: 87, unit: "%", label: "Q3 target", progress: 87 } },
+            { type: "hero", title: "Status", data: { variant: "status", label: "System health", statusLevel: "good", subsystems: [{ name: "API", status: "good" }, { name: "DB", status: "warn" }, { name: "Cache", status: "good" }], count: 1247 } },
+            { type: "hero", title: "Comparison", data: { variant: "comparison", before: 23.5, after: 41.2, improvement: "+75%", beforeLabel: "Last Q", afterLabel: "This Q" } },
+            { type: "hero", title: "Rank", data: { variant: "rank", rank: 3, total: 247, percentile: 99, rankChange: 5 } },
+            { type: "hero", title: "Countdown", data: { variant: "countdown", segments: [{ value: 7, label: "days" }, { value: 14, label: "hours" }, { value: 32, label: "min" }] } },
+            { type: "hero", title: "Threshold", data: { variant: "threshold", value: 78, max: 100, threshold: 80, unit: "%", zones: [{ label: "Safe", from: 0, to: 60, color: "#22c55e" }, { label: "Watch", from: 60, to: 80, color: "#eab308" }, { label: "Critical", from: 80, to: 100, color: "#ef4444" }] } },
+            { type: "hero", title: "Breakdown", data: { variant: "breakdown", items: [{ label: "Tech", value: 40, color: "#3b82f6" }, { label: "Sales", value: 30, color: "#22c55e" }, { label: "Ops", value: 20, color: "#eab308" }, { label: "Other", value: 10, color: "#94a3b8" }] } },
+            { type: "hero", title: "NPS", data: { variant: "nps", value: 67, max: 100, rating: "good" } },
+            { type: "hero", title: "Orb", data: { variant: "orb", value: 87, unit: "%", label: "Active users", color: "#3b82f6" } },
+            { type: "hero", title: "Gem", data: { variant: "gem", value: 1247, label: "Net worth", unit: "k", gemType: "diamond" } },
+        ];
+        const chartData = {
+            type: "dashboard",
+            title: "Hero Variant Catalog",
+            kpis: [
+                { label: "Variants", value: charts.length, suffix: " types" },
+            ],
+            charts,
+            columns: 3,
+            theme: args.theme,
+            footer: { text: "Tool: render_hero_metric - pass variant=<name>. Tip: gem has 8 sub-types (diamond, ruby, sapphire, emerald, golden_pearl, white_pearl, black_pearl, crystal)." },
+        };
+        return await _buildChartResult(server, chartData, `Hero Catalog: ${charts.length} variants of render_hero_metric. Click any card to ask about it.`);
+    });
+    registerAppTool(server, "render_effects_catalog", {
+        title: "Effects Catalog",
+        description: "Show a visual catalog of all 5 effect presets - none, subtle, shimmer, neon, energetic. Each card previews the effect and lists the underlying treatments it bundles. Click any card to use that effect. For a master entry point covering all customization dimensions, see render_catalog.",
+        inputSchema: {},
+        _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    }, async () => {
+        return await _buildChartResult(server, { type: "effects_catalog" }, "Effects Catalog: 5 effect previews with the bundled treatments labeled. Click any card to use it. Pass effects=<name> on any chart to override theme defaults.");
+    });
+    registerAppTool(server, "render_catalog", {
+        title: "Master Catalog",
+        description: "Master entry point to discover everything mcp-dashboards can do. Each tile is a live visual preview of one customization dimension - a real bar chart for charts, a pie for themes, a progress ring for hero variants, a neon-glowing card for effects. Click any tile then hit Ask, and the AI will route to the matching sub-catalog tool (render_chart_catalog, render_theme_catalog, render_hero_catalog, render_effects_catalog).",
+        inputSchema: { theme: ThemeParam },
+        _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    }, async (args) => {
+        // Each tile is a real working chart - the card title carries the tool
+        // name so click + Ask routes the model to the matching sub-catalog,
+        // and the visual itself is what that catalog contains (variety of
+        // chart types, palette colors, a hero metric, an effect glow).
+        const charts = [
+            {
+                type: "bar",
+                title: "Charts",
+                labels: ["Pie", "Bar", "Line", "Radar", "Map", "Hero"],
+                datasets: [{ label: "Variety", data: [8, 14, 11, 6, 9, 12] }],
+            },
+            {
+                type: "pie",
+                title: "Themes",
+                data: [
+                    { label: "Boardroom", value: 18 },
+                    { label: "Tokyo-midnight", value: 16 },
+                    { label: "Forest-amber", value: 14 },
+                    { label: "Sky-ocean", value: 13 },
+                    { label: "Office-red", value: 12 },
+                    { label: "Black-matrix", value: 11 },
+                    { label: "Zen-garden", value: 16 },
+                ],
+            },
+            {
+                type: "bar",
+                title: "Hero variants",
+                labels: ["Number", "Ring", "Status", "Compare", "Rank", "Count", "Bar", "NPS", "Orb", "Gem"],
+                datasets: [{ label: "Variants", data: [9, 12, 7, 10, 8, 6, 11, 9, 13, 10] }],
+            },
+            {
+                type: "bar",
+                title: "Effects",
+                labels: ["None", "Subtle", "Shimmer", "Neon", "Energetic"],
+                datasets: [{ label: "Presets", data: [4, 7, 11, 15, 13] }],
+            },
+        ];
+        const chartData = {
+            type: "dashboard",
+            title: "MCP Dashboards Catalog",
+            kpis: [
+                { label: "Total dimensions", value: charts.length, suffix: " catalogs" },
+                { label: "Tip", value: "Click any tile, hit Ask" },
             ],
-            structuredContent: { type: "theme_catalog" },
+            charts,
+            columns: 2,
+            theme: args.theme,
+            footer: { text: "Each tile previews what its sub-catalog contains. Click any tile then hit Ask to open the matching catalog. Or call render_chart_catalog / render_theme_catalog / render_hero_catalog / render_effects_catalog directly." },
         };
+        return await _buildChartResult(server, chartData, `Master Catalog: ${charts.length} customization dimensions, each shown as a live preview. Click any tile and hit Ask to open the matching sub-catalog (render_chart_catalog, render_theme_catalog, render_hero_catalog, render_effects_catalog).`);
     });
-    // -- Tool: render_radar_chart --
     _registerChartTool(server, "render_radar_chart", {
         title: "Radar Chart",
         description: "Render a radar (spider/web) chart - 'How do items compare across multiple dimensions?' Great for skill profiles, product comparisons, competitive analysis.",
@@ -643,7 +745,6 @@ export function createServer() {
         const ds = args.datasets;
         return `${args.title}: ${ds.map((d) => d.label).join(", ")} across ${args.labels.length} dimensions`;
     });
-    // -- Tool: render_treemap_chart --
     _registerChartTool(server, "render_treemap_chart", {
         title: "Treemap",
         description: "Render a treemap - 'What takes up the most space?' Nested rectangles sized by value. Supports optional grouping for hierarchical data (e.g. region > country). Great for budget breakdowns, disk usage, portfolio allocation.",
@@ -667,7 +768,6 @@ export function createServer() {
         const items = args.data;
         return `${args.title}: ${items.length} items, largest: ${items.sort((a, b) => b.value - a.value)[0]?.label}`;
     });
-    // -- Tool: render_sankey_chart --
     _registerChartTool(server, "render_sankey_chart", {
         title: "Sankey Diagram",
         description: "Render a sankey flow diagram - 'Where does it go?' Shows flows between nodes with width proportional to value. Great for budget flows, user journeys, energy transfers, conversion funnels with multiple paths.",
@@ -692,7 +792,6 @@ export function createServer() {
         const nodes = [...new Set(flows.flatMap((f) => [f.from, f.to]))];
         return `${args.title}: ${flows.length} flows across ${nodes.length} nodes`;
     });
-    // -- Tool: render_wordcloud_chart --
     _registerChartTool(server, "render_wordcloud_chart", {
         title: "Word Cloud",
         description: "Render a word cloud - 'What are the dominant themes?' Words sized by frequency or importance. Great for survey responses, keyword analysis, topic frequency.",
@@ -715,7 +814,6 @@ export function createServer() {
         const top = words.sort((a, b) => b.value - a.value).slice(0, 5).map((w) => w.text);
         return `${args.title}: ${words.length} words, top: ${top.join(", ")}`;
     });
-    // -- Tool: render_boxplot_chart --
     _registerChartTool(server, "render_boxplot_chart", {
         title: "Boxplot / Violin",
         description: "Render a boxplot or violin chart - 'What is the distribution?' Shows median, quartiles, whiskers, and outliers. Pass raw number arrays per category - stats computed automatically. Use style='violin' for density shape.",
@@ -741,7 +839,6 @@ export function createServer() {
         const ds = args.datasets;
         return `${args.title}: ${ds.map((d) => d.label).join(", ")} across ${args.labels.length} categories`;
     });
-    // -- Tool: render_live_chart --
     _registerChartTool(server, "render_live_chart", {
         title: "Live Chart",
         description: "Render a real-time auto-updating line chart that polls a tool at a regular interval. Use when the user wants to MONITOR a live data source. Set pollTool to 'poll_http' with pollArgs containing a preset or URL to poll external APIs (including other MCP servers' data). The chart auto-refreshes - no user action needed.",
@@ -775,7 +872,6 @@ export function createServer() {
         const series = args.values.map((v) => v.label).join(", ");
         return `Live chart "${args.title}" - polling ${args.pollTool} every ${args.interval ?? 2}s: ${series}`;
     });
-    // -- Tool: render_scatter_chart --
     registerAppTool(server, "render_scatter_chart", {
         title: "Scatter Chart",
         description: "Render an interactive scatter plot with x/y coordinate data. Supports multiple series and optional connecting lines. Supports themes for styled visuals.",
@@ -789,6 +885,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,15 +900,8 @@ 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", {
         title: "Candlestick Chart",
         description: "Render an interactive candlestick or OHLC financial chart. Provide date/OHLC data for stock prices, crypto, forex, or any time-series financial data. Supports themes for styled visuals.",
@@ -825,6 +915,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,15 +930,8 @@ 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", {
         title: "Data Table",
         description: "Render a sortable, interactive data table. Click column headers to sort. Supports themes for styled visuals.",
@@ -865,6 +949,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,15 +962,8 @@ 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", {
         title: "Auto Chart",
         description: "Automatically detect the best chart type for arbitrary JSON data. Pass any JSON - arrays, objects, nested structures - and get the most appropriate visualization.",
@@ -897,6 +975,7 @@ export function createServer() {
             }).optional(),
         },
         _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         const chartData = {
             type: "auto",
@@ -904,15 +983,8 @@ 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", {
         title: "Chart from URL",
         description: "Fetch JSON data from a URL and automatically visualize it. The server fetches the data, detects the best chart type, and renders it interactively.",
@@ -924,9 +996,15 @@ 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, {
+            // SSRF protection: reject private/loopback/link-local destinations
+            // unless the hostname is in MCP_URL_ALLOWLIST.
+            const safeUrl = await assertSafeUrl(args.url);
+            // Throttle outbound calls per hostname.
+            await acquireOutbound(safeUrl.hostname);
+            const response = await fetch(safeUrl, {
                 headers: { "Accept": "application/json", "User-Agent": "MCP-Dashboard/1.0" },
                 signal: AbortSignal.timeout(15000),
             });
@@ -943,42 +1021,92 @@ 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) {
+            const msg = err instanceof UrlSafetyError
+                ? err.message
+                : `Error fetching ${args.url}: ${err.message}`;
             return {
-                content: [{ type: "text", text: `Error fetching ${args.url}: ${err.message}` }],
+                content: [{ type: "text", text: msg }],
                 isError: true,
             };
         }
     });
-    // -- Tool: save_file (app-only, invisible to AI model) --
-    // Used by the UI to save exports since iframe sandbox blocks direct downloads.
-    server.tool("save_file", "Save a file to the user's Downloads folder. Used internally by the dashboard UI for PNG/CSV export.", {
-        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"),
+    // -- Tool: save_file --
+    // Two-layer defense:
+    //   1. _meta.ui.visibility=["app"] tells compliant MCP clients (Claude Code,
+    //      Claude Desktop, etc.) to NOT surface this tool to the LLM. Only the
+    //      View bundle running inside the chart iframe can invoke it via
+    //      app.callServerTool() over the MCP Apps PostMessage transport.
+    //   2. Extension allowlist (.png, .csv) is the server-side enforcement that
+    //      runs regardless of client compliance, so even a buggy/malicious
+    //      client cannot make us write arbitrary file types to ~/Downloads.
+    //
+    // The View only ever emits PNG (chart screenshots) and CSV (table data) -
+    // see addPngExportButton / addCsvExportButton in src/charts/shared.ts.
+    const SAVE_FILE_ALLOWED_EXTS = new Set([".png", ".csv"]);
+    registerAppTool(server, "save_file", {
+        title: "Save File",
+        description: "Save a chart export (PNG or CSV) to the user's Downloads folder. App-only - invoked by the chart View's Download buttons, not by the AI.",
+        inputSchema: {
+            filename: z.string().describe("Filename with extension (.png or .csv only)"),
+            data: z.string().describe("File contents: base64-encoded binary or plain text"),
+            encoding: z.enum(["base64", "utf-8"]).describe("How data is encoded"),
+        },
+        _meta: {
+            ui: {
+                resourceUri: RESOURCE_URI,
+                visibility: ["app"],
+            },
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
     }, async (args) => {
         try {
-            const sanitized = path.basename(args.filename);
+            // Sanitize the filename - replace path separators and Windows-reserved chars
+            // with hyphens rather than using path.basename (which would strip the title
+            // down to only the trailing segment when a chart title happens to contain `/`
+            // or `\`, e.g. "Cost / yr" becoming "yr.png").
+            const INVALID = /[\\/:*?"<>|\x00-\x1f]/g;
+            const extMatch = args.filename.match(/\.[A-Za-z0-9]{1,5}$/);
+            const ext = (extMatch ? extMatch[0] : "").toLowerCase();
+            // Server-side extension allowlist - defense even if a non-compliant
+            // client surfaces this tool to the LLM despite the visibility hint.
+            if (!SAVE_FILE_ALLOWED_EXTS.has(ext)) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Refusing to save: extension "${ext || "(none)"}" not in allowlist. Allowed: ${[...SAVE_FILE_ALLOWED_EXTS].join(", ")}`,
+                        }],
+                    isError: true,
+                };
+            }
+            const base = ext ? args.filename.slice(0, -ext.length) : args.filename;
+            let sanitized = (base.replace(INVALID, "-").trim() || "chart") + ext;
+            // Cap to 200 chars to stay comfortably under the 255 byte NTFS limit.
+            if (sanitized.length > 200) {
+                sanitized = sanitized.slice(0, 200 - ext.length) + ext;
+            }
             const downloadsDir = path.join(os.homedir(), "Downloads");
-            // Ensure Downloads folder exists
             await fs.mkdir(downloadsDir, { recursive: true });
             const filePath = path.join(downloadsDir, sanitized);
+            // Defense in depth: confirm the resolved path stays inside Downloads.
+            const resolved = path.resolve(filePath);
+            const downloadsResolved = path.resolve(downloadsDir);
+            if (path.dirname(resolved) !== downloadsResolved) {
+                return {
+                    content: [{ type: "text", text: "Refusing to save: path escapes Downloads directory" }],
+                    isError: true,
+                };
+            }
             if (args.encoding === "base64") {
-                await fs.writeFile(filePath, Buffer.from(args.data, "base64"));
+                await fs.writeFile(resolved, Buffer.from(args.data, "base64"));
             }
             else {
-                await fs.writeFile(filePath, args.data, "utf-8");
+                await fs.writeFile(resolved, args.data, "utf-8");
             }
             return {
-                content: [{ type: "text", text: `Saved to ${filePath}` }],
+                content: [{ type: "text", text: `Saved to ${resolved}` }],
             };
         }
         catch (err) {
@@ -988,7 +1116,136 @@ export function createServer() {
             };
         }
     });
-    // -- New chart tools (Phase 2) --
+    // -- Tool: list_chart_files (model-visible) --
+    // Lists chart preview HTML files currently on disk in the temp folder.
+    // Returns name, ID, size (KB), and modified timestamp for each. Read-only.
+    server.tool("list_chart_files", "List all chart preview HTML files saved on disk (in the system temp folder). These are auto-generated each time a chart is rendered and auto-cleaned after 7 days (configurable via MCP_DASHBOARDS_RETAIN_DAYS env var). Returns file metadata (id, name, size, age). Use this to audit disk usage, then call delete_chart_files to remove specific files or all of them.", {}, { readOnlyHint: true, destructiveHint: false, idempotentHint: true }, async () => {
+        try {
+            const entries = await fs.readdir(TEMP_DIR).catch(() => []);
+            const files = [];
+            for (const name of entries) {
+                if (!CHART_FILENAME_RE.test(name))
+                    continue;
+                try {
+                    const stat = await fs.stat(path.join(TEMP_DIR, name));
+                    const id = name.replace(/^chart-/, "").replace(/\.html$/, "");
+                    files.push({
+                        id,
+                        name,
+                        sizeKB: Math.round(stat.size / 1024),
+                        modifiedAt: new Date(stat.mtimeMs).toISOString(),
+                    });
+                }
+                catch { /* skip locked / permission-denied */ }
+            }
+            // Sort newest first
+            files.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+            const retainDays = Number.parseInt(process.env.MCP_DASHBOARDS_RETAIN_DAYS ?? "7", 10);
+            const summary = files.length === 0
+                ? `No chart files in ${TEMP_DIR}`
+                : `${files.length} chart file(s) in ${TEMP_DIR} (auto-cleanup at ${retainDays} days)`;
+            const structured = { dir: TEMP_DIR, retainDays, files };
+            return {
+                content: [
+                    { type: "text", text: summary },
+                    { type: "text", text: JSON.stringify(structured) },
+                ],
+                structuredContent: structured,
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Failed to list chart files: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // -- Tool: delete_chart_files (destructive) --
+    // Manually deletes chart preview HTML files. User-initiated only (the AI calls
+    // this when the user explicitly asks). Scope is hard-locked to the temp subfolder
+    // and the chart-{hex}.html pattern - it cannot delete anything else.
+    server.tool("delete_chart_files", "Delete chart preview HTML files saved on disk (in the system temp folder). REQUIRES the user's explicit instruction to run - it deletes files from disk and cannot be undone. Provide at least one of: chartIds (specific file IDs to delete), olderThanDays (bulk delete by age), or all=true (delete every chart file). Scope is hard-locked to mcp-dashboards temp folder; cannot touch anything else. Returns lists of successfully deleted files and per-file failures (e.g. files currently locked by an open browser).", {
+        chartIds: z.array(z.string()).optional().describe("Specific chart IDs to delete (12-char hex strings). Each must match /^[a-f0-9]{12}$/ or it is rejected."),
+        olderThanDays: z.number().int().positive().optional().describe("Delete chart files older than N days (positive integer)."),
+        all: z.boolean().optional().describe("Explicit confirmation to delete ALL chart files in the temp folder. Defaults to false."),
+    }, { readOnlyHint: false, destructiveHint: true, idempotentHint: false }, async (args) => {
+        const { chartIds, olderThanDays, all } = args;
+        if (!chartIds?.length && olderThanDays === undefined && !all) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "delete_chart_files requires at least one of: chartIds, olderThanDays, or all=true. Refusing to act on empty input.",
+                    }],
+                isError: true,
+            };
+        }
+        const deleted = [];
+        const failed = [];
+        try {
+            const entries = await fs.readdir(TEMP_DIR).catch(() => []);
+            const now = Date.now();
+            const ageCutoff = olderThanDays !== undefined
+                ? now - olderThanDays * 24 * 60 * 60 * 1000
+                : null;
+            const idSet = chartIds?.length ? new Set(chartIds.filter((id) => /^[a-f0-9]{12}$/.test(id))) : null;
+            for (const name of entries) {
+                if (!CHART_FILENAME_RE.test(name))
+                    continue;
+                const id = name.replace(/^chart-/, "").replace(/\.html$/, "");
+                // Decide whether this file qualifies for deletion
+                let qualifies = false;
+                if (all)
+                    qualifies = true;
+                if (!qualifies && idSet?.has(id))
+                    qualifies = true;
+                if (!qualifies && ageCutoff !== null) {
+                    try {
+                        const stat = await fs.stat(path.join(TEMP_DIR, name));
+                        if (stat.mtimeMs < ageCutoff)
+                            qualifies = true;
+                    }
+                    catch { /* fall through, treat as not qualifying */ }
+                }
+                if (!qualifies)
+                    continue;
+                // Verify the resolved path stays inside TEMP_DIR (defense in depth)
+                const full = path.join(TEMP_DIR, name);
+                if (path.dirname(full) !== TEMP_DIR) {
+                    failed.push({ id, name, reason: "path escapes temp dir" });
+                    continue;
+                }
+                try {
+                    await fs.unlink(full);
+                    // Also evict from in-memory chart store so the localhost URL stops
+                    // resolving. Without this, the URL keeps serving the cached chart
+                    // even though the file is gone - confusing for users who deleted
+                    // the chart and expect the link to be dead.
+                    evictChartFromCache(id);
+                    deleted.push({ id, name });
+                }
+                catch (err) {
+                    failed.push({ id, name, reason: err.code || err.message || "unknown error" });
+                }
+            }
+            const parts = [`Deleted ${deleted.length} chart file(s) from ${TEMP_DIR}`];
+            if (failed.length)
+                parts.push(`${failed.length} failed (locked or permission issues)`);
+            const structured = { dir: TEMP_DIR, deleted, failed };
+            return {
+                content: [
+                    { type: "text", text: parts.join("; ") },
+                    { type: "text", text: JSON.stringify(structured) },
+                ],
+                structuredContent: structured,
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Failed to delete chart files: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
     _registerChartTool(server, "render_bullet_chart", {
         title: "Bullet Chart",
         description: "Render bullet charts - 'Are we hitting target?' Horizontal bars with qualitative zones and a target marker. Supports 2-8 zones with optional labels and colors. Great for KPI vs target, seniority bands, maturity models.",
@@ -1341,7 +1598,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 = {};
@@ -1369,7 +1626,19 @@ export function createServer() {
             if (args.headers) {
                 fetchHeaders = { ...args.headers, ...fetchHeaders };
             }
-            const resp = await fetch(fetchUrl, {
+            // SSRF protection: validate target before fetch. Presets are trusted
+            // (operator-configured at env-var level), so they skip the check; raw
+            // URLs from the AI go through the full guard.
+            let safeUrl;
+            if (args.preset) {
+                safeUrl = new URL(fetchUrl);
+            }
+            else {
+                safeUrl = await assertSafeUrl(fetchUrl);
+            }
+            // Throttle outbound calls per hostname (covers both presets and raw).
+            await acquireOutbound(safeUrl.hostname);
+            const resp = await fetch(safeUrl, {
                 method: args.method ?? "GET",
                 headers: fetchHeaders,
                 body: args.method === "POST" ? args.body : undefined,
@@ -1384,8 +1653,11 @@ export function createServer() {
             return { content: [{ type: "text", text }] };
         }
         catch (err) {
+            const msg = err instanceof UrlSafetyError
+                ? err.message
+                : `poll_http failed: ${err.message}`;
             return {
-                content: [{ type: "text", text: `poll_http failed: ${err.message}` }],
+                content: [{ type: "text", text: msg }],
                 isError: true,
             };
         }