query_component_definition
Query OSCAL Component Definitions to find capabilities and components. Supports searching by UUID, title, or type, with capabilities prioritized over components.
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 JSON. 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 JSON - component_count: Number of Components the Capability incorporates - 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 JSON
- total_count: Total number of matching Components across all pages
- offset, limit, hasMore: Pagination metadata
- query_type, component_definitions_searched, filtered_byRaises: ValueError: If required query parameters are missing or no data is loaded.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| component_definition_filter | No | ||
| query_type | No | all | |
| query_value | No | ||
| return_format | No | raw | |
| offset | No | ||
| limit | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||