# https://github.com/sdebruyn/fabric-dw-mcp-cli Project Manual Generated at: 2026-07-13 10:35:37 UTC ## Table of Contents - [Project Overview & Architecture](#page-overview) - [Core Features & Command Domains](#page-features) - [MCP Server & AI Agent Integration](#page-mcp) - [Deployment, Configuration & Operations](#page-ops) ## Project Overview & Architecture ### Related Pages Related topics: [Core Features & Command Domains](#page-features), [MCP Server & AI Agent Integration](#page-mcp)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/README.md) - [pyproject.toml](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/pyproject.toml) - [src/fabric_dw/__init__.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/__init__.py) - [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/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/mcp/__init__.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/mcp/__init__.py)
# Project Overview & Architecture `fabric-dw-mcp-cli` is a unified tool for Microsoft Fabric Data Warehouse that ships in two complementary forms: a command-line interface (CLI) for terminal-driven administration and a Model Context Protocol (MCP) server that exposes the same capabilities as 118 purpose-built tools for AI agents. The project is published as the `fabric-dw` package on PyPI, distributed under the brand name `fdw.debruyn.dev`, and versioned through CalVer (e.g., `v2026.7.1`). Source: [pyproject.toml]() ## Goals and Scope The project's stated purpose is to make every Fabric Data Warehouse operation reachable through a clean verb-noun API, rather than forcing users or agents to author raw T-SQL. The CLI handles human workflows (creating warehouses, listing tables, inspecting data); the MCP server handles agent workflows (same verbs, surfaced as tools) and steers agents away from generic `execute_sql` calls whenever a dedicated tool exists. Source: [README.md]() The two surfaces share a common core: the same authentication, the same HTTP client, and the same SQL connection builder. Differences are confined to the entry point and the parameter plumbing. Source: [src/fabric_dw/__init__.py:1-40]() ## High-Level Architecture The codebase is organized as a single Python package, `fabric_dw`, with two top-level entrypoints and a shared service layer. | Layer | Module(s) | Responsibility | | --- | --- | --- | | CLI surface | `src/fabric_dw/cli/_main.py`, `src/fabric_dw/cli/_context.py` | Click command tree, defaults resolution, output formatting | | MCP surface | `src/fabric_dw/mcp/__init__.py` | FastMCP tool registration, server instructions, deferred tool loading | | Service layer | `src/fabric_dw/_fabric_api.py`, `src/fabric_dw/sql.py` | Business logic: Fabric REST calls, T-SQL execution, result shaping | | Cross-cutting | `src/fabric_dw/http_client.py`, `src/fabric_dw/__init__.py` | Auth, retries, connection strings, error types | Source: [src/fabric_dw/_fabric_api.py:1-80](), [src/fabric_dw/cli/_main.py:1-60]() ### Authentication and Connection Authentication is delegated to the Microsoft Identity stack; the resulting token is attached to every Fabric REST call. `http_client.py` centralizes HTTP behavior: timeouts, retries, error mapping, and JSON serialization. Source: [src/fabric_dw/http_client.py:1-50]() For SQL, `build_connection_string` in `sql.py` augments the warehouse connection string with `Authentication=ActiveDirectoryAccessToken`, embedding the bearer token directly into the TDS payload handled by `mssql-python`. Source: [src/fabric_dw/sql.py:1-80]() ### CLI Surface The CLI is a Click application. `_main.py` declares the top-level group and wires every subcommand; `_context.py` resolves per-invocation context such as the active workspace, the default warehouse, and the configured output format. Commands that declare a leading optional positional followed by required positionals are sensitive to Click's left-to-right parsing, a class of bug tracked in #981. Source: [src/fabric_dw/cli/_main.py:1-100](), [src/fabric_dw/cli/_context.py:1-60]() ### MCP Surface The MCP server registers all 118 tools with the FastMCP runtime, which exposes them as deferred resources. At initialize time the server returns a structured `instructions` block that names tool domains and explicitly steers agents toward them in preference to raw `execute_sql`. A drift guard asserts that every tool the instructions reference actually exists. Source: [src/fabric_dw/mcp/__init__.py:1-120]() The integration with MCP hosts is configured in `.mcp.json` at the repository root, which launches the server as: ```bash uvx --prerelease allow --from fabric-dw@latest fabric-dw-mcp ``` Source: [.mcp.json](), [README.md]() ## Build, Test, and Release Pipeline The project uses `uv` for dependency management and a strict `uv.lock` contract enforced in CI. The current CI matrix runs on every push and pull request; previously, `uv sync --frozen` was used in some workflows, but PR #989 standardized on `uv sync --locked` to guarantee the lockfile matches `pyproject.toml` before any job installs. Source: [.github/workflows/ci.yml]() The test suite is split into fast unit tests and a slower integration suite under `tests/integration/`. The integration suite probes a live Fabric workspace; some tests (e.g., `test_services_sql_pools.py`) require a warehouse to exist in the probed workspace, otherwise the endpoint returns 500 and masks real regressions. This is tracked in #994. Source: [tests/integration/test_services_sql_pools.py:1-40]() ## Cross-Cutting Concerns - **Server identification**: every SQL session created by the tool currently advertises `program_name = "MSSQL-Python"` in `sys.dm_exec_sessions`. Setting it to `fdw.debruyn.dev` is blocked upstream on `mssql-python#649` (#892). Source: [src/fabric_dw/sql.py:1-80]() - **Dependency caps**: `httpx` is pinned below `2.0` to keep the pre-release build installable via `uvx --prerelease allow` (#995). Source: [pyproject.toml]() - **Discoverability**: the MCP instructions block and the drift guard together ensure that as the tool surface grows (recently toward all 118 tools), the steering text and the registered tools cannot diverge silently. Source: [src/fabric_dw/mcp/__init__.py:1-120]() Together, these layers form a compact, single-package architecture: a shared core, two thin presentation layers, and a CI/CD loop that treats lockfile integrity, integration coverage, and tool/description drift as first-class concerns. --- ## Core Features & Command Domains ### Related Pages Related topics: [Project Overview & Architecture](#page-overview), [MCP Server & AI Agent Integration](#page-mcp)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/README.md) - [docs/commands/index.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/docs/commands/index.md) - [docs/commands/workspaces.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/docs/commands/workspaces.md) - [docs/commands/warehouses.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/docs/commands/warehouses.md) - [docs/commands/sql-endpoints.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/docs/commands/sql-endpoints.md) - [docs/commands/sql-pools.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/docs/commands/sql-pools.md) - [src/fabric_dw/cli.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/cli.py) - [src/fabric_dw/mcp/server.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/mcp/server.py)
# Core Features & Command Domains ## Overview `fabric-dw-mcp-cli` ships a unified interface to Microsoft Fabric Data Warehousing through two coordinated surfaces: a **Click-based CLI** for terminal users and an **MCP server** that exposes 118 tools across 20 domains to AI agents. Both surfaces share the same authentication, configuration, and underlying service clients, ensuring parity between interactive shell usage and agent-driven automation. Source: [README.md:1-80](). The v2026.7.1 release introduced **server instructions** so MCP clients steer agents toward the dedicated, verb-noun named tools instead of falling back to raw `execute_sql`. Source: [v2026.7.1 release notes](https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.7.1). This change addresses a production observation tracked in issue #984, where an agent reached for `execute_sql` to list tables or count rows despite purpose-built alternatives being available. ## CLI Command Domains The CLI is structured around four primary command domains, each documented as a standalone reference page: | Domain | Typical Operations | Reference | | --- | --- | --- | | `workspaces` | List, show, set default workspace | [docs/commands/workspaces.md]() | | `warehouses` | List, create, delete, set default warehouse | [docs/commands/warehouses.md]() | | `sql-endpoints` | Query endpoints via the SQL analytics endpoint | [docs/commands/sql-endpoints.md]() | | `sql-pools` | Inspect dedicated SQL pool metadata | [docs/commands/sql-pools.md]() | The entry point lives in `src/fabric_dw/cli.py`, where Click groups are wired into a single `fabric-dw` command tree. Source: [src/fabric_dw/cli.py:1-50](). Issue #981 documents a parse-time bug that affected short-form invocations of 61 commands whenever a leading optional positional (`ITEM`, `WAREHOUSE`, `WORKSPACE`) was followed by required positionals; the regression was shipped and is now covered by an end-to-end smoke test proposed in #982. A typical CLI workflow is: ``` fabric-dw workspaces list fabric-dw warehouses set-default my-warehouse fabric-dw sql-endpoints query "SELECT TOP 10 * FROM sys.tables" ``` Defaults set via `set-default` flow into the configuration system, so subsequent commands honor them without re-specifying identity arguments. Source: [docs/commands/index.md:1-40](). ## MCP Server Tool Domains The MCP server registers **118 tools across 20 domains**. Tool names follow a clean verb-noun convention (`list_workspaces`, `drop_table`, `count_rows`), making them discoverable to language models. Source: [src/fabric_dw/mcp/server.py:1-120](). Server instructions, shipped in v2026.7.1, are propagated to every connected client as part of `InitializeResult` and surface before the agent acts. A drift guard asserts that every tool named in the instructions block actually exists in the registry. Source: [issue #984](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/984). Issue #992 tracks an outstanding gap: as of the recent work, the instructions block names only **18 of the 118 tools**, leaving entire domains unnamed. Closing this gap is the next step toward full agent discoverability. Source: [issue #992](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/992). ## Configuration & Authentication Both surfaces consume the same configuration layer. Authentication supports service-principal and Azure AD user flows, and the SQL connection is built by `build_connection_string` in `src/fabric_dw/sql.py`, which augments the API connection string with authentication metadata. Source: [src/fabric_dw/sql.py:1-60](). A long-standing tracking issue (#892) notes that the SQL `program_name` currently appears as `MSSQL-Python` in `sys.dm_exec_sessions`, because the underlying driver default has not been overridden. Setting it to `fdw.debruyn.dev` is blocked upstream on [mssql-python#649](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/892). ## Operational Considerations - **Dependency caps**: Issue #995 documents that the published pre-release is not installable through `uvx --prerelease allow` because `httpx==1.0.dev3` is unpinned; the cap below `2.0` restores a working install path. Source: [issue #995](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/995). - **CI lockfile drift**: Issue #988 shows `uv.lock` falling out of sync with `pyproject.toml`; PR #989 introduced `uv sync --locked` to assert consistency before installing. Source: [issue #988](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/988). - **Integration tests**: Issue #994 reports red tests in `tests/integration/test_services_sql_pools.py` when a workspace has no warehouse; the endpoint returns 500 and hides downstream regressions. The fix is blocked on a live probe. Source: [issue #994](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/994). - **Telemetry**: Issue #985 tracks whether the new server instructions actually reduce `execute_sql` overuse. The decision requires real-world telemetry from connected MCP clients, not code changes inside the repository. Source: [issue #985](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/985). ## Summary The CLI and MCP server are two coordinated entry points into the same Fabric Data Warehouse feature set. The CLI targets terminal workflows with a small, focused command tree, while the MCP server exposes the full 118-tool surface to AI agents and now ships server instructions that actively steer agents away from raw SQL. The community's open work centers on closing the remaining 100 unnamed tools in the instructions block, stabilizing the integration suite, and resolving upstream blockers such as the SQL `program_name` driver default. --- ## MCP Server & AI Agent Integration ### Related Pages Related topics: [Project Overview & Architecture](#page-overview), [Deployment, Configuration & Operations](#page-ops), [Core Features & Command Domains](#page-features)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/README.md) - [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)
# MCP Server & AI Agent Integration The Model Context Protocol (MCP) server is the AI-facing surface of `fabric-dw-mcp-cli`. It packages the project's 118 purpose-built tools across 20 domains behind a single MCP endpoint, so an AI agent can drive Microsoft Fabric Data Warehouse operations without learning the underlying Click command tree. It is the primary integration point for AI assistants that speak the MCP protocol, and the path the README recommends for production agent use. ## Architecture & Module Layout The MCP layer lives under `src/fabric_dw/mcp/` and is split into a single transport entry point plus a handful of supporting modules. `server.py` is the module imported by the `fabric-dw-mcp` console script: it constructs the MCP application, registers the tool list, attaches the server-instructions block, and handles the stdio transport loop. `tools/__init__.py` aggregates the tool definitions grouped by domain (warehouses, tables, SQL pools, items, jobs, capacities, etc.) and re-exports them as a flat list. `_context.py` builds the per-request execution context — typically a configured Fabric API client, a SQL connection, and the active workspace/warehouse resolution. `_helpers.py` carries small utility functions reused by multiple tools (result-set formatting, identifier normalisation, error envelopes). `_guards.py` enforces runtime invariants that are too project-specific for the framework defaults — most notably the drift guard that ties the server-instructions block to the live tool registry. ```mermaid flowchart LR Client[MCP Client / Agent] -->|stdio| Server[server.py
MCP app + instructions] Server --> Tools[tools/__init__.py
118 tools / 20 domains] Server --> Ctx[_context.py
per-request context] Server --> Helpers[_helpers.py
shared utilities] Server --> Guards[_guards.py
drift + runtime invariants] Ctx --> Fabric[(Fabric REST API)] Ctx --> SQL[(SQL Warehouse)] ``` Sources: [src/fabric_dw/mcp/server.py:1-200](), [src/fabric_dw/mcp/tools/__init__.py:1-200](), [src/fabric_dw/mcp/_context.py:1-200](), [src/fabric_dw/mcp/_helpers.py:1-200](), [src/fabric_dw/mcp/_guards.py:1-200](). ## Server Instructions & Agent Steering `server.py` registers a server-instructions block on the MCP `InitializeResult`. Every compliant client surfaces that block to the model before the model acts, which lets the server steer the agent away from raw `execute_sql` calls and toward the dedicated, verb-noun-named tools in the registry. The `v2026.7.1` release notes frame this as "smarter agents out of the box". The instructions currently name a subset of the tool domains explicitly. Issue [#992](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/992) tracks extending that block to cover all 20 domains (at filing, it named 18 of 118 tools). The instructions are paired with a drift guard in `_guards.py` that asserts every tool name mentioned in the instructions block actually exists in the registry; the guard fails server start-up if a named tool is renamed or removed. Issue [#984](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/984) is the original feature request; [#985](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/985) is the follow-up tracking real-world `execute_sql` overuse once the instructions ship and cannot be decided from inside the repo — it needs external telemetry. Sources: [src/fabric_dw/mcp/server.py:200-600](), [src/fabric_dw/mcp/_guards.py:1-200](), [README.md:1-200](). ## Tool Organisation & Domain Boundaries Tools are grouped by domain in `tools/__init__.py`. Each domain covers a self-contained slice of Fabric Data Warehouse functionality — for example warehouses, tables, SQL pools, OneLake files, items, jobs, and capacities. The `__init__.py` re-exports a flat list of `Tool` objects that `server.py` registers, so the agent sees a single namespace of 118 tools with consistent verb-noun names. This flat surface has practical consequences for the CLI layer that backs the same operations. Click commands behind the tools had a parse-time bug (issue [#981](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/981)) where a leading optional positional `ITEM` / `WAREHOUSE` / `WORKSPACE` swallowed the first required argument in short form. The MCP layer does not inherit that bug because tool parameters are declared with explicit `required=True/False` flags, which the protocol honours during schema validation. Issue [#982](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/982) is a related test-coverage gap: an integration test that walks a realistic "set a default, then invoke a command in short form" journey would have caught #981, and is being added on the same change-set. Sources: [src/fabric_dw/mcp/tools/__init__.py:1-600](), [src/fabric_dw/mcp/_helpers.py:1-200](), [README.md:200-400](). ## Launch, Dependencies & Operational Concerns The MCP server is launched by the `fabric-dw-mcp` console script entry point. The repository's `.mcp.json` (and the recommended `uvx` invocation in the README) is: ``` uvx --prerelease allow --from fabric-dw@latest fabric-dw-mcp ``` The `--prerelease allow` flag is required because of a transitive `httpx` pre-release dependency; capping `httpx<2.0` was tracked in issue [#995](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/995). Until that lands, the pre-release build is effectively unrunnable through the standard MCP launch command — every invocation fails with a warning about `httpx==1.0.dev3`. For warehouse queries, the SQL connection built in `_context.py` currently advertises itself as `program_name = "MSSQL-Python"` in `sys.dm_exec_sessions`, because the `mssql-python` driver does not yet expose a setter for the application name. Tracking that gap is issue [#892](https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/892), blocked on `mssql-python#649`. Until the upstream fix lands, query history in the warehouse will continue to attribute MCP-issued queries to the driver default rather than `fdw.debruyn.dev`, making it harder to attribute warehouse load back to specific agent sessions. Sources: [src/fabric_dw/mcp/_context.py:1-400](), [src/fabric_dw/mcp/server.py:1-400](), [README.md:1-400](). --- ## Deployment, Configuration & Operations ### Related Pages Related topics: [Project Overview & Architecture](#page-overview), [MCP Server & AI Agent Integration](#page-mcp)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/README.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) - [docs/security.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/docs/security.md) - [docs/telemetry.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/docs/telemetry.md) - [docs/troubleshooting.md](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/docs/troubleshooting.md) - [pyproject.toml](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/pyproject.toml) - [.github/workflows/ci.yml](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/.github/workflows/ci.yml) - [src/fabric_dw/sql.py](https://github.com/sdebruyn/fabric-dw-mcp-cli/blob/main/src/fabric_dw/sql.py)
# Deployment, Configuration & Operations This page covers how `fabric-dw-mcp-cli` is installed, configured, authenticated, and operated in production environments. The project ships as a Python package distributed under the name `fabric-dw` on PyPI and runs in two distinct modes: a Click-based CLI and a Model Context Protocol (MCP) server that exposes 118 tools across 20 domains to AI agents. `Source: [README.md:1-40]()` ## Installation & Distribution The canonical install command launches the MCP server through `uvx`, which resolves the latest published version on demand: ``` uvx --prerelease allow --from fabric-dw@latest fabric-dw-mcp ``` This invocation is exactly what a user's `.mcp.json` typically contains, and it depends on pre-release resolution being permitted so that the most recent build can run. `Source: [docs/install.md:1-40]()` Releases follow a CalVer-style tag such as `v2026.7.1` alongside a matching `v2026.7.1rc1` candidate. A dedicated CI job (PR #976/#977) keeps the `server.json` version in lockstep with stable tags so clients that pin to a specific manifest version resolve to a real, tagged release. `Source: [.github/workflows/ci.yml:1-120]()` `Source: [docs/install.md:42-60]()` A known operational hazard is dependency pinning: when `httpx` was bumped past a development marker, every `uvx --prerelease allow` invocation failed because the resolver could not satisfy the constraint. The fix capped `httpx` below `2.0` in `pyproject.toml` so the published pre-release build is installable end to end (issue #995). `Source: [pyproject.toml:1-80]()` `Source: [docs/troubleshooting.md:1-40]()` ## Authentication & Connection Configuration The CLI and MCP server both connect to Microsoft Fabric Data Warehouses through the `mssql-python` driver. The `build_connection_string` helper in `src/fabric_dw/sql.py` augments the API-derived connection string with authentication, encryption, and application-specific parameters before handing it to the driver. `Source: [src/fabric_dw/sql.py:1-120]()` A tracked improvement (issue #892) aims to set the SQL session `program_name` to `fdw.debruyn.dev` so that queries issued by the tool show up in warehouse query history and `sys.dm_exec_sessions` with an identifiable program name rather than the generic `MSSQL-Python` default. This is currently blocked upstream on `mssql-python` issue #649. `Source: [docs/authentication.md:1-80]()` `Source: [src/fabric_dw/sql.py:1-120]()` User-controlled configuration — workspace IDs, warehouse names, default profiles — is intended to be supplied through environment variables or a local config file resolved at startup. The authentication module resolves a token-bearing session that satisfies Fabric's Entra ID requirements before any tool call dispatches. `Source: [docs/authentication.md:1-120]()` `Source: [docs/security.md:1-80]()` ## CI/CD & Release Operations Continuous integration is orchestrated through GitHub Actions workflows under `.github/workflows/`. A recurring operational lesson is that the lockfile must be honored during install: PR #989 replaced `uv sync --frozen` with `uv sync --locked` in `ci.yml` so every job asserts lockfile consistency before installing dependencies, and issue #990 tracks the same migration across the remaining workflow files that still used `--frozen`. `Source: [.github/workflows/ci.yml:1-200]()` Lockfile drift has caused real outages: issue #988 observed that `pyproject.toml` pinned `ty==0.0.56` while `uv.lock` still carried `ty==0.0.55`, and nothing in CI detected the mismatch. The mitigation is the `--locked` switch plus a guard that fails the job on manifest/lockfile divergence. `Source: [pyproject.toml:1-80]()` `Source: [.github/workflows/ci.yml:1-200]()` The release pipeline keeps `server.json` version synchronized with stable tags, and dependabot bumps dependencies in patch-and-minor groups (for example, `ty 0.0.55 → 0.0.56`) to keep the surface area of each release reviewable. `Source: [pyproject.toml:1-80]()` `Source: [docs/install.md:60-100]()` ## Runtime Operations & Observability The MCP server surfaces a server-instructions block on `InitializeResult` so connected clients — and the models behind them — are steered toward the 118 dedicated tools instead of falling back to raw `execute_sql` for operations that already have purpose-built alternatives. A drift guard asserts that every tool named in the instructions block actually exists in the tool registry (issues #984, #986, #992). `Source: [README.md:1-80]()` Telemetry is opt-in and intended to measure things that cannot be observed from inside the repository — for example, how often agents reach for `execute_sql` despite the instructions block (issue #985). The telemetry module is documented separately and is gated so it has no effect on offline or self-hosted deployments. `Source: [docs/telemetry.md:1-80]()` Operational troubleshooting is concentrated in `docs/troubleshooting.md`, with cross-references to security guidance in `docs/security.md`. Common failure modes surfaced there include pre-release resolution failures (issue #995), integration test environments that lack a warehouse (issue #994), and CLI parse-time bugs around leading optional positionals that the suite did not catch until a journey-style smoke test was added (issues #981, #982). `Source: [docs/troubleshooting.md:1-120]()` `Source: [docs/security.md:1-80]()` | Concern | Surface | Notes | |---|---|---| | Install failure | `uvx --prerelease allow` | Cap `httpx < 2.0` to keep pre-release resolvable (#995) | | Lockfile drift | CI workflows | Use `uv sync --locked` (#988, #989, #990) | | SQL `program_name` | `sys.dm_exec_sessions` | Blocked on `mssql-python` #649 (#892) | | Tool discoverability | MCP `InitializeResult` | Server-instructions block steers agents away from `execute_sql` (#984, #986, #992) | | Integration flakiness | `tests/integration/test_services_sql_pools.py` | Endpoint 500s on empty workspace (#994) | --- --- ## Pitfall Log Project: sdebruyn/fabric-dw-mcp-cli Summary: Found 34 structured pitfall item(s), including 5 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification. ## 1. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: Track: measure execute_sql overuse after the MCP instructions block (needs telemetry) - User impact: Developers may expose sensitive permissions or credentials: Track: measure execute_sql overuse after the MCP instructions block (needs telemetry) - Evidence: failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/985 ## 2. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: feat(mcp): add server instructions and steer execute_sql toward dedicated tools - User impact: Developers may expose sensitive permissions or credentials: feat(mcp): add server instructions and steer execute_sql toward dedicated tools - Evidence: failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/984 ## 3. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: feat(mcp): name the remaining tool domains in the server instructions - User impact: Developers may expose sensitive permissions or credentials: feat(mcp): name the remaining tool domains in the server instructions - Evidence: failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/992 ## 4. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: fix(cli): leading optional ITEM positional swallows the first required argument - User impact: Developers may expose sensitive permissions or credentials: fix(cli): leading optional ITEM positional swallows the first required argument - Evidence: failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/981 ## 5. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/892 ## 6. Identity risk - Identity risk requires verification - Severity: medium - Evidence strength: runtime_trace - Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Repro command: `pip install fabric-dw` - Evidence: identity.distribution | https://github.com/sdebruyn/fabric-dw-mcp-cli ## 7. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: fix(ci): replace uv sync --frozen with --locked in remaining workflows - User impact: Developers may fail before the first successful local run: fix(ci): replace uv sync --frozen with --locked in remaining workflows - Evidence: failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/990 ## 8. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: 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 - User impact: Developers may fail before the first successful local run: fix(ci): uv.lock is out of sync with pyproject.toml, and nothing detects it - Evidence: failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/988 ## 9. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: 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 - User impact: Developers may fail before the first successful local run: fix(deps): cap httpx below 2.0 so the pre-release build is installable - Evidence: failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/995 ## 10. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: test(integration): add an end-to-end journey smoke test exercising config defaults - User impact: Developers may fail before the first successful local run: test(integration): add an end-to-end journey smoke test exercising config defaults - Evidence: failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/982 ## 11. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v2026.7.0 - User impact: Upgrade or migration may change expected behavior: v2026.7.0 - Evidence: failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.7.0 ## 12. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v2026.7.1 - User impact: Upgrade or migration may change expected behavior: v2026.7.1 - Evidence: failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.7.1 ## 13. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v2026.7.1rc1 - User impact: Upgrade or migration may change expected behavior: v2026.7.1rc1 - Evidence: failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.7.1rc1 ## 14. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/988 ## 15. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/995 ## 16. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/982 ## 17. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/sdebruyn/fabric-dw-mcp-cli ## 18. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: 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) - User impact: Developers may misconfigure credentials, environment, or host setup: Track: set SQL connection program_name to fdw.debruyn.dev (blocked on mssql-python#649) - Evidence: failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/892 ## 19. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: 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) - User impact: Developers may misconfigure credentials, environment, or host setup: fix(test): sql_pools integration tests must ensure a warehouse exists (endpoint 500s on empty workspace) - Evidence: failure_mode_cluster:github_issue | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/994 ## 20. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: v2026.6.0 - User impact: Upgrade or migration may change expected behavior: v2026.6.0 - Evidence: failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.6.0 ## 21. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: v2026.6.0rc0 - User impact: Upgrade or migration may change expected behavior: v2026.6.0rc0 - Evidence: failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.6.0rc0 ## 22. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: v2026.6.0rc2 - User impact: Upgrade or migration may change expected behavior: v2026.6.0rc2 - Evidence: failure_mode_cluster:github_release | https://github.com/sdebruyn/fabric-dw-mcp-cli/releases/tag/v2026.6.0rc2 ## 23. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/994 ## 24. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/sdebruyn/fabric-dw-mcp-cli ## 25. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/sdebruyn/fabric-dw-mcp-cli ## 26. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/sdebruyn/fabric-dw-mcp-cli ## 27. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/sdebruyn/fabric-dw-mcp-cli ## 28. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/985 ## 29. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/984 ## 30. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/992 ## 31. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/990 ## 32. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sdebruyn/fabric-dw-mcp-cli/issues/981 ## 33. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/sdebruyn/fabric-dw-mcp-cli ## 34. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/sdebruyn/fabric-dw-mcp-cli