Start onboarding through your AI assistant#800
Draft
joaodaher wants to merge 9 commits into
Draft
Conversation
Adds the foundation for AI-driven dbt platform onboarding. An LLM agent can now start or resume an onboarding session and check its progress — all without touching any UI. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
joaodaher
requested review from
a team,
b-per,
jairus-m and
jasnonaz
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces the foundation for AI-driven dbt platform onboarding by adding a new dbt_admin/onboarding/ package and exposing two new Admin API MCP tools to initialize and inspect an onboarding session from an AI assistant.
Changes:
- Add onboarding session scaffolding (in-memory session store + phases), response models, and an HTTP client for
GET /onboarding/state/. - Register two new MCP tools (
dbt_admin_onboarding_init,dbt_admin_onboarding_state) under theadmin_apitoolset and wire them into server tool registration. - Add unit tests covering the session store and the new onboarding tools; update README/tool description mappings and changelog entry.
Reviewed changes
Copilot reviewed 15 out of 17 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
src/dbt_mcp/dbt_admin/onboarding/session.py |
Adds in-memory session state + phase enum for onboarding flow. |
src/dbt_mcp/dbt_admin/onboarding/client.py |
Introduces a minimal HTTP client for onboarding state API calls. |
src/dbt_mcp/dbt_admin/onboarding/decision_points.py |
Scaffolds decision-point representation and an (empty) registry function. |
src/dbt_mcp/dbt_admin/onboarding/models.py |
Adds Pydantic models for init/state tool responses. |
src/dbt_mcp/dbt_admin/onboarding/tools.py |
Implements and registers init/state tools with context binding. |
src/dbt_mcp/mcp/server.py |
Registers onboarding tools in both single- and multi-project server setups. |
src/dbt_mcp/tools/tool_names.py |
Adds tool name constants for onboarding tools. |
src/dbt_mcp/tools/toolsets.py |
Maps onboarding tools into the ADMIN_API toolset. |
src/dbt_mcp/tools/readme_mappings.py |
Adds README descriptions for onboarding tools. |
src/dbt_mcp/prompts/admin_api/onboarding_init.md |
Adds prompt guidance for onboarding init tool behavior. |
src/dbt_mcp/prompts/admin_api/onboarding_state.md |
Adds prompt guidance for onboarding state tool behavior. |
tests/unit/dbt_admin/onboarding/test_session.py |
Adds unit tests for session store behavior and phase logic. |
tests/unit/dbt_admin/onboarding/test_tools.py |
Adds unit tests for tool registration and tool behavior. |
README.md |
Documents the new onboarding tools in the Admin API tool list. |
.changes/unreleased/Enhancement or New Feature-20260608-120113.yaml |
Adds an unreleased changelog entry for onboarding scaffold/tools. |
tests/unit/dbt_admin/onboarding/__init__.py |
Creates package init for onboarding unit tests. |
src/dbt_mcp/dbt_admin/onboarding/__init__.py |
Creates package init for onboarding module. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Use Field(default_factory=dict) for ServerOnboardingState.data to avoid shared mutable default
- Coalesce raw API data field with `or {}` to handle null payloads safely
- Make InMemorySessionStore.get_or_create async with asyncio.Lock to prevent race conditions
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Fix API client: use /onboarding/ (GET + POST) instead of non-existent /state/ and /apply/ paths - dbt_admin_onboarding_init now calls POST /onboarding/ to create-or-get the backend record - dbt_admin_onboarding_state now always calls GET /onboarding/ (backend is source of truth) - Remove DBT_PROJECT_IDS requirement for admin API tools — they operate at account level - Simplify session.py: drop in-memory state machine now that backend owns state Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace init/state with three purpose-built tools: - dbt_admin_onboarding_get: GET /onboarding/ — check current status - dbt_admin_onboarding_validate: POST /onboarding/validate/ — check data without applying - dbt_admin_onboarding_apply: POST /onboarding/ — submit data incrementally (idempotent) All three verified against the warm PR env. validate returns a clean error until the backend implements the /validate/ endpoint. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The validate endpoint is not a separate path — it's the same POST /onboarding/ with a dry_run=1 query param. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Move DBT_TOKEN and host prefix checks into the outer guard that covers
admin API, so admin-API-only users still get token validation
- Delete stale onboarding_init.md and onboarding_state.md prompt files
- Add missing onboarding_get/validate/apply prompt files (were untracked)
- Fix apply client to coalesce null data response with `or {}`
- Regenerate README tool list
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Use e.response.json() instead of response.json() in validate error path - Fix changelog body to reflect actual tool names (get/validate/apply) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- apply() raises AdminAPIError when API returns no data instead of
silently returning {} (which would cause KeyError downstream)
- validate() docstring now accurately describes the raw API return shape
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What's this?
This is the foundation phase of AI-driven dbt platform onboarding. Instead of navigating a UI, users can now start a dbt platform onboarding session directly from their AI assistant (Claude Code, Cursor, etc.) by just saying something like "I need to set up my dbt project."
What's included
New package: `dbt_admin/onboarding/`
Three new MCP tools (part of the `admin_api` toolset):
What's not here yet
This is the first of several incremental phases. The backend resource creation (project, connection, repository, environments, job) is handled by the platform API in companion tickets.
How it works
An agent can:
Testing
For now, an agent tries to fully onboard the user, which is not yet supported. But it can definitely get the current onboarding state.