# `MCP005` Search and filter requirements
{bdg-ref-info}`mcp | tools <mcp:tools>`
{bdg-ref-info}`mcp | query <mcp:query>`
{bdg-ref-info}`mcp | discovery <mcp:discovery>`
> I would like to discover what requirements exist by searching with filters like tags or categories.
> For example, "show me all requirements tagged with 'security'" or "what functional requirements exist?"
> This helps me explore the specification and find related requirements when working on a feature.
> 

The user shall be able to search for requirements using optional filter criteria.

The MCP server shall expose a tool named `search_requirements` that accepts
optional filter parameters and returns matching requirements.

Filter parameters:
- `tag`: Filter by tag (exact match, e.g., "input" or "output:pdf"). If the
  tag does not exist in the loaded specifications, an error shall be returned.
- `category`: Filter by category (exact match, e.g., "functional"). If the
  category does not exist in the loaded specifications, an error shall be returned.

If no filters are provided, all requirements shall be returned.

The response shall be a list of requirement summaries, each containing:
- `id`: The unique identifier
- `short`: The short description (if present)
- `category`: The requirement category
- `tags`: List of tags (if present)

The list shall be sorted alphabetically by ID.


:::{dropdown} Properties
:icon: note
:color: primary

__author__: Claude

__since__: `0.2.0`

:::
:::{dropdown} Tested by
:open: 
:icon: check-circle-fill
:color: success

- [`TMCP011` search_requirements returns all when unfiltered](/tests/TMCP011)
- [`TMCP012` search_requirements filtered by tag](/tests/TMCP012)
- [`TMCP013` search_requirements filtered by namespaced tag](/tests/TMCP013)
- [`TMCP014` search_requirements filtered by category](/tests/TMCP014)
- [`TMCP015` search_requirements errors on unknown tag](/tests/TMCP015)
- [`TMCP031` search_requirements errors on unknown category](/tests/TMCP031)
:::

:::{dropdown} References
:icon: link
:color: secondary

__Referenced by:__
- [`MCP010` Get test plan coverage for requirements](/requirements/MCP010)
- [`MCP011` Search and filter tests](/requirements/MCP011)

:::

:::{dropdown} Source
:icon: file-code
:color: info

__Source file__: [`specs/mcp/discovery.yaml`](https://github.com/agagniere/speky/blob/master/specs/mcp/discovery.yaml)

__Loaded from__: [`speky_mcp`](https://github.com/agagniere/speky/blob/master/specs/mcp/mcp.toml)

__Implemented in:__
{fab}`python` [`handle_search_requirements`](https://github.com/agagniere/speky/blob/master/python/speky_mcp/tools.py#L109)
:::