USM

Appearance

MCP Tools Reference ​

Tools available in the USM MCP server for AI agents.

All Tools ​

ToolSummary
usm_draft_featureMCP write tools — let agents author and update .usm feature specs as part of the spec-first workflow
usm_get_contractsMCP contracts tool — extracts the contracts array from a feature .usm file, including id, descriptio
usm_get_flowsMCP flows tool — extracts the flows array from a feature .usm file, including id, name, description,
usm_listMCP list tool — lists all .usm files in a directory or monorepo with id, type, version, and summary,
usm_queryusm_query MCP tool — predicate query over all .usm files. Selectors (features/services/.../all), com
usm_readMCP read tool — reads and parses a .usm file, returning the full object plus metadata (id, type, ver
usm_referencesMCP references tool — finds all .usm files that reference a target $id, useful for impact analysis.
usm_report_feedbackAgent feedback protocol — teaches AI agents a consistent, configurable way to surface bugs and impro
usm_searchMCP search tool — searches all .usm files for a query string, returning matching files with excerpts
usm_summaryMCP summary tool — returns a quick summary of a .usm file with id, type, version, summary, and type-
usm_update_featureMCP write tools — let agents author and update .usm feature specs as part of the spec-first workflow
usm_update_feature_statusMCP write tools — let agents author and update .usm feature specs as part of the spec-first workflow
usm_validateMCP validate tool — validates a .usm file by path or inline YAML content against the v1 JSON Schema.
usm_write_featureMCP write tools — let agents author and update .usm feature specs as part of the spec-first workflow

usm_draft_feature ​

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.

usm_get_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.

usm_get_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.

usm_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.

usm_query ​

usm_query MCP tool — predicate query over all .usm files. Selectors (features/services/.../all), comparisons (= != > < >= <=), contains (~), has, and/or/not with parens. Read-only, capped at 50 by default, hits include paths for direct usm_read.

Purpose:

Agents answering questions like "which planned features have no contracts?" or "what does this service own?" currently list everything (usm_list) or grep raw YAML (usm_search). A typed predicate query over parsed .usm data gives drift checks, impact analysis, and triage in one call — for agents via MCP, mirroring the usm query CLI. Read-only, results capped for context safety.

usm_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.

usm_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.

usm_report_feedback ​

Agent feedback protocol — teaches AI agents a consistent, configurable way to surface bugs and improvements, governed by a schema-driven policy set up at init time, rendered into every agent-facing rules file, and backed by a usm_report_feedback MCP write tool that records structured .usm/feedback entries. Stops agents inventing ad-hoc bug-tracking files.

Purpose:

Agents using USM currently improvise when they discover issues — one agent autonomously created a root-level bugs.md because no canonical protocol exists. There is no taught, configurable behaviour for how an agent should report a bug or suggest an improvement. This feature adds (1) a system.feedback policy block to the v1 schema with three modes — human-gate (default, surface in conversation and ask), direct-to-feedback (write structured entries to .usm/feedback), and direct-to-github (file a real issue via gh); (2) interactive prompts in usm init / scan that ask whether the dev agent has GitHub auth and which policy to use; (3) a shared Feedback Protocol block generated into all four rules files (AGENTS.md, CLAUDE.md, .cursor/rules/usm.mdc, copilot-instructions.md) that renders the project's configured policy and forbids ad-hoc tracking files; and (4) a usm_report_feedback MCP write tool that validates and persists structured feedback entries. One source of truth (system.usm feedback policy) drives consistent agent behaviour across the whole ecosystem.

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.

usm_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.

usm_update_feature ​

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.

usm_update_feature_status ​

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.

usm_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.

usm_write_feature ​

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.

Next steps ​