@luquimbo/bi-superpowers 1.0.0

package/desktop-extension/server.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+/**
+ * BI Agent Superpowers — MCP Server for Claude Desktop
+ *
+ * Lightweight MCP server that exposes all 24 BI skills as prompts.
+ * Bundled into a .mcpb extension via `super build-desktop`.
+ *
+ * Skills are loaded from the ./skills/ directory (copied at build time).
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillsDir = path.join(__dirname, 'skills');
+
+// Create the MCP server instance
+const server = new McpServer({
+  name: 'bi-superpowers',
+  version: '0.0.0-template',
+});
+
+// Load all skill markdown files from the bundled skills/ directory
+const skillFiles = fs.existsSync(skillsDir)
+  ? fs.readdirSync(skillsDir).filter((f) => f.endsWith('.md'))
+  : [];
+
+// Register each skill as an MCP prompt that Claude Desktop can invoke
+for (const file of skillFiles) {
+  const name = path.basename(file, '.md');
+  const content = fs.readFileSync(path.join(skillsDir, file), 'utf8');
+
+  // Extract first line as description (skip markdown headers)
+  const firstLine = content
+    .split('\n')
+    .find((l) => l.trim() && !l.startsWith('#'));
+  const description = firstLine
+    ? firstLine.slice(0, 120).trim()
+    : `BI Superpowers: ${name}`;
+
+  server.prompt(name, { description }, () => ({
+    messages: [
+      {
+        role: 'user',
+        content: { type: 'text', text: content },
+      },
+    ],
+  }));
+}
+
+// Register a setup-mcp helper prompt with Power BI/Fabric/Excel MCP instructions
+server.prompt(
+  'setup-mcp',
+  { description: 'Instructions to configure Power BI, Fabric & Excel MCP servers in Claude Desktop' },
+  () => ({
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `# Configure MCP Servers for Claude Desktop
+
+To connect Power BI, Fabric, and Excel to Claude Desktop, add the following
+to your \`claude_desktop_config.json\` (Settings > Developer > Edit Config):
+
+\`\`\`json
+{
+  "mcpServers": {
+    "powerbi-remote": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-remote", "https://mcp.powerbi.com/sse"]
+    },
+    "fabric-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-remote", "https://mcp.fabric.microsoft.com/v1/sse"]
+    }
+  }
+}
+\`\`\`
+
+After saving, restart Claude Desktop. The MCP servers will appear in your tools.
+`,
+        },
+      },
+    ],
+  })
+);
+
+// Start the server with stdio transport
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/docs/openrouter-free-models.md

@@ -0,0 +1,92 @@
+# Configure Claude Code with OpenRouter (Free Models)
+
+Use free AI models with Claude Code CLI and 1code.dev via OpenRouter.
+
+## Prerequisites
+
+- Node.js installed
+- Claude Code CLI installed (`npm install -g @anthropic-ai/claude-code`)
+- Free account at [openrouter.ai](https://openrouter.ai)
+
+## Step 1: Create OpenRouter API Key
+
+1. Go to [openrouter.ai](https://openrouter.ai) and create account (free)
+2. Go to [openrouter.ai/keys](https://openrouter.ai/keys)
+3. Click "Create Key"
+4. Copy the key (starts with `sk-or-v1-...`)
+
+## Step 2: Configure Environment Variables
+
+Add to the end of `~/.zshrc` (macOS/Linux) or your shell profile:
+
+```bash
+# OpenRouter + Claude Code
+export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
+export ANTHROPIC_AUTH_TOKEN="sk-or-v1-YOUR-KEY-HERE"
+export ANTHROPIC_API_KEY=""
+```
+
+> **Important**: `ANTHROPIC_API_KEY` MUST be empty (`""`). If it doesn't exist, Claude Code will try to authenticate with Anthropic directly.
+
+Then reload the shell:
+
+```bash
+source ~/.zshrc
+```
+
+## Step 3: Sign Out of Anthropic (if needed)
+
+If you previously used Claude Code with an Anthropic account:
+
+```bash
+claude
+# inside the session:
+/logout
+```
+
+## Step 4: Verify Connection
+
+```bash
+claude
+# inside the session:
+/status
+```
+
+Should show that it's connected to OpenRouter.
+
+## Recommended Free Models for Coding
+
+| Model | OpenRouter ID | Context | Best For |
+|-------|---------------|---------|----------|
+| **Qwen3 Coder 480B** | `qwen/qwen3-coder-480b-a35b:free` | 262K | Best free model for agentic coding |
+| **DeepSeek R1** | `deepseek/deepseek-r1:free` | 164K | Complex reasoning, debugging |
+| **Devstral** | `mistralai/devstral-small:free` | 128K | Multi-file, agentic coding |
+| **Llama 3.3 70B** | `meta-llama/llama-3.3-70b-instruct:free` | 128K | General purpose, fast |
+
+To select a specific model, add to `~/.zshrc`:
+
+```bash
+export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b:free"
+```
+
+Or use the free automatic router:
+
+```bash
+export ANTHROPIC_MODEL="openrouter/free"
+```
+
+## Limitations
+
+- **Rate limits**: ~20 requests/min, ~200 requests/day on free models
+- **Tool use**: Not all free models support tool calling (needed for agents)
+- **Quality**: Inferior to Claude Opus/Sonnet for complex tasks
+- **Availability**: Free models may disappear without notice
+- **Not recommended for production**
+
+## Verification
+
+1. Open a new terminal (to load the variables)
+2. `echo $ANTHROPIC_BASE_URL` → should show `https://openrouter.ai/api`
+3. `claude` → should start without asking for Anthropic login
+4. `/status` → confirm connection to OpenRouter
+5. Ask a simple coding question to verify response

package/library/examples/README.md

@@ -0,0 +1,151 @@
+# Examples
+
+Complete, end-to-end examples demonstrating BI Agent Superpowers patterns in real-world scenarios.
+
+---
+
+## Available Examples
+
+| Example | Description | Components |
+|---------|-------------|------------|
+| [retail-analytics](./retail-analytics/) | Complete retail sales analytics solution | Star schema, 50+ DAX measures, data model |
+| [finance-reporting](./finance-reporting/) | P&L, Balance Sheet, variance analysis | Multi-statement model, 60+ financial measures |
+| [hr-analytics](./hr-analytics/) | Headcount, turnover, diversity metrics | Employee snapshots, 40+ HR measures |
+| [udf-library](./udf-library/) | DAX User Defined Functions library | 50+ reusable UDFs, typed parameters |
+
+---
+
+## Learning Path (Recommended Order)
+
+New to Power BI? Follow this progression to build your skills:
+
+### Level 1: Foundations
+1. **[retail-analytics](./retail-analytics/)** - Start here!
+   - Learn star schema basics (facts + dimensions)
+   - Understand fundamental DAX patterns (SUM, CALCULATE, time intelligence)
+   - Build your first KPI dashboard
+
+### Level 2: Intermediate
+2. **[hr-analytics](./hr-analytics/)** - Expand your skills
+   - Work with snapshot data (point-in-time analysis)
+   - Learn turnover and retention calculations
+   - Understand Row-Level Security (RLS) basics
+
+### Level 3: Advanced
+3. **[finance-reporting](./finance-reporting/)** - Master complex scenarios
+   - Handle multi-statement financial models
+   - Work with hierarchical account structures
+   - Build variance analysis (Actual vs Budget)
+
+### Level 4: Expert
+4. **[udf-library](./udf-library/)** - Cutting-edge DAX
+   - Create reusable User Defined Functions (preview feature)
+   - Build a personal library of typed functions
+   - Master advanced DAX patterns
+
+---
+
+## What Each Example Includes
+
+### Documentation
+- **README.md** - Overview, business requirements, implementation guide
+- **data-model.md** - Complete table definitions, relationships, sample data
+
+### Code
+- **measures.dax** - Complete DAX measure library, organized by category
+
+### Styling
+- Use themes from `library/themes/power-bi/` for consistent formatting
+
+---
+
+## Using Examples
+
+### 1. Understand the Scenario
+
+Read the README.md to understand:
+- Business requirements and stakeholders
+- Key questions the solution answers
+- Recommended visualizations
+
+### 2. Adapt the Data Model
+
+Use data-model.md as a template:
+- Match columns to your source data
+- Adjust data types as needed
+- Add/remove columns for your scenario
+
+### 3. Copy Relevant Measures
+
+From measures.dax:
+- Start with base measures (Revenue, Cost, Profit)
+- Add time intelligence as needed
+- Customize rankings and percentages
+
+### 4. Apply a Theme
+
+1. Choose a theme from `library/themes/power-bi/`
+2. View > Themes > Browse for themes
+3. Select the JSON file
+
+---
+
+## Example Structure
+
+```
+library/examples/
+├── README.md                    # This file
+│
+├── retail-analytics/            # Retail sales analytics
+│   ├── README.md                # Overview and guide
+│   ├── data-model.md            # Table definitions
+│   └── measures.dax             # 50+ DAX measures
+│
+├── finance-reporting/           # Financial statements
+│   ├── README.md                # P&L, Balance Sheet guide
+│   ├── data-model.md            # Account structure, scenarios
+│   └── measures.dax             # 60+ financial measures
+│
+├── hr-analytics/                # HR workforce analytics
+│   ├── README.md                # Headcount, turnover guide
+│   ├── data-model.md            # Employee snapshot model
+│   └── measures.dax             # 40+ HR measures
+│
+└── udf-library/                 # DAX User Defined Functions
+    ├── README.md                # UDF usage guide and catalog
+    └── functions.dax            # 50+ reusable typed functions
+```
+
+---
+
+## Upcoming Examples
+
+- **marketing-dashboard** - Campaign performance, funnel analysis
+- **supply-chain** - Inventory, fulfillment, vendor performance
+- **project-management** - Resource allocation, timeline tracking
+
+---
+
+## Contributing Examples
+
+Want to add an example? Include:
+
+1. **README.md** with:
+   - Business scenario description
+   - Stakeholder requirements
+   - Data model diagram
+   - Visualization recommendations
+   - Implementation checklist
+
+2. **data-model.md** with:
+   - All table definitions
+   - Column specifications
+   - Relationship diagram
+   - Sample data
+
+3. **measures.dax** with:
+   - Organized by category
+   - Comments explaining each measure
+   - Naming conventions followed
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for submission guidelines.

package/library/examples/finance-reporting/README.md

@@ -0,0 +1,351 @@
+# Finance Reporting - Complete Example
+
+A comprehensive financial reporting solution for P&L, Balance Sheet, and Cash Flow analysis.
+
+---
+
+## Overview
+
+This example demonstrates building a complete financial reporting solution using:
+
+- **Multi-statement data model** supporting P&L, Balance Sheet, and Cash Flow
+- **DAX measures** for period comparisons, variances, and financial ratios
+- **Budget vs Actual** analysis with variance explanations
+- **Rolling forecasts** and trend analysis
+
+---
+
+## Business Requirements
+
+### Stakeholders
+- CFO: Executive financial overview
+- Controllers: Detailed variance analysis
+- FP&A Team: Budget tracking and forecasting
+- Business Unit Leaders: Departmental P&L
+
+### Key Questions
+1. How are we performing vs. budget and prior year?
+2. What's driving variance from plan?
+3. What are our key financial ratios and trends?
+4. How does each department/cost center perform?
+5. What's the cash position and forecast?
+
+---
+
+## Data Model
+
+### Star Schema Design
+
+```
+                    ┌─────────────────┐
+                    │   DimDate       │
+                    │─────────────────│
+                    │ DateKey (PK)    │
+                    │ Date            │
+                    │ FiscalYear      │
+                    │ FiscalPeriod    │
+                    │ FiscalQuarter   │
+                    │ IsCurrentPeriod │
+                    └────────┬────────┘
+                             │
+┌─────────────────┐          │          ┌─────────────────┐
+│   DimAccount    │          │          │  DimCostCenter  │
+│─────────────────│          │          │─────────────────│
+│ AccountKey (PK) │          │          │ CostCenterKey   │
+│ AccountCode     │          │          │ CostCenterCode  │
+│ AccountName     │          │          │ CostCenterName  │
+│ AccountType     │          │          │ Department      │
+│ AccountGroup    │          │          │ Division        │
+│ FinancialStmt   │          │          │ Manager         │
+│ NaturalSign     │          │          └────────┬────────┘
+│ SortOrder       │          │                   │
+└────────┬────────┘          │                   │
+         │     ┌─────────────┴───────────────┐   │
+         │     │       FactFinancials        │   │
+         │     │─────────────────────────────│   │
+         └────>│ FinancialKey (PK)           │<──┘
+               │ DateKey (FK)                │
+               │ AccountKey (FK)             │
+               │ CostCenterKey (FK)          │
+               │ ScenarioKey (FK)            │
+               │ Amount                      │
+               └─────────────┬───────────────┘
+                             │
+                    ┌────────┴────────┐
+                    │  DimScenario    │
+                    │─────────────────│
+                    │ ScenarioKey (PK)│
+                    │ ScenarioName    │
+                    │ ScenarioType    │
+                    │ IsActual        │
+                    └─────────────────┘
+```
+
+### Account Types
+
+| AccountType | FinancialStatement | NaturalSign | Examples |
+|-------------|-------------------|-------------|----------|
+| Revenue | Income Statement | Credit (+) | Sales, Service Revenue |
+| COGS | Income Statement | Debit (-) | Cost of Goods Sold |
+| OpEx | Income Statement | Debit (-) | Salaries, Rent, Marketing |
+| OtherIncome | Income Statement | Credit (+) | Interest Income |
+| OtherExpense | Income Statement | Debit (-) | Interest Expense |
+| Tax | Income Statement | Debit (-) | Income Tax |
+| Asset | Balance Sheet | Debit (+) | Cash, AR, Inventory |
+| Liability | Balance Sheet | Credit (-) | AP, Debt |
+| Equity | Balance Sheet | Credit (-) | Retained Earnings |
+
+### Scenarios
+
+| ScenarioName | ScenarioType | IsActual | Purpose |
+|--------------|--------------|----------|---------|
+| Actual | Actual | TRUE | Recorded transactions |
+| Budget | Budget | FALSE | Annual plan |
+| Forecast | Forecast | FALSE | Rolling forecast |
+| Prior Year | Actual | TRUE | Comparison baseline |
+
+---
+
+## Key Measures
+
+### Base Measures
+
+```dax
+// Actuals only
+Actual Amount =
+CALCULATE(
+    SUM(FactFinancials[Amount]),
+    DimScenario[IsActual] = TRUE()
+)
+
+// Budget only
+Budget Amount =
+CALCULATE(
+    SUM(FactFinancials[Amount]),
+    DimScenario[ScenarioName] = "Budget"
+)
+
+// Forecast only
+Forecast Amount =
+CALCULATE(
+    SUM(FactFinancials[Amount]),
+    DimScenario[ScenarioName] = "Forecast"
+)
+```
+
+### Income Statement Measures
+
+```dax
+// Revenue (positive = good)
+Revenue =
+CALCULATE(
+    [Actual Amount],
+    DimAccount[AccountType] = "Revenue"
+)
+
+// Gross Profit
+Gross Profit =
+[Revenue] + CALCULATE([Actual Amount], DimAccount[AccountType] = "COGS")
+
+// Gross Margin %
+Gross Margin % =
+DIVIDE([Gross Profit], [Revenue])
+
+// Operating Expenses
+OpEx =
+CALCULATE(
+    [Actual Amount],
+    DimAccount[AccountType] = "OpEx"
+)
+
+// EBITDA
+EBITDA =
+[Gross Profit] + [OpEx]
+
+// Net Income
+Net Income =
+CALCULATE(
+    [Actual Amount],
+    DimAccount[FinancialStmt] = "Income Statement"
+)
+```
+
+### Variance Analysis
+
+```dax
+// Budget Variance (Actual - Budget)
+Budget Variance =
+[Actual Amount] - [Budget Amount]
+
+// Budget Variance %
+Budget Variance % =
+DIVIDE([Budget Variance], ABS([Budget Amount]))
+
+// Favorable/Unfavorable indicator
+Variance Status =
+VAR _Variance = [Budget Variance]
+VAR _AccountType = SELECTEDVALUE(DimAccount[AccountType])
+VAR _IsExpense = _AccountType IN {"COGS", "OpEx", "OtherExpense", "Tax"}
+RETURN
+    SWITCH(
+        TRUE(),
+        ISBLANK(_Variance), BLANK(),
+        _IsExpense && _Variance < 0, "Favorable",
+        _IsExpense && _Variance > 0, "Unfavorable",
+        NOT _IsExpense && _Variance > 0, "Favorable",
+        "Unfavorable"
+    )
+```
+
+### YTD and Period Comparisons
+
+```dax
+// Year-to-Date Actual
+Actual YTD =
+TOTALYTD([Actual Amount], DimDate[Date])
+
+// Prior Year Same Period
+Actual PY =
+CALCULATE(
+    [Actual Amount],
+    SAMEPERIODLASTYEAR(DimDate[Date])
+)
+
+// Prior Year YTD
+Actual YTD PY =
+CALCULATE(
+    [Actual YTD],
+    SAMEPERIODLASTYEAR(DimDate[Date])
+)
+
+// YoY Growth %
+YoY Growth % =
+DIVIDE([Actual Amount] - [Actual PY], ABS([Actual PY]))
+```
+
+See [measures.dax](./measures.dax) for the complete measure library (50+ measures).
+
+---
+
+## Report Pages
+
+### 1. Executive Summary
+
+| Visual | Content |
+|--------|---------|
+| KPI Cards | Revenue, Net Income, EBITDA with YoY % |
+| Waterfall | Revenue to Net Income bridge |
+| Line Chart | Monthly trend vs Prior Year |
+| Table | Key metrics by Quarter |
+
+### 2. P&L Statement
+
+| Visual | Content |
+|--------|---------|
+| Matrix | Full P&L with hierarchy (Account Group > Account) |
+| Columns | Actual, Budget, Variance, Variance %, PY |
+| Conditional | Red/Green variance highlighting |
+| Drill-through | To account detail page |
+
+### 3. Variance Analysis
+
+| Visual | Content |
+|--------|---------|
+| Decomposition Tree | Variance drivers by dimension |
+| Scatter Plot | Budget vs Actual by Cost Center |
+| Table | Top 10 variances with explanations |
+| Bar Chart | Variance by Department |
+
+### 4. Balance Sheet
+
+| Visual | Content |
+|--------|---------|
+| Matrix | Assets, Liabilities, Equity structure |
+| KPI Cards | Current Ratio, Quick Ratio, Debt/Equity |
+| Waterfall | Change in Cash position |
+
+### 5. Cash Flow
+
+| Visual | Content |
+|--------|---------|
+| Waterfall | Operating, Investing, Financing flows |
+| Line Chart | Cash balance trend |
+| Table | Cash sources and uses |
+
+---
+
+## Financial Ratios
+
+```dax
+// Profitability
+Gross Margin % = DIVIDE([Gross Profit], [Revenue])
+Operating Margin % = DIVIDE([EBITDA], [Revenue])
+Net Margin % = DIVIDE([Net Income], [Revenue])
+ROE = DIVIDE([Net Income TTM], [Total Equity])
+ROA = DIVIDE([Net Income TTM], [Total Assets])
+
+// Liquidity
+Current Ratio = DIVIDE([Current Assets], [Current Liabilities])
+Quick Ratio = DIVIDE([Current Assets] - [Inventory], [Current Liabilities])
+Cash Ratio = DIVIDE([Cash], [Current Liabilities])
+
+// Leverage
+Debt to Equity = DIVIDE([Total Debt], [Total Equity])
+Debt to Assets = DIVIDE([Total Debt], [Total Assets])
+Interest Coverage = DIVIDE([EBITDA], [Interest Expense])
+
+// Efficiency
+Days Sales Outstanding = DIVIDE([Accounts Receivable], [Revenue]) * 365
+Days Payable Outstanding = DIVIDE([Accounts Payable], [COGS]) * 365
+Inventory Turnover = DIVIDE([COGS], [Average Inventory])
+```
+
+---
+
+## Implementation Checklist
+
+### Data Model
+- [ ] Create DimDate with fiscal calendar attributes
+- [ ] Create DimAccount with proper hierarchy and signs
+- [ ] Create DimCostCenter with department/division structure
+- [ ] Create DimScenario for Actual/Budget/Forecast
+- [ ] Load FactFinancials with all scenario data
+- [ ] Set up relationships
+- [ ] Mark DimDate as Date Table
+
+### Measures
+- [ ] Create base measures (Actual, Budget, Forecast)
+- [ ] Create P&L subtotals (Revenue, Gross Profit, EBITDA, Net Income)
+- [ ] Create variance measures with favorable/unfavorable logic
+- [ ] Create time intelligence (YTD, PY, YoY)
+- [ ] Create financial ratios
+- [ ] Organize in display folders
+
+### Reports
+- [ ] Executive Summary page
+- [ ] P&L Statement with drill-through
+- [ ] Variance Analysis with decomposition
+- [ ] Balance Sheet snapshot
+- [ ] Cash Flow statement
+- [ ] Apply theme and formatting
+
+---
+
+## Files in This Example
+
+| File | Description |
+|------|-------------|
+| [README.md](./README.md) | This overview |
+| [data-model.md](./data-model.md) | Complete table definitions |
+| [measures.dax](./measures.dax) | 50+ DAX measures |
+
+---
+
+## Tips for Financial Reporting
+
+1. **Sign conventions matter** - Use NaturalSign to handle debit/credit properly
+2. **Fiscal vs calendar** - Finance always uses fiscal periods
+3. **Variance coloring** - Favorable expenses (under budget) should be green even if negative
+4. **YTD resets** - Use fiscal year start date in TOTALYTD
+5. **Balance sheet** - Point-in-time, not period aggregations
+6. **Drill-through** - Essential for explaining variances