dbt-doctor - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #react #ai #llm #go #android #machine-learning #deep-learning #java #windows #awesome #awesome-list #pytorch

dbt-doctor

(★ 132)

AI-driven quality & governance MCP Server for dbt projects. Audit coverage, profile data, detect schema drift, and auto-generate documentation — all through natural language with your AI assistant.

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
  - publish.yml
- architecture.png
- - __init__.py
  - server.py
- - __init__.py
  - sample_manifest.json
- __init__.py
- conftest.py
- test_auditor.py
- test_dag_analyzer.py
- test_manifest_parser.py
- test_profiler.py
- test_test_suggester.py
- test_yaml_writer.py
.gitignore
ARCHITECTURE_AND_PLAN.md
CHANGELOG.md
CONTRIBUTING.md
KNOWN_LIMITATIONS.md
LICENSE
logo.png
pyproject.toml
README.md
SECURITY.md
STATUS.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/Astoriel/dbt-doctor

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd dbt-doctor

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. 공식 설치 스크립트

쉬움 추천

사전 준비물

Python 3 pip 명령어를 쓰려면 Python이 필요합니다.

pip install dbt-doctor

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

✅ 설치 후 새 터미널을 열고, 프로그램의 버전 확인 명령(예: --version)으로 정상 설치됐는지 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Python

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Python 3 설치 시 'Add Python to PATH' 옵션을 꼭 체크하세요 (Windows).

pip install dbt-doctor

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

✅ 에러 메시지 없이 실행되고 터미널에 안내 문구가 출력되면 정상입니다.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
  <img src="logo.png" alt="dbt-doctor logo" width="300"/>
  <p><strong>AI-driven quality and governance MCP Server for dbt projects.</strong></p>
  <p>Audit coverage, profile data, detect schema drift, and auto-generate documentation—all through natural language with an AI assistant.</p>
</div>

<p align="center">
  <a href="https://github.com/Astoriel/dbt-doctor/actions/workflows/ci.yml">
    <img src="https://github.com/Astoriel/dbt-doctor/actions/workflows/ci.yml/badge.svg" alt="CI"/>
  </a>
  <a href="https://pypi.org/project/dbt-doctor/">
    <img src="https://badge.fury.io/py/dbt-doctor.svg" alt="PyPI version"/>
  </a>
  <a href="https://python.org">
    <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"/>
  </a>
  <a href="LICENSE">
    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"/>
  </a>
</p>

---

## Project status

Active alpha. Snapshot date: 2025-12-25. See [STATUS.md](STATUS.md) and [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md) for what is working today, what is planned, and what is not claimed.

## What is dbt-doctor?

dbt-doctor is a Model Context Protocol (MCP) server that provides your AI coding assistant with deep context regarding your dbt project's health. Instead of manually running CLI commands and analyzing outputs, you can interact with your AI:

- "What's the overall health of my dbt project?"
- "Profile the fct_orders model and suggest appropriate tests."
- "Auto-document the models that have the lowest test coverage."

The tool handles the heavy operations—reading the manifest, profiling your data warehouse, detecting schema drift, and writing back to schema.yml files—without requiring you to leave the chat.

Note: This tool is designed to complement the official dbt-labs/dbt-mcp. While dbt-labs/dbt-mcp focuses on running dbt commands, dbt-doctor focuses on auditing, profiling, and documentation.

## Key Features

### Project Auditing
Evaluate your project with a 0–100% score based on documentation, testing, and naming conventions. Access a ranked list of models lacking coverage to prioritize your efforts.

### Data Profiling  
Perform efficient single-pass column statistics—including NULL rates, cardinality, min/max values, and uniqueness—using one batched SQL query per table to avoid slow row-by-row scanning.

### Schema Drift Detection
Compare the current state of your data warehouse against the definitions in your `manifest.json`. Instantly identify added, removed, or type-changed columns.

### Intelligent Test Suggestions
Translate profiling statistics into actionable dbt test recommendations. For example, a uniquely populated column without nulls will prompt suggestions for `not_null` and `unique` tests, while low cardinality will suggest `accepted_values` with predefined options.

### Non-Destructive YAML Writing
Update `schema.yml` files using `ruamel.yaml` to retain hand-written comments, existing tests, and formatting. The tool only appends missing information and preserves your manual configurations.

### End-to-End Documentation Generation
Execute a complete workflow in a single conversational turn: profile a model, suggest tests, preview changes, and write to schema.yml.

---

## Included MCP Tools

| Category | Tool | Description |
|---|---|---|
| Context | `list_models` | Overview of all models and their coverage status |
| Context | `get_model_details` | Detailed model information including SQL, columns, lineage, and tests |
| Audit | `audit_project` | Project health score and naming convention violations |
| Audit | `check_test_coverage` | Models ranked by their test coverage percentage |
| Audit | `analyze_dag` | Detection of orphan models and high fan-out nodes |
| Audit | `get_project_health` | Single-call dashboard summarizing project status |
| Profiling | `profile_model` | Batched column statistics |
| Profiling | `execute_query` | Read-only SQL execution against your warehouse |
| Profiling | `detect_schema_drift` | Comparison of database columns against manifest definitions |
| Generation | `suggest_tests` | Translation of profile data into dbt test recommendations |
| Generation | `update_model_yaml` | Safe merging of documentation and tests to schema.yml |
| Generation | `generate_model_docs` | Complete end-to-end documentation workflow |

---

## Quick Start

### Installation

```bash
pip install dbt-doctor
```

### Configuration (Claude Desktop)

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "dbt-doctor": {
      "command": "dbt-doctor",
      "args": ["--project-dir", "/absolute/path/to/your/dbt/project"]
    }
  }
}
```

### Configuration (Cursor)

Add the following to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "dbt-doctor": {
      "command": "dbt-doctor",
      "args": ["--project-dir", "/absolute/path/to/your/dbt/project"]
    }
  }
}
```

*Prerequisite: Run `dbt compile` prior to usage to ensure `target/manifest.json` is available for dbt-doctor to parse.*

---

## Architecture

![dbt-doctor architecture](https://raw.githubusercontent.com/Astoriel/dbt-doctor/main/docs/architecture.png)

The application connects the AI Assistant with your dbt project and database through the MCP protocol. It features a read-only analysis layer combined with a secure generation toolkit that merges changes seamlessly into your existing YAML schemas.

---

## Security Design

- **Read-only execution:** All `execute_query` operations operate within a read-only transaction. Write processes are restricted at the database connector level.
- **SQL validation:** Table and column identifiers are strictly validated against a whitelist to prevent injection.
- **Stateless connections:** Data warehouse credentials are instantiated per connection and are never cached in memory.
- **Preview before commit:** The document generation process provides a difference preview prior to rewriting `schema.yml`, ensuring you retain control over modifications.

---

## Related Projects

| Project | Description |
|---|---|
| dbt-labs/dbt-mcp | Official MCP focused on dbt command execution |
| dbt-coverage | CLI tool for coverage reporting without AI integration |
| dbt-project-evaluator | dbt package for project evaluation, requiring installation per project |

dbt-doctor uniquely consolidates auditing, profiling, drift detection, and AI-driven YAML updates into a single server interface.

---

## License

MIT — see the [LICENSE](LICENSE) file.