项目概述

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 作为推荐的运行与依赖管理工具。安装入口在 pyproject.toml 中声明，包含 fabric-dw、fabric-dw-mcp 等可执行入口 资料来源：pyproject.toml:1-50。

最简安装与运行方式是借助 uvx 启动预发布版本（这也是 .mcp.json 默认采用的方式）：

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 单独使用可以直接：

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。

典型的认证流程如下：

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 解决 资料来源：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。

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 工具域保持一致，按业务域聚合。下表列出常见域及其典型命令：

每个域在 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 <item> 的短形式调用会被 Click 把 <item> 错误填入 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

概述

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）。

flowchart LR
    A[MCP Client<br/>AI Agent] -->|Initialize| B[server.py<br/>server instructions]
    B --> C[tools/__init__.py<br/>118 tools / 20 domains]
    B --> D[_guards.py<br/>drift guard / checks]
    C --> E[sql_exec.py<br/>execute_sql]
    C --> F[_helpers.py<br/>shared utilities]
    G[_context.py<br/>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 保证一致性。

一、内部架构概览

项目以 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 两端复用。

资料来源：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）。

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）。

Pitfall Log / 踩坑日志

项目：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