内容
<h1 align="center">力织 MCP 服务器</h1>
<p align="center">
<strong>检测问题。自动修复问题。优化您的 Fabric 租户。</strong><br>
一个 MCP 服务器，扫描 Lakehouses、Warehouses、Eventhouses 和 Semantic Models，拥有 120 条规则 — 其中 45 条可自动修复。
</p>
<p align="center">
<a href="#-快速开始">快速开始</a> •
<a href="#-检测-扫描">检测</a> •
<a href="#-自动修复">自动修复</a> •
<a href="#-规则参考">规则</a> •
<a href="#-架构">架构</a>
</p>
---
## ✨ 主要功能
### 🔍 检测 — 4 个 Fabric 项目的 120 条规则
| 项目 | 规则 | 扫描内容 |
|------|-------|----------------|
| 🏠 **Lakehouse** | 29 | SQL 端点 + OneLake Delta 日志（VACUUM 历史记录、文件大小、分区、保留） |
| 🏗️ **Warehouse** | 39 | 架构、查询性能、安全（PII、RLS）、数据库配置 |
| 📊 **Eventhouse** | 20/数据库 | 扩展碎片、缓存/保留/合并/编码/分区策略、摄入、查询性能、物化视图、存储函数 |
| 📐 **Semantic Model** | 32 | DAX 表达式反模式、模型结构、COLUMNSTATISTICS BPA |
| | **120 总计** | |
### 🔧 修复 — 45 个可自动修复的问题
| 项目 | 自动修复 | 方法 |
|------|-----------|--------|
| 🏗️ **Warehouse** | 12 个修复 | 直接执行的 SQL DDL |
| 🏠 **Lakehouse** | 14 个修复 | REST API（3）+ Notebook Spark SQL（11） |
| 📐 **Semantic Model** | 12 个修复 | model.bim REST API（6）+ Notebook sempy（6） |
| 📊 **Eventhouse** | 7 个修复 | KQL 管理命令（带有 dry-run 预览） |
| | **45 总计** | |
### 📊 统一输出
每次扫描都返回一个干净的结果表 — 只显示问题，总结中计算通过的规则：
```
29 条规则 — ✅ 18 通过 | 🔴 1 失败 | 🟡 10 警告
| 规则 | 状态 | 发现 | 建议 |
|------|--------|---------|----------------|
| LH-007 关键列不为空 | 🔴 | 16 个关键列允许为空：table.finding_id，... | 添加 NOT NULL 约束 |
| LH-017 定期 VACUUM 执行 | 🟡 | 4 个表需要 VACUUM：table1，table2，... | 每周运行 VACUUM |
```
---
## 🚀 快速开始
### 先决条件
- **Node.js** 18+
- **Azure CLI** 已完成 `az login`
- **Fabric 容量** 带有要扫描的项目
### 安装
```bash
git clone https://github.com/tmdaidevs/Force-Fabric-MCP-Server.git
cd Force-Fabric-MCP-Server
npm install
npm run build
```
### 配置 VS Code
将以下内容添加到您的项目中的 `.vscode/mcp.json`：
```json
{
"servers": {
"fabric-optimization": {
"type": "stdio",
"command": "node",
"args": ["dist/index.js"],
"cwd": "/path/to/Force-Fabric-MCP-Server"
}
}
}
```
### 使用
```
1. "使用 azure_cli 登录到 Fabric"
2. "列出工作区 <id> 中的所有 lakehouse"
3. "扫描工作区 <id> 中的 lakehouse <id>"
4. "修复工作区 <id> 中的 warehouse <id>"
```
---
## 🔍 检测和扫描
### 可用的扫描工具
| 工具 | 功能 |
|------|-------------|
| `lakehouse_optimization_recommendations` | 扫描 SQL 端点 + 读取 OneLake 中的 Delta 日志文件 |
| `warehouse_optimization_recommendations` | 通过 SQL 连接并运行 39 个诊断查询 |
| `warehouse_analyze_query_patterns` | 针对慢/频繁/失败查询的聚焦分析 |
| `eventhouse_optimization_recommendations` | 对每个 KQL 数据库运行 KQL 诊断 |
| `semantic_model_optimization_recommendations` | 执行 DAX + MDSCHEMA DMV 以进行 BPA 分析 |
### 使用的数据源
```
┌─────────────────────────────────────┐
│ Fabric REST API │
│ 工作区、项目、元数据 │
└──────────────┬──────────────────────┘
│
┌──────────────┬───────────────┼───────────────┬──────────────┐
▼ ▼ ▼ ▼ ▼
┌─────────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────────┐
│ SQL 客户端 │ │ KQL REST │ │ OneLake ADLS │ │ DAX API │ │ MDSCHEMA DMV │
│ （费力） │ │ API │ │ Gen2 API │ │executeQry│ │ 通过 REST │
└──────┬──────┘ └────┬─────┘ └──────┬───────┘ └────┬─────┘ └──────┬───────┘
│ │ │ │ │
Lakehouse SQL Eventhouse Delta 日志 JSON Semantic Semantic
Warehouse SQL KQL 数据库 文件元数据 模型 DAX 模型元数据
```
---
## 🔧 自动修复
### Warehouse 修复（`warehouse_fix`）
运行所有安全修复或指定个别规则 ID：
| 规则 ID | 修复内容 | SQL 命令 |
|---------|--------------|-------------|
| WH-001 | 缺失主键 | `ALTER TABLE ADD CONSTRAINT PK NOT ENFORCED` |
| WH-008 | 过时统计信息（>30 天） | `UPDATE STATISTICS [table]` |
| WH-009 | 禁用约束 | `ALTER TABLE WITH CHECK CHECK CONSTRAINT ALL` |
| WH-016 | 缺失审计列 | `ALTER TABLE ADD created_at DATETIME2 DEFAULT GETDATE()` |
| WH-018 | 未屏蔽敏感数据 | `ALTER COLUMN ADD MASKED WITH (FUNCTION='...')` |
| WH-026 | 自动更新统计信息关闭 | `ALTER DATABASE SET AUTO_UPDATE_STATISTICS ON` |
| WH-027 | 结果集缓存关闭 | `ALTER DATABASE SET RESULT_SET_CACHING ON` |
| WH-028 | 快照隔离关闭 | `ALTER DATABASE SET ALLOW_SNAPSHOT_ISOLATION ON` |
| WH-029 | 页面验证不是 CHECKSUM | `ALTER DATABASE SET PAGE_VERIFY CHECKSUM` |
| WH-030 | ANSI 设置关闭 | `ALTER DATABASE SET ANSI_NULLS ON; ...` |
| WH-032 | 缺失统计信息 | `UPDATE STATISTICS [table]` |
| WH-036 | 没有默认值的 NOT NULL | `ALTER TABLE ADD DEFAULT ... FOR column` |
### Eventhouse 修复（`eventhouse_fix`）
支持 **dry-run 模式**（`dryRun: true`）以预览命令而不执行它们：
| 规则 ID | 修复内容 | KQL 命令 |
|---------|--------------|-------------|
| EH-002 | 碎片化扩展 | `.merge table ['name']` |
| EH-004 | 缺失缓存策略 | `.alter table/database policy caching hot = 30d` |
| EH-005 | 缺失保留策略 | `.alter table/database policy retention softdelete = 365d` |
| EH-006 | 不健康的物化视图 | `.enable materialized-view ['name']` |
| EH-014 | 缺失摄入批处理 | `.alter table/database policy ingestionbatching ...` |
| EH-016 | 大型表格无分区 | `.alter table policy partitioning ...` |
| EH-017 | 次优合并策略 | `.alter table policy merge ...` |
### Lakehouse 修复（`lakehouse_run_table_maintenance`）
| 修复 | 参数 |
|-----|-----------|
| 使用 V-Order 优化 | `optimizeSettings: { vOrder: true }` |
| 按列进行 Z-Order | `optimizeSettings: { zOrderColumns: ["col1", "col2"] }` |
| 清理过期文件 | `vacuumSettings: { retentionPeriod: "7.00:00:00" }` |
### Semantic Model 修复（`semantic_model_fix`）
下载模型.bim，应用修改，上传回去：
| 修复 ID | 修复内容 | 方法 |
|--------|--------------|--------|
| SM-FIX-FORMAT | 为没有格式字符串的度量添加格式字符串 | model.bim |
| SM-FIX-DESC | 为可见的表添加描述 | model.bim |
| SM-FIX-HIDDEN | 在隐藏的列上设置 IsAvailableInMDX=false | model.bim |
| SM-FIX-DATE | 将日期/日历表标记为日期表 | model.bim |
| SM-FIX-KEY | 在关系中设置 IsKey=true 的主键列 | model.bim |
| SM-FIX-AUTODATE | 删除自动日期表 | model.bim |
### 📓 基于笔记本的修复
对于需要 Spark SQL 的修复，MCP 服务器会创建一个 **临时笔记本**，运行它，然后删除它：
```
1. POST /notebooks → 创建临时笔记本并修复代码
2. POST /items/{id}/jobs → 执行笔记本
3. GET /items/{id}/jobs/{job} → 轮询直到完成
4. DELETE /notebooks/{id} → 清理
```
#### Lakehouse 笔记本修复
| 规则 | Spark SQL 命令 |
|------|------------------|
| LH-003 | `CONVERT TO DELTA spark_catalog.lakehouse.table` |
| LH-005 | `DROP TABLE lakehouse.table` |
| LH-009 | `ALTER TABLE lakehouse.table RENAME COLUMN old TO new` |
| LH-014 | `ALTER TABLE t ADD COLUMN created_at TIMESTAMP DEFAULT current_timestamp()` |
| LH-020 | `ALTER TABLE t SET TBLPROPERTIES ('delta.autoOptimize.optimizeWrite'='true')` |
| LH-021 | `ALTER TABLE t SET TBLPROPERTIES ('delta.logRetentionDuration'='interval 30 days')` |
| LH-024 | `ALTER TABLE t SET TBLPROPERTIES ('delta.dataSkippingNumIndexedCols'='32')` |
| LH-S04 | `ALTER TABLE t ADD COLUMN id BIGINT` |
#### Semantic Model 笔记本修复（通过 sempy_labs）
| 修复 | sempy 代码 |
|-----|-----------|
| 删除计算列 | `tom.remove_column(table, column)` |
| 删除计算表 | `tom.remove_table(table)` |
| 修复双向关系 | `rel.CrossFilteringBehavior = OneDirection` |
| 修复 RLS 表达式 | `table_permission.FilterExpression = ...` |
| 同步 DirectLake 架构 | `labs.update_direct_lake_model_lakehouse_schema()` |
| 刷新模型 | `fabric.refresh_dataset(dataset, workspace)` |
---
## 📋 规则参考
### 总结
| 类别 | HIGH | MEDIUM | LOW | INFO | 总计 | 自动修复 |
|----------|------|--------|-----|------|-------|----------|
| 🏠 Lakehouse | 5 | 14 | 9 | 1 | **29** | 14（3 REST + 11 笔记本） |
| 🏗️ Warehouse | 8 | 17 | 12 | 0 | **39** | 12（SQL DDL） |
| 📊 Eventhouse | 4 | 7 | 3 | 3 | **20** | 7（KQL + dry-run） |
| 📐 Semantic Model | 7 | 14 | 9 | 0 | **32** | 12（6 model.bim + 6 笔记本） |
| **总计** | **24** | **52** | **33** | **4** | **120** | **45** |
<details>
<summary><strong> 🏠 Lakehouse — 29 条规则</strong>（点击展开)</summary>
| # | 规则 | 类别 | 严重性 | 自动修复 |
|---|------|----------|----------|----------|
| LH-001 | SQL 端点活动 | 可用性 | HIGH | — |
| LH-002 | Medallion 架构命名 | 可维护性 | LOW | — |
| LH-003 | 所有表格使用 Delta 格式 | 性能 | HIGH | 📓 笔记本 |
| LH-003 | 所有表格使用 Delta 格式 | 性能 | HIGH | 📓 笔记本 |
| LH-004 | 表名 | <br> |
| LH-004 | 表维护推荐 | 性能 | 中等 | — |
| LH-005 | 没有空表 | 数据质量 | 中等 | 📓 笔记本 |
| LH-006 | 没有过度预配的字符串列 | 性能 | 中等 | — |
| LH-007 | 关键列不能为空 | 数据质量 | 高 | — |
| LH-008 | 没有浮点/实数精度问题 | 数据质量 | 中等 | — |
| LH-009 | 列命名约定 | 可维护性 | 低 | 📓 笔记本 |
| LH-010 | 日期列使用正确类型 | 数据质量 | 中等 | — |
| LH-011 | 数值列使用正确类型 | 数据质量 | 中等 | — |
| LH-012 | 没有过度宽的表格 | 可维护性 | 低 | — |
| LH-013 | 架构有 NOT NULL 约束 | 数据质量 | 中等 | — |
| LH-014 | 表格有审计列 | 可维护性 | 低 | 📓 笔记本 |
| LH-015 | 一致的日期类型 | 数据质量 | 低 | — |
| LH-S01 | 没有未受保护的敏感数据 | 安全 | 高 | — |
| LH-S02 | 标识了大表格 | 性能 | 信息 | — |
| LH-S03 | 没有已弃用的数据类型 | 可维护性 | 高 | — |
| LH-S04 | 所有表格都有关键列 | 数据质量 | 中等 | 📓 笔记本 |
| LH-016 | 大型表格已分区 | 性能 | 中等 | — |
| LH-017 | 定期 VACUUM 执行 | 维护 | 中等 | 🔧 REST API |
| LH-018 | 定期 OPTIMIZE 执行 | 性能 | 中等 | 🔧 REST API |
| LH-019 | 没有小文件问题 | 性能 | 高 | 🔧 REST API |
| LH-020 | 启用自动优化 | 性能 | 中等 | 📓 笔记本 |
| LH-021 | 配置了保留策略 | 维护 | 低 | 📓 笔记本 |
| LH-022 | Delta 日志版本计数合理 | 性能 | 低 | 🔧 REST API |
| LH-023 | 低写放大 | 性能 | 中等 | — |
| LH-024 | 配置了数据跳跃 | 性能 | 低 | 📓 笔记本 |
| LH-025 | 大型表格上的 Z-Order | 性能 | 中等 | 🔧 REST API |
</details>
<details>
<summary><strong> 🏗️ Warehouse — 39 条规则</strong>（点击展开）</summary>
| # | 规则 | 类别 | 严重性 | 自动修复 |
|---|------|----------|----------|----------|
| WH-001 | 定义主键 | 数据质量 | 高 | 🔧 SQL |
| WH-002 | 没有已弃用的数据类型 | 可维护性 | 高 | — |
| WH-003 | 没有浮点/实数精度问题 | 数据质量 | 中等 | — |
| WH-004 | 没有过度预配的列 | 性能 | 中等 | — |
| WH-005 | 列命名约定 | 可维护性 | 低 | — |
| WH-006 | 表格命名约定 | 可维护性 | 低 | — |
| WH-007 | 视图中没有 SELECT * | 可维护性 | 低 | — |
| WH-008 | 统计信息新鲜 | 性能 | 中等 | 🔧 SQL |
| WH-009 | 没有禁用的约束 | 数据质量 | 中等 | 🔧 SQL |
| WH-010 | 关键列不能为空 | 数据质量 | 高 | — |
| WH-011 | 没有空表 | 可维护性 | 中等 | — |
| WH-012 | 没有过度宽的表格 | 可维护性 | 中等 | — |
| WH-013 | 一致的日期类型 | 数据质量 | 低 | — |
| WH-014 | 定义外键 | 可维护性 | 中等 | — |
| WH-015 | 没有大 BLOB 列 | 性能 | 中等 | — |
| WH-016 | 表格有审计列 | 可维护性 | 低 | 🔧 SQL |
| WH-017 | 没有循环外键 | 数据质量 | 高 | — |
| WH-018 | 敏感数据受保护 | 安全 | 高 | 🔧 SQL |
| WH-019 | 行级安全性 | 安全 | 中等 | — |
| WH-020 | 最小化 db_owner 权限 | 安全 | 中等 | — |
| WH-021 | 没有过于复杂的视图 | 可维护性 | 低 | — |
| WH-022 | 最小化跨模式依赖 | 可维护性 | 低 | — |
| WH-023 | 没有非常慢的查询 | 性能 | 高 | — |
| WH-024 | 没有频繁的慢查询 | 性能 | 高 | — |
| WH-025 | 没有最近的查询失败 | 可靠性 | 中等 | — |
| WH-026 | 启用 AUTO_UPDATE_STATISTICS | 性能 | 高 | 🔧 SQL |
| WH-027 | 启用结果集缓存 | 性能 | 中等 | 🔧 SQL |
| WH-028 | 启用快照隔离 | 并发性 | 中等 | 🔧 SQL |
| WH-029 | 页面验证 CHECKSUM | 可靠性 | 中等 | 🔧 SQL |
| WH-030 | 正确的 ANSI 设置 | 标准 | 低 | 🔧 SQL |
| WH-031 | 数据库在线 | 可用性 | 高 | — |
| WH-032 | 所有表格都有统计信息 | 性能 | 中等 | 🔧 SQL |
| WH-033 | 最佳数据类型 | 性能 | 中等 | — |
| WH-034 | 没有近乎空的表格 | 可维护性 | 低 | — |
| WH-035 | 存储过程有文档 | 可维护性 | 低 | — |
| WH-036 | 没有默认值的 NOT NULL | 数据质量 | 中等 | 🔧 SQL |
| WH-037 | 一致的字符串类型 | 可维护性 | 低 | — |
| WH-038 | 模式有文档 | 可维护性 | 低 | — |
| WH-039 | 查询性能健康 | 性能 | 中等 | — |
</details>
<details>
<summary><strong> 📊 Eventhouse — 20 条规则/数据库</strong>（点击展开）</summary>
| # | 规则 | 类别 | 严重性 | 自动修复 |
|---|------|----------|----------|----------|
| EH-001 | 查询端点可用 | 可用性 | 高 | — |
| EH-002 | 没有扩展碎片 | 性能 | 高 | 🔧 KQL |
| EH-003 | 良好的压缩比率 | 性能 | 中等 | — |
| EH-004 | 配置缓存策略 | 性能 | 中等 | 🔧 KQL |
| EH-005 | 配置保留策略 | 数据管理 | 中等 | 🔧 KQL |
| EH-006 | 物化视图健康 | 可靠性 | 高 | 🔧 KQL |
| EH-007 | 数据新鲜 | 数据质量 | 中等 | — |
| EH-008 | 没有慢查询模式 | 性能 | 高 | — |
| EH-009 | 没有最近的失败命令 | 可靠性 | 中等 | — |
| EH-010 | 没有摄入失败 | 可靠性 | 高 | — |
| EH-011 | 配置摄入设置 | 性能 | 信息 | — |
| EH-012 | 持续导出健康 | 可靠性 | 中等 | — |
| EH-013 | 热缓存覆盖 | 性能 | 中等 | — |
| EH-014 | 配置摄入批处理 | 性能 | 低 | 🔧 KQL |
| EH-015 | 更新策略配置 | 数据管理 | 信息 | — |
| EH-016 | 大型表格分区 | 性能 | 中等 | 🔧 KQL |
| EH-017 | 配置合并策略 | 性能 | 低 | 🔧 KQL |
| EH-018 | 不良压缩策略 | 性能 | 中等 | — |
| EH-019 | 行顺序策略 | 性能 | 低 | — |
| EH-020 | 存储函数清单 | 数据管理 | 信息 | — |
</details>
<details>
<summary><strong> 📐 Semantic Model — 32 条规则</strong>（点击展开）</summary>
| # | 规则 | 类别 | 严重性 | 自动修复 |
|---|------|----------|----------|----------|
| SM-001 | 避免 IFERROR 函数 | DAX | 中等 | 📓 笔记本 |
| SM-002 | 使用 DIVIDE 函数 | DAX | 中等 | 📓 笔记本 |
| SM-003 | 生产环境中没有 EVALUATEANDLOG | DAX | 高 | 📓 笔记本 |
| SM-004 | 使用 TREATAS 而不是 INTERSECT | DAX | 中等 | — |
| SM-005 | 没有重复的度量定义 | DAX | 低 | — |
| SM-006 | 按列而非表格筛选 | DAX | 中等 | 📓 笔记本 |
| SM-007 | 避免在度量中添加 0 | DAX | 低 | — |
| SM-008 | 度量有文档 | 维护 | 低 | 🔧 model.bim + 📓 |
| SM-009 | 模型有表格 | 维护 | 高 | — |
| SM-010 | 模型有日期表格 | 性能 | 中等 | 🔧 model.bim |
| SM-011 | 避免 1-(x/y) 语法 | DAX | 中等 | — |
| SM-012 | 直接度量引用 | DAX | 低 | — |
| SM-013 | 避免嵌套 CALCULATE | DAX | 中等 | — |
| SM-014 | 使用 SUM 而不是 SUMX | DAX | 低 | — |
| SM-015 | 度量有格式字符串 | 格式化 | 低 | 🔧 model.bim |
| SM-016 | 避免 FILTER(ALL(...)) | DAX | 中等 | — |
| SM-017 | 度量命名约定 | 格式化 | 低 | — |
| SM-018 | 表格数量合理 | 性能 | 低 | — |
| SM-B01 | 没有高基数文本列 | 数据类型 | 高 | — |
| SM-B02 | 没有描述/注释列 | 数据类型 | 高 | — |
| SM-B03 | 没有 GUID/UUID 列 | 数据类型 | 高 | — |
| SM-B04 | 没有常量列 | 数据类型 | 中等 | — |
| SM-B05 | 没有将布尔值存储为文本 | 数据类型 | 中等 | — |
| SM-B06 | 没有将日期存储为文本 | 数据类型 | 中等 | — |
| SM-B07 | 没有将数字存储为文本 | 数据类型 | 中等 | — |
| SM-B08 | 整数键而不是字符串键 | 数据类型 | 中等 | — |
| SM-B09 | 没有过度宽的表格 | 数据类型 | 中等 | — |
| SM-B10 | 没有极宽的表格 | 数据类型 | 高 | — |
| SM-B11 | 没有多个高基数列 | 数据类型 | 高 | — |
| SM-B12 | 没有单一列表格 | 数据类型 | 低 | — |
| SM-B13 | 没有高精度时间戳 | 数据类型 | 中等 | — |
| SM-B14 | 事实表格中没有低基数 | 数据类型 | 低 | — |
</details>
---
## 🏗️ 架构
```
src/
├── index.ts MCP 服务器入口点（stdio 传输）
├── auth/
│ └── fabricAuth.ts Azure 身份验证（CLI，浏览器，设备代码，SP）
├── clients/
│ ├── fabricClient.ts Fabric REST API + DAX + model.bim CRUD
│ ├── sqlClient.ts 通过 tedious 的 SQL（Lakehouse + Warehouse）
│ ├── kqlClient.ts KQL/Kusto REST API（Eventhouse）
│ ├── onelakeClient.ts OneLake ADLS Gen2 + Delta 日志解析器
│ └── xmlaClient.ts XMLA SOAP 客户端（实验中）
└── tools/
├── ruleEngine.ts 共享 RuleResult 类型 + 统一渲染器
├── auth.ts auth_login, auth_status, auth_logout
├── workspace.ts workspace_list
├── lakehouse.ts 29 条规则 + 表维护
├── warehouse.ts 39 条规则 + 12 个自动修复
├── eventhouse.ts 20 条规则 + 7 个自动修复（带有 dry-run）
└── semanticModel.ts 32 条规则 + 6 个自动修复（model.bim）
```
## 🔐 身份验证
| 方法 | 用例 |
|--------|----------|
| `azure_cli` | **推荐** — 使用您的 `az login` 会话 |
| `interactive_browser` | 打开浏览器进行交互式登录 |
| `device_code` | 无头/远程环境 |
| `vscode` | 使用 VS Code Azure 帐户 |
| `service_principal` | CI/CD（需要 tenantId, clientId, clientSecret） |
| `default` | 自动检测最佳可用方法 |
## 📄 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器