usm/mcp-search

MCP search tool — searches all .usm files for a query string, returning matching files with excerpts and relevance scores.

Intent

Agents need to find .usm files related to a concept (e.g. "authentication", "billing") without knowing exact file paths. Search scans all files for the query, scores by occurrence count, and returns the top 10 results with excerpts.

Flows

Search .usm files (search-files)

Agent searches for a term across all .usm files

1. get → query string and optional directory
2. parse → each .usm file, serialize to JSON for searching
3. observe → top 10 results sorted by score

Contracts

search-top-10

Search returns the top 10 most relevant results

Acceptance criteria:

• [ ] Case-insensitive by default
• [ ] Score based on occurrence count
• [ ] Excerpt from summary around first match

Tests

search-finds-match

Given:

• usm_files_with_auth_keyword: true

Then:

• assertion: search for "auth" returns relevant files
• assertion: max 10 results returned

Implementation

• Primary: src/mcp/search.ts
• Test code status: none

See Also

• usm/mcp