# PBIP Builder MCP Server

PBIP Builder MCP Server is a local TypeScript MCP server that helps AI coding agents create, inspect, validate, and modify Power BI Project (`.pbip`) folders. It generates PBIR-style report folders, TMDL semantic model files, report pages, and templated visuals from structured inputs instead of asking an agent to free-write report JSON.

## What It Builds

Generated projects follow the Power BI Desktop developer mode layout:

```text
SalesDashboard/
├── SalesDashboard.pbip
├── SalesDashboard.Report/
│   ├── .platform
│   ├── definition.pbir
│   └── definition/
│       ├── version.json
│       ├── report.json
│       └── pages/
│           ├── pages.json
│           └── <PageId>/
│               ├── page.json
│               └── visuals/<VisualId>/
│                   ├── visual.json
│                   └── mobile.json
└── SalesDashboard.SemanticModel/
    ├── .platform
    ├── definition.pbism
    └── definition/
        ├── database.tmdl
        ├── model.tmdl
        ├── relationships.tmdl
        ├── roles/
        └── tables/<TableName>.tmdl
```

## Install

```bash
npm install
npm run build
```

## Run The MCP Server

```bash
npm run dev
```

The server uses stdio transport. A VS Code MCP configuration is included in [.vscode/mcp.json](.vscode/mcp.json).

To restrict writes, set `PBIP_ALLOWED_WORKSPACES` to one or more workspace roots separated by the OS path delimiter. If unset, writes are limited to `process.cwd()`.

## Microsoft JSON Schemas

The schema registry looks for Microsoft schemas under [schemas/microsoft-json-schemas](schemas/microsoft-json-schemas). Add a local copy of the Microsoft `json-schemas` repository there:

```bash
git clone https://github.com/microsoft/json-schemas schemas/microsoft-json-schemas
```

When schemas are unavailable, validation still checks project structure, JSON parsing, page/visual references, and semantic field bindings, and returns schema warnings rather than failing the project.

## Tools

Project tools: `pbip_create_project`, `pbip_open_project`, `pbip_describe_project`, `pbip_validate_project`, `pbip_delete_project`, `pbip_export_summary`.

Semantic model tools: `model_add_table`, `model_update_table`, `model_delete_table`, `model_add_column`, `model_add_measure`, `model_update_measure`, `model_delete_measure`, `model_add_relationship`, `model_delete_relationship`, `model_add_role`, `model_generate_from_schema`, `model_describe`, `model_validate`.

Report/page/visual tools: `report_create`, `report_update_settings`, `report_set_theme`, `report_validate`, `page_add`, `page_update`, `page_delete`, `page_rename`, `page_set_size`, `page_list`, `visual_add`, `visual_update`, `visual_delete`, `visual_set_position`, `visual_bind_fields`, `visual_set_format`, `visual_set_filter`, `visual_list`, `visual_describe`.

Blueprint and schema tools: `blueprint_generate_project`, `blueprint_apply`, `blueprint_validate`, `blueprint_preview`, `schema_list`, `schema_get`, `schema_validate_json`, `schema_sync`, `schema_explain_error`.

## Example

```bash
npm run generate:example
```

This creates `examples/generated/SalesDashboard` from [examples/sales-dashboard-blueprint.json](examples/sales-dashboard-blueprint.json), including one semantic model table, one report page, and five visual types: card, clustered column chart, table, slicer, and line chart.

## Testing

```bash
npm test
```

Tests cover project creation, dry runs, path safety, semantic model generation, page generation, visual generation, blueprint generation, and validation.

## Limitations

This is the MVP local generator. Fabric publishing, refresh, live data source setup, custom visuals, advanced formatting, page duplication, visual duplication, and automatic Power BI Desktop repair workflows are intentionally left for later phases. Final compatibility should still be confirmed by opening generated `.pbip` files in Power BI Desktop.