How kannandreams/dbt-mcp-server works
Project Type and Purpose
• This is a lightweight, JSON‑driven “MCP (Model Control Protocol) Server” for running dbt models via CLI, HTTP API, or AI clients (e.g. Claude).
• It unifies trigger workflows (dbt commands, tests, etc.) and sends Slack notifications on completion.
High‑Level Architecture Components
a. Clients
• CLI client (invokes mcp_dispatcher.py with a JSON file)
• HTTP client (e.g. uvicorn mcp_dispatcher:app)
• AI client example (claude_client_example.py)
b. API / Dispatcher Layer
• FastAPI app in mcp_dispatcher.py (serves /run endpoint)
• JSON request parser (reads mcp_request.json)
• Template loader (prompt_templates/*.txt – optional for prompts)
c. Command Definition Store
• mcp_servers.json – maps each “mcpServer” key to a command and args
d. Execution Engine
• Subprocess orchestration (spawns dbt or node commands per config)
• Environment management (.python‑version, pyproject.toml, Dockerfile)
e. Notification Service
• Slack webhook integration (SLACK_WEBHOOK_URL)
• Sends success/failure alerts
f. External Dependencies
• dbt runtime (assumed installed or containerized)
• Claude or other AI (optional)
• Slack
Relationships & Data Flow
1. Client sends JSON payload →
2. FastAPI receives HTTP POST (or CLI script loads JSON) →
3. Dispatcher matches payload key against mcp_servers.json →
4. Dispatcher spawns corresponding subprocess (e.g., dbt run) →
5. On completion, captures exit status/logs →
6. Posts notification to Slack →
7. Returns JSON response to client
Architectural Patterns & Principles
• “Plugin” style command mapping via JSON file (mcp_servers.json)
• Single‑responsibility: dispatcher handles routing, execution, and notification separately
• External‑service integration abstracted behind a simple interface (Slack webhook)
• Containerization support for environment consistency (Dockerfile)
Technologies & Frameworks
• Python + FastAPI + Uvicorn
• JSON for configuration and requests
• Docker for packaging
• Slack Webhooks
• dbt CLI
• Optional AI client integration (Claude)