🚀 Fabric AI Gateway
MCP Server cho Microsoft Fabric Cloud - Chạy Native trên macOS
📋 Mô tả
Fabric AI Gateway là một MCP (Model Context Protocol) Server cho phép AI CLI (Gemini, Codex) tương tác trực tiếp với Microsoft Fabric Cloud mà không cần Windows VM hoặc Power BI Desktop.
Hỗ trợ 2 chế độ:
| Mode | Mô tả | Backend |
|---|
| Semantic Model | Đọc schema, thực thi DAX, tạo/sửa Measures | REST API + XMLA |
| Data Warehouse | Quét cấu trúc, profiling, sampling, SQL | pyodbc + ODBC 18 |
🏗️ Kiến trúc Hệ thống
┌─────────────────────────────────────────────────────────────────────────────┐
│ USER │
│ │ │
│ ┌───────────▼───────────┐ │
│ │ mcp_cloud_fabric.py │ ◄── Entry Point │
│ │ (Auth + Setup) │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Gemini CLI │ │ Codex CLI │ │ Standalone CLI │ │
│ │ │ │ │ │ (src/cli.py) │ │
│ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │
│ │ stdio │ stdio │ direct │
│ └────────────────────┼────────────────────┘ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ MCP Server │ │
│ │ (src/mcp_server.py) │ │
│ │ │ │
│ │ ┌─────────────────┐ │ │
│ │ │ Context Manager │ │ ◄── ~/.fabric-gateway/ │
│ │ │ │ │ context.json │
│ │ └─────────────────┘ │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌─────────────────┴─────────────────┐ │
│ ▼ ▼ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ SEMANTIC MODE │ │ WAREHOUSE MODE │ │
│ │ (13 Tools) │ │ (3 Tools) │ │
│ │ │ │ │ │
│ │ ● list_workspaces │ │ ● get_warehouse_ │ │
│ │ ● list_datasets │ │ tables │ │
│ │ ● connect_dataset │ │ ● execute_sql │ │
│ │ ● get_tables │ │ ● describe_table │ │
│ │ ● get_columns │ │ │ │
│ │ ● get_measures * │ └──────────┬───────────┘ │
│ │ ● get_relationships*│ │ │
│ │ ● execute_dax │ ▼ │
│ │ ● get_dataset_info │ ┌──────────────────────┐ │
│ │ ● refresh_dataset │ │ warehouse_adapter │ │
│ │ ● create_measure * │ │ (pyodbc + Token) │ │
│ │ ● delete_measure * │ └──────────┬───────────┘ │
│ │ ● create_relationship* │ │
│ └──────────┬───────────┘ │ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ semantic_adapter │ │ Fabric Warehouse │ │
│ │ (REST API + DAX) │ │ (SQL Endpoint) │ │
│ └──────────┬───────────┘ └──────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Power BI Service │ * = Requires Premium/Fabric │
│ │ (api.powerbi.com) │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
📁 Cấu trúc Project
MCP_Cloud_Fabric/
├── mcp_cloud_fabric.py # 🚀 Entry Point - Auth + CLI Launch
├── config.yaml.template # ⚙️ Config template (copy to config.yaml)
├── requirements.txt # Python dependencies
├── CHANGELOG.md # 📝 Lịch sử thay đổi
│
├── src/
│ ├── mcp_server.py # 🤖 MCP Server (JSON-RPC stdio)
│ ├── cli.py # 🖥️ Standalone CLI
│ ├── auth.py # 🔐 MSAL Authentication
│ ├── context_manager.py # 📋 State Management
│ ├── semantic_adapter.py # 📊 Power BI REST API + DAX
│ ├── warehouse_adapter.py # 🗄️ SQL via pyodbc
│ └── utils/
│ ├── xmla_client.py # XMLA wrapper
│ ├── tmsl_generator.py # TMSL generator
│ ├── fabric_client_wrapper.py # .NET client wrapper
│ └── FabricClient/ # 🔧 .NET Middleware (ADOMD/TOM)
│ ├── Program.cs
│ └── FabricClient.csproj
│
├── bin/TabularEditor/ # Windows binaries (Mono compatible)
│
├── scripts/ # Shell launchers
│ ├── fabricgw, geminigw, codexgw
│
├── tests/ # Unit tests (pytest)
│
└── docs/ # Documentation
⚡ Yêu cầu Hệ thống
| Component | Yêu cầu |
|---|
| OS | macOS (Apple Silicon hoặc Intel) |
| Python | 3.9+ |
| ODBC Driver | ODBC Driver 18 for SQL Server |
| Azure AD | App Registration với Fabric permissions |
Cài đặt ODBC Driver
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
brew install msodbcsql18
🛠️ Cài đặt
# Clone repository
git clone
cd MCP_Cloud_Fabric
# Tạo virtual environment
python3 -m venv venv
source venv/bin/activate
# Cài đặt dependencies
pip install -r requirements.txt
# Copy và cấu hình config
cp config.yaml.template config.yaml
# Sửa config.yaml với Client ID và Tenant ID của bạn
⚙️ Cấu hình
config.yaml
auth:
client_id: "YOUR_AZURE_AD_APP_CLIENT_ID"
tenant_id: "YOUR_AZURE_AD_TENANT_ID"
limits:
max_dax_rows: 1000
sample_rows: 10
Azure AD App Permissions
| API | Permission | Type |
|---|
| Power BI Service | Dataset.Read.All | Delegated |
| Power BI Service | Dataset.ReadWrite.All | Delegated |
| Power BI Service | Workspace.Read.All | Delegated |
| Azure SQL Database | user_impersonation | Delegated |
🚀 Sử dụng
Chạy CLI chính
python mcp_cloud_fabric.py
Flow sử dụng
1. Authenticate (Browser login)
│
▼
2. Select Workspace
│
▼
3. Select Mode ─────────────────────────┐
│ │
▼ ▼
[Semantic Model] [Data Warehouse]
│ │
│ ▼
│ Enter SQL Endpoint
│ Enter Warehouse Name
│ │
└──────────────┬───────────────┘
│
▼
4. Select Interface ────────────────────┐
│ │ │
▼ ▼ ▼
[Gemini CLI] [Codex CLI] [Standalone]
│ │ │
▼ ▼ ▼
Chat với AI Chat với AI Gõ lệnh thủ công
về data về data (dax, sql, etc.)
🔧 MCP Tools Reference
Semantic Model Mode (14 Tools)
| Tool | Mô tả | Premium? | XMLA Write? |
|---|
list_workspaces | Liệt kê tất cả workspaces | ❌ | - |
list_datasets | Liệt kê semantic models trong workspace | ❌ | - |
connect_dataset | Kết nối tới một model | ❌ | - |
get_tables | Lấy danh sách tables + số columns | ❌ | - |
get_columns | Lấy chi tiết columns (có filter) | ❌ | - |
get_measures | Lấy tất cả measures | ✅ | - |
get_relationships | Lấy tất cả relationships | ✅ | - |
execute_dax | Chạy DAX query | ❌ | - |
get_dataset_info | Lấy metadata dataset | ❌ | - |
refresh_dataset | Trigger refresh | ❌ | - |
create_measure | Tạo measure mới | ✅ | ✅ Middleware |
delete_measure | Xóa measure | ✅ | ✅ Middleware |
create_relationship | Tạo relationship | ✅ | ✅ Middleware |
delete_relationship | Xóa relationship | ✅ | ✅ Middleware |
✅ macOS Support: Các tool write sử dụng .NET Middleware (FabricClient) với TOM API để thực thi trực tiếp qua XMLA endpoint. Nếu middleware không khả dụng, tool sẽ trả về TMSL script để chạy thủ công trong SSMS hoặc Tabular Editor.
Data Warehouse Mode (3 Tools)
| Tool | Mô tả |
|---|
get_warehouse_tables | Liệt kê all tables (có filter schema) |
execute_sql | Chạy SQL SELECT query |
describe_table | Lấy schema của bảng |
🔒 Bảo mật
- ✅ Token cache mã hóa tại
~/.fabric-gateway/token_cache.bin - ✅ Kết nối SQL được mã hóa (
Encrypt=yes) - ✅ Không sử dụng
TrustServerCertificate=yes - ✅ SQL queries được validate để chặn lệnh nguy hiểm
- ✅ Context file chỉ lưu IDs, không lưu credentials
� License
MIT License
📚 Tài liệu thêm
