powerbi-kit

Power BI agentic workspace setup for OpenCode.

powerbi-kit scaffolds a local workspace with Power BI agents, skills, MCP presets, and a PBIX testing manual. It is OpenCode-first for 0.1.0, uses Microsoft's official Power BI Modeling MCP, and keeps Power BI Desktop in control of the open PBIX.

Status: experimental MVP. The OpenCode + Power BI Modeling MCP path has been validated locally; broader adapter support is still evolving.

Why

Power BI agent work needs more than a prompt. A useful workspace needs model-aware agents, DAX and Power Query skills, safe MCP permissions, repeatable setup, and a clear way to test against an open PBIX.

powerbi-kit gives you that baseline in one command.

Install

Use it directly with npx:

npx powerbi-kit --opencode

Or install into a dedicated project folder:

mkdir E:\DEV\teste-powerbi-opencode
mkdir E:\DEV\teste-powerbi-opencode\pbix
npx powerbi-kit --opencode --target E:\DEV\teste-powerbi-opencode

Local development from this repository:

node E:\DEV\powerbi-kit\bin\powerbi-kit.js --opencode --target E:\DEV\teste-powerbi-opencode
node E:\DEV\powerbi-kit\bin\powerbi-kit.js doctor --target E:\DEV\teste-powerbi-opencode

Full install notes: docs/INSTALL.md.

Quickstart

1. Create a workspace and a pbix folder.
2. Copy a .pbix file into pbix\.
3. Open the PBIX in Power BI Desktop.
4. Install the kit:

npx powerbi-kit --opencode --target E:\DEV\teste-powerbi-opencode

5. Validate the workspace:

npx powerbi-kit doctor --target E:\DEV\teste-powerbi-opencode

6. Open OpenCode in that folder and run:

Use the registered Power BI Modeling MCP tools, not shell commands. Connect to the open Power BI Desktop model, then list tables, measures, relationships, and connection status.

PBIX smoke test guide: docs/OPEN_CODE_PBIX_TESTING.md.

What You Get

The OpenCode install writes:

• AGENTS.md
• .powerbi-kit/agents/
• .powerbi-kit/skills/
• .powerbi-kit/mcp/
• .opencode/agent/*.md
• .opencode/skills/*/SKILL.md
• .opencode/README.md
• opencode.json
• docs/OPEN_CODE_PBIX_TESTING.md

Agent team:

• powerbi-orchestrator: routes broad Power BI requests.
• powerbi-modeler: works with semantic model metadata and MCP operations.
• dax-specialist: reviews and creates DAX safely.
• power-query-specialist: handles Power Query/M, sources, parameters, and refresh flow.
• data-engineer: handles source contracts, SQL, ETL, and data quality.
• report-documenter: creates model and measure documentation.
• report-qa: checks reports against acceptance criteria.

Safety Model

The kit does not parse .pbix files directly. For live model inspection, open the PBIX in Power BI Desktop and let Power BI Modeling MCP connect to the running local model.

Default MCP mode is readonly. It can inspect model metadata but should not write changes. To allow edits:

npx powerbi-kit --opencode --target E:\DEV\teste-powerbi-opencode --mcp-mode readwrite

Or edit opencode.json and remove only --readonly from mcp.powerbi-modeling.command.

After changing MCP permissions, restart or reload OpenCode MCP connections. Do not close or restart Power BI Desktop as part of MCP recovery unless you intentionally want to close the open PBIX.

MCP Modes

# Safe default: inspect only
npx powerbi-kit --opencode --target E:\DEV\teste-powerbi-opencode --mcp-mode readonly

# Allows model edits after MCP reload
npx powerbi-kit --opencode --target E:\DEV\teste-powerbi-opencode --mcp-mode readwrite

opencode.json includes:

• powerbi-modeling via npx -y @microsoft/powerbi-modeling-mcp@latest --start --compatibility=powerbi
• context-mode via npx -y context-mode

Use this inside the generated project to verify the MCP is loaded:

opencode mcp list

Troubleshooting guide: docs/MCP_TROUBLESHOOTING.md.

Roadmap

Near-term direction:

• OpenCode-first 0.1.x validation.
• Stronger Power BI Modeling MCP workflows.
• Better docs for safe read/write model changes.
• Antigravity support after OpenCode is stable.
• PBIP/TMDL fallback workflows.

Full roadmap: docs/ROADMAP.md.

Contributing

Contributions are welcome while the project is still small and explicit. Read CONTRIBUTING.md before opening a PR.

Release process is manual for now. See docs/RELEASE.md.

Release Safety

Before publishing:

npm test
npm run release:check

This project is MIT licensed.