Add version awareness to product_docs toolset#638
Conversation
mirnawong1
requested review from
a team,
b-per,
jairus-m and
jasnonaz
as code owners
src/dbt_mcp/product_docs/tools.py
Outdated
|
|
||
| version_note: str | None = None | ||
| if detect_eol_page(normalized): | ||
| version_note = "This page is for an end-of-life dbt Core version (v1.6 or older)." |
There was a problem hiding this comment.
Honest question: would it be more reliable to determine EOL based on the parsed version number rather than the contents of the page?
| dbt_version: str | None = None | ||
| project_yml = settings.dbt_project_yml | ||
| if project_yml and project_yml.require_dbt_version: | ||
| dbt_version = parse_dbt_version_minor(project_yml.require_dbt_version) |
There was a problem hiding this comment.
Does this hold the full dbt version or just the minor version?
There was a problem hiding this comment.
It looks like the full version, so I would suggest renaming the function.
| return None | ||
| raw = require_dbt_version if isinstance(require_dbt_version, str) else require_dbt_version[0] | ||
| match = _DBT_MINOR_VERSION_RE.search(raw) | ||
| return f"1.{match.group(1)}" if match else None |
There was a problem hiding this comment.
This would be a bit flaky if we ever release a 2.0 version. I don't think we should hard-code a 1. prefix.
| def parse_dbt_version_minor(require_dbt_version: str | list[str] | None) -> str | None: | ||
| """Extract the minimum dbt minor version (e.g. ``"1.8"``) from a ``require-dbt-version`` spec. | ||
|
|
||
| Handles common forms: ``">=1.8.0"``, ``"1.8"``, ``[">=1.8.0", "<2.0"]``. | ||
| Returns ``None`` when the version cannot be determined. |
There was a problem hiding this comment.
Could we include an example of what this function returns in the docstring? Or, use a more specific type than string. For example:
@dataclass
class SemVer:
major: int
minor: int
patch: str # pre-releases can contain non-numeric patch versions
Detect the user's dbt version from dbt_project.yml require-dbt-version at server startup and surface it in search/page responses so the LLM can give version-contextualized guidance. EOL pages (v1.6 and older) are annotated with a warning, and both tool prompts now include VERSION AWARENESS instructions for the LLM. Made-with: Cursor
mirnawong1
force-pushed
the
add/product-docs-version
branch
from
013c2e2 to
f6b27f0
Compare
Just some high-level thoughts on the above! In the field and in my experience with past projects, Would another approach be using the existing dbt CLI executable instead? So using the DBT_PATH and then quite literally running |
3 participants
Summary
Detect the user's dbt version from
dbt_project.ymlrequire-dbt-versionat server startup and surface it in search/page responses so the LLM can give version-contextualized guidance. EOL pages (v1.6 and older) are annotated with a warning, and both tool prompts now include VERSION AWARENESS instructions for the LLM.What Changed
Version detection at startup:
DbtProjectYamlnow parses therequire-dbt-versionfield fromdbt_project.ymlparse_dbt_version_minor()helper extracts the minor version (e.g.">=1.8.0"becomes"1.8")Configcarries the detecteddbt_versionand passes it through toProductDocsToolContextat registration time (one-time, no per-call overhead)Version-aware responses:
SearchProductDocsResponseandGetProductDocPagesResponsenow include adbt_project_versionfieldProductDocPageResponsehas a newversion_notefield for EOL page flaggingdetect_eol_page()identifies pages under the/core-upgrade/Older versions/path>>> VERSION NOTICEwarning prepended to their contentLLM prompt updates:
search_product_docsandget_product_doc_pagesprompts now include aVERSION AWARENESSsection instructing the LLM to:User impact: Zero-config. Version detection works automatically for users who already have
DBT_PROJECT_DIRset andrequire-dbt-versionin theirdbt_project.yml. When version is unavailable, behavior is unchanged.Why
Users reported that the
product_docstoolset could return documentation for dbt versions that don't match their project -- including EOL versions (v1.6 and older) that are no longer supported. Since docs.getdbt.com serves a single unversioned corpus, the MCP server needs to provide version context so the LLM can guide users appropriately (e.g. flagging newer features they can't use yet, or warning about outdated EOL content).Related Issues
Closes #
Related to #
Checklist
Additional Notes
DBT_PROJECT_DIR) and requires a server restart to pick updbt_project.ymlchanges -- consistent with the existing MCP architecture.jaffle-shopproject (require-dbt-version: ">=1.5.0") via MCP Inspector -- version detection, response fields, and EOL annotation all work as expected.