Metadata-Version: 2.4
Name: dbt-mshhcp-setup
Version: 0.2.0
Summary: The silent dbt MCP configurator for VS Code — sets up dbt-mcp with a secure, minimal configuration
Project-URL: Repository, https://github.com/rapha-pereira/dbt-mshhcp-setup
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Description-Content-Type: text/markdown

# 🤫 dbt-mshhcp-setup

> The simple and silent dbt MCP configurator for VS Code.

Sets up the [dbt MCP server](https://docs.getdbt.com/docs/dbt-ai/about-mcp) in your VS Code workspace without touching your existing environment. A step-by-step wizard asks for confirmation at every stage — it never modifies anything without your explicit approval.

**This project doesn't reinvent the wheel, nor is it full of innovations and glitz. It just does what it needs to do without any fuss.**

## What it does

Generates a `.vscode/mcp.json` file that connects GitHub Copilot (and other MCP clients in VS Code) to your local dbt project via the `dbt-mcp` server. The configuration is minimal and secure by design:

- **Only dbt CLI tools are enabled** (`DBT_MCP_ENABLE_DBT_CLI=true`) — `dbt run`, `build`, `test`, `compile`, `list`, `parse`, `show`, and lineage queries.
- **All platform features are disabled** — Semantic Layer, Discovery API, Admin API, SQL execution, Codegen, and LSP stay off. This is achieved via dbt's [enable-mode allowlist](https://docs.getdbt.com/docs/dbt-ai/mcp-environment-variables#enable-mode-allowlist): setting any `DBT_MCP_ENABLE_*` variable activates allowlist mode, so only explicitly enabled toolsets are available — including any new ones added in future dbt-mcp versions.
- **Existing configs are never silently overwritten** — if `mcp.json` already exists, the wizard shows the current servers and asks whether to add a new one.

## Requirements

| Requirement | Notes |
| ------------- | ------- |
| Python 3.10+ | Included with most systems |
| [uv](https://docs.astral.sh/uv/) | The wizard installs it automatically if missing |
| A local dbt project | Folder containing `dbt_project.yml` |
| dbt installed locally | Either in a `.venv` or on `PATH` |
| VS Code | With [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) or another MCP client |

**Supported platforms:** Ubuntu 24.04, Windows 11, Windows 11 (WSL 2).

## Quick start

No clone required. Run directly with `uvx`:

```sh
uvx dbt-mshhcp-setup
```

The wizard walks you through 7 steps:

```text
  ┌─────┐ ┌─────┐ ┌─────┐
  │  d  ├─┤  b  ├─┤  t  │   🤫  shhh...
  └─────┘ └─────┘ └─────┘
  dbt-mshhcp-setup · v0.1.0
  The silent dbt MCP configurator

[1/6] Checking prerequisites...
  ✓ uv 0.7.x found

[2/6] Target workspace
  ? Path to your VS Code workspace: /home/you/my-repo
  ✓ .vscode directory found

[3/6] Checking existing configuration...
  ✓ No existing mcp.json — ready to configure

[4/6] Configure server(s)
  --- Server 1 ---
  ? Server name (e.g. dbt-databricks): dbt-databricks
  ? Path to dbt project (folder containing dbt_project.yml): /home/you/my-repo/dbt_project
  ✓ dbt project found.
  Environment loading method:
    1) direnv
    2) --env-file  (recommended by dbt)
    3) None  (direct uvx)
  ? Select [3]: 2
  ? Absolute path to .env file: /home/you/my-repo/dbt_project/.env
  ℹ Auto-detected DBT_PATH: /home/you/my-repo/dbt_project/.venv/bin/dbt
  ? DBT_PATH [/home/you/my-repo/dbt_project/.venv/bin/dbt]:
  ? DBT_CLI_TIMEOUT (seconds) [180]:
  ✓ Server 'dbt-databricks' configured.

  ? Add another server? [y/N]: n

[5/6] Review

  Configuration preview (1 server(s)):

  {
    "servers": {
      "dbt-databricks": {
        "command": "uvx",
        "args": ["--env-file", "/home/you/my-repo/dbt_project/.env", "dbt-mcp"],
        "env": {
          "DBT_PROJECT_DIR": "/home/you/my-repo/dbt_project",
          "DBT_PATH": "/home/you/my-repo/dbt_project/.venv/bin/dbt",
          "DBT_CLI_TIMEOUT": "180",
          "DBT_MCP_ENABLE_DBT_CLI": "true"
        }
      }
    }
  }

  ℹ Only dbt CLI tools are enabled (DBT_MCP_ENABLE_DBT_CLI=true).
     All platform features (Semantic Layer, Discovery, Admin API, etc.) are disabled.

  ? Write to /home/you/my-repo/.vscode/mcp.json? [Y/n]: Y
  ✓ Written to /home/you/my-repo/.vscode/mcp.json

[6/6] Smoke test
  Validating paths and checking uvx can resolve dbt-mcp...
  ✓ All paths valid.
  ✓ dbt-mcp is available via uvx.

[7/7] Copilot awareness (optional)
  ? Configure Copilot to be aware of this dbt MCP setup? [y/N]: y
  ? Default production schema for 'dbt-databricks' (e.g. analytics.marts): analytics.marts
  Delivery method:
    1) Instructions file  (automatic — Copilot applies when relevant)
    2) Reusable prompt file  (manual — /server-name per session)
    3) Skip
  ? Select [1]: 1
  ✓ Written: /home/you/.copilot/instructions/dbt-mcp.instructions.md

✓ All done! Restart VS Code to activate the MCP server(s).
```

## How it works

```mermaid
flowchart TD
    START([uvx dbt-mshhcp-setup]) --> S1

    subgraph S1 ["[1/6] Prerequisites"]
        UV{uv installed?}
        UV -- Yes --> UV_OK([✓ continue])
        UV -- No --> UV_PROMPT{Install uv now?}
        UV_PROMPT -- No --> E1([Exit])
        UV_PROMPT -- Yes --> UV_INSTALL[Run installer]
        UV_INSTALL --> UV_CHECK{Installed OK?}
        UV_CHECK -- No --> E2([Exit])
        UV_CHECK -- Yes --> UV_OK
    end

    S1 --> S2

    subgraph S2 ["[2/6] Target workspace"]
        WS[Prompt workspace path]
        WS --> WS_DIR{Directory exists?}
        WS_DIR -- No --> WS
        WS_DIR -- Yes --> VSCODE{.vscode/ exists?}
        VSCODE -- Yes --> VSCODE_OK([✓ continue])
        VSCODE -- No --> VSCODE_CREATE{Create .vscode/?}
        VSCODE_CREATE -- No --> E3([Exit])
        VSCODE_CREATE -- Yes --> MKDIR[mkdir .vscode/]
        MKDIR --> VSCODE_OK
    end

    S2 --> S3

    subgraph S3 ["[3/6] Existing configuration"]
        MCP{mcp.json exists?}
        MCP -- No --> MCP_FRESH([✓ fresh config])
        MCP -- Yes --> MCP_SHOW[Show existing servers]
        MCP_SHOW --> MCP_ADD{Add a new server?}
        MCP_ADD -- No --> E4([Exit — no changes])
        MCP_ADD -- Yes --> MCP_FRESH
    end

    S3 --> S4

    subgraph S4 ["[4/6] Configure server(s)"]
        NAME[Prompt server name]
        NAME --> NAME_OK{Valid & unique?}
        NAME_OK -- No --> NAME
        NAME_OK -- Yes --> PROJ[Prompt dbt project path]
        PROJ --> PROJ_OK{"dbt_project.yml\nfound?"}
        PROJ_OK -- No --> PROJ
        PROJ_OK -- Yes --> ENV[Prompt env loading mode]
        ENV --> ENV_CHOICE{Mode?}
        ENV_CHOICE -- direnv --> DIRENV[Prompt direnv exec path]
        ENV_CHOICE -- env-file --> ENVFILE[Prompt .env file path]
        ENV_CHOICE -- direct --> DBTPATH
        DIRENV --> DBTPATH[Auto-detect DBT_PATH]
        ENVFILE --> DBTPATH
        DBTPATH --> DBTPATH_CONFIRM[Confirm / override path]
        DBTPATH_CONFIRM --> TIMEOUT[Prompt timeout]
        TIMEOUT --> ANOTHER{Add another server?}
        ANOTHER -- Yes --> NAME
        ANOTHER -- No --> S4_DONE([✓ servers collected])
    end

    S4 --> S5

    subgraph S5 ["[5/6] Review & write"]
        PREVIEW[Show JSON preview]
        PREVIEW --> SEC_NOTE["ℹ DBT_MCP_ENABLE_DBT_CLI=true\nAll platform features disabled"]
        SEC_NOTE --> WRITE_Q{Write mcp.json?}
        WRITE_Q -- No --> E5([Exit — no changes])
        WRITE_Q -- Yes --> WRITE[Write .vscode/mcp.json]
        WRITE --> S5_DONE([✓ written])
    end

    S5 --> S6

    subgraph S6 ["[6/6] Smoke test"]
        TEST_PATHS[Validate all paths exist]
        TEST_PATHS --> UVX_AVAIL{uvx in PATH?}
        UVX_AVAIL -- No --> WARNS
        UVX_AVAIL -- Yes --> TEST_UVX[Check uvx resolves dbt-mcp]
        TEST_UVX --> WARNS{Any warnings?}
        WARNS -- Yes --> SHOW_WARN[Print warnings]
        WARNS -- No --> ALL_OK[All checks passed]
        SHOW_WARN --> DONE_WARN([Done — review warnings])
        ALL_OK --> DONE([✓ All done!])
    end
```

## Environment loading modes

Each server can load environment variables (database credentials, profiles, etc.) in one of three ways:

| Mode | `command` | Use case |
| ------ | ----------- | ---------- |
| **direnv** | `direnv exec /path uvx dbt-mcp` | Projects that use [direnv](https://direnv.net/) for automatic env loading |
| **--env-file** | `uvx --env-file /path/.env dbt-mcp` | Projects with a `.env` file (recommended by dbt) |
| **direct** | `uvx dbt-mcp` | Simple setups where env vars are already in the `env` block |

The database credentials themselves live in your `.env` or `direnv` setup — `dbt-mshhcp-setup` never reads, stores, or prints them.

## Multiple dbt projects

You can configure more than one server in a single run (e.g. one for Databricks, one for BigQuery). Each server gets its own entry in `mcp.json`:

```json
{
  "servers": {
    "dbt-databricks": {
      "command": "direnv",
      "args": ["exec", "/home/you/data-platform/dbt_project", "uvx", "dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/home/you/data-platform/dbt_project",
        "DBT_PATH": "/home/you/data-platform/dbt_local_run/.venv/bin/dbt",
        "DBT_CLI_TIMEOUT": "180",
        "DBT_MCP_ENABLE_DBT_CLI": "true"
      }
    },
    "dbt-bigquery": {
      "command": "uvx",
      "args": ["--env-file", "/home/you/people-analytics/.env", "dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/home/you/people-analytics",
        "DBT_PATH": "/home/you/people-analytics/.venv/bin/dbt",
        "DBT_CLI_TIMEOUT": "180",
        "DBT_MCP_ENABLE_DBT_CLI": "true"
      }
    }
  }
}
```

If `mcp.json` already exists with servers you configured earlier, re-running the wizard offers to add a new server — it will not touch the existing entries.

## WSL 2 notes

**mcp.json (steps 1–6):** The wizard always writes to the workspace `.vscode/mcp.json`, which is the correct location for WSL. VS Code user settings do not work for MCP in WSL — workspace settings do. See the [dbt VS Code integration docs](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-vscode) for details.

**Copilot awareness (step 7):** Method 1 writes to `~/.copilot/instructions/dbt-mcp.instructions.md` — a standard user-level path that VS Code reads automatically on all platforms (Linux, Windows, WSL). No path detection needed. Method 2 (reusable prompt file) still requires detecting the VS Code user directory; when WSL is detected, the tool tries `~/.config/Code/User/` first (VS Code Server in WSL), then `/mnt/c/Users/<user>/AppData/Roaming/Code/User/` (VS Code for Windows), with a manual fallback.

## Development

```sh
git clone https://github.com/your-org/dbt-mshhcp-setup
cd dbt-mshhcp-setup
uv sync          # creates .venv, installs runtime + dev deps, generates uv.lock
uv run pytest    # run tests
uv run dbt-mshhcp-setup  # run the wizard locally
```

## Project structure

```text
dbt-mshhcp-setup/
├── pyproject.toml                    # deps, build config, entry point
├── uv.lock                           # reproducible dependency lock (commit this)
├── .python-version                   # pins Python 3.10
└── src/
    └── dbt_mshhcp_setup/
        ├── __init__.py               # __version__
        ├── cli.py                    # interactive wizard (7 steps)
        ├── config.py                 # build / read / write mcp.json
        ├── checks.py                 # uv detection, path validation, smoke test
        └── copilot.py               # VS Code Copilot awareness (step 7)
```

## What is NOT in scope

This tool is intentionally minimal. It does **not**:

- Configure dbt platform / dbt Cloud features (Semantic Layer, Discovery API, OAuth)
- Set up or scaffold dbt projects
- Manage database credentials
- Modify VS Code `settings.json`

For full dbt MCP documentation, see [docs.getdbt.com/docs/dbt-ai](https://docs.getdbt.com/docs/dbt-ai/about-mcp).

