List Architecture Diagrams
diagrams_listList PlantUML and Mermaid diagram files in the project's diagrams directory. Filter by diagram type and page through results to find existing diagrams.
Instructions
List all PlantUML and Mermaid diagram files stored under the project's diagrams directory.
This tool scans the configured diagrams root recursively and returns every file with a recognized diagram extension (.puml, .plantuml, .mmd, .mermaid). It does NOT create, modify, or render diagrams — read-only.
Args:
type_filter ('plantuml' | 'mermaid' | 'all'): Restrict results to one diagram type (default: 'all')
offset (number, optional): Zero-based number of matching diagrams to skip (default: 0)
limit (number, optional): Maximum diagrams to return (1-500). Omit to return every remaining match
Returns: JSON with schema: { "diagrams_root": string, // absolute path being scanned "count": number, // number of diagrams in this page "total": number, // number of diagrams matching type_filter, before paging "offset": number, // effective offset of this page "limit": number, // effective limit of this page (requested limit, or remaining count when omitted) "has_more": boolean, // true when diagrams after this page remain "diagrams": [ { "relative_path": string, // path to use with diagrams_get / diagrams_update "type": "plantuml" | "mermaid", "title": string | null, // best-effort extracted title "size_bytes": number, "modified_at": string // ISO 8601 timestamp } ] }
Pagination is explicit: omitting offset/limit returns every match with has_more=false. Nothing is ever silently dropped — has_more tells the caller when to request the next page with offset=<offset+count>.
Examples:
Use when: "What diagrams exist for this project?" -> type_filter="all"
Use when: "Show me all the Mermaid diagrams" -> type_filter="mermaid"
Use when: "List diagrams ten at a time" -> limit=10, then offset=10 for the next page
Don't use when: You already know the exact path and just need its content (use diagrams_get instead)
Error Handling:
Returns an empty "diagrams" array if the diagrams directory doesn't exist yet or is empty (this is not an error)
Returns an empty page (count 0, has_more=false) when offset is past the end of the matches
Returns "Error: Invalid pagination: ..." if offset is negative/non-integer or limit is outside 1-500
Unexpected internal failures return a generic "Error: Unexpected internal error ..." with isError:true and are logged to stderr without source, paths, or secrets
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of diagrams to return (1-500). Omit to return every remaining match. | |
| offset | No | Zero-based number of matching diagrams to skip before the returned page (default: 0). | |
| type_filter | No | Restrict results to a single diagram type, or 'all' for both. | all |