How do I use it-architecture?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@it-architecture Render an architecture diagram for a three-tier web app with an ALB, API servers, and a database." 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.

it-architecture

by slajzad

Overview Schema Related Servers Score Discussions

Python

Local

it-architecture — MCP server for architecture drawings

An MCP server that turns a text description of an IT architecture into a standalone .svg drawing, in a choice of visual styles.

It is built to run entirely on your VDI:

No dependencies. Pure Python standard library — nothing to pip install, no wheels to get through a proxy. Python 3.8+ is all you need.
No network. No rendering service, no headless browser, no icon CDN, no telemetry. The layout engine, the ~60 component icons and the SVG writer are all in this repository.
No surprises in the output. Every SVG is self-contained: no <script>, no external fonts, no embedded rasters. Safe to commit to git, paste into Confluence/SharePoint, or open in Inkscape or a browser.

customer [user]     "Customer"                 ┌──────────┐      ┌──────────┐
alb      [lb]       "Application LB"           │ Customer │─────▶│   ALB    │─ ─ ▶ …
api      [service]  "Payments API"             └──────────┘      └──────────┘
customer -> alb : "HTTPS"
alb -> api

1. Install

Nothing to build — the checkout is the install.

Windows (`C:\Tools\MCP`)

cd C:\Tools\MCP
git clone <this-repo> mcp-architecture
cd mcp-architecture
py -3 -m itarch.cli render examples\three-tier.arch --style cloud

That writes %USERPROFILE%\architecture-diagrams\three-tier.svg. If it does, the MCP server will work too.

Linux / macOS

git clone <this-repo> ~/tools/mcp-architecture
cd ~/tools/mcp-architecture
python3 -m itarch.cli render examples/three-tier.arch --style cloud

Optionally install it as a command (itarch, itarch-mcp) — still zero dependencies: python -m pip install --user -e .

Related MCP server: Azure Diagram MCP Server

2. Connect it to your local CLI / AI tool

The server speaks JSON-RPC 2.0 and negotiates MCP protocol 2025-06-18, 2025-03-26 or 2024-11-05, whichever the client asks for. Two transports are available; pick the one your client's config wants.

A. HTTP — for clients configured with a `url` (pi.dev and similar)

Start the server, then point the client at it.

Windows — double-click scripts\start-mcp-http.bat, or:

C:\Tools\MCP\mcp-architecture\scripts\start-mcp-http.bat

Linux / macOS:

python3 -m itarch --http                      # 127.0.0.1:8787/mcp
python3 -m itarch --http --port 9000          # somewhere else

Client config (this is mcp.example.json):

{
  "mcpServers": {
    "it-architecture": {
      "url": "http://127.0.0.1:8787/mcp",
      "lifecycle": "eager",
      "directTools": true
    }
  }
}

Check it is up at any time — curl.exe http://127.0.0.1:8787/ returns a one-line health page.

lifecycle: eager means the client connects at startup, so the server has to already be listening. To start it automatically at logon (per-user Scheduled Task, no admin rights):

cd C:\Tools\MCP\mcp-architecture
powershell -ExecutionPolicy Bypass -File .\scripts\install-autostart.ps1
Start-ScheduledTask -TaskName 'it-architecture MCP'      # start now, don't wait for logon

-Port 9000, -OutputDir D:\diagrams and -Uninstall are supported.

B. stdio — for clients that launch the server themselves

Nothing to start by hand; the client spawns it. See mcp.stdio.example.json:

{
  "mcpServers": {
    "it-architecture": {
      "command": "python",
      "args": ["-m", "itarch"],
      "env": { "PYTHONPATH": "C:\\Tools\\MCP\\mcp-architecture" }
    }
  }
}

Claude Code has a shorthand for the same thing:

claude mcp add it-architecture --env PYTHONPATH=$HOME/tools/mcp-architecture -- python3 -m itarch
claude mcp list        # should show: it-architecture: connected

C. No MCP client at all

The same engine has a plain CLI:

itarch render mydiagram.arch --style blueprint -o ./docs/img
itarch render mydiagram.arch --all-styles          # one file per style
itarch check  mydiagram.arch                       # validate, don't draw
itarch convert mydiagram.arch --to json
itarch styles | itarch types | itarch guide

(Without pip install, use python3 -m itarch.cli ….)

3. Where files go

ITARCH_OUTPUT_DIR, falling back to ~/architecture-diagrams (on Windows, C:\Users\<you>\architecture-diagrams). Every call can override it with output_dir. Alongside each SVG the server writes a .arch source file, so a diagram can be edited and re-rendered later instead of being described from scratch.

Because the HTTP transport hands back file paths, the server and the client have to see the same filesystem — which they do when both run on your machine. That is the intended deployment; the server is not built to be shared.

Tools exposed over MCP

Tool	What it does
`get_authoring_guide`	The full notation, styles and icon list. The agent should read this first.
`render_architecture`	Draw a diagram, save `.svg` (one or several styles at once). Also answers to `draw_diagram_svg`.
`render_all_styles`	Same diagram in every style, so a human can pick.
`preview_architecture`	Return the SVG markup inline instead of writing a file.
`validate_architecture`	Parse only; reports every error at once plus warnings.
`convert_notation`	DSL ⇄ JSON spec, normalised.
`list_styles`	The available looks and what each is good for.
`list_node_types`	Every component icon, its category and aliases.

Layout is fully automatic — layering, ordering, crossing reduction, edge routing and group boxes. Coordinates are never part of the input.

render_architecture is also advertised as draw_diagram_svg (identical behaviour). Some clients only expose tools through a keyword search over tool names; without a name containing "draw", "diagram" or "svg", a model asked to "draw this and export it as SVG" searches, finds nothing, and wrongly concludes the server cannot do it. The informational tools also end their output by naming the drawing tool, for the same reason.

Prompts — making it part of the workflow

Beyond tools, the server offers MCP prompts, which most clients surface as slash commands or a menu. Picking one and typing a description is the whole workflow; no tool call to spell out.

Prompt	Arguments	What it does
`architecture_diagram`	`description`*, `style`, `direction`	Plain English in, SVG out.
`restyle_diagram`	`source`*, `style`	Redraw an existing `.arch`/`.json` in another style, or in all of them.
`review_architecture`	`source`*	Validate, comment on what stands out, then draw.
`diagram_notation`	—	Load the authoring guide so the agent reaches for the tool from then on.

If your client does not support prompts, docs/agent-instructions.md has a short rule to paste into its system prompt / rules file instead. Note that a client with "lifecycle": "eager" caches the tool and prompt list at connect, so changes need a server restart and a fresh session.

The notation

title: Payments platform
subtitle: Target state, Q3
direction: LR                      # LR (default), RL, TB, BT

group vpc "Production VPC" [cloud] {
  group public "Public subnet" [zone] {
    alb [lb] "Application LB" : "TLS 1.3 termination"
  }
  group private "Private subnet" [zone] {
    api    [service]  "Payments API" : "Java 21" {badge: PCI}
    ledger [postgres] "Ledger" : "PostgreSQL 16" {shape: cylinder}
  }
}
customer [user] "Customer"

customer -> alb : "HTTPS"
alb -> api : "mTLS"
api -> ledger : "SQL" {style: dashed}
api <-> idp : "OIDC"

Components: id [type] "Label" : "sublabel" {badge:…, shape:…, accent:…}
Connections: -> <- <-> -- (no arrow) ..> (dotted) ==> (thick), chains (a -> b -> c), labels after :
Groups nest freely; kinds are zone, cloud, region, cluster, onprem, external, plain. Declare a component inside its group, or declare it up front and list its bare id inside the group block — a bare id that names a known component moves it, it is not a redeclaration
# and // start comments

Everything is equally expressible as JSON — see examples/microservices.json, or call convert_notation.

Styles

Style	Use it for
`cloud` (default)	Public-cloud reference look: white service cards, colour-coded icon tiles, dashed VPC/subnet zones.
`azure`	Cool corporate blue, square cards with an accent bar.
`material`	Light product-doc look, soft cards, curved connectors.
`c4`	C4 model: filled boxes with `[type]` stereotypes.
`blueprint`	Dark navy grid paper, monospaced, orthogonal — network and infra plans.
`whiteboard`	Hand-drawn workshop sketch. Signals "draft, let's discuss".
`minimal`	Monochrome line art for print, ADRs and PDFs.
`neon`	Dark presentation style with glowing accents.
`slate`	Understated enterprise deck style.

Aliases work too: aws→cloud, gcp→material, dark→neon, print/bw→minimal, sketch→whiteboard, infra→blueprint.

Component icons

About 60 glyphs across clients, compute, network, storage, data, integration, security and ops — server, service, function, container, k8s, database, nosql, cache, bucket, queue, topic, stream, gateway, lb, cdn, firewall, waf, auth, secret, monitor, logs, ci, user, browser, mobile, mainframe, thirdparty, …

Everyday names are aliased, so postgres, rds, lambda, eks, kafka, s3, sqs, redis, splunk all resolve to the right glyph. Unknown types degrade to a plain box rather than failing.

Examples

python3 -m itarch.cli render examples/three-tier.arch   --style cloud
python3 -m itarch.cli render examples/network-zones.arch --style blueprint
python3 -m itarch.cli render examples/c4-context.arch    --style c4
python3 -m itarch.cli render examples/event-driven.arch  --all-styles

Development

python3 -m unittest discover -s tests -v

105 tests, no fixtures to install. They cover the DSL, the spec validator, the layout invariants (no overlapping nodes, groups contain their members, nothing escapes its band, content fits the declared canvas), SVG well-formedness for every style, XML escaping of untrusted labels, the MCP protocol handling including malformed input and protocol downgrade, and the HTTP transport driven over a real socket.

Layout, briefly

itarch/layout.py is a compact Sugiyama pipeline: DFS cycle-breaking → longest-path layering → dummy nodes for long edges → barycenter crossing reduction → one reserved cross-axis band per group (siblings that never share a layer share the space) → exact isotonic (PAVA) 1-D placement inside each band → group boxes → edge routing. Everything is computed in layer/cross coordinates and mapped to screen space at the very end, which is why LR/RL/TB/BT all come out of the same code path.

Adding a style

Add one entry to STYLES in itarch/styles.py. The renderer, layout engine and icon set need no changes.

Adding an icon

Add a draw function and one ICONS entry in itarch/icons.py. Glyphs are authored in a 0..100 box using plain SVG primitives.

Security notes

On stdio the server opens no socket at all. On --http it binds 127.0.0.1 only by default and validates the Origin header, so a web page you happen to have open cannot reach it by DNS rebinding. There is no authentication, so --host 0.0.0.0 is for trusted networks only — the server warns you when you do it.
It never reads a file it was not given a path to; the only writes are the .svg/.arch files in the output directory, with filenames sanitised to a single path component.
Labels are XML-escaped, so text coming from a ticket or a log cannot inject markup into the drawing.
Output is deterministic: the same input always produces byte-identical SVG, which keeps diagrams reviewable in git.

Available Tools

8 tools

convert_notationA

Convert a diagram between the compact DSL and the JSON spec (both directions), normalising it on the way. Useful for editing a diagram that was written in the other notation.

ParametersJSON Schema

Name	Required	Description
`to`	No	Target notation. Default 'json'.
`dsl`	No	Diagram in the it-architecture DSL (preferred). Call get_authoring_guide once to learn it.
`spec`	No	Structured diagram spec; alternative to 'dsl'.
`title`	No	Overrides the title in dsl/spec.
`subtitle`	No
`direction`	No	Flow direction; LR is the default.

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It mentions conversion and normalisation but does not clarify side effects, permissions, idempotency, or whether the operation is read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two succinct sentences with no wasted words; front-loaded with key purpose and usage hint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of nested objects and no output schema, the description covers the core conversion purpose but could elaborate on what 'normalising' entails and the outcome when both dsl and spec are provided.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high (83%) and the description adds value by directing users to call get_authoring_guide to learn the DSL, providing guidance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'convert' and the resource 'diagram between the compact DSL and the JSON spec (both directions)', and distinguishes it from siblings like validate, render, and preview which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use case ('editing a diagram that was written in the other notation') but does not explicitly state when not to use it or compare with alternatives such as validate or render.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_authoring_guideA

Read this first. Returns the complete notation for describing an IT architecture (compact DSL + equivalent JSON), the available styles, group kinds and a worked example. No arguments.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It describes the return value (notation, styles, group kinds, example) but does not disclose any side effects, rate limits, or other behavioral traits beyond being a read-only documentation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with a single sentence plus the 'No arguments' note. It front-loads 'Read this first' to establish priority. Every part is necessary and adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, no output schema, and a clear purpose as an introductory guide, the description fully equips an agent to understand and invoke the tool correctly. The sibling list reinforces its role as a starting point.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the description explicitly confirms 'No arguments'. With 100% schema coverage and no parameters to document, the description adds sufficient clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns 'the complete notation for describing an IT architecture', along with styles, group kinds, and a worked example. This distinguishes it from sibling tools like list_styles or list_node_types which likely return subsets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The tool is explicitly labeled 'Read this first', indicating it should be used before other tools. It also states 'No arguments' for simplicity. However, it does not explicitly exclude alternatives or provide when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_node_typesA

List every component icon (server, database, queue, k8s, firewall, ...) with its category and the aliases that map onto it.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description discloses return content (icons, category, aliases) but lacks details on side effects, permissions, or pagination. With no annotations, the description partially fulfills the burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded, no wasted words. Efficiently conveys purpose and output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and no output schema, the description adequately explains what is listed. Could specify order or if exhaustive, but 'every' implies completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, baseline 4 per rubric. Description adds no param info but none needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb 'List' and resource 'every component icon' with details on what is returned (category, aliases). Distinguishes from sibling 'list_styles' which lists styles, not node types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus siblings. Implied usage for retrieving node types, but no exclusions or alternative recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_stylesA

List the available drawing styles (cloud, azure, material, c4, blueprint, whiteboard, minimal, neon, slate) with a description of each look.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It accurately describes a read-only listing operation with no side effects, fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence listing all styles and stating purpose. No wasted words, front-loaded with action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and no output schema, the description fully conveys what the tool does and what it returns (list of styles with descriptions). Complete for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so baseline 4 applies. The description adds no parameter info because none are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool lists available drawing styles with descriptions, using a specific verb and resource. It distinguishes from siblings like list_node_types which list node types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing to know available styles. No explicit exclusions or alternatives are needed given the lack of similar tools, but it could mention it is for style selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

preview_architectureA

Return the SVG markup inline instead of writing a file. Use when the client can display or post-process SVG directly.

ParametersJSON Schema

Name	Required	Description
`dsl`	No	Diagram in the it-architecture DSL (preferred). Call get_authoring_guide once to learn it.
`spec`	No	Structured diagram spec; alternative to 'dsl'.
`style`	No
`title`	No	Overrides the title in dsl/spec.
`footer`	No
`legend`	No
`subtitle`	No
`direction`	No	Flow direction; LR is the default.
`transparent`	No

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It clearly states the key behavioral trait: returns inline SVG without writing a file. This is sufficient for understanding, though additional details like error handling or prerequisites could enhance transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-front-loaded sentence that conveys the essential action and usage condition without any wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description covers the core purpose and usage, it omits crucial context such as the need to provide either 'dsl' or 'spec' (both optional in schema but at least one required) and the output format. Given the tool's complexity with 9 parameters and nested objects, more context is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 44%, and the description does not add any parameter explanations beyond what the schema provides. It fails to compensate for the low coverage, leaving the agent without guidance on using the two input alternatives (dsl vs spec) or other parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns SVG markup inline rather than writing a file, which distinguishes it from siblings like render_architecture. The verb 'Return' and resource 'SVG markup' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises use when the client can display or post-process SVG directly, providing a clear usage condition. However, it does not explicitly name alternatives or when not to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

render_all_stylesA

Render the same architecture once per available style into one directory, so a human can pick the look they want. Files are suffixed with the style name.

ParametersJSON Schema

Name	Required	Description
`dsl`	No	Diagram in the it-architecture DSL (preferred). Call get_authoring_guide once to learn it.
`spec`	No	Structured diagram spec; alternative to 'dsl'.
`style`	No	Drawing style, see list_styles. Default 'cloud'.
`title`	No	Overrides the title in dsl/spec.
`footer`	No	Small caption under the drawing.
`legend`	No	Draw a category colour legend.
`styles`	No	Render the same diagram in several styles at once.
`filename`	No	Base name without extension; defaults to the title.
`subtitle`	No
`direction`	No	Flow direction; LR is the default.
`output_dir`	No	Where to write. Defaults to $ITARCH_OUTPUT_DIR or ~/architecture-diagrams.
`save_source`	No	Also write a .arch source file next to the SVG (default true) so the diagram can be edited later.
`transparent`	No	Omit the background fill.

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears the full burden of behavioral disclosure. It explains the output behavior: files go into one directory, suffixed with style name. It does not mention output format (assumed SVG from sibling tools), the interaction between 'style' and 'styles' parameters, or whether existing files are overwritten. The description is minimally adequate but leaves several behavioral aspects unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, extremely concise, and front-loaded with the core action. Every word adds value. There is no wasted text or redundancy. This is an exemplary model of conciseness for a tool description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (13 parameters, nested objects, enums), the description is quite sparse. It fails to explain the interplay between the 'dsl' and 'spec' inputs, the default behavior when no styles are specified, and output details like format. The schema compensates heavily, but for a tool with multiple output mode and many configuration options, the description lacks completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 92% (high), so the baseline is 3. The description adds little beyond schema: it mentions file suffixing (tied to filename/style) but does not explain the distinction between 'style' and 'styles' or how they interact. Most parameter meanings are already well-documented in the schema, so the description provides marginal added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool renders the same architecture in multiple styles into one directory, with files suffixed by style name. It is specific about the verb (Render) and resource (architecture per style). However, the term 'available style' is ambiguous as it could mean all known styles versus those specified via the 'styles' parameter, slightly reducing clarity. It distinguishes from sibling render_architecture by implying multiple outputs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for generating multiple style variants for comparison, but it does not explicitly state when to use it over siblings like render_architecture (single style) or preview_architecture (preview). No explicit instructions on prerequisites or when not to use it are provided. The usage context is implied but not clearly delineated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

render_architectureB

Draw an IT architecture and save it as a standalone .svg file (optionally in several styles at once). Layout, routing and grouping are automatic - never supply coordinates. Returns the absolute file paths.

ParametersJSON Schema

Name	Required	Description
`dsl`	No	Diagram in the it-architecture DSL (preferred). Call get_authoring_guide once to learn it.
`spec`	No	Structured diagram spec; alternative to 'dsl'.
`style`	No	Drawing style, see list_styles. Default 'cloud'.
`title`	No	Overrides the title in dsl/spec.
`footer`	No	Small caption under the drawing.
`legend`	No	Draw a category colour legend.
`styles`	No	Render the same diagram in several styles at once.
`filename`	No	Base name without extension; defaults to the title.
`subtitle`	No
`direction`	No	Flow direction; LR is the default.
`output_dir`	No	Where to write. Defaults to $ITARCH_OUTPUT_DIR or ~/architecture-diagrams.
`save_source`	No	Also write a .arch source file next to the SVG (default true) so the diagram can be edited later.
`transparent`	No	Omit the background fill.

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description partially covers behavior: it says layout is automatic and returns file paths. Missing details on side effects like file overwriting, default output location, or the fact that it writes to disk.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences front-load the main purpose and key constraints. No redundant or unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity with 13 parameters and no output schema, the description is minimal. It doesn't mention the need to call get_authoring_guide to learn the DSL, nor does it hint at default style or how to specify diagram content.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 92%, so parameters are well-documented in the schema. The description adds no new param-specific meaning beyond what's already in the schema, meeting the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool draws an IT architecture and saves as SVG, mentioning optional multi-style output. However, it does not distinguish from sibling 'render_all_styles' which also generates multiple styles, leaving potential ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool over alternatives like validate_architecture or preview_architecture. The instruction to not supply coordinates is a usage rule but not a context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_architectureA

Parse a diagram without drawing it. Reports every syntax/reference error at once, plus warnings about orphan nodes, empty groups and unknown icon types. Cheap to call before rendering.

ParametersJSON Schema

Name	Required	Description
`dsl`	No	Diagram in the it-architecture DSL (preferred). Call get_authoring_guide once to learn it.
`spec`	No	Structured diagram spec; alternative to 'dsl'.
`title`	No	Overrides the title in dsl/spec.
`subtitle`	No
`direction`	No	Flow direction; LR is the default.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully carries the burden. It clearly states the tool is non-destructive (parses without drawing), reports errors/warnings, and is cheap to call. This adequately discloses its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action, and every word adds value. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the schema has nested objects and no output schema, the description adequately explains what types of errors/warnings it produces (syntax, references, orphan nodes, etc.). It could hint at the response format but is sufficient for a validation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 80% of parameters with descriptions, so the description need not repeat them. It briefly mentions 'dsl' and 'spec' but adds no significant meaning beyond the schema's own descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool parses a diagram without drawing it and reports all errors and warnings, distinguishing it from rendering tools like render_architecture.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises using it before rendering because it is cheap, implying cost-effective validation. It could explicitly mention when not to use or mention alternative tools for learning the DSL (get_authoring_guide) or fetching icon types (list_node_types).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

8 tool updatesv1.0.0Jul 29, 2026
- First observedconvert_notation
- First observedget_authoring_guide
- First observedlist_node_types
- First observedlist_styles
- First observedpreview_architecture
- First observedrender_all_styles
- First observedrender_architecture
- First observedvalidate_architecture

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: guide, listing of styles, listing of node types, validation, rendering, multi-style rendering, preview, and notation conversion. No overlaps.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case, e.g., list_styles, render_architecture, convert_notation.

Tool Count5/5

Eight tools cover the core workflow of IT architecture diagramming without being excessive or insufficient.

Completeness5/5

The tools provide complete lifecycle support: learning (guide), configuration (styles, node types), validation, rendering, preview, and notation conversion. No obvious gaps.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Flowgraf A
in.flowgraf
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Software Architecture Design Tools
32
Agentic Mermaid A
io.github.adewale
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Data Visualization Software Architecture
9210
hjarni AOAuth
com.hjarni
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Note Taking Workplace & Productivity
3
PlanExe A
io.github.PlanExeOrg
MCP server for generating rough-draft project plans from natural-language prompts.
Autonomous Agents Developer Tools Project Management
113398

Related MCP Servers

excalidraw-architect-mcp
Design Tools Software Architecture Developer Tools
BV-Venky
A
license
B
quality
A
maintenance
An MCP server that generates beautiful Excalidraw architecture diagrams with perfect auto-layout, stateful editing, and architecture-aware component styling.
Updated 11 days ago (2026-08-25 19:10 UTC)
26
148
MIT
Azure Diagram MCP Server
Cloud Platforms Software Architecture
Jah-yee
A
license
A
quality
D
maintenance
An MCP server that generates professional infrastructure diagrams using the Python diagrams DSL, with first-class Azure support and GitHub Copilot integration for natural language diagram generation.
Updated 6 months ago (2026-02-26 17:56 UTC)
4
MIT
mermaid-to-excalidraw-mcp
yannick-cw
A
license
A
quality
D
maintenance
MCP server that converts Mermaid diagrams to styled Excalidraw files, saving them directly to disk without token overhead.
Updated 7 months ago (2026-01-29 09:30 UTC)
2
MIT
repo-cartographer
Code Analysis Software Architecture
builditwithgk
A
license
A
quality
A
maintenance
An MCP server that maps any repository into architecture diagrams, providing tools for scanning code facts, building import graphs, and generating Mermaid/DOT diagrams, plus architecture rule enforcement for CI.
Updated a month ago (2026-08-05 15:32 UTC)
5
61
1
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/slajzad/mcp-architecture'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

it-architecture — MCP server for architecture drawings

1. Install

Windows (C:\Tools\MCP)

Linux / macOS

2. Connect it to your local CLI / AI tool

A. HTTP — for clients configured with a url (pi.dev and similar)

B. stdio — for clients that launch the server themselves

C. No MCP client at all

3. Where files go

Tools exposed over MCP

Prompts — making it part of the workflow

The notation

Styles

Component icons

Examples

Development

Layout, briefly

Adding a style

Adding an icon

Security notes

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

Windows (`C:\Tools\MCP`)

A. HTTP — for clients configured with a `url` (pi.dev and similar)