Diagrams MCP Server

DIAGRAMS MCP SERVER ===================

Engineering documentation for a local first MCP server that keeps PlantUML and Mermaid diagrams beside the code they describe

The server gives an MCP client a controlled interface for reading and maintaining diagram source and for comparing that source with a codebase It also produces reviewable diagram drafts and rendered exports Source files remain the editable record of the architecture

READING PATHS =============

Start with installation and the diagram workflow to connect a client and review changes Choose your editor or assistant from the supported clients Read the system model and configuration to understand process boundaries and renderer requirements Use tool contracts and operational limits when integrating or troubleshooting For contribution work follow source organization and the engineering documentation index The index separates current guidance from historical design and handoff records

PROJECT STATUS ==============

The project is a technical preview Version zero eleven zero contains fifteen tools Check the installed package version when comparing its behavior with this guide

Version zero ten zero adds nullable and array scaffold labels and corrects sequence sender ownership when caller names collide across files

The package declares Node 18 or newer as its runtime requirement Current main continuous integration checks Node 20 and Node 22 and Node 24 on Ubuntu and Windows The TypeScript compiler is a development dependency rather than a required production dependency

INSTALLATION AND CLIENT CONNECTION ==================================

Install the published server with npm:

npm install -g diagrams-mcp-server

Run guided setup from the project directory:

diagrams-mcp-server setup

Supported MCP clients

Choose a client below for noninteractive setup Install the selected client before using its integration The table describes the setup methods implemented by this server

Project scope and verification

For a Cursor configuration pinned to the current project:

diagrams-mcp-server setup --client cursor --scope project --yes

Global scope is the default and leaves PROJECT_ROOT out of the server entry The server then uses the working directory supplied by the launching client Project scope places PROJECT_ROOT in the configuration so the server stays attached to one codebase An explicit --project-root also pins the root VS Code setup writes project configuration OpenCode setup prints instructions only so configure its project environment manually when a fixed PROJECT_ROOT is required

After setup reload the client configuration and inspect its available tools Use diagrams_list to confirm the diagrams root before creating files An empty inventory is valid for a new project

Other stdio MCP clients can launch diagrams-mcp-server directly or use npx with arguments -y diagrams-mcp-server The server command accepts no tool requests through ordinary CLI arguments Tool calls travel through the MCP connection

For available startup and setup options:

diagrams-mcp-server --help diagrams-mcp-server setup --help

WORKING WITH DIAGRAMS =====================

Start by discovering existing diagrams with diagrams_list Read the selected source with diagrams_get before proposing a change Use diagrams_diff to compare the existing source with a proposed revision Then apply the reviewed revision through diagrams_update Use diagrams_create for a new diagram and diagrams_delete for explicit removal

Create refuses an existing target Update operates on an existing diagram Storage validates recognized diagram extensions and source structure These checks establish basic dialect shape rather than full language correctness Use rendering and human review to inspect the resulting diagram

For a new architecture draft use diagrams_generate on a narrow code scope For a call flow draft use diagrams_generate_sequence For a blank design use diagrams_template These tools return source for review without saving a diagram Pass reviewed source to diagrams_create when you decide to persist it

Run diagrams_check_consistency after a code change to inspect declaration evidence for diagram entities Treat unmatched names as review prompts An unmatched name can reflect unsupported syntax or incomplete scanning rather than an architectural defect

This workflow connects the tools through explicit review steps The arrows describe a suggested user workflow rather than an automatic pipeline Generation and comparison do not save files on your behalf

flowchart TB

accTitle: Diagram review workflow accDescr: Read or draft source then review and compare before explicitly saving and rendering and checking consistency stored["Read existing diagram source"] --> review["Review source"] draft["Generate or template a draft"] --> review review --> compare["Compare revisions when needed"] compare --> save["Explicit create or update"] save --> render["Render and inspect"] render --> check["Check consistency against code"] check -->|Revise when needed| review

SYSTEM MODEL ============

An MCP client starts the server as a child process and exchanges protocol messages over standard input and standard output Startup diagnostics use standard error so they do not occupy the protocol stream

The project root defines the code analysis boundary The diagrams root defines the diagram storage boundary Custom template definitions are read separately beneath the project root These roots are resolved once when the server starts Diagram paths supplied to tools are relative to the diagrams root Code scopes supplied to analysis tools are relative to the project root

The architecture separates protocol handling from services and external resources Responses return through the tool adapter to the connected client

flowchart TB

accTitle: System architecture accDescr: MCP requests pass through strict schemas and adapters to storage and analysis and rendering services client["MCP client"] <-->|stdio| server["CLI and MCP server"] server --> schemas["Strict input schemas"] schemas --> adapters["Tool adapters"] adapters --> store["Diagram storage"] adapters --> analysis["Analysis and generation"] adapters --> rendering["Rendering service"] store --> diagrams[("Diagrams root")] analysis --> code[("Project root")] rendering --> external["Local commands or opt in PlantUML endpoint"]

Tool adapters own protocol contracts and response formatting Services own filesystem operations and analysis and source generation Renderers invoke external command line tools through a separate command boundary Expected domain failures become tool errors Unexpected failures return a generic error and are logged through the shared error handling layer

CONFIGURATION AND RENDERING ===========================

PROJECT_ROOT selects the codebase used for analysis Its default is the server process working directory

DIAGRAMS_DIR selects the diagrams root Its default is the diagrams directory beneath PROJECT_ROOT A relative value is resolved beneath PROJECT_ROOT An absolute value selects a separate storage location Restart the server after changing either root

Rendering requires a working external renderer on PATH PlantUML uses the plantuml command Mermaid uses the mmdc command from the Mermaid CLI package The server package does not install either renderer for you External renderer packages have their own runtime requirements

To install the Mermaid command:

npm install -g @mermaid-js/mermaid-cli

PlantUML rendering prefers the local command When that command is missing remote fallback remains disabled unless ALLOW_REMOTE_PLANTUML is exactly true DISABLE_REMOTE_PLANTUML set to exactly true overrides that permission PLANTUML_SERVER_URL selects the remote endpoint when fallback is enabled The default endpoint is the public PlantUML rendering service

Remote fallback sends diagram source to the configured server Mermaid rendering always uses the local command A local renderer execution failure is an error rather than a reason to retry remotely Rendering uses temporary files that are cleaned up after the operation

Renderer selection follows the decision chart below Remote permission means ALLOW_REMOTE_PLANTUML is exactly true while DISABLE_REMOTE_PLANTUML is not true Only a missing local PlantUML command reaches that decision

flowchart TB

accTitle: Renderer selection accDescr: Mermaid uses mmdc while PlantUML uses a local CLI or an explicitly permitted remote endpoint dialect{"Dialect"} -->|Mermaid| mermaid["Run local mmdc"] dialect -->|PlantUML| local{"Local plantuml command"} local -->|Available| plantuml["Run local plantuml"] local -->|Missing| permission{"Remote fallback allowed"} permission -->|No| failure["Return a render error"] permission -->|Yes| remote["Send source to configured endpoint"]

TOOL CONTRACTS ==============

The chart groups the fifteen tools by their primary purpose It describes the tool surface rather than project completion

pie showData

accTitle: Tool categories accDescr: Five storage tools and three rendering tools and two analysis tools and four diagram drafting and template tools and one code drafting tool title Tool categories "Diagram storage" : 5 "Rendering and sharing" : 3 "Analysis and comparison" : 2 "Diagram drafting and templates" : 4 "Code drafting" : 1

Inventory and source access

diagrams_list supports type_filter and zero based offset pagination An explicit limit accepts 1 through 500 Omitting limit returns all remaining matches The response distinguishes the page count from the total and reports has_more so callers can continue without guessing

diagrams_get returns complete source unless max_chars requests a window An explicit window accepts 1 through 100000 UTF-16 code units The response reports offset and returned_chars and total_chars together with is_partial and has_more An offset beyond the source is an error

diagrams_create and diagrams_update and diagrams_delete are the explicit diagram mutation tools All fifteen tools in the current checkout reject unknown input arguments Clients should use the tool schemas exposed by MCP discovery as the exact argument reference

Analysis and comparison

diagrams_check_consistency compares extracted diagram names with source declaration evidence and reports matched files and analyzer tiers Its extractors include language specific declaration patterns and a generic whole word fallback The optional TypeScript compiler improves selected analysis paths The result remains heuristic and does not establish runtime correct