Nodes Tool
Relevant source files
The following files were used as context for generating this wiki page:
The Nodes Tool module provides functionalities for interacting with individual infrastructure objects, known as nodes, within Infrahub. It serves as the primary interface for AI assistants to list, retrieve, search, create, update, and delete infrastructure state through the Model Context Protocol (MCP).
This module enables high-level operations that bypass raw GraphQL complexities by utilizing the Infrahub SDK's typed node interface. It ensures that all infrastructure interactions remain branch-aware and conform to the project's Branch-Safe by Default principle.
Sources: CAPABILITIES.md:27-147, dev/constitution.md:65-75, specs/002-traversal-tools/spec.md:57-60
Core Node Operations
The Nodes Tool implements several MCP tools categorized into read and write operations. Read operations typically default to the main branch, while write operations are isolated to session branches to protect production data.
Node Retrieval and Search
Retrieval tools allow users to find nodes using specific filters or partial string matches.
- get_nodes: Lists nodes of a specific kind. It supports filtering, pagination via
offsetandlimit, and can return either human-readable display labels or full attribute dictionaries. - search_nodes: Performs partial substring matching against all attributes of a specific node kind. This is useful when the exact attribute name is unknown.
Sources: CAPABILITIES.md:44-66, CAPABILITIES.md:131-147, src/infrahub_mcp/tools/nodes.py
Node Mutation
Mutation tools handle the lifecycle of nodes within an isolated session branch.
- node_upsert: Creates a new node or updates an existing one identified by
idorhfid(Human-Friendly Identifier). It accepts scalar attribute fields within adataobject. - node_delete: Removes a node from the active session branch.
Sources: CAPABILITIES.md:92-113, dev/constitution.md:65-75, src/infrahub_mcp/tools/nodes.py
Architecture and Data Flow
The Nodes Tool acts as a mediator between the MCP Client (AI Assistant) and the Infrahub SDK. It validates inputs before passing them to the SDK to ensure protocol compliance and security.
The Nodes Tool follows a structured flow where tool inputs are validated and then translated into typed Infrahub SDK calls.
Sources: dev/constitution.md:38-48, dev/constitution.md:120-125, specs/001-infrahub-testcontainers/tasks.md:95-100
Tool Parameter Summary
| Tool Name | Parameters | Description |
|---|---|---|
get_nodes | kind, filters, include_attributes, limit, offset, branch | Retrieves nodes with specific filtering. |
search_nodes | kind, query, limit, branch | Substring search across all attributes. |
node_upsert | kind, data, id, hfid | Create/Update nodes on session branch. |
node_delete | kind, id, hfid | Delete nodes on session branch. |
Sources: CAPABILITIES.md:44-147
Implementation Standards
Branch Safety
All write operations target a session branch automatically created on the first mutation (e.g., mcp/session-YYYYMMDD-<hex>). The node_upsert and node_delete tools are explicitly tagged with "write" to trigger safety middleware.
Sources: dev/constitution.md:65-75, CAPABILITIES.md:92-101
Input Resolution
Tools support multi-format identifiers. A node can be referenced by its internal UUID or its kind-qualified Human-Friendly ID (HFID). The system automatically resolves these references before performing graph operations.
The Nodes Tool resolves human-friendly identifiers into internal UUIDs before executing mutations through the SDK.
Sources: specs/002-traversal-tools/spec.md:57-65, CAPABILITIES.md:102-113
Integration Testing
The Nodes Tool is validated using integration tests against real Infrahub containers. These tests ensure that get_nodes correctly handles pagination and filtering against actual data models.
- Pagination Verification: Tests confirm that
total_countandhas_morefields behave correctly when usinglimitandoffset. - Filter Logic: Integration tests exercise
kindfilters and attribute-specific filters (e.g.,name__value) against seeded data.
Sources: tests/integration/test_node_tools.py, specs/001-infrahub-testcontainers/tasks.md:95-100
The Nodes Tool provides a robust, branch-safe interface for managing infrastructure objects, abstracting GraphQL complexities into deterministic MCP tools.