dbt-mcp: Instructions file for Claude Code

CLAUDE.md

Project Overview

dbt-mcp is an MCP (Model Context Protocol) server that exposes dbt functionality as tools to AI assistants. Built on FastMCP from the mcp SDK.

Key Paths

• Entry point: src/dbt_mcp/main.py
• Server: src/dbt_mcp/mcp/server.py (DbtMCP class, create_dbt_mcp())
• Tool infra: src/dbt_mcp/tools/ (definitions, registration, injection, toolsets, tool_names)
• Tool categories: discovery/, semantic_layer/, dbt_cli/, dbt_codegen/, dbt_admin/, lsp/, mcp_server_metadata/
• Prompts (tool descriptions): src/dbt_mcp/prompts/
• Config: src/dbt_mcp/config/
• Tests: tests/unit/, tests/integration/

Tool Architecture

Tools follow a consistent pattern:

1. @dbt_mcp_tool defines metadata and requires an explicit access declaration: target argument annotations, top-level requirements=(AccountTarget(requires=…),) or a host policy enum. Use requirements=(AccessPolicy.LOCAL,) for local execution and requirements=() for public tools. Hosts implement enforcement; shared declarations contain semantic permissions and preserve host policies without interpreting them.
2. ToolName enum in tools/tool_names.py — every tool needs an entry
3. Toolset mapping in tools/toolsets.py — maps tools to categories
4. Context injection builds the framework callable; the declared input contract and host bindings determine the model schema
   • Declare Annotated[..., ProjectTarget(...)] and EnvironmentTarget(...) on the canonical tool arguments. Keep a required Field(...) default for selectors; context adapters pass these arguments through, but bodies read resolved context/config and leave selectors unused. The model sees the declared non-nullable type or no parameter when bound. Adaptation preserves the canonical metadata. JobTarget/RunTarget describe ordinary IDs used by the body whose owning project/environment the host resolves. Resource-specific job/run tools require only their JobTarget/RunTarget permission; AccountTarget is reserved for genuinely account-wide operations. Listing visibility must not add an account-wide runtime requirement. Hosts check owners only for supplied IDs and leave requiredness to input validation.
   • Discovery and semantic-layer tools declare ProjectTarget(requires=..., environment=EnvironmentRole.PRODUCTION). The host resolves production alongside the project before authorization; no environment-ID argument is needed. Job listing declares AccessPolicy.JOBS_LISTING; hosts authorize the configured project/environment scope or account fallback. Tool bodies consume the configuration supplied by their context mapper.
   • adapt_with_mappers(context=build_context, project_id=resolved_project) injects parameters by name. Mapper inputs form the framework signature, shared inputs must agree, and each mapper runs once per invocation. Canonical input types/defaults define the model contract independently of mapper omission support. Target annotations remain on caller-visible inputs. All injection is explicit by parameter name; type-based and positional mapper APIs have been removed.
   • Context mappers explicitly declare the selectors and ordinary arguments they need. Hosts resolve and authorize those inputs, then build the final context. Framework context can supply request authorization while adapters choose the visible selector inputs. Ordinary mapper inputs also reach the body unchanged. project_id=HIDE removes a model input without supplying a value; dependent mappers must allow omission. Zero-argument value mappers hide and inject known values; compose them after context adaptation so context builders receive the selected values. FastMCP generates and validates the resulting callable with extra inputs forbidden. Discovery contexts construct fetchers with resolved config.
   • Discovery and semantic-layer tools have one canonical implementation and one registration entry point. Project-aware providers resolve either the configured environment or an explicit project. The local server uses one registry and projects schemas per credential selection: a unique project/configured environment hides the selector; multiple projects expose the tool's declared selector. Invocation rejects supplied bound selectors. Optional job filters use nullable JobTarget arguments alongside AccessPolicy.RUNS_LISTING; hosts check the owner when supplied and the account when omitted. Shared listing policies are implemented by hosts alongside AccessPolicy.LOCAL. list_jobs accepts an optional project filter that overrides the configured environment. Without an explicit filter, it uses the configured environment (including staging), then the configured project, then account-wide listing. Optional local selectors retain their defaults when hidden and permit omission in multi-project mode; required selectors remain required.
5. register_tools() in tools/register.py — precedence-based enablement (individual > toolset > default)