ArchSmith

What the ArchSmith MCP server does

The ArchSmith MCP server converts a validated JSON intermediate representation into an SVG architecture diagram. Its output follows one governed layered or swimlane convention rather than a general-purpose diagramming syntax. The layout uses five left-to-right areas: Inbound Actors, Ingress, Core Platform, Egress, and External Systems.

A diagram document supplies content such as a title, descriptions, platform components, systems of record, and external dependencies. It can also identify selected roles with governed color tokens, dots, or pill-style tags. Layout coordinates, box dimensions, text wrapping, spacing, and typography are derived by the renderer instead of being specified in the input.

How it works

The ArchSmith MCP server separates interpretation from rendering. An agent or developer creates the structured JSON description, then calls validation before requesting a render. Validation checks the document against ArchSmith's schema and governed registries. Rendering turns accepted content into an SVG using the project's fixed visual rules.

The MCP interface provides render and validate capabilities as callable tools. The schema and registries are exposed as MCP resources, allowing an agent to inspect the accepted document structure and available values. This arrangement is useful when an automated workflow needs to create diagrams while keeping visual decisions consistent across documents.

ArchSmith currently supports one architecture convention. It does not aim to cover sequence diagrams, state machines, or the broader range of diagram types supported by general-purpose tools such as Mermaid or PlantUML.

Setup and configuration

The repository documents installation through the ArchSmith CLI package, including a global npm installation with npm install -g @archsmith/cli or one-off execution through npx @archsmith/cli. The CLI requires Node.js 20 or newer. The provided material does not specify MCP-specific environment variables or client configuration.

Input files may use the .archsmith.json naming convention so editors and integrations can recognize them, although the CLI accepts any JSON path. Existing JSON can be validated and rendered, while the interactive author command can guide creation of a new document and save the JSON and SVG together. Editing an existing document through that wizard is not supported; corrections require editing the saved JSON or starting another session.

Tools and capabilities

• Validate an architecture JSON document.
• Render a validated document as SVG.
• Expose the schema as an MCP resource.
• Expose registries for sub-layers, colors, and icons as MCP resources.
• Produce a fixed five-column layered architecture layout.
• Apply consistent box shapes, spacing, wrapping, and embedded font handling during rendering.

Limitations and notes

The project is pre-1.0, and the schema and API may change. The current renderer supports one opinionated layered architecture style, so it may not fit workflows requiring arbitrary positioning or multiple diagram types. The supplied material does not identify named MCP clients, transport details, authentication options, or server-specific environment variables.