@mcp-consultant-tools/azure-devops 29.0.0 → 30.0.0-beta.10

package/build/tools/visualize-tools.js

@@ -0,0 +1,145 @@
+/**
+ * Visualization Tools — Generative UI via MCP Apps
+ *
+ * Two-tool pattern:
+ * 1. visualize-data: Fetches work items, returns data + design system prompt to host LLM
+ * 2. render-visualization: Receives LLM-generated HTML, sanitizes it, returns structuredContent
+ *
+ * The host LLM generates the HTML using its own subscription — no API key, no extra cost.
+ */
+import { z } from 'zod';
+import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
+import { DESIGN_SYSTEM_PROMPT } from '../genui/design-system-prompt.js';
+import { sanitizeGenUiHtml } from '../genui/sanitize-html.js';
+export function registerVisualizeTools(server, ctx) {
+    const workItemsResourceUri = "ui://ado/work-items";
+    // Tool 1: Fetch data and instruct host LLM to generate HTML
+    server.tool("visualize-data", "Fetch work item data and prepare it for a rich visual dashboard. ONLY use this tool when the user explicitly asks for a " +
+        "visual, chart, dashboard, or graphic representation of their data (e.g. 'visualize', 'show me a chart', 'create a dashboard'). " +
+        "Do NOT use for regular queries — use query-work-items or run-saved-query instead, which are faster. " +
+        "Accepts either a WIQL query or a saved query ID (GUID). " +
+        "After receiving the response, generate a complete HTML snippet following the design system rules, " +
+        "then call render-visualization with the HTML.", {
+        project: z.string().describe("The ADO project name"),
+        wiql: z.string().optional().describe("WIQL query to fetch work items. Provide either wiql OR queryId, not both. " +
+            "Example: SELECT [System.Id], [System.Title], [System.State], " +
+            "[System.WorkItemType], [System.AssignedTo] FROM WorkItems WHERE [System.TeamProject] = 'MyProject' " +
+            "AND [System.State] <> 'Removed' ORDER BY [System.ChangedDate] DESC"),
+        queryId: z.string().optional().describe("Saved query GUID. Provide either queryId OR wiql, not both. " +
+            "Found in ADO query URLs: https://dev.azure.com/{org}/{project}/_queries/query/{queryId}/"),
+        intent: z.string().describe("What visualization to create. Examples: 'sprint status dashboard', 'burndown chart', " +
+            "'team workload by assignee', 'priority breakdown', 'bug trend over time'"),
+        theme: z.enum(["light", "dark"]).optional().describe("Color theme (default: light)"),
+        maxResults: z.number().optional().describe("Maximum work items to fetch (default: 20 for visualization)"),
+    }, async ({ project, wiql, queryId, intent, theme, maxResults }) => {
+        try {
+            if (!wiql && !queryId) {
+                return {
+                    content: [{ type: "text", text: "Error: Provide either 'wiql' or 'queryId' parameter." }],
+                    isError: true,
+                };
+            }
+            const effectiveMaxResults = maxResults ?? 20;
+            let items;
+            if (queryId) {
+                // Execute saved query
+                const result = await ctx.workItem.runSavedQuery(project, queryId, effectiveMaxResults);
+                items = Array.isArray(result) ? result : result?.workItems ?? [];
+            }
+            else {
+                // Execute WIQL query
+                const result = await ctx.workItem.queryWorkItems(project, wiql, effectiveMaxResults);
+                items = Array.isArray(result) ? result : result?.workItems ?? result;
+            }
+            const itemCount = Array.isArray(items) ? items.length : 0;
+            const org = process.env.AZUREDEVOPS_ORGANIZATION || 'unknown-org';
+            const effectiveTheme = theme || 'light';
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `## Visualization Data (${itemCount} work items)`,
+                            `**Intent:** ${intent}`,
+                            `**Theme:** ${effectiveTheme}`,
+                            `**Organization:** ${org}`,
+                            `**Project:** ${project}`,
+                            ``,
+                            `### Work Item Data`,
+                            '```json',
+                            JSON.stringify(items, null, 2),
+                            '```',
+                            ``,
+                            `### Design System Rules`,
+                            ``,
+                            DESIGN_SYSTEM_PROMPT,
+                            ``,
+                            `### Instructions`,
+                            ``,
+                            `Generate a complete HTML snippet following the design system rules above.`,
+                            `Use the organization "${org}" and project "${project}" to construct work item URLs.`,
+                            `The visualization intent is: "${intent}"`,
+                            `Theme: "${effectiveTheme}"`,
+                            ``,
+                            `After generating the HTML, call the \`render-visualization\` tool with:`,
+                            `- \`html\`: the complete HTML snippet`,
+                            `- \`title\`: a short title for the visualization`,
+                            ``,
+                            `Return ONLY the HTML when calling render-visualization. No markdown, no explanation.`,
+                        ].join('\n'),
+                    }],
+            };
+        }
+        catch (error) {
+            console.error("Error in visualize-data:", error);
+            return {
+                content: [{ type: "text", text: `Failed to fetch work item data: ${error.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // Tool 2: Receive generated HTML and render it via MCP App
+    registerAppTool(server, "render-visualization", {
+        title: "Render Visualization",
+        description: "Render generated HTML as an interactive visualization in the MCP App. " +
+            "Call this after generating HTML from visualize-data results. " +
+            "Pass the complete HTML snippet — it will be sanitized and rendered in an iframe.",
+        inputSchema: {
+            html: z.string().describe("The complete HTML snippet to render. Must be self-contained with inline CSS and scripts."),
+            title: z.string().optional().describe("Short title for the visualization (e.g. 'Sprint Status Dashboard')"),
+        },
+        _meta: { ui: { resourceUri: workItemsResourceUri } },
+    }, async ({ html, title }) => {
+        try {
+            // Validate: basic HTML check
+            if (!html || (!html.includes('<') && !html.includes('>'))) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Error: The provided content does not appear to be valid HTML. Please regenerate following the design system rules.",
+                        }],
+                    isError: true,
+                };
+            }
+            // Strip markdown code fences if the LLM wrapped the HTML
+            let cleanHtml = html;
+            if (cleanHtml.startsWith('```')) {
+                cleanHtml = cleanHtml.replace(/^```(?:html)?\n?/i, '').replace(/\n?```$/i, '').trim();
+            }
+            // Sanitize
+            const sanitized = sanitizeGenUiHtml(cleanHtml);
+            const displayTitle = title || 'Visualization';
+            return {
+                content: [{ type: "text", text: `Rendered: ${displayTitle}` }],
+                structuredContent: { type: "genui", html: sanitized, title: displayTitle },
+            };
+        }
+        catch (error) {
+            console.error("Error in render-visualization:", error);
+            return {
+                content: [{ type: "text", text: `Failed to render visualization: ${error.message}` }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=visualize-tools.js.map

package/build/tools/visualize-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualize-tools.js","sourceRoot":"","sources":["../../src/tools/visualize-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAG9D,MAAM,UAAU,sBAAsB,CAAC,MAAW,EAAE,GAAmB;IACrE,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;IAEnD,4DAA4D;IAC5D,MAAM,CAAC,IAAI,CACT,gBAAgB,EAChB,0HAA0H;QAC1H,iIAAiI;QACjI,sGAAsG;QACtG,0DAA0D;QAC1D,oGAAoG;QACpG,+CAA+C,EAC/C;QACE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;QACpD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAClC,4EAA4E;YAC5E,+DAA+D;YAC/D,qGAAqG;YACrG,oEAAoE,CACrE;QACD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CACrC,8DAA8D;YAC9D,0FAA0F,CAC3F;QACD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CACzB,uFAAuF;YACvF,0EAA0E,CAC3E;QACD,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;QACpF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6DAA6D,CAAC;KAC1G,EACD,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAO,EAAE,EAAE;QACnE,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACtB,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,sDAAsD,EAAE,CAAC;oBACzF,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YAED,MAAM,mBAAmB,GAAG,UAAU,IAAI,EAAE,CAAC;YAC7C,IAAI,KAAY,CAAC;YAEjB,IAAI,OAAO,EAAE,CAAC;gBACZ,sBAAsB;gBACtB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC;gBACvF,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,MAAc,EAAE,SAAS,IAAI,EAAE,CAAC;YAC5E,CAAC;iBAAM,CAAC;gBACN,qBAAqB;gBACrB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,mBAAmB,CAAC,CAAC;gBACrF,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,MAAc,EAAE,SAAS,IAAI,MAAM,CAAC;YAChF,CAAC;YACD,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAE1D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,aAAa,CAAC;YAClE,MAAM,cAAc,GAAG,KAAK,IAAI,OAAO,CAAC;YAExC,OAAO;gBACL,OAAO,EAAE,CAAC;wBACR,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;4BACJ,0BAA0B,SAAS,cAAc;4BACjD,eAAe,MAAM,EAAE;4BACvB,cAAc,cAAc,EAAE;4BAC9B,qBAAqB,GAAG,EAAE;4BAC1B,gBAAgB,OAAO,EAAE;4BACzB,EAAE;4BACF,oBAAoB;4BACpB,SAAS;4BACT,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;4BAC9B,KAAK;4BACL,EAAE;4BACF,yBAAyB;4BACzB,EAAE;4BACF,oBAAoB;4BACpB,EAAE;4BACF,kBAAkB;4BAClB,EAAE;4BACF,2EAA2E;4BAC3E,yBAAyB,GAAG,kBAAkB,OAAO,gCAAgC;4BACrF,iCAAiC,MAAM,GAAG;4BAC1C,WAAW,cAAc,GAAG;4BAC5B,EAAE;4BACF,yEAAyE;4BACzE,uCAAuC;4BACvC,kDAAkD;4BAClD,EAAE;4BACF,sFAAsF;yBACvF,CAAC,IAAI,CAAC,IAAI,CAAC;qBACb,CAAC;aACH,CAAC;QACJ,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;YACjD,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,mCAAmC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;gBACrF,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;IAEF,2DAA2D;IAC3D,eAAe,CACb,MAAM,EACN,sBAAsB,EACtB;QACE,KAAK,EAAE,sBAAsB;QAC7B,WAAW,EACT,wEAAwE;YACxE,+DAA+D;YAC/D,kFAAkF;QACpF,WAAW,EAAE;YACX,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0FAA0F,CAAC;YACrH,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oEAAoE,CAAC;SAC5G;QACD,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,oBAAoB,EAAE,EAAE;KACrD,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,EAAO,EAAE,EAAE;QAC7B,IAAI,CAAC;YACH,6BAA6B;YAC7B,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBAC1D,OAAO;oBACL,OAAO,EAAE,CAAC;4BACR,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,oHAAoH;yBAC3H,CAAC;oBACF,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YAED,yDAAyD;YACzD,IAAI,SAAS,GAAG,IAAI,CAAC;YACrB,IAAI,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChC,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YACxF,CAAC;YAED,WAAW;YACX,MAAM,SAAS,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;YAE/C,MAAM,YAAY,GAAG,KAAK,IAAI,eAAe,CAAC;YAC9C,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,YAAY,EAAE,EAAE,CAAC;gBAC9D,iBAAiB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE;aAC3E,CAAC;QACJ,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,gCAAgC,EAAE,KAAK,CAAC,CAAC;YACvD,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,mCAAmC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;gBACrF,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}