Schema Tool
Relevant source files
The following files were used as context for generating this wiki page:
The Schema Tool allows AI agents and users to discover the data models available within an Infrahub instance. It provides structural information about specific infrastructure "kinds," including their attributes, relationships, and the filters accepted by other retrieval tools. This tool serves as the primary discovery mechanism for agents to understand how to author valid GraphQL queries or use typed node tools.
Sources: specs/002-traversal-tools/spec.md:57-61, CAPABILITIES.md:92-105
Overview and Purpose
The Schema Tool provides a compact JSON representation of the Infrahub catalog. When called without parameters, it returns a list of all available node kinds. When a specific kind is requested, the tool returns detailed metadata, including attributes and relationships. A key feature of the tool is Single-Level Schema Expansion, which inlines the schema of related peer kinds exactly one level deep to assist in query authoring without excessive token usage.
Sources: specs/002-traversal-tools/spec.md:57-73, specs/002-traversal-tools/research.md:32-37
Architecture and Implementation
The Schema Tool is implemented as a read-only MCP tool. It interacts with the Infrahub SDK to fetch schema definitions and processes them to ensure they are token-efficient for AI contexts.
Data Flow
The following diagram illustrates the flow of a schema request through the system:
Single-Level Expansion Logic
The system uses a boolean toggle, INFRAHUB_MCP_SCHEMA_EXPAND_PEERS, to control whether related schemas are inlined.
- Expansion Enabled: Relationships include the peer's attributes and relationships inlined exactly one level deep. Peer blocks omit their own filters to save space.
- Expansion Disabled: Relationships are returned as plain peer references without inlined details.
Sources: specs/002-traversal-tools/spec.md:86-90, specs/002-traversal-tools/research.md:32-37
Tool Parameters and Features
The get_schema tool accepts parameters to scope the discovery process and control the depth of information returned.
| Parameter | Type | Description |
|---|---|---|
kind | string | The specific infrastructure kind to inspect (e.g., InfraDevice). If null, returns the full catalog. |
branch | string | The Infrahub branch to query against. |
expand | boolean | Overrides the server default for peer schema inlining. |
Sources: CAPABILITIES.md:107-111, src/infrahub_mcp/tools/schema.py:12-16
Key Functional Requirements
- FR-008: The tool must inline at most one level of peer schemas and must not recurse further.
- FR-009: Inlined peer schemas must omit filter maps; the root schema retains its full filter map.
- FR-010: Peer inlining is controlled by the
INFRAHUB_MCP_SCHEMA_EXPAND_PEERSsetting. - FR-011: The tool is strictly read-only and is not tagged as a write tool.
Sources: specs/002-traversal-tools/spec.md:86-91
Technical Specifications
Response Formatting
Detailed schema responses are encoded using the TOON tabular format for token efficiency. This format uses a header to declare fields once, followed by rows representing specific attributes or relationships.
Sources: CAPABILITIES.md:270-275, specs/002-traversal-tools/spec.md:85-85
Configuration
The Schema Tool's behavior is influenced by the following environment configuration:
| Variable | Default | Purpose |
|---|---|---|
INFRAHUB_MCP_SCHEMA_EXPAND_PEERS | True | Global toggle for single-level relationship expansion. |
Sources: specs/002-traversal-tools/spec.md:90-90, specs/002-traversal-tools/research.md:32-37
Conclusion
The Schema Tool provides the necessary context for agents to navigate the Infrahub data graph. By implementing a strict single-level expansion policy, it balances the need for descriptive relationship metadata with the constraints of AI context windows, replacing previous recursive depth models with a predictable and efficient discovery mechanism.
Sources: specs/002-traversal-tools/spec.md:104-106, specs/002-traversal-tools/research.md:32-37