usm/mcp-list

MCP list tool — lists all .usm files in a directory or monorepo with id, type, version, and summary, optionally filtered by $type.

Intent

AI agents need to discover what .usm files exist before reading them. The list tool returns a summary of all files, optionally filtered by type, so agents can navigate the system map without reading every file.

Flows

List all .usm files (list-all)

Agent lists all .usm files in the monorepo

1. get → directory path or monorepo root
2. parse → each .usm file for $id, $type, $version, summary
3. observe → filtered results sorted by path

Contracts

list-returns-metadata

List must return path, id, type, version, and summary for each file

Acceptance criteria:

• [ ] Count of files returned
• [ ] Optional $type filter applied
• [ ] Results sorted by path

Tests

list-with-filter

Given:

• usm_files_mixed_types: true

Then:

• assertion: type=service returns only service files
• assertion: count matches filtered set

Implementation

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

See Also

• usm/mcp