Traversal Tool
Relevant source files
The following files were used as context for generating this wiki page:
The Traversal Tool module provides Model Context Protocol (MCP) wrappers for the Infrahub graph traversal API. It enables AI agents to discover how objects are connected and perform impact analysis by walking the live data graph. This system replaces recursive schema-depth expansion with direct server-side queries for relationship discovery.
Sources: dev/adr/0008-graph-traversal-over-schema-depth.md:1-24, specs/002-traversal-tools/spec.md:6-12
Architecture and Core Logic
The traversal implementation follows a decoupled architecture, separating core resolution and shaping logic from the MCP tool wrappers. The core logic resides in src/infrahub_mcp/traversal.py, which interacts with the infrahub-sdk to perform path traversal and reachable node lookups.
Sources: specs/002-traversal-tools/plan.md:7-14, specs/002-traversal-tools/research.md:46-51
Node Resolution
The system resolves node references provided as either internal UUIDs or kind-qualified Human-Friendly Identifiers (HFIDs), such as InfraDevice__atl1-edge1. If an HFID is provided, the system parses it using a double-underscore separator and retrieves the node via the SDK client.
Sources: specs/002-traversal-tools/research.md:20-27, src/infrahub_mcp/traversal.py
Request Flow Diagram
The following diagram illustrates the flow of a traversal request from the MCP tool through the core logic to the Infrahub SDK.
Path Discovery
The find_paths tool identifies the shortest route(s) between two objects. It returns ordered hops, where each hop specifies the object reached and the relationship used to reach it.
Sources: specs/002-traversal-tools/spec.md:14-25, src/infrahub_mcp/tools/traversal.py
Tool Parameters: find_paths
| Parameter | Type | Description |
|---|---|---|
source | str | Starting node UUID or kind-qualified HFID. |
destination | str | Ending node UUID or kind-qualified HFID. |
branch | str | None | The branch to query (defaults to main/active session). |
max_depth | int | None | Maximum number of hops to search (default 5). |
kind_filter | list[str] | None | Restrict search to specific node kinds. |
relationship_filter | list[str] | None | Restrict search to specific relationship names. |
| Sources: specs/002-traversal-tools/spec.md:86-90, specs/002-traversal-tools/research.md:39-44 |
Reachability and Blast Radius
The find_reachable tool identifies all nodes of specified kinds reachable from a source object. This is primarily used for impact analysis and dependency discovery.
Sources: specs/002-traversal-tools/spec.md:31-41, src/infrahub_mcp/tools/traversal.py
Tool Parameters: find_reachable
| Parameter | Type | Description |
|---|---|---|
source | str | Starting node UUID or kind-qualified HFID. |
target_kinds | list[str] | The node kinds of interest to find. |
max_depth | int | None | Maximum number of hops from source. |
max_results | int | Cap on the number of results (default 20). |
shortest_paths_only | bool | Whether to return only the shortest path to each node. |
| Sources: specs/002-traversal-tools/spec.md:91-95, specs/002-traversal-tools/research.md:39-44 |
Result Shaping and Token Efficiency
To minimize token usage for AI agents, traversal results are encoded using the project's compact TOON response format. The system shapes results by including minimal per-hop content, such as node kinds and display labels, while reserving full identifiers for top-level source and destination nodes.
Sources: specs/002-traversal-tools/research.md:39-44, src/infrahub_mcp/traversal.py
Sequence Diagram: Traversal Implementation
The sequence below shows how the MCP tool wrapper delegates logic and handles version errors.
Error Handling and Constraints
The traversal tools include specific guards for server compatibility and input validation:
- Version Guarding: The tools require Infrahub Server 1.10 or later. If an older server is connected, the SDK raises a
VersionNotSupportedError, which the tool wrapper translates into aToolErrorwith a remediation hint. - Resolution Failures: If a node HFID cannot be resolved, the tools fail with a message directing the user to node-listing tools.
- Read-Only Integrity: Both tools are registered with
readOnlyHint=Trueand tagged for retrieval, ensuring they do not perform mutations.
Sources: specs/002-traversal-tools/spec.md:96-105, specs/002-traversal-tools/research.md:33-37, src/infrahub_mcp/tools/traversal.py:53-60
Conclusion
The Traversal Tool module provides a high-performance alternative to deep schema inspection for infrastructure discovery. By utilizing server-side graph walks and compact result shaping, it allows agents to perform complex blast-radius and connection analysis while remaining within context token limits.
Sources: dev/adr/0008-graph-traversal-over-schema-depth.md:26-36, specs/002-traversal-tools/spec.md:107-115