内容
# fabric-mcp-server
一款适用于 **Microsoft Fabric** 的[模型上下文协议](https://modelcontextprotocol.io)服务器。它为MCP客户端（Claude Code、Claude Desktop等）提供对Fabric工作区、项目、管道运行历史、作业计划、部署管道、OneLake存储的读取访问权限，以及对语义模型的只读DAX查询 - 此外还可选地支持写入操作（管道/笔记本运行、刷新、Git同步、计划、阶段部署、项目创建/删除、以及工作区角色授予），这些操作都需要在写入标志后面。
它与公共Fabric REST API (`api.fabric.microsoft.com`) 和Power BI REST API (`api.powerbi.com`) 进行通信，使用 [`@azure/identity`](https://www.npmjs.com/package/@azure/identity) 进行身份验证，这样您就可以交互式地运行它，或者在无头模式（设备代码）、通过Azure CLI或作为服务主体运行。
## 功能
- 通过 **显示名称或GUID** 解析工作区、项目、管道、部署管道和语义模型 - 无需搜索ID。
- 内置续页标记分页、HTTP 429重试（遵守`Retry-After`）和长运行操作轮询（处理`202+Location`和`200`带正文的情况）。
- 默认只读；所有修改操作都需要在显式写入模式下，并且在stderr中记录审计日志。
## 工具
| 工具 | 模式 | 描述 |
|------|------|-------------|
| `list_workspaces` | 读取 | 列出已登录身份可见的所有Fabric工作区。 |
| `list_items` | 读取 | 列出工作区中的项目（笔记本、数据湖、仓库、语义模型、报告、管道），可选类型筛选。 |
| `list_pipelines` | 读取 | 列出工作区中的数据管道。 |
| `list_pipeline_runs` | 读取 | 管道的运行（作业实例）历史，最近一次在前，可选状态筛选。 |
| `get_pipeline_run` | 读取 | 通过作业实例ID获取一次运行的完整详细信息，包括`failureReason`。 |
| `get_refresh_history` | 读取 | 语义模型的最近刷新历史，最近一次在前 — 刷新是否成功，为什么失败。 |
| `get_git_status` | 读取 | 工作区与其连接的Git分支之间更改的项目，以及远程提交哈希和工作区头部。 |
| `get_item_definition` | 读取 | 获取项目的定义部分（语义模型TMDL、笔记本内容、报告）。默认情况下为清单；对于命名部分，内容会被解码。 |
| `execute_dax` | 读取 | 对语义模型运行只读DAX查询（Power BI `executeQueries`），并返回结果行。 |
| `list_schedules` | 读取 | 项目上的作业计划，包括每个计划的`所有者`（ID + 类型）— 在部署/更新后发现所有权漂移。 |
| `list_deployment_pipelines` | 读取 | 列出身份可见的部署管道。 |
| `list_deployment_stages` | 读取 | 部署管道的阶段；可选地，阶段中的项目（`deploy_stage`的源ID + 类型）。 |
| `list_onelake` | 读取 | 通过DFS API列出OneLake中项目下的文件/表 — 当SQL端点元数据滞后时，无滞后的真实情况。 |
| `read_onelake_file` | 读取 | 从项目的OneLake存储中读取一个小文件（日志、JSON结果）为解码文本，大小上限。 |
| `list_workspace_roles` | 读取 | 工作区上的角色分配（哪些主体拥有管理员/成员/贡献者/查看者）。 |
| `list_sql_databases` | 读取 | 工作区中的SQL数据库 + 连接属性（服务器FQDN、数据库名称、连接字符串）。 |
| `run_pipeline` | **写入** | 触发按需管道运行。 |
| `cancel_pipeline_run` | **写入** | 取消正在进行的运行。 |
| `refresh_dataset` | **写入** | 触发语义模型的按需刷新。 |
| `update_from_git` | **写入** | 从其连接的Git分支更新工作区（拉取存储库→工作区），在冲突时优先使用远程存储库。 |
| `update_item_definition` | **写入** | 从本地文件夹部署项目定义，覆盖实时项目。首先快照当前定义，进行一次调用回滚。 |
| `create_schedule` | **写入** | 在项目上创建作业计划（由创建身份所有）。 |
| `update_schedule` | **写入** | 启用/禁用（暂停/恢复）或重新配置计划。PATCH重新将所有者标记为调用者。 |
| `delete_schedule` | **写入** | 删除计划；首先将其快照到本地JSON。 |
| `deploy_stage` | **写入** | 部署管道阶段之间的选择性部署（需要显式项目列表）；轮询到完成。 |
| `run_notebook` | **写入** | 按需运行笔记本作为作业；默认情况下等待终端状态。 |
| `create_item` | **写入** | 创建项目，可选地从本地定义文件夹。 |
| `delete_item` | **写入** | 删除项目（自动处理Gen2数据流端点怪癖）；尽力而为地快照定义首先。 |
| `add_workspace_role` | **写入** | 授予主体在工作区上的角色（管理员/成员/贡献者/查看者）。 |
写入工具仅在 `FABRIC_MCP_MODE=write` 时注册。
## 要求
- Node.js >= 20
- 具有目标Fabric工作区访问权限的Entra（Azure AD）身份。
- 对于 `execute_dax`：目标语义模型的**构建**权限，以及租户的**"数据集执行查询REST API"** 管理设置启用。
## 安装
```bash
git clone <此存储库网址> fabric-mcp-server
cd fabric-mcp-server
npm install
```
## 配置
所有配置均通过环境变量（参见 [`.env.example`](.env.example)）。在MCP客户端的`env`块中设置它们，或复制`.env.example`到`.env`进行本地调试。
| 变量 | 必需 | 目的 |
|----------|----------|---------|
| `FABRIC_AUTH_MODE` | 否（默认为 `interactive`） | `interactive`、`device-code`、`cli`、`service-principal`、`managed-identity`或`default`。 |
| `AZURE_TENANT_ID` | interactive / device-code / service-principal | 您的Entra租户ID。 |
| `AZURE_CLIENT_ID` | service-principal | 应用程序注册客户端ID。 |
| `AZURE_CLIENT_SECRET` | service-principal | 应用程序注册密钥。 |
| `FABRIC_MCP_MODE` | 否（默认为 `read`） | `read`或`write`（参见工具表）。 |
### 身份验证模式
- **interactive** — 打开浏览器；适用于桌面/AVD。
- **device-code** — 打印代码 + 网址到stderr；适用于SSH / WSL / 无头。
- **cli** — 重用现有的`az login`会话。
- **service-principal** — 非交互式，带有客户端ID + 密钥。
- **managed-identity** — 适用于在Azure上托管。
- **default** — 依次尝试env → managed-identity → CLI → 浏览器。
## 与Claude Code / Claude Desktop一起使用
将以下内容添加到您的MCP客户端配置中（例如，`~/.claude.json`适用于Claude Code，或`claude_desktop_config.json`适用于Claude Desktop）：
```json
{
"mcpServers": {
"fabric": {
"command": "node",
"args": ["/绝对路径/到/fabric-mcp-server/index.js"],
"env": {
"FABRIC_AUTH_MODE": "interactive",
"AZURE_TENANT_ID": "<您的Entra租户ID>"
}
}
}
}
```
要启用管道执行，请在`env`块中添加 `"FABRIC_MCP_MODE": "write"`。
## 示例
检查昨晚管道的运行情况：
> “使用fabric，**my_pipeline**昨晚在**My-Workspace**中运行得怎么样？”
> → `list_pipeline_runs` → 在失败的实例上运行`get_pipeline_run`。
针对实时模型验证度量：
> “在**My-Workspace**中，对**Production Analytics**模型运行此DAX：
> `EVALUATE ROW("Sales", [Total Sales])`”
> → `execute_dax` 返回该行。
## 安全注意事项
- 存储库中不存储任何机密。凭证来自运行时环境变量；`.env`被git忽略。
- 写入工具（`run_pipeline`、`cancel_pipeline_run`、`refresh_dataset`、`update_from_git`、`update_item_definition`、`create_schedule`、`update_schedule`、`delete_schedule`、`deploy_stage`、`run_notebook`、`create_item`、`delete_item`、`add_workspace_role`）仅在`FABRIC_MCP_MODE=write`下公开，并且每个都记录一个 `[AUDIT]` 行到stderr。
- `list_onelake` / `read_onelake_file` 调用OneLake DFS API（`onelake.dfs.fabric.microsoft.com`），该API使用Azure **Storage**令牌受众（`https://storage.azure.com/.default`）— 相同的`@azure/identity`凭证获取它，无需额外配置。
- `update_item_definition` 整体覆盖实时项目；它首先将当前定义快照到本地JSON（在OS临时目录下），并返回路径，以便您可以使用`restore_snapshot`回滚。
- `execute_dax` 使用Power BI `executeQueries` API，该API仅运行只读DAX（数据修改查询被服务拒绝）。
## 许可证
[MIT](LICENSE)
