Add version awareness to product_docs toolset

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

Author: mirnawong1

.changes/unreleased/Enhancement or New Feature-20260311-103100.yaml

@@ -0,0 +1,5 @@
+kind: Enhancement or New Feature
+body: 'Add version awareness to product_docs toolset: detects dbt version from dbt_project.yml,
+  includes it in search/page responses, annotates EOL pages, and adds LLM prompt instructions
+  for version-specific guidance'
+time: 2026-03-11T10:31:00.789229Z

src/dbt_mcp/config/config.py

@@ -7,6 +7,7 @@
     DefaultProxiedToolConfigProvider,
     DefaultSemanticLayerConfigProvider,
 )
+from dbt_mcp.config.dbt_project import parse_dbt_version_minor
 from dbt_mcp.config.settings import (
     CredentialsProvider,
     DbtMcpSettings,
@@ -81,6 +82,7 @@ class Config:
     admin_api_config_provider: DefaultAdminApiConfigProvider | None
     credentials_provider: CredentialsProvider
     lsp_config: LspConfig | None
+    dbt_version: str | None = None
 
 
 def load_config(enable_proxied_tools: bool = True) -> Config:
@@ -161,6 +163,11 @@ def load_config(enable_proxied_tools: bool = True) -> Config:
             lsp_binary_info=lsp_binary_info,
         )
 
+    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)
+
     return Config(
         disable_tools=settings.disable_tools or [],
         enable_tools=settings.enable_tools,
@@ -174,4 +181,5 @@ def load_config(enable_proxied_tools: bool = True) -> Config:
         admin_api_config_provider=admin_api_config_provider,
         credentials_provider=credentials_provider,
         lsp_config=lsp_config,
+        dbt_version=dbt_version,
     )

src/dbt_mcp/config/dbt_project.py

@@ -1,4 +1,6 @@
-from pydantic import BaseModel, ConfigDict
+import re
+
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class DbtProjectFlags(BaseModel):
@@ -9,3 +11,22 @@ class DbtProjectFlags(BaseModel):
 class DbtProjectYaml(BaseModel):
     model_config = ConfigDict(extra="allow")
     flags: None | DbtProjectFlags = None
+    require_dbt_version: str | list[str] | None = Field(
+        None, alias="require-dbt-version"
+    )
+
+
+_DBT_MINOR_VERSION_RE = re.compile(r"1\.(\d+)")
+
+
+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.
+    """
+    if require_dbt_version is None:
+        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

src/dbt_mcp/mcp/server.py

@@ -171,6 +171,7 @@ async def create_dbt_mcp(config: Config) -> DbtMCP:
     logger.info("Registering product docs tools")
     register_product_docs_tools(
         dbt_mcp,
+        dbt_version=config.dbt_version,
         disabled_tools=disabled_tools,
         enabled_tools=enabled_tools,
         enabled_toolsets=enabled_toolsets,

src/dbt_mcp/product_docs/client.py

@@ -86,6 +86,20 @@
 
 _LLMS_TXT_ENTRY_RE = re.compile(r"^-\s+\[([^\]]+)\]\(([^)]+)\)(?::\s*(.+))?$")
 
+_EOL_URL_RE = re.compile(r"/core-upgrade/Older(?:\s|%20)versions/", re.IGNORECASE)
+
+EOL_PAGE_WARNING = (
+    ">>> VERSION NOTICE: This page describes a dbt Core version that has "
+    "reached end-of-life (EOL) and is no longer supported. The information "
+    "may be outdated or differ from current behavior. See the latest version "
+    "support info at https://docs.getdbt.com/docs/dbt-versions/core\n\n---\n\n"
+)
+
+
+def detect_eol_page(url: str) -> bool:
+    """Return ``True`` if *url* points to a page for an EOL dbt Core version."""
+    return bool(_EOL_URL_RE.search(url))
+
 # Relevance scoring weights for search_index ranking.
 # Higher weights push results toward the top when terms appear in
 # more-specific fields (title > description > section).

src/dbt_mcp/product_docs/tools.py

@@ -17,8 +17,10 @@
 from pydantic import Field
 
 from dbt_mcp.product_docs.client import (
+    EOL_PAGE_WARNING,
     MAX_CONTENT_CHARS_PER_PAGE,
     ProductDocsClient,
+    detect_eol_page,
     display_url,
     expand_keywords,
     normalize_doc_url,
@@ -44,6 +46,7 @@
 @dataclass
 class ProductDocsToolContext:
     client: ProductDocsClient = field(default_factory=ProductDocsClient)
+    dbt_version: str | None = None
 
 
 def _dict_to_doc_search_result(entry: dict[str, str]) -> DocSearchResult:
@@ -76,10 +79,17 @@ async def _fetch_page(client: ProductDocsClient, url: str) -> ProductDocPageResp
             error=f"Failed to fetch page: {normalized} ({e})",
         )
 
+    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)."
+        content = EOL_PAGE_WARNING + content
+
     content = truncate_content(
         content, MAX_CONTENT_CHARS_PER_PAGE, display_url(normalized)
     )
-    return ProductDocPageResponse(url=display_url(normalized), content=content)
+    return ProductDocPageResponse(
+        url=display_url(normalized), content=content, version_note=version_note
+    )
 
 
 @dbt_mcp_tool(
@@ -106,6 +116,7 @@ async def search_product_docs(
             total_matches=0,
             showing=0,
             results=[],
+            dbt_project_version=context.dbt_version,
             error="Query must not be empty.",
         )
 
@@ -136,6 +147,7 @@ async def search_product_docs(
         total_matches=len(doc_results),
         showing=len(doc_results),
         results=doc_results,
+        dbt_project_version=context.dbt_version,
         search_method="query_expansion" if used_query_expansion else None,
     )
 
@@ -184,7 +196,9 @@ async def get_product_doc_pages(
         else:
             pages.append(result)
 
-    return GetProductDocPagesResponse(pages=pages)
+    return GetProductDocPagesResponse(
+        pages=pages, dbt_project_version=context.dbt_version
+    )
 
 
 PRODUCT_DOCS_TOOLS = [
@@ -196,6 +210,7 @@ async def get_product_doc_pages(
 def register_product_docs_tools(
     dbt_mcp: FastMCP,
     *,
+    dbt_version: str | None = None,
     disabled_tools: set[ToolName],
     enabled_tools: set[ToolName] | None,
     enabled_toolsets: set[Toolset],
@@ -205,7 +220,7 @@ def register_product_docs_tools(
     shared_client = ProductDocsClient()
 
     def bind_context() -> ProductDocsToolContext:
-        return ProductDocsToolContext(client=shared_client)
+        return ProductDocsToolContext(client=shared_client, dbt_version=dbt_version)
 
     register_tools(
         dbt_mcp,

src/dbt_mcp/product_docs/types.py

@@ -15,6 +15,7 @@ class SearchProductDocsResponse:
     total_matches: int
     showing: int
     results: list[DocSearchResult]
+    dbt_project_version: str | None = None
     search_method: str | None = None
     error: str | None = None
 
@@ -24,8 +25,10 @@ class ProductDocPageResponse:
     url: str
     content: str
     error: str | None = None
+    version_note: str | None = None
 
 
 @dataclass
 class GetProductDocPagesResponse:
     pages: list[ProductDocPageResponse] = field(default_factory=list)
+    dbt_project_version: str | None = None

src/dbt_mcp/prompts/product_docs/get_product_doc_pages.md

@@ -6,3 +6,12 @@ IMPORTANT — how to present docs content to the user:
 3. Call out practical limitations and edge cases from the docs.
 4. Close with clear guidance: if the feature only partially answers the question, say what else they can do and where.
 5. ALWAYS include the docs page URL(s) as markdown hyperlinks at the end of your response, e.g. [Page title](https://docs.getdbt.com/...).
+
+VERSION AWARENESS:
+The response includes a `dbt_project_version` field with the user's dbt version from their dbt_project.yml. Pages may also have a `version_note` field if they cover an EOL version. If `dbt_project_version` is null, the version could not be detected — present docs normally without version-specific callouts.
+
+When presenting page content to the user, you MUST:
+1. If `dbt_project_version` is set, tell the user their version and note any version mismatches with the content.
+2. If a page covers features from a newer dbt version, explicitly tell the user: "This feature is available in dbt [version]+. Your project currently uses [their version]. Upgrading would give you access to this."
+3. If `version_note` is set, prominently warn the user that the page is for an end-of-life version and the information may be outdated. Suggest they look at the current docs instead.
+4. Never silently present content from a different version than the user's without calling it out.

src/dbt_mcp/prompts/product_docs/search_product_docs.md

@@ -3,3 +3,12 @@ Search the dbt product documentation at docs.getdbt.com for pages matching a que
 If the title/description search finds few matches, it automatically falls back to a deep full-text search across all documentation content to find pages where the topic is discussed in the body text.
 
 If your first query returns few results, try rephrasing with synonyms or the full term (e.g. 'user-defined functions' instead of 'UDFs', 'version control' instead of 'git'). Use the abbreviations on the page as well.
+
+VERSION AWARENESS:
+The response includes a `dbt_project_version` field (e.g. "1.8") detected from the user's dbt_project.yml `require-dbt-version`. If null, the version could not be detected — present docs normally without version-specific callouts.
+
+When presenting results to the user, you MUST:
+1. State the user's detected dbt version upfront if available (e.g. "Based on your project (dbt 1.8), here's what I found:").
+2. If a result is about a feature introduced in a newer version than the user's, say so explicitly (e.g. "This feature requires dbt 1.9+. You're currently on 1.8 — upgrading would give you access to this.").
+3. If a result is for an older/EOL version (v1.6 or earlier), clearly flag it: "Note: this page covers dbt v1.X, which has reached end-of-life and is no longer supported."
+4. Results include content for ALL dbt versions. The docs site does not serve version-specific pages, so always tell the user which version(s) a page applies to when it matters.

tests/unit/tools/test_product_docs.py

@@ -6,9 +6,11 @@
 import pytest
 
 from dbt_mcp.config.config import load_config
+from dbt_mcp.config.dbt_project import parse_dbt_version_minor
 from dbt_mcp.dbt_cli.binary_type import BinaryType
 from dbt_mcp.mcp.server import create_dbt_mcp
 from dbt_mcp.product_docs.client import (
+    detect_eol_page,
     normalize_doc_url,
     parse_llms_full_txt,
     parse_llms_txt,
@@ -93,6 +95,16 @@ def context(mock_client):
     """Create ProductDocsToolContext with a mocked client."""
     ctx = ProductDocsToolContext.__new__(ProductDocsToolContext)
     ctx.client = mock_client
+    ctx.dbt_version = None
+    return ctx
+
+
+@pytest.fixture
+def versioned_context(mock_client):
+    """Create ProductDocsToolContext with a mocked client and dbt version set."""
+    ctx = ProductDocsToolContext.__new__(ProductDocsToolContext)
+    ctx.client = mock_client
+    ctx.dbt_version = "1.8"
     return ctx
 
 
@@ -500,6 +512,115 @@ async def test_ranks_by_keyword_frequency(self):
         assert results[0]["url"].endswith("incremental-models-overview")
 
 
+class TestParseDbtVersionMinor:
+    def test_string_constraint(self):
+        assert parse_dbt_version_minor(">=1.8.0") == "1.8"
+
+    def test_list_constraint(self):
+        assert parse_dbt_version_minor([">=1.8.0", "<2.0"]) == "1.8"
+
+    def test_bare_version(self):
+        assert parse_dbt_version_minor("1.10") == "1.10"
+
+    def test_none(self):
+        assert parse_dbt_version_minor(None) is None
+
+    def test_unparseable(self):
+        assert parse_dbt_version_minor("latest") is None
+
+    def test_patch_version(self):
+        assert parse_dbt_version_minor(">=1.9.3") == "1.9"
+
+    def test_exact_version_string(self):
+        assert parse_dbt_version_minor("1.7.0") == "1.7"
+
+
+class TestDetectEolPage:
+    def test_older_versions_url(self):
+        url = "https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older versions/upgrading-to-v1.5.md"
+        assert detect_eol_page(url) is True
+
+    def test_url_encoded_older_versions(self):
+        url = "https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3.md"
+        assert detect_eol_page(url) is True
+
+    def test_current_upgrade_url(self):
+        url = "https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9.md"
+        assert detect_eol_page(url) is False
+
+    def test_regular_docs_url(self):
+        url = "https://docs.getdbt.com/docs/build/models.md"
+        assert detect_eol_page(url) is False
+
+
+class TestVersionInSearchResponse:
+    @pytest.mark.asyncio
+    async def test_search_includes_dbt_project_version(
+        self, versioned_context, mock_client
+    ):
+        mock_client.search_index.return_value = [
+            {"title": "Models", "url": "https://docs.getdbt.com/docs/build/models"},
+        ]
+        result = await search_product_docs.fn(versioned_context, "models")
+        assert result.dbt_project_version == "1.8"
+
+    @pytest.mark.asyncio
+    async def test_search_version_none_when_not_set(self, context, mock_client):
+        mock_client.search_index.return_value = [
+            {"title": "Models", "url": "https://docs.getdbt.com/docs/build/models"},
+        ]
+        result = await search_product_docs.fn(context, "models")
+        assert result.dbt_project_version is None
+
+    @pytest.mark.asyncio
+    async def test_search_empty_query_still_has_version(self, versioned_context):
+        result = await search_product_docs.fn(versioned_context, "")
+        assert result.dbt_project_version == "1.8"
+        assert result.error is not None
+
+
+class TestVersionInGetPagesResponse:
+    @pytest.mark.asyncio
+    async def test_get_pages_includes_dbt_project_version(
+        self, versioned_context, mock_client
+    ):
+        mock_client.get_page.return_value = "# Page Content"
+        result = await get_product_doc_pages.fn(
+            versioned_context, ["/docs/build/models"]
+        )
+        assert result.dbt_project_version == "1.8"
+
+    @pytest.mark.asyncio
+    async def test_get_pages_version_none_when_not_set(self, context, mock_client):
+        mock_client.get_page.return_value = "# Page Content"
+        result = await get_product_doc_pages.fn(context, ["/docs/build/models"])
+        assert result.dbt_project_version is None
+
+
+class TestEolPageAnnotation:
+    @pytest.mark.asyncio
+    async def test_fetched_eol_page_has_warning(self, context, mock_client):
+        mock_client.get_page.return_value = "# Upgrading to v1.5\n\nOld content."
+        result = await get_product_doc_pages.fn(
+            context,
+            [
+                "https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older versions/upgrading-to-v1.5"
+            ],
+        )
+        page = result.pages[0]
+        assert page.version_note is not None
+        assert "end-of-life" in page.version_note
+        assert page.content.startswith(">>> VERSION NOTICE:")
+
+    @pytest.mark.asyncio
+    async def test_fetched_current_page_no_annotation(self, context, mock_client):
+        mock_client.get_page.return_value = "# Models\n\nCurrent content."
+        result = await get_product_doc_pages.fn(context, ["/docs/build/models"])
+        page = result.pages[0]
+        assert page.version_note is None
+        assert not page.content.startswith(">>>")
+
+
 class TestProductDocsRegistration:
     @pytest.mark.asyncio
     async def test_tools_registered_by_default(self, env_setup):