feat: add get_lineage direction param; mark deprecated tools in README; regenerate contract snapshot

Author: theyostalservice

.changes/unreleased/Enhancement or New Feature-20260629-113027.yaml

@@ -1,3 +1,3 @@
 kind: Enhancement or New Feature
-body: Enrich get_lineage results with a description field per node; deprecate get_model_parents and get_model_children in favor of get_lineage(depth=1)
+body: Enrich get_lineage results with a description field per node; add a direction param (upstream/downstream/both) to narrow results to one side of the graph; deprecate get_model_parents and get_model_children in favor of get_lineage(depth=1, direction=...)
 time: 2026-06-29T11:30:27.420545-07:00

README.md

@@ -50,10 +50,10 @@ To learn more about the dbt Discovery API, click [here](https://docs.getdbt.com/
 - `get_lineage`: Gets full lineage graph (ancestors and descendants) with type and depth filtering.
 - `get_macro_details`: Gets details for a specific macro.
 - `get_mart_models`: Retrieves all mart models.
-- `get_model_children`: Gets downstream dependents of a model.
+- `get_model_children`: Gets downstream dependents of a model. **Deprecated** — use `get_lineage` instead.
 - `get_model_details`: Gets model details including compiled SQL, columns, and schema.
 - `get_model_health`: Gets health signals: run status, test results, and upstream source freshness.
-- `get_model_parents`: Gets upstream dependencies of a model.
+- `get_model_parents`: Gets upstream dependencies of a model. **Deprecated** — use `get_lineage` instead.
 - `get_model_performance`: Gets execution history for a model; option to include test results.
 - `get_related_models`: Finds similar models using semantic search.
 - `get_seed_details`: Gets details for a specific seed.

scripts/generate_docs.py

@@ -4,7 +4,11 @@
 import sys
 from pathlib import Path
 
-from dbt_mcp.tools.readme_mappings import HUMAN_DESCRIPTIONS, TOOLSET_DESCRIPTIONS
+from dbt_mcp.tools.readme_mappings import (
+    DEPRECATED_TOOLS,
+    HUMAN_DESCRIPTIONS,
+    TOOLSET_DESCRIPTIONS,
+)
 from dbt_mcp.tools.toolsets import toolsets
 
 logging.basicConfig(level=logging.INFO, format="%(message)s")
@@ -50,7 +54,11 @@ def generate_readme_tools_section() -> str:
         sorted_tools = sorted(tool_names, key=lambda t: t.value)
         for tool in sorted_tools:
             desc = HUMAN_DESCRIPTIONS.get(tool, "")
-            lines.append(f"- `{tool.value}`: {desc}")
+            line = f"- `{tool.value}`: {desc}"
+            replacement = DEPRECATED_TOOLS.get(tool)
+            if replacement:
+                line += f" **Deprecated** — use `{replacement}` instead."
+            lines.append(line)
 
         lines.append("")  # Empty line after each section
 

src/dbt_mcp/discovery/client.py

@@ -12,7 +12,7 @@
 from dbt_mcp.errors import InvalidParameterError, ToolCallError
 from dbt_mcp.errors.common import NotFoundError
 from dbt_mcp.gql.errors import raise_gql_error
-from dbt_mcp.tools.parameters import LineageResourceType
+from dbt_mcp.tools.parameters import LineageDirection, LineageResourceType
 
 DEFAULT_PAGE_SIZE = 100
 DEFAULT_MAX_NODE_QUERY_LIMIT = 10000
@@ -819,6 +819,7 @@ async def fetch_lineage(
         unique_id: str,
         depth: int,
         types: list[LineageResourceType] | None = None,
+        direction: LineageDirection = LineageDirection.BOTH,
         *,
         config: DiscoveryConfig,
     ) -> list[dict]:
@@ -828,10 +829,11 @@ async def fetch_lineage(
             unique_id: The dbt unique ID of the resource to get lineage for.
             depth: how many levels to traverse (0 = infinite, 1 = immediate neighbors only, higher = deeper)
             types: List of resource types to include. If None, includes all types.
+            direction: Which direction(s) to traverse relative to unique_id.
             config: Discovery API connection and environment.
 
         Returns:
-            List of nodes connected to unique_id (upstream + downstream).
+            List of nodes connected to unique_id, filtered to `direction`.
         """
         if depth < 0:
             raise ToolCallError("Depth must be greater than or equal to 0")
@@ -857,17 +859,22 @@ async def fetch_lineage(
         )
 
         # Filter to connected nodes only
-        return self._filter_connected_nodes(all_nodes, unique_id, depth)
+        return self._filter_connected_nodes(all_nodes, unique_id, depth, direction)
 
     def _filter_connected_nodes(
-        self, nodes: list[dict], target_id: str, depth: int
+        self,
+        nodes: list[dict],
+        target_id: str,
+        depth: int,
+        direction: LineageDirection = LineageDirection.BOTH,
     ) -> list[dict]:
-        """Return only nodes connected to target_id (upstream and downstream).
-        Uses BFS to find all nodes reachable from target in both directions.
+        """Return only nodes connected to target_id, filtered to `direction`.
+        Uses BFS to find all nodes reachable from target in the requested direction(s).
         Args:
             nodes: List of all nodes in the lineage graph.
             target_id: The unique ID of the target node.
             depth: how many levels to traverse (0 = infinite, 1 = immediate neighbors only, higher = deeper)
+            direction: Which direction(s) to traverse relative to target_id.
         """
         node_map = {
             n["uniqueId"]: n
@@ -882,6 +889,15 @@ def _filter_connected_nodes(
         if target_id not in node_map:
             return []
 
+        include_upstream = direction in (
+            LineageDirection.UPSTREAM,
+            LineageDirection.BOTH,
+        )
+        include_downstream = direction in (
+            LineageDirection.DOWNSTREAM,
+            LineageDirection.BOTH,
+        )
+
         # BFS to find all connected nodes
         connected = {target_id}
         queue = [(target_id, 0)]
@@ -897,22 +913,24 @@ def _filter_connected_nodes(
                 continue
 
             # Traverse upstream (parents)
-            for parent_id in node.get("parentIds", []):
-                if parent_id not in connected and parent_id in node_map:
-                    connected.add(parent_id)
-                    queue.append((parent_id, current_depth + 1))
+            if include_upstream:
+                for parent_id in node.get("parentIds", []):
+                    if parent_id not in connected and parent_id in node_map:
+                        connected.add(parent_id)
+                        queue.append((parent_id, current_depth + 1))
 
             # Traverse downstream (children)
-            for candidate in nodes:
-                candidate_id = candidate.get("uniqueId")
-                if not candidate_id or candidate_id not in node_map:
-                    continue
-                if (
-                    current_id in candidate.get("parentIds", [])
-                    and candidate_id not in connected
-                ):
-                    connected.add(candidate_id)
-                    queue.append((candidate_id, current_depth + 1))
+            if include_downstream:
+                for candidate in nodes:
+                    candidate_id = candidate.get("uniqueId")
+                    if not candidate_id or candidate_id not in node_map:
+                        continue
+                    if (
+                        current_id in candidate.get("parentIds", [])
+                        and candidate_id not in connected
+                    ):
+                        connected.add(candidate_id)
+                        queue.append((candidate_id, current_depth + 1))
 
         # Return in original order
         return [node_map[uid] for uid in connected]

src/dbt_mcp/discovery/param_descriptions.py

@@ -36,15 +36,17 @@
 
 # Not a JSON Schema param description — used as the `arg_mapping` for the
 # get_model_parents/get_model_children deprecation banner. get_lineage isn't a
-# drop-in: it requires unique_id (these tools accept name alone), defaults to
-# depth=5, and even at depth=1 returns the target node plus BOTH parents and
-# children (LineageFetcher._filter_connected_nodes traverses parentIds in both
-# directions) — callers must filter the result themselves to isolate one
-# direction, using the parentIds field each node already carries.
-GET_LINEAGE_ARG_MAPPING = (
-    "Call get_lineage(unique_id=..., depth=1) — it requires unique_id (not name) "
-    "and, at depth=1, returns the target node plus both parents and children "
-    "(not filtered to one direction). Derive one direction from the result via "
-    "parentIds: parents are nodes whose uniqueId is in the target's parentIds; "
-    "children are nodes whose parentIds contain the target's uniqueId."
+# drop-in on its own: it requires unique_id (these tools accept name alone) and
+# defaults to depth=5. The `direction` param (upstream/downstream/both) makes it
+# a true drop-in once both differences are called out.
+GET_MODEL_PARENTS_ARG_MAPPING = (
+    'Call get_lineage(unique_id=..., depth=1, direction="upstream") — it '
+    'requires unique_id (not name) and defaults to depth=5; direction="upstream" '
+    "returns only parents, matching this tool's behavior."
+)
+
+GET_MODEL_CHILDREN_ARG_MAPPING = (
+    'Call get_lineage(unique_id=..., depth=1, direction="downstream") — it '
+    'requires unique_id (not name) and defaults to depth=5; direction="downstream" '
+    "returns only children, matching this tool's behavior."
 )

src/dbt_mcp/discovery/tools.py

@@ -18,7 +18,8 @@
     SourcesFetcher,
 )
 from dbt_mcp.discovery.param_descriptions import (
-    GET_LINEAGE_ARG_MAPPING,
+    GET_MODEL_CHILDREN_ARG_MAPPING,
+    GET_MODEL_PARENTS_ARG_MAPPING,
     MACRO_INCLUDE_DEFAULT_DBT_PACKAGES,
     MACRO_PACKAGE_NAMES,
     MACRO_RETURN_PACKAGE_NAMES_ONLY,
@@ -32,12 +33,13 @@
 from dbt_mcp.tools.deprecation import deprecated_description, deprecation_meta
 from dbt_mcp.tools.fields import (
     DEPTH_FIELD,
+    DIRECTION_FIELD,
     NAME_FIELD,
     TYPES_FIELD,
     UNIQUE_ID_FIELD,
     UNIQUE_ID_REQUIRED_FIELD,
 )
-from dbt_mcp.tools.parameters import LineageResourceType
+from dbt_mcp.tools.parameters import LineageDirection, LineageResourceType
 from dbt_mcp.tools.register import register_tools
 from dbt_mcp.tools.tool_names import ToolName
 from dbt_mcp.tools.toolsets import Toolset
@@ -163,7 +165,7 @@ async def get_model_details(
 
 @dbt_mcp_tool(
     description=deprecated_description(
-        replacement="get_lineage", arg_mapping=GET_LINEAGE_ARG_MAPPING
+        replacement="get_lineage", arg_mapping=GET_MODEL_PARENTS_ARG_MAPPING
     ),
     meta=deprecation_meta(replacement="get_lineage"),
     title="Get Model Parents",
@@ -184,7 +186,7 @@ async def get_model_parents(
 
 @dbt_mcp_tool(
     description=deprecated_description(
-        replacement="get_lineage", arg_mapping=GET_LINEAGE_ARG_MAPPING
+        replacement="get_lineage", arg_mapping=GET_MODEL_CHILDREN_ARG_MAPPING
     ),
     meta=deprecation_meta(replacement="get_lineage"),
     title="Get Model Children",
@@ -266,10 +268,15 @@ async def get_lineage(
     unique_id: str = UNIQUE_ID_REQUIRED_FIELD,
     types: list[LineageResourceType] | None = TYPES_FIELD,
     depth: int = DEPTH_FIELD,
+    direction: LineageDirection = DIRECTION_FIELD,
 ) -> list[dict]:
     config = await context.config_provider.get_config()
     return await context.lineage_fetcher.fetch_lineage(
-        unique_id=unique_id, types=types, depth=depth, config=config
+        unique_id=unique_id,
+        types=types,
+        depth=depth,
+        direction=direction,
+        config=config,
     )
 
 

src/dbt_mcp/discovery/tools_multiproject.py

@@ -23,7 +23,8 @@
 )
 from dbt_mcp.discovery.param_descriptions import (
     DISCOVERY_PROJECT_ID_DESCRIPTION,
-    GET_LINEAGE_ARG_MAPPING,
+    GET_MODEL_CHILDREN_ARG_MAPPING,
+    GET_MODEL_PARENTS_ARG_MAPPING,
     MACRO_INCLUDE_DEFAULT_DBT_PACKAGES,
     MACRO_PACKAGE_NAMES,
     MACRO_RETURN_PACKAGE_NAMES_ONLY,
@@ -37,12 +38,13 @@
 from dbt_mcp.tools.deprecation import deprecated_description, deprecation_meta
 from dbt_mcp.tools.fields import (
     DEPTH_FIELD,
+    DIRECTION_FIELD,
     NAME_FIELD,
     TYPES_FIELD,
     UNIQUE_ID_FIELD,
     UNIQUE_ID_REQUIRED_FIELD,
 )
-from dbt_mcp.tools.parameters import LineageResourceType
+from dbt_mcp.tools.parameters import LineageDirection, LineageResourceType
 from dbt_mcp.tools.register import register_tools
 from dbt_mcp.tools.tool_names import ToolName
 from dbt_mcp.tools.toolsets import Toolset
@@ -175,7 +177,7 @@ async def get_model_details(
 
 @dbt_mcp_tool(
     description=deprecated_description(
-        replacement="get_lineage", arg_mapping=GET_LINEAGE_ARG_MAPPING
+        replacement="get_lineage", arg_mapping=GET_MODEL_PARENTS_ARG_MAPPING
     ),
     meta=deprecation_meta(replacement="get_lineage"),
     title="Get Model Parents",
@@ -197,7 +199,7 @@ async def get_model_parents(
 
 @dbt_mcp_tool(
     description=deprecated_description(
-        replacement="get_lineage", arg_mapping=GET_LINEAGE_ARG_MAPPING
+        replacement="get_lineage", arg_mapping=GET_MODEL_CHILDREN_ARG_MAPPING
     ),
     meta=deprecation_meta(replacement="get_lineage"),
     title="Get Model Children",
@@ -284,10 +286,15 @@ async def get_lineage(
     unique_id: str = UNIQUE_ID_REQUIRED_FIELD,
     types: list[LineageResourceType] | None = TYPES_FIELD,
     depth: int = DEPTH_FIELD,
+    direction: LineageDirection = DIRECTION_FIELD,
 ) -> list[dict]:
     config = await context.config_provider.get_config(project_id=project_id)
     return await context.lineage_fetcher.fetch_lineage(
-        unique_id=unique_id, types=types, depth=depth, config=config
+        unique_id=unique_id,
+        types=types,
+        depth=depth,
+        direction=direction,
+        config=config,
     )
 
 

src/dbt_mcp/prompts/discovery/get_lineage.md

@@ -10,7 +10,12 @@ A list of all nodes in the connected subgraph, where each node contains:
 - `description`: The resource's description, if one is defined (may be null)
 - `parentIds`: List of unique IDs that this resource directly depends on
 
-Call `get_lineage(unique_id=..., depth=1)` to retrieve only the immediate parents and children of a resource.
+Call `get_lineage(unique_id=..., depth=1)` to retrieve the target node plus only its immediate parents and children.
+
+Use `direction` to narrow the response to one side of the graph and reduce payload size:
+- `direction="upstream"`: target node plus ancestors only (no descendants)
+- `direction="downstream"`: target node plus descendants only (no ancestors)
+- `direction="both"` (default): target node plus both ancestors and descendants
 
 **Example Response:**
 ```json
@@ -52,6 +57,12 @@ get_lineage(unique_id="model.analytics.customers", depth=1)
 
 # Get deeper lineage for comprehensive analysis
 get_lineage(unique_id="model.analytics.customers", depth=10)
+
+# Get only upstream dependencies (ancestors), e.g. for dependency tracking
+get_lineage(unique_id="model.analytics.customers", direction="upstream")
+
+# Get only downstream dependents (descendants), e.g. for impact analysis
+get_lineage(unique_id="model.analytics.customers", direction="downstream")
 ```
 
 **Traversing the Graph:**

src/dbt_mcp/tools/fields.py

@@ -2,6 +2,8 @@
 
 from pydantic import Field
 
+from dbt_mcp.tools.parameters import LineageDirection
+
 
 _UNIQUE_ID_DESCRIPTION = (
     "Fully-qualified unique ID of the resource. "
@@ -40,3 +42,10 @@
     "If not provided, includes all types. "
     "Valid types: Model, Source, Seed, Snapshot, Exposure, Metric, SemanticModel, SavedQuery, Test.",
 )
+
+DIRECTION_FIELD = Field(
+    default=LineageDirection.BOTH,
+    description="Which direction(s) of the graph to return, relative to the target node: "
+    "`upstream` (ancestors/parents only), `downstream` (descendants/children only), "
+    "or `both` (default). Narrowing to one direction reduces response size.",
+)

src/dbt_mcp/tools/parameters.py

@@ -15,3 +15,11 @@ class LineageResourceType(StrEnum):
     SEMANTIC_MODEL = "SemanticModel"
     SAVED_QUERY = "SavedQuery"
     TEST = "Test"
+
+
+class LineageDirection(StrEnum):
+    """Which direction(s) of the lineage graph to include, relative to the target."""
+
+    UPSTREAM = "upstream"
+    DOWNSTREAM = "downstream"
+    BOTH = "both"