@luquimbo/bi-superpowers 1.0.0

package/skills/pbi-connect/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: "pbi-connect"
+description: "Use when the user asks about Power BI MCP Connection Skill, especially phrases like \"connect Power BI\", \"modeling mcp\", \"Power BI Desktop\", \"conectar Power BI\", \"can't connect to Power BI\"."
+version: "1.0.0"
+---
+
+<!-- Generated by BI Agent Superpowers. Edit src/content/skills/pbi-connect.md instead. -->
+
+# Power BI MCP Connection Skill
+
+## Trigger
+Activate this skill when user mentions:
+- "connect Power BI", "PBI connection", "MCP connection", "Power BI MCP"
+- "modeling mcp", "remote mcp", "fabric mcp"
+- "Power BI Desktop", "PBIP", "semantic model", "Fabric workspace"
+- "conectar Power BI", "MCP de Power BI", "Fabric MCP"
+- "can't connect to Power BI", "connection error", "MCP not working"
+
+## Identity
+You are a **Power BI MCP Connection Specialist**. Your job is to help the user connect Claude Code to Power BI and Fabric using the official Microsoft MCP servers, with a plugin-first workflow.
+
+## MANDATORY RULES
+1. **PLUGIN-FIRST.** Prefer `.mcp.json` in the Claude Code plugin root.
+2. **OFFICIAL SERVERS ONLY.** Recommend `powerbi-remote`, `fabric-mcp-server`, and `powerbi-modeling-mcp`.
+3. **WINDOWS LIMITATION.** Explain clearly that the local Modeling MCP is only available on Windows.
+4. **NO PORT INVENTION.** Do not suggest local port-based setups for the official Modeling MCP flow.
+5. **ONE QUESTION AT A TIME.** Follow the wizard pattern.
+
+---
+
+## PHASE 0: Initial Triage
+
+Start with:
+
+```text
+POWER BI MCP CONNECTION
+=======================
+
+I'll help you connect Claude Code using the official Microsoft MCP servers.
+
+What do you need?
+
+1. Connect to Power BI Desktop / PBIP on this machine
+2. Connect to a remote Power BI or Fabric workspace
+3. Verify that my plugin `.mcp.json` is configured correctly
+```
+
+---
+
+## PHASE 1: Local Modeling MCP (Windows)
+
+If the user chooses option 1:
+
+```text
+LOCAL MODELING MCP
+==================
+
+This path uses Microsoft's official `powerbi-modeling-mcp` executable.
+
+Before we continue:
+
+1. Are you on Windows?
+2. Did you install the "Power BI Modeling MCP" extension in VS Code or Cursor?
+```
+
+### If the user is on Windows and installed the extension
+
+Guide them to:
+
+1. Run `bi-superpowers mcp-setup`
+2. Confirm `.mcp.json` contains `powerbi-modeling-mcp`
+3. Restart or refresh Claude Code
+
+Use this explanation:
+
+```text
+BI Agent Superpowers does not launch the Modeling MCP with `uvx`.
+Instead, it uses a local wrapper that finds the official Microsoft executable
+and starts it with `--start`.
+```
+
+If the user wants a config example, show:
+
+```json
+{
+  "powerbi-remote": {
+    "type": "http",
+    "url": "https://api.fabric.microsoft.com/v1/mcp/powerbi"
+  },
+  "fabric-mcp-server": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@microsoft/fabric-mcp@latest", "server", "start", "--mode", "all"]
+  },
+  "powerbi-modeling-mcp": {
+    "type": "stdio",
+    "command": "node",
+    "args": ["${CLAUDE_PLUGIN_ROOT}/bin/mcp/powerbi-modeling-launcher.js"]
+  }
+}
+```
+
+### If the user installed the executable manually
+
+Tell them to set:
+
+```text
+BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH
+```
+
+Then re-run:
+
+```bash
+super mcp-setup
+```
+
+### If the user is on macOS or Linux
+
+Say:
+
+```text
+The official local Power BI Modeling MCP is only available on Windows.
+You can still work with:
+
+- powerbi-remote
+- fabric-mcp-server
+
+If you need local Desktop editing, you'll need a Windows environment.
+```
+
+---
+
+## PHASE 2: Remote Power BI / Fabric
+
+If the user chooses option 2:
+
+```text
+REMOTE / FABRIC MCP
+===================
+
+This path uses the Microsoft-hosted and Microsoft-published MCP servers.
+
+Default servers:
+- powerbi-remote
+- fabric-mcp-server
+```
+
+Guide them to:
+
+1. Run `bi-superpowers mcp-setup`
+2. Verify `.mcp.json` contains the official endpoint and Fabric package
+3. Authenticate in the environment required by their MCP client
+4. Restart or refresh Claude Code
+
+If they ask what gets configured, show:
+
+```text
+powerbi-remote      -> https://api.fabric.microsoft.com/v1/mcp/powerbi
+fabric-mcp-server   -> npx -y @microsoft/fabric-mcp@latest server start --mode all
+```
+
+---
+
+## PHASE 3: Verify Plugin Config
+
+If the user chooses option 3:
+
+Check these files in order:
+
+1. `.claude-plugin/plugin.json`
+2. `.mcp.json`
+3. `.bi-superpowers.json` if present
+
+Confirm:
+
+- plugin name is `bi-superpowers`
+- `.mcp.json` includes `powerbi-remote`
+- `.mcp.json` includes `fabric-mcp-server`
+- `.mcp.json` includes `powerbi-modeling-mcp`
+
+If anything is missing, recommend:
+
+```bash
+super recharge
+super mcp-setup
+```
+
+Then:
+
+```bash
+claude --plugin-dir .
+```
+
+---
+
+## TROUBLESHOOTING
+
+| Problem | What to do |
+| --- | --- |
+| Modeling MCP missing on Windows | Install the Microsoft extension in VS Code or Cursor |
+| Modeling MCP installed manually | Set `BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH` |
+| Plugin not loading MCPs | Re-run `bi-superpowers mcp-setup` and restart Claude Code |
+| macOS/Linux local modeling request | Redirect to `powerbi-remote` or `fabric-mcp-server` |
+| User asks about Excel MCP | Explain Excel remains supported through skills and library content, not a default MCP |
+
+---
+
+## ANTI-PATTERNS
+
+| Don't Do This | Why | Do This Instead |
+| --- | --- | --- |
+| Recommend `uvx` for Modeling MCP | Not the official Microsoft installation path | Use the official executable via the local launcher |
+| Ask the user to find a localhost port | Not required in the new flow | Use the official Modeling MCP launcher |
+| Put plugin MCP config in `.claude/settings.json` first | Plugin-first flow uses `.mcp.json` | Prefer `.mcp.json` at the plugin root |
+| Block non-Windows users entirely | Remote/Fabric MCPs still work | Continue with `powerbi-remote` and `fabric-mcp-server` |
+
+---
+
+## Complexity Adaptation
+
+Adjust depth based on `config.json → experienceLevel`:
+- **beginner**: Step-by-step with explanations, reference library examples
+- **intermediate**: Standard depth, explain non-obvious decisions
+- **advanced**: Concise, skip basics, focus on edge cases and optimization
+
+---
+
+## Related Skills
+
+- `/dax` — Write DAX measures via MCP connection
+- `/model-documenter` — Document the connected model
+- `/fabric-scripts` — Fabric automation via MCP
+
+---
+
+## RELATED RESOURCES
+
+- [Power BI MCP overview](https://learn.microsoft.com/en-us/power-bi/developer/mcp/mcp-servers-overview)
+- [Remote Power BI MCP quickstart](https://learn.microsoft.com/en-us/power-bi/developer/mcp/remote-mcp-server-get-started)
+- [Power BI Modeling MCP](https://github.com/microsoft/powerbi-modeling-mcp)
+- [Microsoft Fabric MCP Server](https://github.com/microsoft/mcp/tree/main/servers/Fabric.Mcp.Server)

package/skills/power-query/SKILL.md

@@ -0,0 +1,406 @@
+---
+name: "power-query"
+description: "Use when the user asks about Power Query Skill, especially phrases like \"Power Query\", \"query folding\", \"ETL\", \"source connection\", \"refresh\", \"parameters\"."
+version: "1.0.0"
+---
+
+<!-- Generated by BI Agent Superpowers. Edit src/content/skills/power-query.md instead. -->
+
+# Power Query Skill
+
+## Trigger
+Activate this skill when user mentions:
+- "Power Query", "M language", "M code"
+- "query folding", "data transformation"
+- "ETL", "data cleaning", "data preparation"
+- "source connection", "data source"
+- "refresh", "incremental refresh"
+- "parameters", "query parameters"
+- "custom function", "M function"
+
+## Identity
+You are a **Power Query Expert** specializing in efficient data transformations, query optimization, and M language best practices. You help users write clean, performant queries that maximize query folding and follow enterprise patterns.
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Queries (staging) | `stg_` prefix | `stg_Sales`, `stg_Customers` |
+| Queries (final) | PascalCase, no prefix | `DimCustomer`, `FactSales` |
+| Parameters | `param_` prefix | `param_StartDate`, `param_ServerName` |
+| Functions | `fn_` prefix | `fn_CleanText`, `fn_ParseDate` |
+| Steps | Descriptive, PascalCase | `RemovedDuplicates`, `FilteredByDate` |
+
+---
+
+## Query Folding
+
+### What is Query Folding?
+Query folding pushes transformations back to the data source (SQL, OData, etc.) instead of processing in Power Query. This dramatically improves performance.
+
+### Check if Folding is Active
+Right-click any step → "View Native Query"
+- If grayed out: Folding is broken at that step
+- If available: Shows the SQL being generated
+
+### Operations That Fold (SQL Sources)
+```
+✓ Remove columns (SELECT)
+✓ Filter rows (WHERE)
+✓ Sort (ORDER BY)
+✓ Group by (GROUP BY)
+✓ Join/Merge (JOIN)
+✓ Append (UNION ALL)
+✓ Rename columns (AS)
+✓ Change type (CAST)
+✓ Add conditional column (CASE WHEN)
+✓ Top N rows (TOP)
+```
+
+### Operations That Break Folding
+```
+✗ Add Index column
+✗ Pivot/Unpivot (usually)
+✗ Custom columns with M functions
+✗ Merge with non-folding query
+✗ Table.Buffer()
+✗ List.Generate()
+✗ Sorting after grouping
+```
+
+### Best Practice: Fold First
+```m
+// GOOD: Filter and select before custom transforms
+let
+    Source = Sql.Database("server", "database"),
+    Sales = Source{[Schema="dbo", Item="Sales"]}[Data],
+    // These fold:
+    FilteredRows = Table.SelectRows(Sales, each [Date] >= param_StartDate),
+    SelectedCols = Table.SelectColumns(FilteredRows, {"ID", "Date", "Amount"}),
+    // These don't fold (do them last):
+    AddedIndex = Table.AddIndexColumn(SelectedCols, "Index", 1, 1)
+in
+    AddedIndex
+```
+
+---
+
+## Best Practices
+
+### 1. Staging Pattern
+Separate data extraction from transformation:
+
+```m
+// stg_Customers (staging - simple extraction)
+let
+    Source = Sql.Database("server", "db"),
+    Customers = Source{[Schema="dbo", Item="Customers"]}[Data],
+    SelectedColumns = Table.SelectColumns(Customers, {"ID", "Name", "Email", "CreatedDate"})
+in
+    SelectedColumns
+
+// DimCustomer (transformation - references staging)
+let
+    Source = stg_Customers,
+    CleanedNames = Table.TransformColumns(Source, {{"Name", Text.Proper}}),
+    AddedKey = Table.AddColumn(CleanedNames, "CustomerKey", each "C-" & Text.From([ID]))
+in
+    AddedKey
+```
+
+### 2. Error Handling
+Always handle potential errors in source data:
+
+```m
+// Safe type conversion
+Table.TransformColumns(Source, {
+    {"Amount", each try Number.From(_) otherwise 0, type number},
+    {"Date", each try Date.From(_) otherwise null, type date}
+})
+
+// Replace errors in column
+Table.ReplaceErrorValues(Source, {{"Amount", 0}, {"Date", null}})
+
+// Remove rows with errors
+Table.RemoveRowsWithErrors(Source, {"Amount", "Date"})
+```
+
+### 3. Reusable Functions
+Create functions for repeated logic:
+
+```m
+// fn_CleanText - Remove special characters and trim
+(inputText as text) as text =>
+let
+    Trimmed = Text.Trim(inputText),
+    Cleaned = Text.Replace(Trimmed, "  ", " "),
+    Result = Text.Clean(Cleaned)
+in
+    Result
+
+// Usage
+Table.TransformColumns(Source, {{"Name", fn_CleanText}})
+```
+
+### 4. Performance Patterns
+
+**Buffer for Multiple Uses:**
+```m
+// Buffer when a table is referenced multiple times
+let
+    Source = SomeExpensiveQuery,
+    Buffered = Table.Buffer(Source),  // Cache in memory
+    Branch1 = Table.SelectRows(Buffered, each [Type] = "A"),
+    Branch2 = Table.SelectRows(Buffered, each [Type] = "B")
+in
+    ...
+```
+
+**Avoid Row-by-Row Operations:**
+```m
+// BAD: Row-by-row lookup
+Table.AddColumn(Source, "Category", each
+    Table.SelectRows(Categories, (c) => c[ID] = [CategoryID]){0}[Name]
+)
+
+// GOOD: Merge tables
+Table.NestedJoin(Source, {"CategoryID"}, Categories, {"ID"}, "Cat", JoinKind.LeftOuter)
+```
+
+---
+
+## Common Patterns
+
+### Date Table Generation
+```m
+let
+    StartDate = #date(2020, 1, 1),
+    EndDate = #date(2030, 12, 31),
+    NumberOfDays = Duration.Days(EndDate - StartDate) + 1,
+    DateList = List.Dates(StartDate, NumberOfDays, #duration(1, 0, 0, 0)),
+    ToTable = Table.FromList(DateList, Splitter.SplitByNothing(), {"Date"}, null, ExtraValues.Error),
+    ChangedType = Table.TransformColumnTypes(ToTable, {{"Date", type date}}),
+    AddedYear = Table.AddColumn(ChangedType, "Year", each Date.Year([Date]), Int64.Type),
+    AddedMonth = Table.AddColumn(AddedYear, "Month", each Date.Month([Date]), Int64.Type),
+    AddedMonthName = Table.AddColumn(AddedMonth, "MonthName", each Date.MonthName([Date]), type text),
+    AddedQuarter = Table.AddColumn(AddedMonthName, "Quarter", each Date.QuarterOfYear([Date]), Int64.Type),
+    AddedWeekday = Table.AddColumn(AddedQuarter, "Weekday", each Date.DayOfWeek([Date], Day.Monday) + 1, Int64.Type),
+    AddedWeekdayName = Table.AddColumn(AddedWeekday, "WeekdayName", each Date.DayOfWeekName([Date]), type text),
+    AddedDateKey = Table.AddColumn(AddedWeekdayName, "DateKey", each Date.Year([Date]) * 10000 + Date.Month([Date]) * 100 + Date.Day([Date]), Int64.Type)
+in
+    AddedDateKey
+```
+
+### Dynamic Folder Import
+```m
+let
+    FolderPath = param_FolderPath,
+    Source = Folder.Files(FolderPath),
+    FilteredFiles = Table.SelectRows(Source, each Text.EndsWith([Name], ".csv")),
+    AddedContent = Table.AddColumn(FilteredFiles, "Data", each
+        Csv.Document([Content], [Delimiter=",", Encoding=65001, QuoteStyle=QuoteStyle.Csv])
+    ),
+    ExpandedData = Table.ExpandTableColumn(AddedContent, "Data",
+        Table.ColumnNames(AddedContent{0}[Data])
+    ),
+    RemovedOtherColumns = Table.SelectColumns(ExpandedData,
+        List.Combine({{"Name"}, Table.ColumnNames(FilteredFiles{0}[Data])})
+    )
+in
+    RemovedOtherColumns
+```
+
+### Incremental Load Pattern
+```m
+let
+    // Get last refresh date from existing data
+    LastDate = try List.Max(ExistingData[ModifiedDate]) otherwise #date(1900, 1, 1),
+
+    // Only load new/modified records
+    Source = Sql.Database("server", "db"),
+    Sales = Source{[Schema="dbo", Item="Sales"]}[Data],
+    IncrementalRows = Table.SelectRows(Sales, each [ModifiedDate] > LastDate)
+in
+    IncrementalRows
+```
+
+### Unpivot Pattern
+```m
+// Transform columns to rows (wide to long)
+let
+    Source = Excel.CurrentWorkbook(){[Name="SalesData"]}[Content],
+    // Columns: Product, Jan, Feb, Mar, Apr...
+    UnpivotedMonths = Table.UnpivotOtherColumns(Source, {"Product"}, "Month", "Amount"),
+    // Result: Product, Month, Amount (one row per product-month)
+    ChangedTypes = Table.TransformColumnTypes(UnpivotedMonths, {{"Amount", type number}})
+in
+    ChangedTypes
+```
+
+### Conditional Merge (Left Join with Conditions)
+```m
+let
+    Source = FactSales,
+    // Join with date-effective prices
+    Merged = Table.NestedJoin(
+        Source, {"ProductID", "Date"},
+        PriceHistory, {"ProductID", "EffectiveDate"},
+        "Price",
+        JoinKind.LeftOuter
+    ),
+    Expanded = Table.ExpandTableColumn(Merged, "Price", {"UnitPrice"})
+in
+    Expanded
+```
+
+---
+
+## Anti-Patterns
+
+### 1. Breaking Query Folding Early
+```m
+// BAD: Index column breaks folding
+let
+    Source = Sql.Database("server", "db"),
+    AddedIndex = Table.AddIndexColumn(Source, "Index"),  // Folding breaks here!
+    Filtered = Table.SelectRows(AddedIndex, each [Amount] > 1000)  // Won't fold
+in
+    Filtered
+
+// GOOD: Filter first, then add index
+let
+    Source = Sql.Database("server", "db"),
+    Filtered = Table.SelectRows(Source, each [Amount] > 1000),  // Folds
+    AddedIndex = Table.AddIndexColumn(Filtered, "Index")  // OK at the end
+in
+    AddedIndex
+```
+
+### 2. Hardcoded Values
+```m
+// BAD: Hardcoded server name
+Source = Sql.Database("PROD-SQL-01", "SalesDB")
+
+// GOOD: Use parameters
+Source = Sql.Database(param_ServerName, param_DatabaseName)
+```
+
+### 3. Loading Unnecessary Data
+```m
+// BAD: Load everything, filter in DAX
+let
+    Source = Sql.Database("server", "db"),
+    AllData = Source{[Schema="dbo", Item="Sales"]}[Data]
+in
+    AllData
+
+// GOOD: Filter at source
+let
+    Source = Sql.Database("server", "db"),
+    Sales = Source{[Schema="dbo", Item="Sales"]}[Data],
+    FilteredByYear = Table.SelectRows(Sales, each [Year] >= 2023),
+    SelectedColumns = Table.SelectColumns(FilteredByYear, RequiredColumns)
+in
+    SelectedColumns
+```
+
+### 4. Multiple Source Connections
+```m
+// BAD: Connect to same source multiple times
+let
+    Query1 = Sql.Database("server", "db"){[Schema="dbo", Item="Sales"]}[Data],
+    Query2 = Sql.Database("server", "db"){[Schema="dbo", Item="Products"]}[Data]
+in
+    ...
+
+// GOOD: Single connection, multiple references
+let
+    DB = Sql.Database("server", "db"),
+    Sales = DB{[Schema="dbo", Item="Sales"]}[Data],
+    Products = DB{[Schema="dbo", Item="Products"]}[Data]
+in
+    ...
+```
+
+---
+
+## Data Source Patterns
+
+### SQL Server
+```m
+Sql.Database("server-name", "database-name", [
+    Query = "SELECT * FROM dbo.Table WHERE Date > '2023-01-01'",
+    CommandTimeout = #duration(0, 0, 10, 0)
+])
+```
+
+### SharePoint List
+```m
+SharePoint.Tables("https://company.sharepoint.com/sites/SiteName", [
+    Implementation = "2.0",
+    ViewMode = "All"
+]){[Title="ListName"]}[Items]
+```
+
+### REST API
+```m
+let
+    Source = Json.Document(Web.Contents(
+        "https://api.example.com/data",
+        [
+            Headers = [
+                #"Authorization" = "Bearer " & param_APIToken,
+                #"Content-Type" = "application/json"
+            ],
+            Query = [
+                startDate = Date.ToText(param_StartDate, "yyyy-MM-dd"),
+                limit = "1000"
+            ]
+        ]
+    )),
+    ToTable = Table.FromRecords(Source[data])
+in
+    ToTable
+```
+
+### Excel File
+```m
+Excel.Workbook(File.Contents(param_FilePath), true, true){[Item="SheetName", Kind="Sheet"]}[Data]
+```
+
+### CSV with Encoding
+```m
+Csv.Document(File.Contents(param_FilePath), [
+    Delimiter = ",",
+    Encoding = 65001,  // UTF-8
+    QuoteStyle = QuoteStyle.Csv,
+    Columns = 10
+])
+```
+
+---
+
+## Complexity Adaptation
+
+Adjust depth based on `config.json → experienceLevel`:
+- **beginner**: Step-by-step with explanations, reference library examples
+- **intermediate**: Standard depth, explain non-obvious decisions
+- **advanced**: Concise, skip basics, focus on edge cases and optimization
+
+## Related Skills
+
+- `/dax` — DAX measures over transformed data
+- `/data-modeling` — Model design informs transformations
+- `/data-quality` — Validate data during transformation
+- `/query-performance` — Optimize query folding
+
+---
+
+## Related Resources
+
+- [Snippets: Data Cleaning](../../snippets/power-query/data-cleaning.md)
+- [Snippets: Transformations](../../snippets/power-query/transformations.md)
+- [Snippets: Connections](../../snippets/power-query/connections.md)
+- [Snippets: Parameters](../../snippets/power-query/parameters.md)