Skip to main content
← MCP Tools

get_architecture_brief

Facts for explaining how a repository is put together: its components, which depends on which and how heavily, the layering from foundation to entry point, any dependency cycles, and what each component owns. Returns the facts to write an explanation from, not a written document.

Components are language-agnostic: one per package where the repository has them (a crate, an npm package), and the containing directory otherwise.

Availability: single-repo stdio (travsr mcp) only. Not in global stdio or SSE.

Input schema​

{
"type": "object",
"properties": {
"provenance": {
"type": "string",
"description": "'ratified' (default) excludes the un-ratified live overlay so a bare-name guess cannot invent a dependency; '' accepts everything; any other value names one provenance exactly."
},
"token_budget": {
"type": "integer",
"description": "Approximate size cap for the returned brief, in tokens (default 8000). A brief is meant to be read whole; raise it for a large repository."
}
},
"additionalProperties": false
}

No required fields; call with {} for the default (provenance: "ratified", token_budget: 8000).

Output format​

Plain text, not JSON: a hand-formatted report meant to be read whole, in this order:

  1. A provenance=... | ... header line stating whether tests/benchmarks/docs were excluded.
  2. ## Shape: component count, edge count, layer count, and whether the graph is acyclic.
  3. ## Cycles (N of M), only when at least one dependency cycle exists.
  4. ## Components, by how many others depend on them, capped at 60, each line giving layer, dependent count, dependency count, file count, and symbol count.
  5. ## Dependency edges, heaviest first, capped at 60. Each edge is tagged by where it comes from: code (a resolved reference, weighted by distinct crossing file pairs), manifest (a dependency declared in a package manifest such as Cargo.toml but not seen resolved in code, dev- and build-dependencies included), or code+manifest (both). Counting manifest-declared dependencies means a crate used only through a declaration is no longer shown with too few dependents.
  6. ## What each component owns, capped at 20, with entry points, most-referenced types, and who uses it.
  7. An optional ## Freshness note when Phase B analysis is degraded for a language in the report.
  8. ## What this brief cannot tell you, a fixed disclaimer about missing edges, reference-based type counts, and the absence of causal "why".

Every list discloses how many items were cut when it hits its cap, rather than truncating silently.

Example​

Request:

{ "token_budget": 4000 }

Response (abridged):

ARCHITECTURE BRIEF
provenance=ratified | components are one per package where the repo has them, else the containing directory | tests, benchmarks and docs excluded | snapshot of the code as indexed

## Shape
- 9 components, 14 edges, 4 layers
- acyclic

## Components, by how many others depend on them (9 of 9)
- crates/travsr-core | layer 0 | 5 dependents | depends on 0 | 12 files | 340 symbols
- crates/travsr-store | layer 1 | 3 dependents | depends on 1 | 18 files | 512 symbols
- crates/travsr-retrieval | layer 2 | 2 dependents | depends on 2 | 22 files | 780 symbols
- crates/travsr-mcp | layer 3 | 1 dependent | depends on 3 | 14 files | 940 symbols

## Dependency edges, heaviest first (14 of 14; weight = distinct file pairs crossing)
- crates/travsr-mcp -> crates/travsr-retrieval (18)
- crates/travsr-retrieval -> crates/travsr-store (11)
- crates/travsr-store -> crates/travsr-core (9)

## What each component owns (9 of 9)
### crates/travsr-core
- entry point: crates/travsr-core/src/lib.rs
- most referenced types: Node (412), NodeId (388), VName (201)
- used by: crates/travsr-store, crates/travsr-retrieval, crates/travsr-mcp

## What this brief cannot tell you
- a missing edge means the graph did not resolve it, not that it does not exist
- type counts are references reaching a type or one of its members, so they rank by use and undercount where analysis is incomplete
- nothing here states WHY a dependency exists

When to use​

  • Onboarding or a design review. Get the real dependency shape of a repository instead of trusting a stale diagram in a doc.
  • Spotting an accidental cycle before it becomes a refactor headache.
  • Explaining "what is this codebase" to an agent that has never seen it, before drilling into any one subsystem with get_subsystem_brief.

Notes​

  • Requires resolved cross-file dependency edges; a repository with only structural (Tree-sitter) analysis reports its components with a "no dependencies resolved" note rather than empty edges meaning "independent".
  • provenance: "" includes the un-ratified live overlay (edges from the live editor lane between commits); the default excludes it so a live-only guess cannot invent a dependency that has not been committed.