# Microsoft Fabric MCP Server

A production-grade [Model Context Protocol](https://modelcontextprotocol.io) server for Microsoft Fabric. Exposes Fabric operations as MCP tools over **stdio** (local) and **Streamable HTTP** (hosted/multi-user).

- **TypeScript** (ESM, Node 20+), REST-only (Fabric has no typed SDK)
- Transparent **Long-Running Operation (LRO)** handling — 202 + Location is polled to completion automatically
- Three auth modes: **Azure CLI (`az login`)**, **Service Principal** (deploy path — Fabric has no PAT), **OBO + Entra JWT** (hosted)
- Per-tool **RBAC**, destructive-op guard, secret redaction, structured logging, retry + per-host circuit breaker
- Wraps the **Fabric REST API**, the **Power BI API**, and **OneLake** (per-resource token scopes)

> **Status:** All phases complete — **105 tools** across 17 domains, plus **4 resources** and **4 prompts**:
> - **core** (11) · **items** (7) · **lakehouses** (7) · **warehouses** (4) · **sqlendpoints** (3) · **shortcuts** (4)
> - **notebooks** (6) · **pipelines** (6) · **jobs** (6) · **spark** (6)
> - **semanticmodels** (5) · **reports** (3) · **dataflows** (5)
> - **realtime** (12: eventhouses, KQL databases, eventstreams) · **onelake** (5: files/dirs via DFS)
> - **git** (7: workspace Git integration) · **platform** (8: deployment pipelines, connections, gateways)
> - **Resources:** `fabric://workspaces`, `fabric://workspace/{w}/items`, `…/lakehouses`, `…/item/{id}`
> - **Prompts:** `medallion-architecture`, `document-workspace`, `build-etl`, `diagnose-refresh`
>
> **Hardening:** per-host circuit breaker, retry + Retry-After, transparent LRO polling, secret redaction, per-tool RBAC + destructive guard, audit logging, ESLint, Vitest suite (unit + live MCP-protocol test), Azure Pipelines CI.

---

## 1. Prerequisites

- **Node.js ≥ 20**
- A **Fabric-enabled tenant** and an identity with a **Fabric/Power BI license** (or a service principal enabled for Fabric APIs and added to the workspaces)
- One of: **Azure CLI** (`az login`), a **service principal**, or (hosted) an **Entra app** for OBO

## 2. Install & configure

```bash
cd "E:\MCP Servers\fabric-mcp-server"
npm install
cp .env.example .env   # PowerShell: Copy-Item .env.example .env
```

Minimum for local use with the Azure CLI:

```env
AUTH_MODE=azcli
FABRIC_DEFAULT_WORKSPACE=        # optional default workspace ID
```

### Auth modes

| `AUTH_MODE` | Needs | Notes |
|---|---|---|
| `azcli` | `az login` | Easiest for dev. Token minted for the Fabric scope. |
| `sp` | `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` | **Deployment path.** The SP must be enabled in Fabric tenant settings and added to the workspaces. |
| `obo` | same three | **HTTP transport only.** Validates the caller's Entra JWT, then exchanges it per resource (preserves user identity). |

## 3. Build & run

```bash
npm run build && npm start        # stdio (default)
node dist/index.js --transport http   # Streamable HTTP on PORT (default 3100)
```

## 4. Connect a client (npx)

```json
{
  "mcpServers": {
    "fabric": {
      "command": "npx",
      "args": ["-y", "fabric-mcp-server"],
      "env": { "AUTH_MODE": "azcli", "FABRIC_DEFAULT_WORKSPACE": "<workspace-id>" }
    }
  }
}
```

For deployment use `AUTH_MODE=sp` with the three `AZURE_*` env vars.

## 5. Scripts

| Script | Purpose |
|---|---|
| `npm run build` | Compile TypeScript → `dist/` |
| `npm start` / `start:http` | Run compiled server (stdio / HTTP) |
| `npm run dev` / `dev:http` | Watch-mode dev (tsx) |
| `npm run typecheck` · `lint` · `test` · `ci` | Quality gates |

## 6. Architecture

```
transport (stdio | http)
  → server (McpServer + registry)
    → dispatch (RBAC · destructive guard · audit · error envelope)
      → domain tools (Zod schemas)
        → domain services
          → FabricClient (REST + retry + circuit breaker + LRO polling)
            → credential (AzCli | ServicePrincipal | OBO) → per-resource token
```

Each Fabric area is a self-contained module under `src/domains/<area>/` exporting a `DomainModule`. To add an area, create the module and append it to `domains` in [src/server.ts](src/server.ts).

Key Fabric specifics: **every write is an LRO** (handled in [src/client/fabricClient.ts](src/client/fabricClient.ts)); item definitions (notebooks, pipelines) are **base64 file parts** (helpers in [src/domains/_shared.ts](src/domains/_shared.ts)); tokens are acquired **per resource** (Fabric / Power BI / OneLake).

**Full walkthrough:** see [docs/END_TO_END_FLOW.md](docs/END_TO_END_FLOW.md) for how a request travels through every layer (startup, a tool call step by step, the LRO + item-definition mechanisms, auth/scope flows, resources/prompts, and a worked medallion-ETL example).