usm/mcp-query [built]

usm_query MCP tool — predicate query over all .usm files. Selectors (features/services/.../all), comparisons (= != > < >= <=), contains (~), has, and/or/not with parens. Read-only, capped at 50 by default, hits include paths for direct usm_read.

Status: built

Why this exists

Agents answering questions like "which planned features have no contracts?" or "what does this service own?" currently list everything (usm_list) or grep raw YAML (usm_search). A typed predicate query over parsed .usm data gives drift checks, impact analysis, and triage in one call — for agents via MCP, mirroring the usm query CLI. Read-only, results capped for context safety.

How it works

Run a predicate query (run-query)

1. Accept — query string plus optional limit
2. Evaluate — same parser and evaluator as the usm query CLI (src/query/index.ts)
3. Return — id, type, status, summary, path per hit, plus total and truncated flag

Guarantees

shared-evaluator

Query grammar shared with the CLI

Acceptance criteria:

• [ ] Selector maps to $type filtering
• [ ] Absent fields make predicates false, never errors
• [ ] Friendly parse errors naming token and position

read-only-capped

Read-only with context-safe capping

Acceptance criteria:

• [ ] No file writes on any query path
• [ ] Default limit 50 with total and truncated in the response

Test specifications

query-via-mcp

Given:

• fixture_project: true

Then:

• assertion: usm_query returns results with id and path
• assertion: limit caps results and sets truncated true

Implementation

• Primary: src/mcp/query.ts
• Test code: tests/query.test.ts
• Test code status: generated

See Also

• usm/query-layer