powerbi-agent — Hướng dẫn cài đặt

1Yêu cầu hệ thống

Thành phần	Ghi chú
Windows 10/11	Power BI Desktop chỉ có trên Windows
Python 3.11+	`python --version` để kiểm tra
ADOMD.NET	Có sẵn nếu đã cài SSMS (bản 18–22 đều được), hoặc cài Analysis Services client libraries. Trình cài tự dò mọi vị trí; ép đường dẫn bằng biến môi trường `ADOMD_LIB_DIR`.
Power BI Desktop	Bản cài thường hoặc Microsoft Store đều được
Node.js (tùy chọn)	Chỉ cần nếu chạy kèm `powerbi-modeling` của Microsoft (mục 5)

2Cài bằng AI Agent — 1 câu lệnh (khuyến nghị)

Dán câu này vào agent của bạn (Claude Code / Codex / Antigravity):

Clone https://github.com/ducnguyen221/powerbi-agent vào ~/.mcp/powerbi-mcp rồi chạy install.ps1 trong đó (đọc script trước khi chạy), sau đó restart MCP host.

Hoặc cài tay:

git clone https://github.com/ducnguyen221/powerbi-agent "%USERPROFILE%\.mcp\powerbi-mcp"
cd "%USERPROFILE%\.mcp\powerbi-mcp"
powershell -ExecutionPolicy Bypass -File .\install.ps1

install.ps1 làm gì (in-place, chạy lại nhiều lần an toàn)

Dựng .venv + cài dependencies (rebuild nếu venv copy từ máy khác bị hỏng)

Dò ADOMD.NET + TOM đa phiên bản (SSMS 18–22 / standalone / GAC)

Đăng ký MCP vào cả 3 host (Claude ~/.claude.json · Codex config.toml · Antigravity mcp_config.json) — đường dẫn suy từ vị trí thư mục, giữ nguyên server khác, backup .bak

Copy 3 skill powerbi-mcp + pbi-pipeline + kpim-analysis (kèm references/ + templates/) vào từng host

Tham số	Ý nghĩa
`-Hosts claude,codex,antigravity`	Chọn host (mặc định cả ba)
`-SkipVenv` / `-SkipHosts`	Chỉ cập nhật host / chỉ dựng venv

Cài xong phải khởi động lại host (Claude Code / Codex / Antigravity) để tool mới xuất hiện.

3Kiểm tra sau cài

claude mcp list        # phải thấy: powerbi-mcp-bridge ... ✔ Connected

Rồi mở 1 file .pbix bất kỳ trong Power BI Desktop và hỏi agent:

Liệt kê các báo cáo Power BI đang mở, cho tôi xem danh sách bảng và measure của model.

Bước tiếp theo (1 lần): gõ /pbi-setup — agent hỏi bạn chỉ định Knowledge Dir (folder NGOÀI repo, ưu tiên Brain/knowledge base có sẵn) để lưu tri thức dự án. Sau đó: /pbi-new mở dự án · /pbi-scan quét thiết kế · /pbi-done đóng · /pbi-pack đóng gói · /pbi-recall gợi nhớ. Danh sách đầy đủ + luồng: README.

Agent gọi list_local_reports → list_tables → describe_table là cài đặt thành công.

416 tool có gì

Nhóm	Tool	Chức năng
Khám phá	`list_local_reports`	Báo cáo Desktop đang mở (port + model ID)
	`list_tables`	Danh sách bảng (lọc bảng hệ thống)
	`describe_table`	Cột + kiểu dữ liệu + measure của 1 bảng
Truy vấn 🛡️	`execute_dax_local`	DAX lên Desktop — qua policy an toàn dữ liệu
Truy vấn 🛡️	`execute_dax_service`	DAX lên Power BI Service (cần mục 6)
Ghi model	`add_measure_local`	Tạo/sửa measure qua TOM
Ghi model	`add_relationship_local`	Relationship Many-to-One qua TOM
Template 🎨	`list_templates`	Kit báo cáo có sẵn
	`apply_template`	Dựng trang mới từ kit — style giữ nguyên 100%
	`distill_template`	Trang đẹp → kit tái dùng (sanitize trước khi chia sẻ)
Distill	`distill_model_schema`	Model → blueprint Markdown + Mermaid ERD
Distill	`distill_report_design`	Quét TRỌN báo cáo: mọi trang + theme + DESIGN + CATALOG
Knowledge OS 🧠	`knowledge_status`	Kiểm tra Knowledge Dir + hiện trạng
	`setup_knowledge`	Thiết lập Knowledge Dir user chỉ định (ngoài repo)
	`init_project`	Mở dự án mới projects/<slug>/
	`log_timeline`	Ghi lịch sử/bài học vào TIMELINE.md

5Chạy kèm powerbi-modeling của Microsoft (khuyến nghị)

powerbi-agent không xây lại modeling — phần tạo/sửa hàng loạt table/column/measure/relationship, TMDL, validate DAX giao cho MCP chính chủ Microsoft:

claude mcp add powerbi-modeling -s user -- npx -y "@microsoft/powerbi-modeling-mcp@latest" --start

Phân vai (skill đã dạy agent): query + policy + template/report layer → powerbi-agent · modeling ops → powerbi-modeling. Không ghi 2 server cùng lúc lên 1 model.

6Chính sách an toàn dữ liệu 🛡️

Nguyên tắc: dữ liệu thô ở lại trong engine — chỉ kết quả tổng hợp vào context LLM. Enforce ở server:

Lớp	Mặc định	Điều chỉnh
Chặn dump thô (`EVALUATE 'Bảng'`, `ALL()`)	BẬT	`POWERBI_AGGREGATE_ONLY=0` để tắt
PII blocklist (cột cấm project)	Theo file	Copy `policy.example.json` → `policy.json`, liệt kê cột
Audit log JSONL	BẬT	`~/.powerbi-agent/audit/` (đổi: `POWERBI_AUDIT_DIR`)
Trần 200 dòng cho kết quả có cột dimension	BẬT	`POWERBI_DIMENSION_ROW_CAP`

Trung thực về giới hạn: đây là guard chống rò rỉ sơ ý. Bảo mật cứng = RLS trên model + service principal quyền tối thiểu. Chi tiết kiểm thử: docs/UAT-REPORT.md.

7Power BI Service (cloud — tùy chọn)

Tạo Azure Entra ID App Registration, cấp quyền Power BI Service API + add vào workspace

Copy .env.example → .env, điền TENANT_ID / CLIENT_ID / CLIENT_SECRET

Hỏi agent: "chạy DAX này lên dataset <GUID> trên Service" → execute_dax_service (token có cache)

.env KHÔNG commit, không nằm trong gói chia sẻ — trình cài không bao giờ ghi đè file thật.

8Quy trình KPIM, Template kit & pipeline 9 khâu

Luật sắt: không bao giờ để agent tự dựng layout báo cáo từ đầu — luôn apply_template từ kit đã chứng minh (kit mẫu templates/kpim-business-light đi kèm: card KPI + combo chart + pivot + slicer + map, style đầy đủ).

Trang nào bạn ưng → bảo agent distill_template đóng thành kit riêng — lần sau tái tạo đúng style đó trên dữ liệu khác.

3 skill tự cài vào host:

powerbi-mcp — hướng dẫn 11 tool.
pbi-pipeline — quy trình kỹ thuật 9 khâu (kết nối → transform M → model → DAX → truy vấn → visual → trang → nâng cao → artifact, mỗi khâu có cổng kiểm) + references/ best-practices DAX/Power Query/SQL (nguồn Microsoft Learn).
kpim-analysis — quy trình phân tích KPIM: nhận 1 bộ dữ liệu → tự khảo sát, hỏi ngược người dùng, sinh bộ tài liệu chuẩn hóa (PROJECT.md, DATA_DICTIONARY, METRICS_CALCULATION, DOMAIN_DIMENSION, REPORTS, DESIGN + theme.json, Project_Management.xlsx 6 sheet, 5 mindmap) rồi bàn giao cho pbi-pipeline. Mẫu điền-ngay ở plugins/powerbi-agent/skills/kpim-analysis/templates/.

9Xử lý sự cố

Triệu chứng	Cách xử lý
Tool báo thiếu ADOMD.NET	Cài SSMS hoặc AS client libraries; hoặc set `ADOMD_LIB_DIR` tới thư mục chứa `Microsoft.AnalysisServices.AdomdClient.dll`
`list_local_reports` rỗng	Power BI Desktop phải ĐANG MỞ 1 file; chờ vài giây sau khi mở để engine (msmdsrv) lên
Tool không xuất hiện trong agent	Restart host; kiểm tra `claude mcp list`
Trang mới apply_template không thấy	File .pbip phải ĐÓNG khi apply; nếu đang mở → Đóng KHÔNG LƯU rồi mở lại (Ctrl+S phiên cũ sẽ đè mất trang)
Truy vấn bị chặn "aggregate-only"	Là chủ đích (chống dump thô). Viết lại bằng SUMMARIZECOLUMNS/TOPN/measure; thực sự cần thô → `POWERBI_AGGREGATE_ONLY=0`
Sửa file .ps1 xong chạy lỗi lạ	File .ps1 phải UTF-8 có BOM (PowerShell 5.1 + tiếng Việt)

10Mang sang máy khác / Gỡ cài

powershell -ExecutionPolicy Bypass -File .\pack.ps1   # đóng zip sạch (loại .venv/.env/.git) ra Desktop
.\uninstall.ps1                                        # gỡ khỏi host, giữ file
.\uninstall.ps1 -RemoveVenv                            # gỡ + xóa venv