powerbi-visuals-tools 7.0.3 → 7.1.0

package/Changelog.md

@@ -2,6 +2,19 @@
 
 This page contains information about changes to the PowerBI Visual Tools (pbiviz).
 
+## 7.1.0
+* Added MCP (Model Context Protocol) server support via `pbiviz mcp` command, providing AI-powered tools for visual development.
+* Added MCP tools: available APIs, best practices, certification guidance, visual info, and vulnerabilities detection.
+* Added MCP configuration template for new visuals (`.vscode/mcp.json`).
+* Added unit tests for MCP tools.
+* Updated packages.
+
+## 7.0.4
+* Treated renderingEvents issue as an error when certification-audit and certification-fix are used.
+* Switched to a new webpack plugin.
+* Added rendering events to the visual templates.
+* Updated packages.
+
 ## 7.0.3
 * Fixed missing validation for `author` object in pbiviz.json. The `author` object with `name` and `email` fields is now required.
 * Updated packages.

package/MCP.md

@@ -0,0 +1,234 @@
+# Power BI Visuals Tools - MCP Server
+
+This document describes the MCP (Model Context Protocol) server integration for Power BI Custom Visual Tools, inspired by the Angular 21 MCP implementation.
+
+## What is MCP?
+
+Model Context Protocol (MCP) is an open protocol that allows AI assistants (like GitHub Copilot, Cursor, Claude) to interact with development tools directly. The MCP server exposes "tools" that AI can call to get context-aware information about your project.
+
+## Quick Start
+
+### Option 1: Using VS Code with Copilot
+
+1. Add this to your VS Code settings or create `.vscode/mcp.json`:
+
+```json
+{
+    "servers": {
+        "pbiviz": {
+            "command": "npx",
+            "args": ["-y", "powerbi-visuals-tools", "mcp"]
+        }
+    }
+}
+```
+
+2. Restart VS Code
+3. In Copilot Chat, you can now ask questions like:
+   - "Check my visual for certification readiness"
+   - "What are the best practices for Power BI visuals?"
+   - "Show me available Power BI Visual APIs"
+
+### Option 2: Using Cursor
+
+Add to Cursor settings (`~/.cursor/mcp.json`):
+
+```json
+{
+    "mcpServers": {
+        "pbiviz": {
+            "command": "npx",
+            "args": ["-y", "powerbi-visuals-tools", "mcp"]
+        }
+    }
+}
+```
+
+### Option 3: Run Manually (for testing)
+
+```bash
+cd /path/to/your/visual-project
+pbiviz mcp
+```
+
+The server runs on STDIO, so you won't see output, but it will respond to MCP requests.
+
+## Available Tools
+
+| Tool | Description | Local | Read-only |
+|------|-------------|-------|-----------|
+| `get_best_practices` | Returns best practice guidelines for Power BI visual development | ✅ | ✅ |
+| `check_vulnerabilities` | Scans project for security vulnerabilities in dependencies and code | ✅ | ✅ |
+| `prepare_certification` | Audits visual for Power BI certification readiness | ✅ | ✅ |
+| `list_visual_info` | Returns info about current visual (name, GUID, API version, capabilities) | ✅ | ✅ |
+| `get_available_apis` | Lists available Power BI Visual APIs with examples | ✅ | ✅ |
+
+### Tool Details
+
+#### `get_best_practices`
+
+Returns comprehensive guidelines including:
+- API version management
+- Performance optimization tips
+- Security guidelines
+- Accessibility requirements
+- Project structure recommendations
+- Testing best practices
+
+#### `check_vulnerabilities`
+
+Analyzes:
+- `package.json` dependencies for known vulnerable packages
+- Source code for dangerous patterns (`eval()`, `innerHTML`, external fetch calls)
+- Returns severity-categorized results (critical/high/medium/low/info)
+
+#### `prepare_certification`
+
+Checks:
+- Required files (pbiviz.json, capabilities.json, package.json)
+- Visual configuration (name, GUID, version format, API version)
+- Capabilities (data roles, accessibility support)
+- Assets (icon.png)
+
+#### `list_visual_info`
+
+Extracts from project files:
+- Visual name, display name, GUID
+- Version and API version
+- Author information
+- Defined data roles and format objects
+- Supported features (highlight, keyboard focus, etc.)
+- Dependencies list
+
+#### `get_available_apis`
+
+Provides documentation for:
+- **Data APIs**: fetchMoreData, persistProperties
+- **Formatting APIs**: colorPalette, getFormattingModel, high contrast
+- **Interaction APIs**: selectionManager, tooltipService, contextMenu, drilldown
+- **Utility APIs**: localization, storage, events, modal dialog
+
+Accepts optional `category` parameter: `data`, `formatting`, `interaction`, `utility`, or `all`.
+
+## Example Interactions
+
+### With GitHub Copilot (Agent Mode)
+
+**You:** "Is my visual ready for certification?"
+
+**Copilot:** *calls `prepare_certification` tool*
+
+> Based on the certification check, your visual has:
+> - ✅ 12 passed checks
+> - ⚠️ 2 warnings: Missing keyboard focus support, no README.md
+> - ❌ 1 failed: API version 2.6.0 is outdated
+> 
+> Recommendation: Update to API version 5.x and add `"supportsKeyboardFocus": true` to capabilities.json.
+
+---
+
+**You:** "What APIs can I use for tooltips and selection?"
+
+**Copilot:** *calls `get_available_apis` with category="interaction"*
+
+> For tooltips, use `host.tooltipService.show()`:
+> ```typescript
+> host.tooltipService.show({
+>     dataItems: tooltipData,
+>     coordinates: [x, y]
+> });
+> ```
+> For selection, use `selectionManager`:
+> ```typescript
+> const selectionManager = host.createSelectionManager();
+> selectionManager.select(selectionId);
+> ```
+
+## How It Works
+
+```
+┌─────────────────┐     STDIO      ┌─────────────────┐
+│   VS Code /     │ ◄───────────►  │   pbiviz mcp    │
+│   Copilot       │    (MCP)       │   (MCP Server)  │
+└─────────────────┘                └─────────────────┘
+                                          │
+                                          ▼
+                                   ┌─────────────────┐
+                                   │  Visual Project │
+                                   │  - pbiviz.json  │
+                                   │  - capabilities │
+                                   │  - package.json │
+                                   │  - src/         │
+                                   └─────────────────┘
+```
+
+1. VS Code starts `pbiviz mcp` as a subprocess
+2. Copilot sends `ListTools` request → pbiviz returns available tools
+3. When you ask a question, Copilot may call a tool
+4. pbiviz executes the tool (reads project files, runs checks)
+5. Results are returned to Copilot as structured text
+6. Copilot presents the information in a helpful way
+
+## Development
+
+### Building from Source
+
+```bash
+git clone https://github.com/Microsoft/PowerBI-visuals-tools.git
+cd PowerBI-visuals-tools
+npm install
+npm run build
+```
+
+### Testing MCP Server Locally
+
+```bash
+# In your visual project directory:
+node /path/to/PowerBI-visuals-tools/bin/pbiviz.js mcp
+```
+
+### Adding New Tools
+
+1. Create a new file in `src/mcp/tools/`
+2. Export a function that returns a string result
+3. Register the tool in `src/mcp/McpServer.ts`
+
+Example:
+```typescript
+// src/mcp/tools/myTool.ts
+export function myTool(rootPath: string): string {
+    // Read files, perform checks, return markdown result
+    return "# My Tool Result\n...";
+}
+
+// In McpServer.ts
+this.server.tool(
+    "my_tool",
+    "Description for AI",
+    {},
+    async () => ({
+        content: [{ type: "text", text: myTool(this.rootPath) }]
+    })
+);
+```
+
+## Comparison with Angular 21 MCP
+
+| Feature | Angular CLI | pbiviz (this implementation) |
+|---------|-------------|------------------------------|
+| Best practices | `get_best_practices` | `get_best_practices` |
+| Project info | `list_projects` | `list_visual_info` |
+| Code examples | `find_examples` | `get_available_apis` |
+| Documentation search | `search_documentation` (online) | ❌ (offline only) |
+| Migration tools | `onpush_zoneless_migration` | `prepare_certification` |
+| Build/Run | `build`, `serve` | Use regular CLI commands |
+
+## Requirements
+
+- Node.js >= 18.0.0
+- VS Code with GitHub Copilot (for Chat integration)
+- Or Cursor / other MCP-compatible AI assistant
+
+## License
+
+MIT - Microsoft Corporation

package/bin/pbiviz.js

@@ -111,4 +111,16 @@ pbiviz
         CommandManager.package(options, rootPath);
     });
 
+pbiviz
+    .command('mcp')
+    .description('Start MCP (Model Context Protocol) server for AI assistant integration')
+    .option('--init', 'Initialize MCP configuration in current project (.vscode/mcp.json)')
+    .action((options) => {
+        if (options.init) {
+            CommandManager.mcpInit(rootPath);
+        } else {
+            CommandManager.mcp(rootPath);
+        }
+    });
+
 program.parse(process.argv);

package/lib/CommandManager.js

@@ -1,6 +1,7 @@
 import { createCertificate } from './CertificateTools.js';
 import ConsoleWriter from './ConsoleWriter.js';
 import VisualManager from './VisualManager.js';
+import { startMcpServer, initMcpConfig } from './mcp/McpServer.js';
 export default class CommandManager {
     static async start(options, rootPath) {
         const webpackOptions = {
@@ -50,12 +51,13 @@ export default class CommandManager {
             verbose: options.verbose,
             fix: options.fix,
         };
+        const certificationMode = options.certificationAudit || options.certificationFix;
         const visualManager = new VisualManager(rootPath);
         const visual = await visualManager.prepareVisual(options.pbivizFile);
         await visual.runLintValidation(lintOptions);
         await visual.validateVisual(options.verbose);
         await visual.initializeWebpack(webpackOptions)
-            .then(manager => manager.generatePackage(options.verbose));
+            .then(manager => manager.generatePackage(options.verbose, certificationMode));
     }
     static new({ force, template }, name, rootPath) {
         const generateOptions = {
@@ -72,4 +74,10 @@ export default class CommandManager {
     static async installCert() {
         await createCertificate();
     }
+    static async mcp(rootPath) {
+        await startMcpServer(rootPath);
+    }
+    static async mcpInit(rootPath) {
+        await initMcpConfig(rootPath);
+    }
 }

package/lib/ConsoleWriter.js

@@ -42,6 +42,10 @@ export default class ConsoleWriter {
     static blank() {
         console.info(preferredChalk.reset(' '));
     }
+    /** Outputs a separator line */
+    static separator() {
+        console.log(preferredChalk.white('--------------------------------'));
+    }
     /**
      * Outputs arguments with the "done" tag / colors
      *

package/lib/FeatureManager.js

@@ -7,21 +7,27 @@ export var Status;
 })(Status || (Status = {}));
 export class FeatureManager {
     features = Object.keys(features).map(key => features[key]);
-    validate(stage, sourceInstance) {
+    validate(stage, sourceInstance, certificationMode = false) {
         const result = {
             status: Status.Success,
             logs: {
                 errors: [],
                 warnings: [],
                 info: [],
-                deprecation: []
+                deprecation: [],
+                certificationErrors: []
             }
         };
         this.features
             .filter(feature => feature.stage == stage)
             .filter(feature => feature.visualFeatureType & sourceInstance.visualFeatureType)
             .filter(feature => !feature.isSupported(sourceInstance))
-            .forEach(({ errorMessage, severity }) => {
+            .forEach(({ errorMessage, severity, certificationRequired }) => {
+            if (certificationMode && certificationRequired && severity === Severity.Warning) {
+                result.status = Status.Error;
+                result.logs.certificationErrors.push(errorMessage);
+                return;
+            }
             switch (severity) {
                 case Severity.Error:
                     result.status = Status.Error;

package/lib/VisualManager.js

@@ -90,12 +90,15 @@ export default class VisualManager {
         this.compiler = webpack(this.webpackConfig);
         return this;
     }
-    generatePackage(verbose = false) {
+    generatePackage(verbose = false, certificationMode = false) {
         const callback = (err, stats) => {
             this.parseCompilationResults(err, stats);
             this.createPackageInstance();
-            const logs = this.validatePackage();
+            const { status, logs } = this.validatePackage(certificationMode);
             this.outputResults(logs, verbose);
+            if (certificationMode && status === Status.Error) {
+                process.exit(1);
+            }
         };
         this.compiler.run(callback);
     }
@@ -144,15 +147,15 @@ export default class VisualManager {
     /**
      * Validates the visual package
      */
-    validatePackage() {
+    validatePackage(certificationMode = false) {
         const featureManager = new FeatureManager();
-        const { logs } = featureManager.validate(Stage.PostBuild, this.package);
-        return logs;
+        const { status, logs } = featureManager.validate(Stage.PostBuild, this.package, certificationMode);
+        return { status, logs };
     }
     /**
      * Outputs the results of the validation
      */
-    outputResults({ errors, deprecation, warnings, info }, verbose) {
+    outputResults({ errors, deprecation, warnings, info, certificationErrors }, verbose) {
         const headerMessage = {
             error: `Visual doesn't support some features required for all custom visuals:`,
             deprecation: `Some features are going to be required soon, please update the visual:`,
@@ -160,6 +163,9 @@ export default class VisualManager {
             verboseInfo: `Visual can be improved by adding some features:`,
             shortInfo: `Visual can be improved by adding ${info.length} more optional features.`
         };
+        if (certificationErrors.length) {
+            this.outputCertificationSection(certificationErrors);
+        }
         this.outputLogsWithHeadMessage(headerMessage.error, errors, Severity.Error);
         this.outputLogsWithHeadMessage(headerMessage.deprecation, deprecation, Severity.Deprecation);
         this.outputLogsWithHeadMessage(headerMessage.warning, warnings, Severity.Warning);
@@ -179,6 +185,16 @@ export default class VisualManager {
             ConsoleWriter.error('Unable to load visual info. Please ensure the package is valid.');
         }
     }
+    /**
+     * Outputs certification-required issues in a formatted section with separators
+     */
+    outputCertificationSection(certificationErrors) {
+        ConsoleWriter.separator();
+        ConsoleWriter.info('Certification audit:');
+        certificationErrors.forEach(error => ConsoleWriter.error(error));
+        ConsoleWriter.error(`Found ${certificationErrors.length} certification issue(s). Fix them before submitting for certification.`);
+        ConsoleWriter.separator();
+    }
     /**
      * Creates a new visual
      */

package/lib/features/BaseFeature.js

@@ -5,5 +5,6 @@ export default class BaseFeature {
     static featureName;
     static documentationLink;
     static errorMessage;
+    static certificationRequired = false;
     static isSupported() { }
 }

package/lib/features/RenderingEvents.js

@@ -5,6 +5,7 @@ export default class RenderingEvents {
     static severity = Severity.Warning;
     static stage = Stage.PostBuild;
     static visualFeatureType = VisualFeatureType.All;
+    static certificationRequired = true;
     static errorMessage = `${this.featureName} - ${this.documentationLink}`;
     static isSupported(packageInstance) {
         const keywords = [".eventService", ".renderingStarted", ".renderingFinished"];

package/lib/mcp/McpServer.js

@@ -0,0 +1,122 @@
+/*
+ *  Power BI Visual CLI - MCP Server
+ *
+ *  Copyright (c) Microsoft Corporation
+ *  All rights reserved.
+ *  MIT License
+ */
+"use strict";
+import { McpServer as MCPServerSDK } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import fs from "fs-extra";
+import path from "path";
+import ConsoleWriter from "../ConsoleWriter.js";
+import { getBestPractices } from "./tools/bestPractices.js";
+import { checkVulnerabilities } from "./tools/vulnerabilities.js";
+import { prepareCertification } from "./tools/certification.js";
+import { getVisualInfo } from "./tools/visualInfo.js";
+import { getAvailableApis } from "./tools/availableApis.js";
+export class McpServer {
+    server;
+    rootPath;
+    constructor(rootPath) {
+        this.rootPath = rootPath;
+        this.server = new MCPServerSDK({
+            name: "pbiviz-mcp-server",
+            version: "1.0.0",
+        });
+        this.registerTools();
+    }
+    registerTools() {
+        // Tool 1: Get Best Practices
+        this.server.tool("get_best_practices", "Returns best practice guidelines for Power BI custom visual development. Covers: API version management, performance optimization (update loop, lazy loading, data processing), security (eval, innerHTML, XSS, sanitization, external call/calls, network request/requests), accessibility (keyboard navigation, high contrast, screen reader, ARIA label/labels), project structure (module/modules, error handling), formatting pane (format model, formatting model), testing (unit test/tests, E2E test/tests, edge case/cases), and documentation (README, changelog, comment/comments).", {}, async () => {
+            const practices = await getBestPractices(this.rootPath);
+            return {
+                content: [{ type: "text", text: practices }],
+            };
+        });
+        // Tool 2: Check Vulnerabilities
+        this.server.tool("check_vulnerabilities", "Scans the visual project source code for security vulnerability/vulnerabilities and dangerous code pattern/patterns. Detects: eval(), new Function(), innerHTML assignment, document.write, external fetch/HTTP call/calls, XMLHttpRequest. Also checks for commented-out dangerous code and ESLint configuration. Reports issue/issues by severity (critical, high, medium, low, info) with file path and line number.", {}, async () => {
+            const result = await checkVulnerabilities(this.rootPath);
+            return {
+                content: [{ type: "text", text: result }],
+            };
+        });
+        // Tool 3: Prepare Certification
+        this.server.tool("prepare_certification", "Audits the visual for Power BI certification readiness. Checks: required file/files (pbiviz.json, capabilities.json, package.json, tsconfig.json), visual configuration (name, GUID, version, API version, author, support URL), capability/capabilities (data role/roles, data view mapping/mappings, keyboard focus, highlight support, web access privilege/privileges), and asset/assets (icon.png). Reports pass/fail/warning status for each check.", {}, async () => {
+            const result = await prepareCertification(this.rootPath);
+            return {
+                content: [{ type: "text", text: result }],
+            };
+        });
+        // Tool 4: List Visual Info
+        this.server.tool("list_visual_info", "Returns detailed information about the current Power BI visual project. Shows: visual name, display name, GUID, version, API version, author, description, support URL, data role/roles, data view mapping/mappings, format object/objects (setting/settings), supported feature/features (highlight, keyboard focus, landing page, multi-visual selection), dependency/dependencies from package.json, and quick command/commands.", {}, async () => {
+            const result = await getVisualInfo(this.rootPath);
+            return {
+                content: [{ type: "text", text: result }],
+            };
+        });
+        // Tool 5: Get Available APIs
+        this.server.tool("get_available_apis", "Lists available Power BI Visual API/APIs and feature/features with code example/examples and documentation link/links. Categories: 'data' (fetchMoreData, data snapshot, persist property/properties), 'formatting' (color palette, format pane, formatting model, custom color/colors, high contrast), 'interaction' (selection manager, tooltip/tooltips, tooltip service, context menu, launch URL, drill down/drilldown, warning icon), 'utility' (localization, local storage, file download, rendering event/events, modal dialog, authentication), or 'all'.", {
+            category: z.string().optional().describe("Filter APIs by category: 'data' (fetchMoreData, persist, snapshot), 'formatting' (color palette, format pane, high contrast), 'interaction' (selection, tooltip/tooltips, context menu, drill down, launch URL, warning icon), 'utility' (localization, storage, download, event/events, dialog, auth), or 'all' (default)")
+        }, async ({ category }) => {
+            const result = await getAvailableApis(category || "all", this.rootPath);
+            return {
+                content: [{ type: "text", text: result }],
+            };
+        });
+    }
+    async start() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        // Keep the server running
+        process.on("SIGINT", async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+}
+export async function startMcpServer(rootPath) {
+    const server = new McpServer(rootPath);
+    await server.start();
+}
+const MCP_CONFIG = {
+    servers: {
+        pbiviz: {
+            command: "npx",
+            args: ["-y", "powerbi-visuals-tools", "mcp"]
+        }
+    }
+};
+export async function initMcpConfig(rootPath) {
+    const vscodeDir = path.join(rootPath, ".vscode");
+    const mcpConfigPath = path.join(vscodeDir, "mcp.json");
+    try {
+        // Check if mcp.json already exists
+        if (fs.existsSync(mcpConfigPath)) {
+            ConsoleWriter.warning("MCP configuration already exists at .vscode/mcp.json");
+            ConsoleWriter.info("To reconfigure, delete the file and run this command again.");
+            return;
+        }
+        // Create .vscode directory if it doesn't exist
+        fs.ensureDirSync(vscodeDir);
+        // Write mcp.json
+        fs.writeJsonSync(mcpConfigPath, MCP_CONFIG, { spaces: 4 });
+        ConsoleWriter.done("MCP configuration created successfully!");
+        ConsoleWriter.blank();
+        ConsoleWriter.info("Created: .vscode/mcp.json");
+        ConsoleWriter.blank();
+        ConsoleWriter.info("Next steps:");
+        ConsoleWriter.info("1. Restart VS Code to activate MCP server");
+        ConsoleWriter.info("2. Open Copilot Chat and ask questions like:");
+        ConsoleWriter.info('   - "Check my visual for certification readiness"');
+        ConsoleWriter.info('   - "What are the best practices for Power BI visuals?"');
+        ConsoleWriter.info('   - "Show me available APIs for tooltips"');
+        ConsoleWriter.blank();
+    }
+    catch (error) {
+        ConsoleWriter.error(`Failed to create MCP configuration: ${(error instanceof Error) ? error.message : String(error)}`);
+        process.exit(1);
+    }
+}