dbt-mcp-server: Instructions file for Claude Code

CLAUDE.md

이 파일은 Claude Code가 이 저장소에서 작업할 때 참고하는 컨텍스트입니다.

프로젝트 개요

@us-all/dbt-mcp — dbt artifacts(manifest.json/run_results.json/sources.json/catalog.json) + 사용자 DQ 결과 테이블(BQ/PG)을 노출하는 stdio MCP. 27 도구 (21 primitive + 5 aggregations + 1 meta) + 4 Prompts. 전부 read-only.

• 타겟 dbt: 1.7+ (manifest schema v11/v12 검증 — schemas.getdbt.com 최상단이 v12, v13+ 미존재. 1.7=v11, 1.8~1.12=v12. 신/미지 버전은 lenient 파싱 + caveat)
• DQ 백엔드: BigQuery 기본 + Postgres 옵션, 둘 다 lazy peer import
• Airflow는 별도 서버: @us-all/airflow-mcp
• 표준: @us-all MCP Standard 준수

최근 변경사항

• v1.0.7 (2026-06-19): MCP tool annotations 적용 — @us-all/mcp-toolkit ^1.3.0의 inferToolAnnotations를 중앙 tool() 헬퍼에 추가, 전 도구에 readOnlyHint/destructiveHint/openWorldHint 자동 부여 (override 0). 비파괴 패치. 54/54 test.

디렉토리

src/
├── index.ts                   # 카테고리별 tool() 등록 + Prompts
├── config.ts                  # ENV 로딩 + 검증 (DBT/DQ 2 블록)
├── tool-registry.ts           # CATEGORIES = dbt / quality / meta
├── clients/
│   ├── dbt-artifacts.ts       # manifest/run_results/sources/catalog 로더 + mtime cache + run history walk
│   └── dq-store.ts            # BQ/PG 듀얼 백엔드 lazy import + ?-style placeholder rewrite
├── tools/
│   ├── utils.ts               # wrapToolHandler + WriteBlocked / ConfigMissing / DqStore 에러 클래스
│   ├── dbt-models.ts          # dbt-list-models, dbt-get-model, dbt-graph, dbt-coverage (4)
│   ├── dbt-tests.ts           # dbt-list-tests, dbt-get-test (2)
│   ├── dbt-sources.ts         # dbt-list-sources, dbt-get-source, dbt-list-exposures (3)
│   ├── dbt-macros.ts          # dbt-list-macros, dbt-get-macro (2)
│   ├── dbt-runs.ts            # dbt-list-runs, dbt-get-run-results, dbt-failed-tests, dbt-slow-models (4)
│   ├── quality-results.ts     # dq-list-checks, dq-get-check-history, dq-failed-checks-by-dataset (3)
│   ├── quality-scores.ts      # dq-score-trend, dq-tier-status, dq-tier-by-source (3) — Tier SLA 비교 + source.meta.tier 롤업
│   └── aggregations.ts        # failed-tests-summary, freshness-status, dq-score-snapshot, incident-context, dbt-sla-status (5)
└── prompts/
    └── index.ts               # 4 Prompts

tests/
├── fixtures/                  # 작은 manifest.json / run_results.json / sources.json
├── dbt-models.test.ts         # 6
├── dbt-tests-and-macros.test.ts # 5
├── dbt-sources.test.ts        # 3
├── dbt-runs.test.ts           # 4
└── dq-store.test.ts           # 3 (driver 주입)