dbt-tools-ts

TypeScript packages that turn manifest.json, run_results.json, and related dbt artifacts into structured, deterministic operational intelligence for operators and automation. The repository publishes @dbt-tools/core, @dbt-tools/cli, @dbt-tools/mcp, and @dbt-tools/web; parsing and artifact type definitions come from the external dbt-artifacts-parser npm package.

Packages

Package	Path	Description
@dbt-tools/core	packages/core	Analysis engine: graphs, execution analysis, snapshots, exports, and shared discovery logic.
@dbt-tools/cli	packages/cli	CLI (dbt-tools) for machine-readable artifact analysis, schema introspection, field filtering, and agent-friendly workflows.
@dbt-tools/mcp	packages/mcp	Long-lived MCP server (dbt-tools-mcp) with resident parsed artifact cache for interactive agent workflows.
@dbt-tools/web	packages/web	Browser UI and local static server (dbt-tools-web) for dependency, execution, inventory, and health investigation.

Architecture

graph LR
  dbt["dbt run\ngenerates artifacts"] --> artifacts["target/\nmanifest.json\nrun_results.json"]
  artifacts --> parser["dbt-artifacts-parser\nexternal npm dependency"]
  parser --> core["@dbt-tools/core"]
  core --> cli["@dbt-tools/cli\ndbt-tools"]
  core --> mcp["@dbt-tools/mcp\ndbt-tools-mcp"]
  core --> web["@dbt-tools/web\ndbt-tools-web"]

Product positioning and package boundaries are recorded in ADR-0008. Remote artifact loading semantics are recorded in ADR-0004.

Quick Start

Install Node.js from .node-version, then install workspace dependencies:

pnpm install

Useful development commands:

pnpm build
pnpm test
pnpm dev:web
pnpm lint:report
pnpm coverage:report
pnpm knip

Run published-shaped tools after installation from npm:

npx @dbt-tools/cli status --dbt-target ./target
npx @dbt-tools/mcp --dbt-target ./target
npx @dbt-tools/web --target ./target

Relationship to dbt-artifacts-parser

@dbt-tools/* packages depend on dbt-artifacts-parser for all artifact parsing and type definitions. This repository owns the analysis, CLI, and web layers; it does not generate or publish parser schemas. Parser repository references should remain only when they explicitly describe that external package.

License

The @dbt-tools/* packages use a custom source-available license; they are not OSI open source. See LICENSES/README.md for the repository license map and packages/LICENSE for the binding package terms. Dependencies such as dbt-artifacts-parser remain under their own licenses.