powerbi-visuals-tools 7.0.2 → 7.1.0

package/Changelog.md

@@ -2,6 +2,23 @@
 
 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.
+
 ## 7.0.2
 * Changed source map generation to `eval-source-map`.
 * Fixed load source map error.

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/eslint.config.mjs

@@ -2,18 +2,21 @@ import typescriptEslint from "@typescript-eslint/eslint-plugin";
 import globals from "globals";
 import tsParser from "@typescript-eslint/parser";
 
+const __dirname = import.meta.dirname; // built-in, no imports needed
+
 export default [ 
     {
-        files: ["*.ts", "*tsx"],
         ignores: [
-            "node_modules/",
-            "dist/",
-            "templates/",
-            "spec/*/**",
-            "**/lib/",
-            "bin/",
-            "eslint.config.mjs",
+            "node_modules/**",
+            "dist/**",
+            "templates/**",
+            "spec/**",
+            "lib/**",
+            "bin/**",
         ],
+    },
+    {
+        files: ["**/*.ts", "**/*.tsx"],
         plugins: {
             "@typescript-eslint": typescriptEslint,
         },
@@ -26,7 +29,7 @@ export default [
             sourceType: "module",
             parserOptions: {
                 project: "tsconfig.json",
-                tsconfigRootDir: ".",
+                tsconfigRootDir: __dirname,
             },
         },
         rules: {

package/lib/CertificateTools.js

@@ -179,7 +179,7 @@ async function openCertFile() {
         }
         await exec(`${startCmd} "${certPath}"`);
     }
-    catch (e) {
+    catch {
         ConsoleWriter.info(['Certificate path:', certPath]);
     }
 }

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/Visual.js

@@ -17,6 +17,12 @@ export class Visual {
     isVisualVersionValid(length) {
         return this.visualVersion.split(".").length === length;
     }
+    isAuthorDefined() {
+        const author = this.config?.author;
+        const emailRegex = /^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$/;
+        return typeof author?.name === "string" && author.name.length > 0 &&
+            typeof author?.email === "string" && emailRegex.test(author.email);
+    }
     getVisualFeatureType() {
         const isMatrixSupported = this.capabilities?.dataViewMappings?.some(dataView => dataView.matrix);
         const isSlicer = Boolean(this.capabilities?.objects?.general?.properties?.filter?.type?.filter);

package/lib/VisualGenerator.js

@@ -96,7 +96,7 @@ function fileExists(file) {
     try {
         fs.accessSync(file);
     }
-    catch (e) {
+    catch {
         return false;
     }
     return true;
@@ -120,7 +120,7 @@ function validTemplate(templateName) {
     try {
         fs.accessSync(path.join(VISUAL_TEMPLATES_PATH, templateName));
     }
-    catch (e) {
+    catch {
         return false;
     }
     return true;

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/WebPackWrap.js

@@ -6,7 +6,6 @@ import util from 'util';
 const exec = util.promisify(processExec);
 import { exec as processExec } from 'child_process';
 import lodashCloneDeep from 'lodash.clonedeep';
-import ExtraWatchWebpackPlugin from 'extra-watch-webpack-plugin';
 import { BundleAnalyzerPlugin } from 'webpack-bundle-analyzer';
 import { PowerBICustomVisualsWebpackPlugin, LocalizationLoader } from 'powerbi-visuals-webpack-plugin';
 import ConsoleWriter from './ConsoleWriter.js';
@@ -180,9 +179,14 @@ export default class WebPackWrap {
                 analyzerMode: `static`
             }));
         }
-        this.webpackConfig.plugins.push(new PowerBICustomVisualsWebpackPlugin(pluginConfiguration), new ExtraWatchWebpackPlugin({
-            files: this.pbiviz.capabilities
-        }));
+        this.webpackConfig.plugins.push(new PowerBICustomVisualsWebpackPlugin(pluginConfiguration), {
+            apply: (compiler) => {
+                compiler.hooks.afterCompile.tap('AddCapabilitiesWatch', (compilation) => {
+                    const capabilitiesPath = path.resolve(process.cwd(), this.pbiviz.capabilities);
+                    compilation.fileDependencies.add(capabilitiesPath);
+                });
+            }
+        });
     }
     async configureLoaders({ fast = false, includeAllLocales = false }) {
         this.webpackConfig.module.rules.push({

package/lib/features/AuthorInfo.js

@@ -0,0 +1,14 @@
+import { Severity, Stage, VisualFeatureType } from "./FeatureTypes.js";
+export default class AuthorInfo {
+    static featureName = "Author information";
+    static documentationLink = "https://learn.microsoft.com/en-us/power-bi/developer/visuals/visual-project-structure#metadata-entries";
+    static errorMessage = `${this.featureName} - ${this.documentationLink}`;
+    static severity = Severity.Error;
+    static stage = Stage.PreBuild;
+    static visualFeatureType = VisualFeatureType.All;
+    static isSupported(visual) {
+        return visual.isAuthorDefined();
+    }
+}
+// The pbiviz.json schema validates author.name and author.email when present,
+// but doesn't require the author object itself. This check fills that gap.

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/features/index.js

@@ -1,6 +1,7 @@
 import AdvancedEditMode from './AdvancedEditMode.js';
 import AllowInteractions from './AllowInteractions.js';
 import AnalyticsPane from './AnalyticsPane.js';
+import AuthorInfo from './AuthorInfo.js';
 import Bookmarks from './Bookmarks.js';
 import ColorPalette from './ColorPalette.js';
 import ConditionalFormatting from './ConditionalFormatting.js';
@@ -25,4 +26,4 @@ import TotalSubTotal from './TotalSubTotal.js';
 import WarningIcon from './WarningIcon.js';
 import APIVersion from './APIVersion.js';
 import VisualVersion from './VisualVersion.js';
-export { AdvancedEditMode, AllowInteractions, AnalyticsPane, Bookmarks, ColorPalette, ConditionalFormatting, ContextMenu, DrillDown, FetchMoreData, FileDownload, FormatPane, HighContrast, HighlightData, KeyboardNavigation, LandingPage, LaunchURL, Localizations, LocalStorage, ModalDialog, RenderingEvents, SelectionAcrossVisuals, SyncSlicer, Tooltips, TotalSubTotal, WarningIcon, APIVersion, VisualVersion };
+export { AdvancedEditMode, AllowInteractions, AnalyticsPane, Bookmarks, ColorPalette, ConditionalFormatting, ContextMenu, DrillDown, FetchMoreData, FileDownload, FormatPane, HighContrast, HighlightData, KeyboardNavigation, LandingPage, LaunchURL, Localizations, LocalStorage, ModalDialog, RenderingEvents, SelectionAcrossVisuals, SyncSlicer, Tooltips, TotalSubTotal, WarningIcon, APIVersion, VisualVersion, AuthorInfo };