usm/mcp-references

MCP references tool — finds all .usm files that reference a target $id, useful for impact analysis.

Intent

Before modifying a service or feature, agents need to know what else depends on it. The references tool searches all .usm files for a target $id (e.g. smith-gray/zitadel) and returns every file and field that references it.

Flows

Find references to a $id (find-references)

Agent searches for all files referencing a specific $id

1. get → target_id string
2. parse → each .usm file, recursively walk object for target_id
3. observe → hits with path, id, type, and context (field path)

Contracts

references-deep-walk

References must walk the entire object tree, not just top-level fields

Acceptance criteria:

• [ ] Finds references in $system, $service, depends_on, see_also, and nested objects
• [ ] Returns context field showing where the reference was found
• [ ] Results sorted by path

Tests

references-find-system

Given:

• files_referencing_system_id: true

Then:

• assertion: All files with $system matching target returned
• assertion: context includes the field name (e.g. "$system")

Implementation

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

See Also

• usm/mcp