Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@arc-diagram Validate my architecture doc and scaffold the React Flow diagram project."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that creates polished, interactive architecture-diagram applications instead of returning a diagram string.
The complete Netflix example generates three connected views: system context, application architecture, and the numbered runtime journey from pressing play to Open Connect delivery. It is an illustrative reconstruction from public material—not a claim to reproduce Netflix's full internal design—grounded in the Open Connect overview, appliance and software architecture, and AWS case study.
npm run build
node dist/index.js create examples/netflix-project.json /absolute/path/to/netflix-architectureGive an MCP-capable agent a system description, repository, or design document. The agent distils the source into the arc-diagram contract; this server validates it and scaffolds a complete React Flow application with:
system-context, application, runtime, lifecycle, pyramid, and reference-model dialects;
drag, resize, lasso, keyboard nudge, text sizing, and per-element styling;
light and dark themes;
chrome-free ?embed=<diagramId> views;
cropped 2× PNG exports and a self-contained offline HTML build;
structural validation, canvas-text linting, geometric probes, UX probes, and visual baselines.
The shape is inspired by phxdev1/archy-mcp, but the output is different: Archy produces Mermaid; this project produces an editable multi-view React Flow application.
Related MCP server: arch-viewer
Tool | Purpose |
| Explains when to use each visual grammar. |
| Returns the complete |
| Checks IDs, references, steps, legends, and dialect constraints without writing. |
| Writes a ready-to-run diagram project to an absolute local path. |
The MCP server deliberately has no second AI-provider dependency. The host model already understands the source; the server concentrates on a stable data contract, deterministic scaffolding, and verification.
git clone https://github.com/ArchiJones-AI/arc-diagram-mcp.git
cd arc-diagram-mcp
npm install
npm run buildAdd the built server to any MCP client that accepts a stdio server:
{
"mcpServers": {
"arc-diagram": {
"command": "node",
"args": ["/absolute/path/to/arc-diagram-mcp/dist/index.js"]
}
}
}Restart the client after changing its MCP configuration.
The same engine is usable without an MCP client:
npm run build
node dist/index.js validate examples/minimal-project.json
node dist/index.js create examples/minimal-project.json /absolute/path/to/outputThe second command creates the application; it does not install its dependencies or run browsers. Continue inside the generated directory:
npm install
npm run devInspect the source and choose each view's dialect from its structure or visual metaphor.
Call get_arc_diagram_contract and author DiagramDef objects with evidence in citations.
Call validate_arc_diagram_set until it returns valid: true.
Call create_arc_diagram_project with an absolute, empty destination.
Build and run the generated project's light/dark probes before taking its first visual baseline.
See the authoring contract, the minimal contract example, and the Netflix showcase.
npm install
npm testnpm test compiles the server and exercises validation and deterministic project creation. The embedded template is independently typechecked during the repository smoke test.
Creation requires an absolute output path.
A non-empty destination is refused unless overwrite: true is explicit.
Overwrite mode replaces scaffold-managed files but preserves unrelated files.
Repository analysis and claim grounding remain the responsibility of the calling agent; validation proves structural consistency, not architectural truth.
Apache-2.0.
Create a complete interactive React Flow arc-diagram project from validated DiagramDef objects. The project includes edit mode, embed mode, light/dark themes, geometric probes, PNG export and a self-contained offline HTML build.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Human-readable name for the generated diagram application. | |
| eyebrow | No | Short uppercase label shown above the application title. | |
| diagrams | Yes | Complete DiagramDef objects. Preserve source meaning in the chosen dialect and put evidence in citations. | |
| overwrite | No | Replace files managed by this scaffold while preserving unrelated files. | |
| outputDirectory | Yes | Absolute destination path. Must be empty unless overwrite is true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It says the tool 'creates' a project, which implies a write operation, but it does not disclose that files are written to outputDirectory, that overwrite can replace existing scaffold-managed files, or what happens if the directory is non-empty. These are significant side effects for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence that front-loads the core action and input, then efficiently lists the key output features. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema is rich and covers parameter-level semantics, but the description does not explain the full workflow, such as validating DiagramDef objects first or the file-system impact of the operation. For a complex project-generation tool with no output schema and no annotations, the description leaves some important operational context to be inferred.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds the 'validated' qualifier for DiagramDef objects, which is useful, but it does not otherwise enrich the meaning of title, diagrams, overwrite, or outputDirectory beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Create'), a specific resource ('interactive React Flow arc-diagram project'), and the input type ('validated DiagramDef objects'). It also names concrete output features, which clearly distinguishes it from the sibling tools that list dialects, get contracts, and validate sets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used after validation by saying 'from validated DiagramDef objects', and the sibling validate_arc_diagram_set reinforces that. However, it never explicitly says 'validate first' or names alternatives/exclusions, so the guidance is more implied than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the complete DiagramDef JSON contract plus the core authoring rules used by the renderer.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. 'Return' clearly signals a side-effect-free retrieval operation, and specifying the exact returned content adds transparency about what the tool does. It omits details like response size or format quirks, but those are less critical for a zero-parameter reader tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and object, with no filler or repeated schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool takes no inputs and has no annotations or output schema, the description sufficiently explains what the agent will receive: the complete DiagramDef JSON contract plus the renderer authoring rules. Nothing critical is missing for selecting and invoking this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the schema is an empty object, so there is nothing for the description to add. The zero-parameter baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Return') and a specific artifact ('the complete DiagramDef JSON contract plus the core authoring rules used by the renderer'). This is clearly distinct from listing dialects, validating a set, or creating a project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies when to use it: when an agent needs the DiagramDef contract or renderer authoring rules. However, there is no explicit guidance about when not to use it or how it compares to list_arc_diagram_dialects, validate_arc_diagram_set, or create_arc_diagram_project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the supported arc-diagram visual dialects, their semantics and authoring constraints.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It conveys a read-only listing operation and explicitly names what is returned: 'supported dialects, their semantics and authoring constraints'. It does not discuss permissions or output format, but the 'List' verb makes side effects and mutation unlikely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no wasted words: the action, resource, and content of the result are all front-loaded. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low complexity with no parameters and no output schema, and the description adequately names the result content. It could be slightly more complete by noting the read-only nature explicitly or positioning it against sibling tools, but as a simple listing operation it is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is an empty object with 100% coverage. With no parameters to document, the description does not need to add parameter-level meaning, so the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'List', with a clear resource: 'supported arc-diagram visual dialects'. It also specifies what the list includes ('semantics and authoring constraints'), which distinguishes it from sibling tools like get_arc_diagram_contract, validate_arc_diagram_set, and create_arc_diagram_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but gives no guidance on when to use it versus the sibling tools, no exclusions, and no mention of alternatives. An agent must infer usage from the tool name and sibling list rather than being told.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate diagram identities, references, dialect constraints, steps and control legends without writing files.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Human-readable name for the generated diagram application. | |
| eyebrow | No | Short uppercase label shown above the application title. | |
| diagrams | Yes | Complete DiagramDef objects. Preserve source meaning in the chosen dialect and put evidence in citations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It clearly states that the tool performs validation and does not write files, which is a meaningful side-effect guarantee. It does not describe error behavior or success/failure signaling, but the primary behavioral trait—no file writes—is explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It states the action, the scope of validation, and the key side-effect constraint efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The input schema is large and nested, and there is no output schema, so the description should explain what the validation call returns on success or failure. It does not say whether the tool returns a list of errors, a boolean, or throws an exception, leaving the agent without enough information to interpret the tool's outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with 100% coverage, so the description does not need to repeat their meaning. The description adds no parameter-specific semantics beyond the schema, which sets the baseline at 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb 'Validate' and names the exact resources being validated: diagram identities, references, dialect constraints, steps, and control legends. It also explicitly distinguishes itself from create_arc_diagram_project by noting it does not write files, and its validation role separates it from the list/get sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without writing files' hints that this is a dry-run or pre-flight alternative to create_arc_diagram_project, but there is no explicit statement of when to use this tool versus the list/get siblings. The usage context is implied rather than directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0create_arc_diagram_projectget_arc_diagram_contractlist_arc_diagram_dialectsvalidate_arc_diagram_setScored across 4 tools
Each tool targets a distinct stage of the arc-diagram workflow: listing dialects, retrieving the contract, validating a set, and creating a project. There is no overlap or plausible confusion between the tools.
All tool names follow a consistent verb_noun pattern with the arc_diagram prefix: list, get, validate, and create. The naming is uniform and predictable.
Four tools is well-scoped for the server's purpose: discovery, contract access, validation, and project generation. Each tool earns its place and there is no redundancy.
The tool set covers the full stated pipeline from understanding dialects and the contract, to validating DiagramDef sets, to generating a complete project. There are no obvious gaps or dead ends within the declared domain.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Create and manage Mermaid.js flowcharts and diagrams with AI agents via MCP.
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Public agentic AI doctrine tools plus authenticated architecture, design, and spec validators.
