@microsoft/powerbi-modeling-mcp-linux-arm64 0.5.0-beta.13 → 0.5.0-beta.15

package/dist/Resources/dax_udf_instructions_and_examples.md

@@ -0,0 +1,270 @@
+---
+name: 'DAX UDF Instructions and Examples'
+description: 'Guidelines for creating Power BI DAX user-defined functions (UDFs)'
+uriTemplate: 'resource://dax_udf_instructions_and_examples'
+---
+# DAX User-Defined Functions (UDFs) Guide
+
+## Overview
+
+DAX User-Defined Functions (UDFs) allow you to create reusable function definitions in Power BI semantic models. This guide explains the syntax, type system, and best practices for defining UDFs.
+
+## Basic Syntax
+
+A UDF definition consists of a function name and a function definition with parameters and a body:
+
+```yaml
+FunctionName: MyFunction
+FunctionDefinition: |-
+  (param1 [: Type [Scalar Subtype] [Val|Expr]],
+   param2 [: Type [Scalar Subtype] [Val|Expr]],
+   ...
+  ) =>
+      <Function body>
+```
+
+## Type System
+
+### Parameter Types
+
+DAX UDFs support three main parameter types:
+
+* **Scalar**: A single value (number, text, date/time, boolean)
+* **Table**: A DAX table expression
+* **AnyRef**: A direct reference to an existing semantic model object without pre-evaluation
+
+#### Scalar Subtypes
+
+When using `Scalar` type, you can optionally specify a subtype:
+
+* `Int64`: Integer values
+* `Decimal`: Decimal numbers
+* `Double`: Double-precision floating-point numbers
+* `String`: Text values
+* `DateTime`: Date and time values
+* `Boolean`: True/false values
+* `Numeric`: Any numeric type (Int64, Decimal, or Double)
+* `Variant`: Any scalar type (use when the expression may yield different types)
+
+**Note**: `BLANK()` is valid for any subtype.
+
+### AnyRef Type
+
+Use `AnyRef` when you need a direct reference to a model object rather than its evaluated value. This is useful for functions that need to pass references to functions like CALCULATE, TREATAS, or SAMEPERIODLASTYEAR.
+
+Allowed reference forms:
+
+* Column reference: `'Table'[Column]`
+* Table reference: `'Table'`
+* Measure reference: `[Measure]`
+* Calendar reference: `MyCalendar`
+
+### Parameter Modes
+
+Parameters can be evaluated in two modes:
+
+* **Val** (value mode - default): The argument expression is evaluated at the call site before entering the function. The resulting value is substituted wherever the parameter is used.
+* **Expr** (expression mode): The raw argument expression is substituted into the function body and evaluated in its inner context. Use this when you want the expression to be re-evaluated within inner contexts created by CALCULATE, FILTER, or iteration functions.
+
+## Example Schema
+
+The following examples reference this sample data model:
+
+```yaml
+Tables:
+  - Name: Sales
+    Measures:
+      - Name: Total Amount
+        Type: Decimal
+      - Name: Total Quantity
+        Type: Integer
+    Columns:
+      - Name: CustomerKey
+        Type: Text
+      - Name: ProductKey
+        Type: Text
+      - Name: OrderDate
+        Type: Date
+  - Name: Product
+    Columns:
+      - Name: ProductKey
+        Type: Text
+      - Name: Name
+        Type: Text
+      - Name: Color
+        Type: Text
+  - Name: Customer
+    Columns:
+      - Name: CustomerKey
+        Type: Text
+      - Name: Name
+        Type: Text
+  - Name: Calendar
+    Columns:
+      - Name: Date
+        Type: Date
+      - Name: Month
+        Type: Text
+        SortByColumnName: MonthNumberOfYear
+      - Name: MonthNumberOfYear
+        Type: Integer
+      - Name: Year
+        Type: Integer
+Active Relationships:
+  - PK: 'Product'[ProductKey]
+    FK: 'Sales'[ProductKey]
+    Unidirectional Filter Propagation: "'Product' filters 'Sales'"
+  - PK: 'Customer'[CustomerKey]
+    FK: 'Sales'[CustomerKey]
+    Unidirectional Filter Propagation: "'Customer' filters 'Sales'"
+  - PK: 'Calendar'[Date]
+    FK: 'Sales'[OrderDate]
+    Unidirectional Filter Propagation: "'Calendar' filters 'Sales'"
+```
+
+## Examples
+
+### Example 1: Simple Numeric Calculation
+
+Calculate the area of a circle from its radius.
+
+```yaml
+FunctionName: CircleArea
+FunctionDefinition: |-
+    (radius : Scalar Numeric) =>
+        PI() * radius * radius
+```
+
+**Usage**: `CircleArea(5)` returns approximately 78.54
+
+### Example 2: Basic Value Transformation
+
+Double an input value.
+
+```yaml
+FunctionName: DoubleValue
+FunctionDefinition: |-
+    (inputValue : Scalar Numeric Val) =>
+        inputValue * 2
+```
+
+**Usage**: `DoubleValue(10)` returns 20
+
+### Example 3: Working with AnyRef - Statistical Function
+
+Returns the most frequently occurring value in a column.
+
+```yaml
+FunctionName: Mode
+FunctionDefinition: |-
+    (tab : AnyRef,
+     col : AnyRef
+    ) =>
+        MINX(
+            TOPN(
+                1,
+                ADDCOLUMNS(
+                    VALUES(col),
+                    "Freq", CALCULATE(COUNTROWS(tab))
+                ),
+                [Freq], DESC
+            ),
+            col
+        )
+```
+
+**Explanation**: This function uses `AnyRef` for both parameters because it needs to pass the table and column references to DAX functions like VALUES and CALCULATE. The function finds the value that appears most frequently by counting occurrences.
+
+**Usage**: `Mode('Sales', 'Sales'[ProductKey])`
+
+### Example 4: Using Expr Mode for Time Intelligence
+
+Evaluate any scalar expression in the prior year.
+
+```yaml
+FunctionName: PriorYearValue
+FunctionDefinition: |-
+    (expression : Scalar Variant Expr,
+     dateColumn : AnyRef
+    ) =>
+        CALCULATE(
+            expression,
+            SAMEPERIODLASTYEAR(dateColumn)
+        )
+```
+
+**Explanation**: The `expression` parameter uses `Expr` mode so it's evaluated within the CALCULATE context with the prior year filter applied. The `dateColumn` uses `AnyRef` to pass the column reference to SAMEPERIODLASTYEAR.
+
+**Usage**: `PriorYearValue([Total Amount], 'Calendar'[Date])`
+
+### Example 5: Returning a Table Filter
+
+Return today's date as a one-row table for filtering.
+
+```yaml
+FunctionName: TodayAsDate
+FunctionDefinition: |-
+    () =>
+        TREATAS(
+            { TODAY() },
+            'Date'[Date]
+        )
+```
+
+**Explanation**: This function demonstrates a UDF that returns a table. It uses TREATAS to convert the single-value table into a filter compatible with the Date table.
+
+**Usage**: `CALCULATE([Total Amount], TodayAsDate())`
+
+### Example 6: Table-Returning Function
+
+Return a table of the top 3 Products by the [Sales] measure.
+
+```yaml
+FunctionName: Top3ProductsBySales
+FunctionDefinition: |-
+    () =>
+        TOPN(
+            3,
+            VALUES('Product'[ProductKey]),
+            [Sales], DESC
+        )
+```
+
+**Explanation**: This parameterless function returns a table containing the top 3 products. It can be used anywhere a table expression is expected.
+
+**Usage**: `CALCULATE([Total Amount], Top3ProductsBySales())`
+
+### Example 7: String Manipulation with Table Return
+
+Split a text by a delimiter and return a single-column table.
+
+```yaml
+FunctionName: SplitString
+FunctionDefinition: |-
+    (s : Scalar String,
+     delimiter : Scalar String
+    ) =>
+    VAR str =
+        SUBSTITUTE(s, delimiter, "|")
+    VAR len =
+        PATHLENGTH(str)
+    RETURN
+        SELECTCOLUMNS(
+            GENERATESERIES(1, len),
+            "Value", PATHITEM(str, [Value], TEXT)
+        )
+```
+
+**Explanation**: This function uses variables (VAR) and demonstrates how to build complex logic. It converts the delimiter to a path separator, counts the parts, and returns a table with each part as a row.
+
+**Usage**: `SplitString("apple,banana,cherry", ",")`
+
+## Best Practices
+
+1. **Use appropriate type hints**: Specify types and subtypes to make your functions more robust and self-documenting
+2. **Choose the right parameter mode**: Use `Expr` when you need the expression to be evaluated in the function's context, otherwise use `Val` (default)
+3. **Use AnyRef for references**: When passing columns, tables, or measures to DAX functions that expect references, use `AnyRef`
+4. **Document your functions**: Include clear descriptions of what each function does
+5. **Test with edge cases**: Consider BLANK values and empty tables in your function logic
+6. **Keep functions focused**: Each function should have a single, well-defined purpose
+7. **Use variables**: For complex functions, use VAR to break down logic and improve readability

package/dist/Resources/powerbi_project_instructions.md

@@ -0,0 +1,84 @@
+---
+name: 'PowerBI Project Instructions'
+description: 'Instructions for structuring Power BI projects'
+uriTemplate: 'resource://powerbi_project_instructions'
+---
+You are an expert in Power BI Project (PBIP) file structure.
+
+If the `powerbi-modeling-mcp` MCP server is available, **do not create or edit the TMDL files directly**.
+
+## PBIP structure
+
+```text
+root/
+├── [Name].SemanticModel/
+|   ├── /definition # The semantic model definition using TMDL language
+|   ├──  definition.pbism # The semantic model definition file
+├── [Name].Report/        
+|   ├── /definition # The report definition using PBIR format
+|   ├──  definition.pbir # The report definition file with a byPath relative reference to the semantic model folder
+└── [Name].pbip # A shortcut file to the report folder
+```    
+
+**Example of a definition.pbism file**
+
+No modifications are needed—just create the file exactly as shown in the example.
+
+```json
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/semanticModel/definitionProperties/1.0.0/schema.json",
+    "version": "4.2",
+    "settings": {
+        "qnaEnabled": true
+    }
+}
+```
+
+**Example of a definition.pbir file**
+
+The `byPath` property should reference the semantic model folder using a relative path like below.
+
+```json
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
+    "version": "4.0",
+    "datasetReference": {
+        "byPath": {
+            "path": "../{Name of the Semantic Model}.SemanticModel"
+        }
+    }
+}
+```
+
+**Example of a {Name of the Semantic Model}.pbip file**
+
+```json
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/fabric/pbip/pbipProperties/1.0.0/schema.json",
+    "version": "1.0",
+    "artifacts": [
+        {
+        "report": {
+            "path": "{Name of the Semantic Model}.Report"
+        }
+        }
+    ],
+    "settings": {
+        "enableAutoRecovery": true
+    }
+}
+```
+
+## Open from PBIP
+
+When asked to open/load the semantic model from a PBIP, you must only load the `[Name].SemanticModel/definition` folder. No other folder is suitable to load from semantic model developer tools.
+
+## Save to PBIP
+
+When asked to save to a new PBIP folder make sure you create the folder and files from the structure above using the provided examples.
+
+## Creation of new semantic model
+
+1. Create a PBIP folder for the semantic model following the structure above
+2. Use the `database_operations` tool of the MCP server to `Create` a new database. 
+3. In the end of the authoring session, serialize as TMDL to the `definition/` folder in the PBIP

package/dist/Resources/tools/tool-metadata.override.yaml

@@ -0,0 +1,7 @@
+tools:
+  accept_eula:
+    description: >-
+      Accepts the Power BI Authoring MCP End User License Agreement (EULA) at https://github.com/microsoft/powerbi-modeling-mcp. This tool must not be called automatically or speculatively by an AI agent. Only call it after a human user has reviewed the EULA at that URL and explicitly instructed you to accept it on their behalf.
+    request:
+      EulaUrl: >-
+        The exact EULA URL the user reviewed. Must be https://github.com/microsoft/powerbi-modeling-mcp