dbt_debug
Validate dbt project setup to troubleshoot configuration issues, check database connectivity, and verify dependencies before running models or tests.
Instructions
Run dbt debug to validate the project setup. An AI agent should use this tool when it needs to troubleshoot configuration issues, check database connectivity, or verify that all project dependencies are properly installed. This is essential for diagnosing problems before attempting to run models or tests.
Returns:
Output from the dbt debug command as text (this command does not support JSON output format)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_dir | No | ABSOLUTE PATH to the directory containing the dbt project (e.g. '/Users/username/projects/dbt_project' not '.') | . |
| profiles_dir | No | Directory containing the profiles.yml file (defaults to project_dir if not specified) |
Implementation Reference
- src/tools.py:259-284 (handler)MCP tool handler for 'dbt_debug'. Executes 'dbt debug' command to validate dbt project configuration, database connectivity, and dependencies. Includes input schema via Pydantic Field validators.@mcp.tool() async def dbt_debug( project_dir: str = Field( default=".", description="ABSOLUTE PATH to the directory containing the dbt project (e.g. '/Users/username/projects/dbt_project' not '.')" ), profiles_dir: Optional[str] = Field( default=None, description="Directory containing the profiles.yml file (defaults to project_dir if not specified)" ) ) -> str: """Run dbt debug to validate the project setup. An AI agent should use this tool when it needs to troubleshoot configuration issues, check database connectivity, or verify that all project dependencies are properly installed. This is essential for diagnosing problems before attempting to run models or tests. Returns: Output from the dbt debug command as text (this command does not support JSON output format) """ command = ["debug"] # The --no-print flag is not supported by dbt Cloud CLI # We'll rely on proper parsing to handle any print macros result = await execute_dbt_command(command, project_dir, profiles_dir) # Use the centralized result processor return await process_command_result(result, command_name="debug")
- src/server.py:85-90 (registration)Registers all MCP tools (including dbt_debug) on the FastMCP server instance by calling register_tools(mcp). This is the entry point where the dbt_debug tool becomes available.# Create FastMCP server mcp = FastMCP("dbt-cli", log_level="ERROR") # Register tools register_tools(mcp)
- src/tools.py:261-268 (schema)Input schema definition for the dbt_debug tool using Pydantic Field with descriptions and defaults for project_dir and profiles_dir parameters.project_dir: str = Field( default=".", description="ABSOLUTE PATH to the directory containing the dbt project (e.g. '/Users/username/projects/dbt_project' not '.')" ), profiles_dir: Optional[str] = Field( default=None, description="Directory containing the profiles.yml file (defaults to project_dir if not specified)" )
- src/tools.py:25-25 (registration)The register_tools function where all MCP tools, including dbt_debug, are defined and registered via @mcp.tool() decorators.def register_tools(mcp: FastMCP) -> None: