usm/mcp-read

MCP read tool — reads and parses a .usm file, returning the full object plus metadata (id, type, version, summary, type-specific counts).

Why this exists

Agents need to read the full content of a specific .usm file to understand a service, feature, or system. The read tool parses the file and returns both the complete data and extracted metadata for quick agent scanning.

How it works

Read pipeline (file access) (read-file)

System pipeline behind usm_read: locate, parse, and return a .usm file with metadata.

1. Get — file path
2. Parse — YAML content into typed object
3. Observe — metadata (type-specific counts for features/flows/contracts/tests)

Ground implementation in the governing spec (grounded-implementation)

The spec-first handoff: a spec author assigns a task, and the agent grounds its implementation in the governing spec via MCP read before touching code.

1. Assign — implementation work on a feature
2. Read — the governing .usm spec via usm_read before editing any code
3. Check — the spec's contracts as acceptance criteria and existing flows for context
4. Review — the agent's summary of what the spec requires before implementation proceeds

Guarantees

read-returns-full-data

Read must return both the full parsed object and metadata

Acceptance criteria:

• [ ] Metadata includes id, type, version, summary
• [ ] System files include featureCount, serviceCount
• [ ] Feature files include flowCount, contractCount, testCount

Test specifications

read-feature-file

Given:

• valid_feature_usm: true

Then:

• assertion: response includes full parsed data
• assertion: metadata includes flowCount, contractCount, testCount

Implementation

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

See Also

• usm/mcp