MCP Tools Reference
Tools available in the USM MCP server for AI agents.
All Tools
| Tool | Summary |
|---|---|
mcp-contracts | MCP contracts tool — extracts the contracts array from a feature .usm file, including id, descriptio |
mcp-flows | MCP flows tool — extracts the flows array from a feature .usm file, including id, name, description, |
mcp-list | MCP list tool — lists all .usm files in a directory or monorepo with id, type, version, and summary, |
mcp-read | MCP read tool — reads and parses a .usm file, returning the full object plus metadata (id, type, ver |
mcp-references | MCP references tool — finds all .usm files that reference a target $id, useful for impact analysis. |
mcp-search | MCP search tool — searches all .usm files for a query string, returning matching files with excerpts |
mcp-summary | MCP summary tool — returns a quick summary of a .usm file with id, type, version, summary, and type- |
mcp-validate | MCP validate tool — validates a .usm file by path or inline YAML content against the v1 JSON Schema. |
mcp-write | MCP write tools — let agents author and update .usm feature specs as part of the spec-first workflow |
mcp-contracts
MCP contracts tool — extracts the contracts array from a feature .usm file, including id, description, applies_after, and must_have.
Purpose:
Agents need to review a feature's contracts to plan tests or verify guarantees. The contracts tool returns the full contracts array from a feature file, formatted for easy agent consumption.
mcp-flows
MCP flows tool — extracts the flows array from a feature .usm file, including id, name, description, and steps.
Purpose:
Agents need to understand user journeys described in feature files. The flows tool returns the complete flows array with step details, enabling agents to reason about the feature's behavior.
mcp-list
MCP list tool — lists all .usm files in a directory or monorepo with id, type, version, and summary, optionally filtered by $type.
Purpose:
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.
mcp-read
MCP read tool — reads and parses a .usm file, returning the full object plus metadata (id, type, version, summary, type-specific counts).
Purpose:
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.
mcp-references
MCP references tool — finds all .usm files that reference a target $id, useful for impact analysis.
Purpose:
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.
mcp-search
MCP search tool — searches all .usm files for a query string, returning matching files with excerpts and relevance scores.
Purpose:
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.
mcp-summary
MCP summary tool — returns a quick summary of a .usm file with id, type, version, summary, and type-specific counts.
Purpose:
Agents need a lightweight overview of a .usm file without reading the full content. Summary returns just the key metadata — id, type, version, summary, and counts (features, services, flows, contracts, tests) — for rapid triage.
mcp-validate
MCP validate tool — validates a .usm file by path or inline YAML content against the v1 JSON Schema.
Purpose:
Agents modifying .usm files need to validate their changes before writing. The validate tool checks a file path or inline YAML string against the schema, returning valid/errors without the agent needing to call the CLI.
mcp-write
MCP write tools — let agents author and update .usm feature specs as part of the spec-first workflow. Adds draft_feature, update_feature, and update_feature_status tools to the MCP server, closing the loop between human discussion and agent implementation.
Purpose:
The current MCP server is read-only — agents can list, read, search, and query existing .usm files, but cannot create or update them. The spec-first workflow requires the agent to write a feature .usm spec from a human discussion, show the human the generated markdown for review, then update the feature after implementation. Without write tools, this loop is broken: the human must manually write YAML, which defeats the purpose of agent-first authoring.