MCP Server for OSCAL

Overview Schema Source Related Servers Discussions Admin

query_component_definition

Search OSCAL Component Definition documents to find Capabilities and Components by UUID, title, or type, with optional definition filtering and pagination.

Instructions

Query OSCAL Component Definition documents to find Capabilities and Components.

OSCAL Component Definitions follow a hierarchy: a Component Definition contains Capabilities and Components. A Capability groups related Components and describes a higher-level security function. This tool reflects that hierarchy — when a query matches a Capability (by title or UUID), the Capability is returned directly, including its list of incorporated Components. Only when no matching Capability is found does the search fall through to individual Components.

Prefer querying by Capability name/UUID when exploring what a Component Definition offers. Query by Component only when you need details about a specific service, software, region, or similar leaf-level element.

Use the companion tools to discover valid query filters:

list_capabilities() — lists all Capability UUIDs and names
list_components() — lists all Component UUIDs and titles
list_component_definitions() — lists all Component Definition UUIDs and titles

If you need details about the Component Definition schema, use the tool get_oscal_schema.

Args: ctx: MCP server context (injected automatically by MCP server) component_definition_filter: Optional UUID or metadata.title of a Component Definition to narrow the search scope. Case-insensitive for titles. If omitted, all loaded Component Definitions are searched. query_type: Type of query to perform: - "all": Return all components in the definition(s). Intended for use with a component_definition_filter. Results may be large. For a lightweight summary, use list_components() instead. - "by_uuid": Find a Capability or Component by UUID (requires query_value). Capabilities are checked first. - "by_title": Find a Capability by name or a Component by title (requires query_value). Capabilities are checked first; if no Capability matches, Components are searched with a fallback to property-value matching. - "by_type": Filter Components by type (requires query_value). Does not apply to Capabilities. query_value: The value to search for. Required for by_uuid, by_title, and by_type queries. return_format: Response format. Currently only "raw" is supported, returning complete OSCAL objects as OSCAL JSON (hyphenated keys, nulls omitted). offset: Zero-based pagination offset (default 0). limit: Maximum items to return, 1-100 (default 10).

Returns: dict: When a Capability matches, the response contains: - capability: Full OSCAL Capability object as OSCAL JSON - component_count: Number of entries in the Capability's incorporates-components list (0 if absent) - offset, limit, total, hasMore: Pagination metadata (always 0, 1, 1, False for single-capability results) - query_type, component_definitions_searched, filtered_by

When Components are returned instead, the response contains:
    - components: Paginated list of OSCAL Component objects as OSCAL JSON
    - total_count: Total number of matching Components across all pages
    - offset, limit, hasMore: Pagination metadata
    - query_type, component_definitions_searched, filtered_by

Raises: ValueError: If required query parameters are missing or no data is loaded.

Input Schema

TableJSON Schema

Name	Required	Default
`limit`	No
`offset`	No
`query_type`	No	all
`query_value`	No
`return_format`	No	raw
`component_definition_filter`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 30, 2026

TDQS

A4.7/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does so well: it discloses the Capability-first/Component-fallback ordering, warns that the 'all' query may return large results and points to list_components as a lightweight alternative, and states that only return_format='raw' is supported plus the ValueError conditions. It does not explicitly state read-only/no-side-effects, a minor gap for a query tool.

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?

Well-structured with front-loaded hierarchy explanation, then usage guidance, then per-argument docs and returns. The Returns section is somewhat verbose given an output schema exists, but no sentence is wasted and ordering aids scanning.

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?

Given 6 parameters at 0% schema coverage, an output schema, no annotations, and a rich sibling set, the description covers the hierarchy, query semantics, alternatives, parameter meanings, and error modes. An agent has everything needed to invoke and disambiguate correctly.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate and it does: every one of the six parameters is explained, including the meaning of each query_type enum value, that query_value is required for by_*/by_type, case-insensitivity of the definition filter, the offset/limit bounds (1-100), and return_format semantics.

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?

States a specific verb and resource ('Query OSCAL Component Definition documents to find Capabilities and Components') and immediately explains the internal hierarchy and how it maps to query behavior. It clearly distinguishes this tool from the list_* siblings by describing the search/fallthrough semantics.

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?

Explicitly says to prefer querying by Capability name/UUID when exploring and to query by Component only for leaf-level details, and names three companion discovery tools (list_capabilities, list_components, list_component_definitions) plus get_oscal_schema for schema questions. When-to-use and alternatives are both covered.

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

Deploy Server