Skip to main content
Glama
opsmill

infrahub-mcp

Official
by opsmill
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Search Nodes

search_nodes
Read-only

Find Infrahub nodes by partial substring across all attributes of a given kind, so you can locate records when only part of a value is known.

Instructions

Find nodes of a specific kind by partial substring — use when you only know part of a value.

Matches the query as a substring against all attributes of the kind via Infrahub's any__value filter with partial_match=True. Works uniformly on concrete kinds (e.g. LocationSite) and abstract/generic kinds (e.g. CoreNode) — agents can ping any kind without first checking whether it has a name attribute.

For a filter on one specific attribute (or combining multiple filters), use get_nodes with an explicit filters dict instead.

Each result is labelled with the node's display_label when present, falling back to its HFID (kind-prefixed) and finally its UUID — so generic-kind results that lack a display_label still return a human-readable identifier rather than a bare UUID.

To discover available kinds, read the infrahub://schema resource. If your client does not support MCP resources, call the get_schema tool instead.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
kindYesKind to search within. Check infrahub://schema for valid kinds.
limitNoMaximum number of results to return.
queryYesPartial substring matched across all attributes of the kind via Infrahub's ``any__value`` filter with ``partial_match=True``. Works for both concrete kinds (e.g. ``LocationSite``) and abstract/generic kinds (e.g. ``CoreNode``).
branchNoBranch to query. Defaults to the default branch.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.2.0
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "result": {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "type": "object",
-  "x-fastmcp-wrap-result": true
-}New value: +null
  2. Changed1 schema field changedv1.1.6
    • changedInput schema / properties / query / description
      Previous value: -"Partial name/label to search for. Matched against the 'name' attribute of each node."New value: +"Partial substring matched across all attributes of the kind via Infrahub's ``any__value`` filter with ``partial_match=True``. Works for both concrete kinds (e.g. ``LocationSite``) and abstract/generic kinds (e.g. ``CoreNode``)."
  3. First observedv1.1.5

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already establishes this is a safe read, and the description goes beyond that by explaining the any__value partial_match mechanism, uniform behavior across concrete vs abstract kinds, and the display_label/HFID/UUID labelling fallback for results. That is genuine behavioral context, though no pagination or result-count semantics are disclosed. Given annotations already cover the safety profile, a 3 reflects solid added value without full behavioral coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core discriminator in the first sentence, then adds matching semantics, the alternative, and the result-labelling behavior. Slightly long, and the display_label/FHID/UUID explanation is verbose, but each paragraph carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only search tool with no output schema, the description compensates by explaining what results look like (labelled with display_label/HFID/UUID) and how to discover valid kinds. Combined with the explicit alternative routing, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so query, kind, limit, and branch are all documented in the schema. The description restates the query substring semantics and concrete/abstract behavior but adds no new syntax, format, or defaulting detail beyond what the schema provides. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource plus the discriminating condition ('partial substring — use when you only know part of a value'). It explicitly separates itself from the sibling get_nodes, so an agent can route correctly without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States when to use it (partial value, any kind), when not to (a filter on one specific attribute or multiple filters), and names the alternative (get_nodes with explicit filters dict). It also adds a kind-discovery path via infrahub://schema or get_schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools