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

Retrieve the raw source text of a single PlantUML or Mermaid diagram, in full or as an explicit character window.

Args:

• relative_path (string): Path to the diagram relative to the diagrams root, as returned by diagrams_list

• offset (number, optional): Zero-based character offset where the returned window starts (default: 0)

• max_chars (number, optional): Maximum characters to return from offset (1-100000). Omit to return the full source

Returns: JSON with schema: { "relative_path": string, "type": "plantuml" | "mermaid", "content": string, // full source, or the requested [offset, offset+max_chars) window "is_partial": boolean, // true when content is a window rather than the full source "offset": number, // effective character offset of this window "total_chars": number, // full source length in characters "returned_chars": number,// length of the returned content "has_more": boolean // true when source after this window remains }

The text block always equals structuredContent.content. Content is never silently truncated: omitting offset/max_chars returns everything, and requesting a window is always reported via is_partial/has_more.

Examples:

• Use when: "Show me the order-flow diagram" -> relative_path="system/order-flow.puml"

• Use when: "Read the first 2000 characters of the big diagram" -> relative_path="...", offset=0, max_chars=2000, then offset=2000 for the next window

• Don't use when: You need to list what diagrams exist first (use diagrams_list)

Error Handling:

• Returns "Error: No diagram found at ''" if the file doesn't exist

• Returns "Error: Refused to access path outside the diagrams root" if relative_path attempts to escape the diagrams directory (e.g. via '../..')

• Returns "Error: Invalid source window: ..." if offset/max_chars are negative, non-integer, or max_chars is outside 1-100000

• Returns "Error: offset is out of range ..." if offset points past the end of the source

• Unexpected internal failures return a generic "Error: Unexpected internal error ..." with isError:true and are logged to stderr without source, paths, or secrets

Create a new PlantUML or Mermaid diagram file under the diagrams root.

The diagram type is inferred from the file extension in relative_path:

• .puml or .plantuml -> PlantUML

• .mmd or .mermaid -> Mermaid

This tool refuses to overwrite an existing file — use diagrams_update for that. Intermediate directories in relative_path are created automatically.

Performs a basic, dependency-free syntax check before writing (not full validation): PlantUML must include @startuml/@enduml boundaries; Mermaid must start with a known diagram declaration. Clearly invalid or empty sources are rejected without creating a file.

Args:

• relative_path (string): Path for the new file, relative to the diagrams root, with a recognized extension

• content (string): Full diagram source text

Returns: JSON with schema: { "relative_path": string, "created": true }

Examples:

• Use when: "Create a class diagram for the User model" -> relative_path="models/user-class.puml", content="@startuml\nclass User {\n +id: int\n}\n@enduml"

• Don't use when: The file already exists and you want to change it (use diagrams_update instead)

Error Handling:

• Returns "Error: ... already exists" if a file already exists at relative_path

• Returns "Error: ... does not have a recognized diagram extension" if the extension isn't one of .puml/.plantuml/.mmd/.mermaid

• Returns "Error: Invalid PlantUML diagram (basic check): ..." if PlantUML source is empty or missing @startuml/@enduml boundaries

• Returns "Error: Invalid Mermaid diagram (basic check): ..." if Mermaid source is empty or has no recognized diagram declaration

• Returns "Error: Refused to access path outside the diagrams root" if relative_path attempts to escape the diagrams directory

• Unexpected internal failures return a generic "Error: Unexpected internal error ..." with isError:true and are logged to stderr without source, paths, or secrets

Replace the full content of an existing PlantUML or Mermaid diagram file.

This performs a full-content replace, not a partial edit — pass the complete new diagram source. To create a new diagram, use diagrams_create (or set create_if_missing=true here).

Performs a basic, dependency-free syntax check before writing (not full validation): PlantUML must include @startuml/@enduml boundaries; Mermaid must start with a known diagram declaration. Clearly invalid or empty sources are rejected without overwriting the existing file.

Args:

• relative_path (string): Path to the diagram, relative to the diagrams root

• content (string): Full new diagram source text

• create_if_missing (boolean): Create the file instead of erroring if it doesn't exist (default: false)

Returns: JSON with schema: { "relative_path": string, "updated": true }

Examples:

• Use when: "Add a new field to the User class diagram" -> read current content with diagrams_get first, then call diagrams_update with the modified full content

• Don't use when: The file doesn't exist yet and you don't want auto-creation (use diagrams_create)

Error Handling:

• Returns "Error: No diagram found at ''" if the file doesn't exist and create_if_missing is false

• Returns "Error: ... does not have a recognized diagram extension" if the extension isn't recognized

• Returns "Error: Invalid PlantUML diagram (basic check): ..." if PlantUML source is empty or missing @startuml/@enduml boundaries (original file left unchanged)

• Returns "Error: Invalid Mermaid diagram (basic check): ..." if Mermaid source is empty or has no recognized diagram declaration (original file left unchanged)

• Returns "Error: Refused to access path outside the diagrams root" if relative_path attempts to escape the diagrams directory

• Unexpected internal failures return a generic "Error: Unexpected internal error ..." with isError:true and are logged to stderr without source, paths, or secrets

Delete a single PlantUML or Mermaid diagram file from the diagrams root.

This is destructive and cannot be undone — the file is removed from disk. To replace content instead, use diagrams_update. To remove then recreate with different content, delete first, then use diagrams_create.

Args:

• relative_path (string): Path to the diagram relative to the diagrams root, as returned by diagrams_list

Returns: JSON with schema: { "relative_path": string, "deleted": true }

Examples:

• Use when: "Remove the outdated order-flow diagram" -> relative_path="system/order-flow.puml"

• Don't use when: You want to change the diagram content but keep the file (use diagrams_update)

Error Handling:

• Returns "Error: No diagram found at ''" if the file doesn't exist

• Returns "Error: Refused to access path outside the diagrams root" if relative_path attempts to escape the diagrams directory (e.g. via '../..')

• Unexpected internal failures return a generic "Error: Unexpected internal error ..." with isError:true and are logged to stderr without source, paths, or secrets

Render a PlantUML or Mermaid diagram to an image (SVG or PNG) and return it as base64-encoded image content.

Rendering requirements:

• Mermaid: requires the 'mmdc' CLI (install with: npm install -g @mermaid-js/mermaid-cli). No fallback exists.

• PlantUML: uses a local 'plantuml' CLI if installed. Without one, rendering fails unless remote rendering is explicitly enabled with ALLOW_REMOTE_PLANTUML=true, in which case it falls back to the configured PlantUML rendering server over HTTPS (requires internet access; sends diagram source to that server). DISABLE_REMOTE_PLANTUML=true always disables the fallback, even when the allow flag is set.

Args:

• relative_path (string): Path to the diagram, relative to the diagrams root

• format ('svg' | 'png'): Output image format (default: 'svg')

Returns: An image content block (base64-encoded), plus a JSON summary: { "relative_path": string, "format": "svg" | "png", "rendered": true }

Examples:

• Use when: "Show me what the order-flow diagram looks like" -> relative_path="system/order-flow.puml", format="svg"

• Don't use when: You just need the raw source text (use diagrams_get instead, it's much cheaper)

Error Handling:

• Returns "Error: No diagram found at ''" if the file doesn't exist

• Returns "Error: Mermaid rendering requires the 'mmdc' CLI..." if rendering a Mermaid diagram without mmdc installed

• Returns "Error: PlantUML rendering requires a local 'plantuml' CLI..." when no local CLI is installed and remote rendering is not explicitly enabled (set ALLOW_REMOTE_PLANTUML=true to opt in)

• Returns "Error: PlantUML rendering server responded with ..." if both local and remote PlantUML rendering fail

• Unexpected internal failures return a generic "Error: Unexpected internal error ..." with isError:true and are logged to stderr without source, paths, or secrets

Compare class/interface/component names mentioned in a PlantUML or Mermaid diagram against identifiers that actually exist in the codebase, to catch documentation drift.

This is a heuristic, text-based check (not a full semantic/AST analysis): it extracts entity names from class/interface/enum/component declarations in the diagram, then searches source files under the project root for a matching identifier as a whole word. It flags names that appear in the diagram but were not found anywhere in the scanned code — a signal the diagram may be outdated, or the code was renamed/removed/not yet built.

This tool does NOT modify the diagram or the code. It only reports findings; the caller (agent or human) decides what to do about them.

Args:

• relative_path (string): Path to the diagram to check, relative to the diagrams root

Returns: JSON with schema: { "diagram_path": string, "entities_found": number, // total entity names extracted from the diagram "entities_matched": number, // how many were found somewhere in the code "entities_unmatched": number, // how many were NOT found (potential drift) "files_scanned": number, // how many source files were searched "searched_directory": string, // absolute path of the code root that was scanned "truncated": boolean, // true when the 5,000-file scan cap was reached; unmatched results may be incomplete "scan_limit": number, // maximum source files collected during the scan "scan_warning": string | null, // human-readable warning when truncated, otherwise null "entities": string[], // extracted entity names, in extraction order "matched_entities": string[], // extracted entities found in the code "unmatched_entities": string[],// extracted entities NOT found (potential drift) "analyzers": { // scanned file extensions per analyzer tier "reliable": string[], // per-language declaration patterns (JS/TS, Python, PHP, Java) "experimental": string[], // generic heuristic path (C#, Go, Ruby, Kotlin, Rust) "generic": string[] // other scanned extensions, heuristic path only }, "confidence": "heuristic", // results are evidence, never a definitive verdict "heuristic_warning": string, // human-readable limits of the heuristic "evidence": [ // per-entity evidence, same order as "entities" { "name": string, "matched": boolean, "analyzers": ("reliable" | "experimental" | "generic")[], "matched_files": string[], // POSIX paths relative to searched_directory (capped) "matched_file_count": number } ], "issues": [ { "name": string, // the unmatched entity name "issue": string, // human-readable explanation "severity": "warning" | "info" } ] }

Examples:

• Use when: "Is this class diagram still accurate compared to the code?" -> relative_path="models/user-class.puml"

• Use when: Reviewing a PR that touches architecture, to check the UML docs weren't left behind

• Don't use when: The diagram has no class/interface/component declarations (e.g. a pure sequence diagram) — entities_found will be 0, which is expected, not an error

Error Handling:

• Returns "Error: No diagram found at ''" if the diagram file doesn't exist

• An empty "issues" array with entities_found=0 means no checkable entities were found in the diagram, not that everything matched

• Unexpected internal failures return a generic "Error: Unexpected internal error ..." with isError:true and are logged to stderr without source, paths, or secrets