# https://github.com/sdebruyn/fabric-dw-mcp-cli 项目说明书 生成时间：2026-07-13 10:15:34 UTC ## 目录 - [项目概述、安装与认证](#page-1) - [CLI 命令参考（按域分组）](#page-2) - [MCP 服务器、工具与 AI 集成](#page-3) - [内部架构、部署、遥测与安全](#page-4) ## 项目概述、安装与认证 ### 相关页面 相关主题：[CLI 命令参考（按域分组）](#page-2), [MCP 服务器、工具与 AI 集成](#page-3), [内部架构、部署、遥测与安全](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/README.md) - [docs/index.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/docs/index.md) - [docs/install.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/docs/install.md) - [docs/authentication.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/docs/authentication.md) - [src/fabric_dw/auth.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/auth.py) - [src/fabric_dw/config.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/config.py) - [src/fabric_dw/sql.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/sql.py) - [pyproject.toml](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/pyproject.toml)
# 项目概述、安装与认证 ## 项目概述 `fabric-dw-mcp-cli` 是一个面向 Microsoft Fabric Data Warehouse 的命令行工具与 MCP（Model Context Protocol）服务器。它将 Fabric 数据仓库的日常管理操作（仓库、Lakehouse、SQL 池、表、数据查询、连接字符串生成等）封装为 **118 个专用工具**，覆盖 20 个领域，让 AI 智能体无需依赖通用的 `execute_sql` 就能完成绝大部分仓库管理动作 资料来源：[README.md:1-40]()。 项目同时提供两种使用形态： - **CLI 形态**：在终端中以 `fabric-dw` 命名空间直接调用子命令； - **MCP 服务器形态**：以 `fabric-dw-mcp` 启动，将工具暴露给任何支持 MCP 协议的客户端（Claude Desktop、VS Code、Cursor 等） 资料来源：[docs/index.md:1-30]()。 自 v2026.7.1 起，服务器在 `InitializeResult` 中下发 server instructions 块，使客户端在模型推理之前就能看到对专用工具域的指引，避免智能体回退到 `SELECT * FROM sys.tables` 这类原始 SQL 模式 资料来源：[docs/index.md:30-60]()。 ## 安装 项目以 Python 包 `fabric-dw` 的形式发布在 PyPI，并使用 [uv](https://github.com/astral-sh/uv) 作为推荐的运行与依赖管理工具。安装入口在 `pyproject.toml` 中声明，包含 `fabric-dw`、`fabric-dw-mcp` 等可执行入口 资料来源：[pyproject.toml:1-50]()。 最简安装与运行方式是借助 `uvx` 启动预发布版本（这也是 `.mcp.json` 默认采用的方式）： ```bash uvx --prerelease allow --from fabric-dw@latest fabric-dw-mcp ``` 需要注意：在问题 #995 修复之前，发布到 PyPI 的预发布构建无法在 `--prerelease allow` 下直接安装，因为 `httpx` 被解析到了 `1.0.dev3` 这种不可运行的依赖上 资料来源：[docs/install.md:1-40]()。修复后 `httpx` 依赖被限制在 `<2.0`，预发布版本才能被正确解析。 CLI 单独使用可以直接： ```bash uvx --from fabric-dw@latest fabric-dw --help ``` 安装成功后，工具会读取本地 `config.toml`（位于配置目录，详见下一节）并尝试用缓存的令牌与 Fabric API 建立连接。 ## 认证 认证模块位于 `src/fabric_dw/auth.py`，它基于 **Microsoft Entra ID（原 Azure AD）** 的设备码流（device code flow）或客户端凭据流获取 JWT 访问令牌，并将其缓存到本地以便后续 CLI/MCP 调用复用 资料来源：[src/fabric_dw/auth.py:1-60]()。 典型的认证流程如下： ```mermaid sequenceDiagram participant U as 用户/智能体 participant CLI as fabric-dw / fabric-dw-mcp participant A as Entra ID participant F as Fabric API U->>CLI: 首次调用任意命令 CLI->>A: 请求设备码 (device code) A-->>U: 返回登录 URL + 用户码 U->>A: 在浏览器中完成登录 A-->>CLI: 返回 access_token / refresh_token CLI->>CLI: 缓存令牌到本地 CLI->>F: 携带 Bearer Token 调用 REST API F-->>CLI: 资源数据 ``` 资料来源：[src/fabric_dw/auth.py:60-150]()、[docs/authentication.md:1-40]()。 令牌获取后，`build_connection_string` 会把 Entra 颁发的 JWT 拼装到 `mssql-python` 驱动使用的 ODBC 连接字符串中（追加 `Authentication=ActiveDirectoryAccessToken` 等键值），使 SQL 端点能够复用同一个身份 资料来源：[src/fabric_dw/sql.py:1-40]()。 需要注意的是，工具发起的查询在仓库的 `sys.dm_exec_sessions` / 查询历史中默认显示的 `program_name` 是 `MSSQL-Python`（驱动默认值）。目前无法直接改为 `fdw.debruyn.dev`，因为该能力依赖于上游 [mssql-python#649](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/892) 解决 资料来源：[src/fabric_dw/sql.py:40-80]()。 ## 配置 配置由 `src/fabric_dw/config.py` 负责加载与默认值管理。`config.toml` 中可以预先声明默认工作区（workspace）、默认仓库（warehouse）、默认 SQL 端点等，从而支持命令的“短形式”调用（例如只写仓库名、不写工作区） 资料来源：[src/fabric_dw/config.py:1-80]()。 历史上，#981 修复了一个 Click 参数解析缺陷：当命令声明的“前导位置参数”为可选、而后续位置参数为必填时，Click 会按从左到右顺序吞掉第一个必填参数，导致 61 个命令的短形式不可用 资料来源：[docs/authentication.md:40-60]()。配合配置默认值与该修复，CLI 提供了“设置默认 → 短形式调用”的顺滑体验，这一点也是 #982 中端到端旅程测试要覆盖的核心场景 资料来源：[docs/authentication.md:60-80]()。 | 关键能力 | 说明 | 涉及源码 | | --- | --- | --- | | 118 个专用 MCP 工具 | 跨 20 个领域，避免智能体回退到 `execute_sql` | `README.md`、`docs/index.md` | | `uvx --prerelease allow` 一行启动 | `.mcp.json` 推荐配置 | `docs/install.md`、`pyproject.toml` | | Entra ID 设备码流认证 | 令牌本地缓存复用 | `src/fabric_dw/auth.py` | | `build_connection_string` | 把 JWT 注入 mssql-python 连接串 | `src/fabric_dw/sql.py` | | `config.toml` 默认值 | 短形式命令依赖 | `src/fabric_dw/config.py` | --- ## CLI 命令参考（按域分组） ### 相关页面 相关主题：[MCP 服务器、工具与 AI 集成](#page-3), [内部架构、部署、遥测与安全](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/fabric_dw/cli/_main.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/cli/_main.py) - [src/fabric_dw/cli/_context.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/cli/_context.py) - [src/fabric_dw/cli/_render.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/cli/_render.py) - [src/fabric_dw/cli/commands/_utils.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/cli/commands/_utils.py) - [src/fabric_dw/cli/commands/sql.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/cli/commands/sql.py) - [src/fabric_dw/cli/commands/tables.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/cli/commands/tables.py)
# CLI 命令参考（按域分组） ## 1. 整体结构与设计目标 `fabric-dw` 的 CLI 基于 Click 构建，将 Microsoft Fabric Data Warehouse 的日常运维与查询操作组织为 20 个域、118 个子命令。CLI 与 MCP 服务器共享同一份命令实现：MCP 工具与 CLI 子命令一一对应，因此命令命名遵循"动词+名词"的统一风格，便于人类与 AI 代理双方理解。资料来源：[src/fabric_dw/cli/_main.py:1-1]() 入口 `_main.py` 负责注册 Click 组与子命令；`_context.py` 提供运行时上下文（认证、默认 warehouse、默认 workspace 等）；`_render.py` 负责将 API 返回结果（列表、字典、表格）以人类友好的方式输出。资料来源：[src/fabric_dw/cli/_context.py:1-1](), [src/fabric_dw/cli/_render.py:1-1]() ## 2. 按域分组的命令概览 CLI 子命令与 MCP 工具域保持一致，按业务域聚合。下表列出常见域及其典型命令： | 域 | 代表命令 | 用途 | |---|---|---| | `sql` | `fabric-dw sql execute` | 在 warehouse 上执行 T-SQL | | `tables` | `fabric-dw tables list / drop / count` | 列出、删除、统计表 | | `warehouses` | `fabric-dw warehouses list / show` | 列出与查看 warehouse | | `workspaces` | `fabric-dw workspaces list / select` | 列出与切换工作区 | | `oneLake` | `fabric-dw onelake upload / download` | 与 OneLake 互传文件 | 每个域在 `src/fabric_dw/cli/commands/` 下拥有独立模块，例如 `sql.py` 与 `tables.py`，并通过 `commands/_utils.py` 中共享的 Click 装饰器与选项来声明参数。资料来源：[src/fabric_dw/cli/commands/sql.py:1-1](), [src/fabric_dw/cli/commands/tables.py:1-1](), [src/fabric_dw/cli/commands/_utils.py:1-1]() ## 3. 短形式调用与默认值 为减少重复输入，许多命令支持"短形式"：当用户在配置中设置了 `default_workspace` 或 `default_warehouse` 时，可省略首个位置参数。Issue #982 描述的端到端测试正是为了守护这一行为：先调用 `config set` 设置默认仓库，再以短形式执行 `tables list`，验证默认值被正确注入。资料来源：[tests/integration/test_cli_journey.py:1-1]() ### 已知陷阱：前导可选位置参数 Click 在解析位置参数时是严格"从左到右"填充的，会忽略 `required=True` 标记的元数据。Issue #981 指出：若命令声明的签名是 `ITEM (可选), WAREHOUSE (必需)`，则 `tables drop ` 的短形式调用会被 Click 把 `` 错误填入 `ITEM` 而非 `WAREHOUSE`，导致 61 条命令的短形式失效。修复方式是在解析阶段对元数据进行修正后再交由 Click 派发。资料来源：[src/fabric_dw/cli/_main.py:1-1]() ## 4. 与 MCP 工具域的对应关系 CLI 不仅是人工入口，也是 118 个 MCP 工具的同一份实现。Release v2026.7.1 在 MCP `InitializeResult` 中新增了 server instructions，引导 AI 代理优先使用专用工具（`tables list`、`tables drop`、`tables count` 等）而非原始的 `execute_sql`。但 v2026.7.1 的 instructions 仅命名了 18 / 118 个工具；Issue #992 提出补全剩余域的命名，并加入了"漂移守卫"测试，确保 instructions 中提到的每个工具在注册表中真实存在。资料来源：[src/fabric_dw/mcp/server.py:1-1]() 这一对应关系意味着：CLI 文档与 MCP 工具文档可以共用同一份"按域分组"的索引，降低维护成本。 ## 5. 故障排查与延伸阅读 - **`httpx==1.0.dev3` 预发布依赖**：Issue #995 中指出，使用 `uvx --prerelease allow` 启动 MCP 服务器时会解析到不兼容的 `httpx` 预发布版本，需在 `pyproject.toml` 中将 `httpx` 上限设为 `<2.0`。资料来源：[pyproject.toml:1-1]() - **集成测试 `sql_pools` 持续失败**：Issue #994 报告当 workspace 为空时 warehouse 端点返回 500，需在测试夹具中显式确保 warehouse 存在后再执行 `sql_pools` 用例。资料来源：[tests/integration/test_services_sql_pools.py:1-1]() - **SQL 连接 `program_name`**：Issue #892 跟踪将 `mssql_python` 默认的 `program_name="MSSQL-Python"` 改为 `fdw.debruyn.dev`，使本工具发起的查询在 `sys.dm_exec_sessions` 中可被识别（当前阻塞于 mssql-python#649）。资料来源：[src/fabric_dw/sql.py:1-1]() --- ## MCP 服务器、工具与 AI 集成 ### 相关页面 相关主题：[CLI 命令参考（按域分组）](#page-2), [内部架构、部署、遥测与安全](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/fabric_dw/mcp/server.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/mcp/server.py) - [src/fabric_dw/mcp/_context.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/mcp/_context.py) - [src/fabric_dw/mcp/_guards.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/mcp/_guards.py) - [src/fabric_dw/mcp/_helpers.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/mcp/_helpers.py) - [src/fabric_dw/mcp/tools/__init__.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/mcp/tools/__init__.py) - [src/fabric_dw/mcp/tools/sql_exec.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/mcp/tools/sql_exec.py)
# MCP 服务器、工具与 AI 集成 ## 概述 fabric-dw-mcp-cli 通过 Model Context Protocol (MCP) 把 Microsoft Fabric Data Warehouse 的能力暴露给 AI 客户端，让模型以"调用工具"的方式与仓库交互，而不是直接拼接 SQL。MCP 服务器在 20 个业务领域下共暴露 118 个专用工具，并保留一个通用回退通道 `execute_sql` 供模型执行任意 SQL。自 v2026.7.1 起，服务器在初始化阶段会下发一段 server instructions，主动引导模型优先使用专用工具，从而减少 `execute_sql` 的滥用（参见 issue #984、#985）。 ```mermaid flowchart LR A[MCP Client
AI Agent] -->|Initialize| B[server.py
server instructions] B --> C[tools/__init__.py
118 tools / 20 domains] B --> D[_guards.py
drift guard / checks] C --> E[sql_exec.py
execute_sql] C --> F[_helpers.py
shared utilities] G[_context.py
deps injection] --> C G --> E D -.验证.-> C ``` ## 服务器入口与启动 `src/fabric_dw/mcp/server.py` 是 MCP 服务器的入口模块。它负责装配 FastMCP 实例、加载工具模块、并在初始化阶段构建 server instructions 文本，写入 MCP 的 `InitializeResult.instructions` 字段，客户端在模型介入之前就能读到这段内容 资料来源：[src/fabric_dw/mcp/server.py:1-120]()。 instructions 文本列举了若干核心领域中具有代表性的工具，但目前只覆盖 118 个工具中的 18 个（issue #992）。社区正推动补齐剩余领域的命名，并通过 `_guards.py` 中的 drift guard 保证：instructions 中提到的每一个工具都必须在工具注册表中真实存在，避免"说一套、做一套"的漂移 资料来源：[src/fabric_dw/mcp/_guards.py:1-80]()。 `.mcp.json` 通过 `uvx --prerelease allow --from fabric-dw@latest fabric-dw-mcp` 启动服务器（issue #995）。注意 `httpx` 必须低于 2.0，否则会因为解析 `httpx==1.0.dev3` 等开发版而启动失败 资料来源：[src/fabric_dw/mcp/server.py:120-180]()。 ## 工具组织与领域划分 `src/fabric_dw/mcp/tools/__init__.py` 聚合所有工具模块，按业务领域（tables、warehouses、sql_pools、jobs、items 等 20 个）组织。每个领域对应一组相关资源操作。`__init__.py` 在导入阶段遍历这些模块，把工具装饰器统一注册到全局 MCP 实例，使它们对外以 118 个独立 tool 出现 资料来源：[src/fabric_dw/mcp/tools/__init__.py:1-90]()。 工具名称遵循统一的"动词-名词"约定（如 `list_tables`、`drop_table`、`count_rows`），便于模型按语义匹配。`src/fabric_dw/mcp/tools/sql_exec.py` 实现了唯一的通用入口 `execute_sql` 资料来源：[src/fabric_dw/mcp/tools/sql_exec.py:1-80]()。该工具仍受 server instructions 引导：当存在专用工具时，模型应避免直接执行裸 SQL。 ## 上下文、守卫与共享助手 `src/fabric_dw/mcp/_context.py` 封装一次 MCP 请求可用的依赖（认证 token、Fabric 客户端、当前工作区句柄等），通过 `ContextVar` 在工具调用链中注入 资料来源：[src/fabric_dw/mcp/_context.py:1-60]()。这样工具函数只关心业务逻辑，不必各自管理会话状态。 `src/fabric_dw/mcp/_guards.py` 提供多种前置校验： - **drift guard**：在测试或启动时验证 instructions 中提到的工具是否都已注册（issue #992）； - **仓库存在性检查**：在 SQL 工具被调用前确认目标 warehouse 可用，关联 issue #994 中 `tests/integration/test_services_sql_pools.py` 的 500 错误； - **连接 program_name**：尝试把 mssql-python 驱动默认的 `MSSQL-Python` 程序名改为 `fdw.debruyn.dev`，提升 `sys.dm_exec_sessions` 与 query history 的可识别性（blocked on mssql-python#649，issue #892）。 `src/fabric_dw/mcp/_helpers.py` 提供跨工具复用的辅助函数，例如分页、结果格式化、错误包装、连接字符串拼装 资料来源：[src/fabric_dw/mcp/_helpers.py:1-100]()。`sql_exec.py` 与专用工具都通过这些 helper 统一输出结构，使模型拿到的响应保持一致。 ## AI 引导与遥测 server instructions 的核心目标，是把模型从"什么都用 `execute_sql`"扭转为"先找专用工具"。instructions 文本中显式提示：列举表、删除表、统计行数等任务应优先调用专用工具，`execute_sql` 仅在无法表达时使用 资料来源：[src/fabric_dw/mcp/server.py:60-120]()。 issue #985 正在追踪这一引导的实际效果：需要真实环境遥测才能判断 `execute_sql` 的调用率是否下降，因此目前仅观察、不实现自动化变更。issue #992 进一步要求把剩余领域也写进 instructions，使覆盖范围从 18/118 扩展到接近完整，并通过 `_guards.py` 的 drift guard 保证一致性。 --- ## 内部架构、部署、遥测与安全 ### 相关页面 相关主题：[项目概述、安装与认证](#page-1), [CLI 命令参考（按域分组）](#page-2), [MCP 服务器、工具与 AI 集成](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/fabric_dw/_fabric_api.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/_fabric_api.py) - [src/fabric_dw/http_client.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/http_client.py) - [src/fabric_dw/sql.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/sql.py) - [src/fabric_dw/mcp_server.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/mcp_server.py) - [src/fabric_dw/mcp_instructions.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/mcp_instructions.py) - [src/fabric_dw/cli.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/cli.py) - [src/fabric_dw/config.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/config.py) - [pyproject.toml](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/pyproject.toml) - [uv.lock](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/uv.lock)
# 内部架构、部署、遥测与安全 本文档说明 `fabric-dw-mcp-cli` 的内部模块划分、MCP 服务的部署链路、当前遥测相关的设计意图，以及认证与连接字符串层面的安全考虑。 ## 一、内部架构概览 项目以 Click CLI 为入口，在 `src/fabric_dw/cli.py` 中注册子命令；当用户调用 `fabric-dw-mcp` 时，CLI 转入 MCP server 引导流程。`mcp_server.py` 负责把业务层（`_fabric_api.py` 提供的 REST 调用、`sql.py` 提供的 T-SQL 执行、`sql_pool.py` 提供的连接池管理）以工具形式暴露给模型客户端。 `http_client.py` 统一封装了对 Fabric / Synapse 后端的 HTTP 调用，复用同一个带重试和超时设置的客户端，从而保证 118 个跨 20 个领域的工具有一致的错误处理与链路。SQL 侧的 `sql.py`、`sql_io.py`、`sql_errors.py` 共同构成"执行 → 格式化结果 → 错误归类"的流水线，CLI 与 MCP 两端复用。 | 层 | 主要文件 | 职责 | |---|---|---| | CLI / 入口 | `cli.py`、`config.py` | 命令解析、默认值、用户配置文件 | | MCP 协议层 | `mcp_server.py`、`mcp_instructions.py` | 工具注册、`InitializeResult.serverInstructions` 输出 | | 业务逻辑层 | `_fabric_api.py`、`sql.py`、`sql_pool.py` | REST API、T-SQL、连接池 | | 通用基座 | `http_client.py`、`sql_errors.py` | HTTP 客户端、错误归类 | 资料来源：[src/fabric_dw/mcp_server.py:1-1]() [src/fabric_dw/cli.py:1-1]() [src/fabric_dw/_fabric_api.py:1-1]()。 ## 二、部署链路 部署围绕 `pyproject.toml` 与 `uv.lock` 展开。CLI 与 MCP server 都通过 `uvx` 从 `fabric-dw@latest` 拉取并直接运行；`.mcp.json` 客户端的典型启动命令是 `uvx --prerelease allow --from fabric-dw@latest fabric-dw-mcp`（资料来源：[issue #995]()）。 CI 侧使用 GitHub Actions 流水线，并以 `uv sync --locked` 在所有 job 中强制断言 lockfile 与 `pyproject.toml` 的一致性（资料来源：[issue #988]() [issue #990]()）。`server.json` 在稳定 tag 推送时与版本号同步（资料来源：[v2026.7.1rc1 PR #977]()）。预发布包安装时对 `httpx` 版本进行了封顶约束（`<2.0`），以避免 `httpx==1.0.dev3` 之类的解析失败（资料来源：[issue #995]()）。 ```mermaid flowchart LR A[pyproject.toml] --> B[uv.lock] B --> C[uvx --prerelease allow] C --> D[fabric-dw-mcp 入口] D --> E[mcp_server.py] E --> F[118 个工具 / 20 个领域] ``` ## 三、遥测与可观测性设计意图 MCP 服务在 `mcp_instructions.py` 中维护一段服务器级说明文本，作为 `InitializeResult.serverInstructions` 在客户端握手阶段下发，从而在模型首次行动前"先教育"模型优先选择专用工具而非 `execute_sql`（资料来源：[issue #984]() [issue #986]()）。该说明只覆盖 18/118 个工具，已知仍存在领域命名缺漏（资料来源：[issue #992]()）。 针对 `execute_sql` 的过度使用，仓库仅在 issue 层面建立了追踪，**未在代码中实现真正的遥测上报**（资料来源：[issue #985]()）。SQL 侧曾尝试在连接字符串中写入 `program_name = "fdw.debruyn.dev"`，但被 `mssql-python#649` 阻塞，当前所有来自本工具的查询在 `sys.dm_exec_sessions` 中仍以 `MSSQL-Python` 呈现（资料来源：[issue #892]()）。 ## 四、安全与认证 连接构建集中在 `sql.py` 的 `build_connection_string`，它在 Fabric 返回的基础连接串上追加 `Authentication=` 等键，再交给 `mssql-python` 驱动；该流程也是 `program_name` 设置唯一入口（资料来源：[src/fabric_dw/sql.py:1-1]() [issue #892]()）。HTTP 认证与 token 刷新由 `http_client.py` 与 `_fabric_api.py` 配合处理，避免在调用点散落凭据。`config.py` 负责读取用户配置文件中的默认值，从而让 61 个存在"前导可选 ITEM"问题的命令的短形式调用能够找到 fallback（资料来源：[issue #981]() [issue #982]()）。 集成测试方面，`tests/integration/test_services_sql_pools.py` 在空 workspace 上会因端点 500 而失败，社区已通过"先确保 warehouse 存在"的策略准备修复（资料来源：[issue #994]()）。 --- --- ## Doramagic 踩坑日志 项目：sdebruyn/fabric-dw-mcp-cli 摘要：发现 34 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: Track: measure execute_sql overuse after the MCP instructions block (needs telemetry)。 ## 1. 安全/权限坑 · 失败模式：security_permissions: Track: measure execute_sql overuse after the MCP instructions block (needs telemetry) - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: Track: measure execute_sql overuse after the MCP instructions block (needs telemetry) - 对用户的影响：Developers may expose sensitive permissions or credentials: Track: measure execute_sql overuse after the MCP instructions block (needs telemetry) - 证据：failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/985 | Track: measure execute_sql overuse after the MCP instructions block (needs telemetry) ## 2. 安全/权限坑 · 失败模式：security_permissions: feat(mcp): add server instructions and steer execute_sql toward dedicated tools - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: feat(mcp): add server instructions and steer execute_sql toward dedicated tools - 对用户的影响：Developers may expose sensitive permissions or credentials: feat(mcp): add server instructions and steer execute_sql toward dedicated tools - 证据：failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/984 | feat(mcp): add server instructions and steer execute_sql toward dedicated tools ## 3. 安全/权限坑 · 失败模式：security_permissions: feat(mcp): name the remaining tool domains in the server instructions - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: feat(mcp): name the remaining tool domains in the server instructions - 对用户的影响：Developers may expose sensitive permissions or credentials: feat(mcp): name the remaining tool domains in the server instructions - 证据：failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/992 | feat(mcp): name the remaining tool domains in the server instructions ## 4. 安全/权限坑 · 失败模式：security_permissions: fix(cli): leading optional ITEM positional swallows the first required argument - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: fix(cli): leading optional ITEM positional swallows the first required argument - 对用户的影响：Developers may expose sensitive permissions or credentials: fix(cli): leading optional ITEM positional swallows the first required argument - 证据：failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/981 | fix(cli): leading optional ITEM positional swallows the first required argument ## 5. 安全/权限坑 · 来源证据：Track: set SQL connection program_name to fdw.debruyn.dev (blocked on mssql-python#649) - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Track: set SQL connection program_name to fdw.debruyn.dev (blocked on mssql-python#649) - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/892 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 6. 身份坑 · 仓库名和安装名不一致 - 严重度：medium - 证据强度：runtime_trace - 发现：仓库名 `fabric-dw-mcp-cli` 与安装入口 `fabric-dw` 不完全一致。 - 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 - 复现命令：`pip install fabric-dw` - 证据：identity.distribution | https://github.com/sdebruyn/fabric-dw-mcp-cli | repo=fabric-dw-mcp-cli; install=fabric-dw ## 7. 安装坑 · 失败模式：installation: fix(ci): replace uv sync --frozen with --locked in remaining workflows - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: fix(ci): replace uv sync --frozen with --locked in remaining workflows - 对用户的影响：Developers may fail before the first successful local run: fix(ci): replace uv sync --frozen with --locked in remaining workflows - 证据：failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/990 | fix(ci): replace uv sync --frozen with --locked in remaining workflows ## 8. 安装坑 · 失败模式：installation: fix(ci): uv.lock is out of sync with pyproject.toml, and nothing detects it - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: fix(ci): uv.lock is out of sync with pyproject.toml, and nothing detects it - 对用户的影响：Developers may fail before the first successful local run: fix(ci): uv.lock is out of sync with pyproject.toml, and nothing detects it - 证据：failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/988 | fix(ci): uv.lock is out of sync with pyproject.toml, and nothing detects it ## 9. 安装坑 · 失败模式：installation: fix(deps): cap httpx below 2.0 so the pre-release build is installable - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: fix(deps): cap httpx below 2.0 so the pre-release build is installable - 对用户的影响：Developers may fail before the first successful local run: fix(deps): cap httpx below 2.0 so the pre-release build is installable - 证据：failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/995 | fix(deps): cap httpx below 2.0 so the pre-release build is installable ## 10. 安装坑 · 失败模式：installation: test(integration): add an end-to-end journey smoke test exercising config defaults - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: test(integration): add an end-to-end journey smoke test exercising config defaults - 对用户的影响：Developers may fail before the first successful local run: test(integration): add an end-to-end journey smoke test exercising config defaults - 证据：failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/982 | test(integration): add an end-to-end journey smoke test exercising config defaults ## 11. 安装坑 · 失败模式：installation: v2026.7.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v2026.7.0 - 对用户的影响：Upgrade or migration may change expected behavior: v2026.7.0 - 证据：failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.7.0 | v2026.7.0 ## 12. 安装坑 · 失败模式：installation: v2026.7.1 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v2026.7.1 - 对用户的影响：Upgrade or migration may change expected behavior: v2026.7.1 - 证据：failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.7.1 | v2026.7.1 ## 13. 安装坑 · 失败模式：installation: v2026.7.1rc1 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v2026.7.1rc1 - 对用户的影响：Upgrade or migration may change expected behavior: v2026.7.1rc1 - 证据：failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.7.1rc1 | v2026.7.1rc1 ## 14. 安装坑 · 来源证据：fix(ci): uv.lock is out of sync with pyproject.toml, and nothing detects it - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(ci): uv.lock is out of sync with pyproject.toml, and nothing detects it - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/988 | 来源类型 github_issue 暴露的待验证使用条件。 ## 15. 安装坑 · 来源证据：fix(deps): cap httpx below 2.0 so the pre-release build is installable - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(deps): cap httpx below 2.0 so the pre-release build is installable - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/995 | 来源类型 github_issue 暴露的待验证使用条件。 ## 16. 安装坑 · 来源证据：test(integration): add an end-to-end journey smoke test exercising config defaults - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：test(integration): add an end-to-end journey smoke test exercising config defaults - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/982 | 来源类型 github_issue 暴露的待验证使用条件。 ## 17. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/sdebruyn/fabric-dw-mcp-cli | host_targets=mcp_host, claude ## 18. 配置坑 · 失败模式：configuration: Track: set SQL connection program_name to fdw.debruyn.dev (blocked on mssql-python#649) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Track: set SQL connection program_name to fdw.debruyn.dev (blocked on mssql-python#649) - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Track: set SQL connection program_name to fdw.debruyn.dev (blocked on mssql-python#649) - 证据：failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/892 | Track: set SQL connection program_name to fdw.debruyn.dev (blocked on mssql-python#649) ## 19. 配置坑 · 失败模式：configuration: fix(test): sql_pools integration tests must ensure a warehouse exists (endpoint 500s on empty... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: fix(test): sql_pools integration tests must ensure a warehouse exists (endpoint 500s on empty workspace) - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: fix(test): sql_pools integration tests must ensure a warehouse exists (endpoint 500s on empty workspace) - 证据：failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/994 | fix(test): sql_pools integration tests must ensure a warehouse exists (endpoint 500s on empty workspace) ## 20. 配置坑 · 失败模式：configuration: v2026.6.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v2026.6.0 - 对用户的影响：Upgrade or migration may change expected behavior: v2026.6.0 - 证据：failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.6.0 | v2026.6.0 ## 21. 配置坑 · 失败模式：configuration: v2026.6.0rc0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v2026.6.0rc0 - 对用户的影响：Upgrade or migration may change expected behavior: v2026.6.0rc0 - 证据：failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.6.0rc0 | v2026.6.0rc0 ## 22. 配置坑 · 失败模式：configuration: v2026.6.0rc2 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v2026.6.0rc2 - 对用户的影响：Upgrade or migration may change expected behavior: v2026.6.0rc2 - 证据：failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.6.0rc2 | v2026.6.0rc2 ## 23. 配置坑 · 来源证据：fix(test): sql_pools integration tests must ensure a warehouse exists (endpoint 500s on empty workspace) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：fix(test): sql_pools integration tests must ensure a warehouse exists (endpoint 500s on empty workspace) - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/994 | 来源类型 github_issue 暴露的待验证使用条件。 ## 24. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/sdebruyn/fabric-dw-mcp-cli | README/documentation is current enough for a first validation pass. ## 25. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/sdebruyn/fabric-dw-mcp-cli | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/sdebruyn/fabric-dw-mcp-cli | no_demo; severity=medium ## 27. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/sdebruyn/fabric-dw-mcp-cli | no_demo; severity=medium ## 28. 安全/权限坑 · 来源证据：Track: measure execute_sql overuse after the MCP instructions block (needs telemetry) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Track: measure execute_sql overuse after the MCP instructions block (needs telemetry) - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/985 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 29. 安全/权限坑 · 来源证据：feat(mcp): add server instructions and steer execute_sql toward dedicated tools - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(mcp): add server instructions and steer execute_sql toward dedicated tools - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/984 | 来源类型 github_issue 暴露的待验证使用条件。 ## 30. 安全/权限坑 · 来源证据：feat(mcp): name the remaining tool domains in the server instructions - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(mcp): name the remaining tool domains in the server instructions - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/992 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 31. 安全/权限坑 · 来源证据：fix(ci): replace uv sync --frozen with --locked in remaining workflows - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：fix(ci): replace uv sync --frozen with --locked in remaining workflows - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/990 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 32. 安全/权限坑 · 来源证据：fix(cli): leading optional ITEM positional swallows the first required argument - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：fix(cli): leading optional ITEM positional swallows the first required argument - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/981 | 来源类型 github_issue 暴露的待验证使用条件。 ## 33. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/sdebruyn/fabric-dw-mcp-cli | issue_or_pr_quality=unknown ## 34. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/sdebruyn/fabric-dw-mcp-cli | release_recency=unknown