Renders and validates architecture diagrams from a governed JSON intermediate representation.
Also known as ayeshLK/archsmith, @archsmith/mcp-server
- Stars
- 7
- Tools
- 5
- Downloads, 30 days
- 587
- Latest version
- 0.8.2
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is ArchSmith MCP?
ArchSmith renders and validates architecture diagrams from a governed JSON intermediate representation. It exposes 5 tools, such as get_schema, validate, render.
Summary generated from the project's README
About ArchSmith MCP server
ArchSmith provides a way for AI agents to generate and verify architecture diagrams using a governed JSON intermediate representation. The server operates over stdio and can be integrated into hosts like Claude Desktop by pointing to the npx entrypoint. It allows developers to transform structured data into visual SVG diagrams while ensuring the input adheres to specific architectural rules.
Users can access tools such as render, validate, get_schema, list_registries, and get_registry to manage their design workflows. The server handles large outputs intelligently by using a resource_link mechanism for any SVG exceeding 25,000 bytes. This prevents massive token consumption by returning a small descriptor instead of the full text. For portability, the render tool includes an embedFonts option that subsets the Arimo font to only the necessary glyphs, keeping file sizes proportional to the diagram content.
Beyond tool calls, the server exposes resources like archsmith://schema and archsmith://registries/<name> so agents can access live definitions. It also maintains a bounded in-memory cache for the 20 most recent large renders, accessible via unique URIs.
What you can do with it
- 1Manage large diagram outputsThe system handles massive architectural diagrams by providing a URI link instead of flooding the chat with thousands of tokens.
Written from the project's README. Every use case is checked against a quote from it.
How to install ArchSmith MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall ArchSmith MCP in Claude Code
$ claude mcp add archsmith -- npx -y @archsmith/mcp-serverInstall ArchSmith MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"archsmith": {
"command": "npx",
"args": [
"-y",
"@archsmith/mcp-server"
]
}
}
}Install ArchSmith MCP in VS Code
.vscode/mcp.json
{
"servers": {
"archsmith": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@archsmith/mcp-server"
]
}
}
}Install ArchSmith MCP in VS Code CLI
$ code --add-mcp '{"name":"archsmith","type":"stdio","command":"npx","args":["-y","@archsmith/mcp-server"]}'Install ArchSmith MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"archsmith": {
"command": "npx",
"args": [
"-y",
"@archsmith/mcp-server"
]
}
}
}Install ArchSmith MCP in Codex
$ codex mcp add archsmith -- npx -y @archsmith/mcp-serverInstall ArchSmith MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.archsmith] command = "npx" args = ["-y", "@archsmith/mcp-server"]
Install ArchSmith MCP in Gemini CLI
$ gemini mcp add -s user archsmith npx -- -y @archsmith/mcp-serverInstall ArchSmith MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"archsmith": {
"command": "npx",
"args": [
"-y",
"@archsmith/mcp-server"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @archsmith/mcp-server 0.8.2 in an isolated container with no network and no keys. It answered and listed 5 tools.
ArchSmith MCP tools 5
Read from the server with tools/listget_schemaReturns the ArchSmith diagram IR JSON Schema (draft 2020-12) — the structural contract a diagram IR document must satisfy. Call this, and get_registry for governed vocabulary, before authoring an IR.
validateValidates an ArchSmith diagram IR document against the schema and governed registries (sub-layers, colors). Call get_schema and get_registry first to learn the required structure and governed vocabulary before authoring an IR. Returns { valid, errors }.
renderValidates then renders an ArchSmith diagram IR to a complete SVG document. Call get_schema and get_registry first to learn the required IR structure and governed vocabulary before authoring a document. Font embedding defaults to false to keep MCP responses compact; only opt in if the SVG must render portably without installed fonts — embedding adds a font subset sized to this diagram's own text, not a fixed cost, but it's still an added cost worth opting into deliberately. A render under 25,000 bytes is returned as one text content block; a larger one (e.g. a big diagram, or embedFonts:true on one) is returned as a resource_link instead, fetchable via resources/read, so the tool result itself never grows unbounded. Fails with the validation errors (isError: true) instead of rendering if the IR is invalid — never renders broken geometry from an invalid document.
list_registriesLists the governed registries (e.g. sub-layers, colors, icons) available via get_registry.
get_registryReturns the raw, current contents of a governed registry — the live source of truth for which colors/sub-layer types a diagram IR may use. This is governed vocabulary, not the IR's structural document contract; see get_schema for that. For 'colors' specifically, pass family to get just one color family instead of the whole registry.
| get_schema | Returns the ArchSmith diagram IR JSON Schema (draft 2020-12) — the structural contract a diagram IR document must satisfy. Call this, and get_registry for governed vocabulary, before authoring an IR. | |
| validate | Validates an ArchSmith diagram IR document against the schema and governed registries (sub-layers, colors). Call get_schema and get_registry first to learn the required structure and governed vocabulary before authoring an IR. Returns { valid, errors }. | |
| render | Validates then renders an ArchSmith diagram IR to a complete SVG document. Call get_schema and get_registry first to learn the required IR structure and governed vocabulary before authoring a document. Font embedding defaults to false to keep MCP responses compact; only opt in if the SVG must render portably without installed fonts — embedding adds a font subset sized to this diagram's own text, not a fixed cost, but it's still an added cost worth opting into deliberately. A render under 25,000 bytes is returned as one text content block; a larger one (e.g. a big diagram, or embedFonts:true on one) is returned as a resource_link instead, fetchable via resources/read, so the tool result itself never grows unbounded. Fails with the validation errors (isError: true) instead of rendering if the IR is invalid — never renders broken geometry from an invalid document. | |
| list_registries | Lists the governed registries (e.g. sub-layers, colors, icons) available via get_registry. | |
| get_registry | Returns the raw, current contents of a governed registry — the live source of truth for which colors/sub-layer types a diagram IR may use. This is governed vocabulary, not the IR's structural document contract; see get_schema for that. For 'colors' specifically, pass family to get just one color family instead of the whole registry. |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableayeshlk/archsmith is public and reachablegithub.com/ayeshlk/archsmith ↗Pass
- Package names this repository as its source@archsmith/mcp-server names ayeshlk/archsmith as sourcenpmjs.com/package/@archsmith/mcp-server ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/ayeshlk/archsmith ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @archsmith/mcp-serverPass
- No critical advisory in the package or its dependencies116 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@archsmith/mcp-server
The archsmith-mcp MCP server for ArchSmith — exposes render/validate/registry lookups to any MCP-capable agent, over stdio.
A sibling of @archsmith/cli, not a wrapper around it: both call render()/validate() from @archsmith/renderer directly. See the root README for the full picture.
Connecting it to an MCP host
Point the host at the built entrypoint, e.g. in Claude Desktop's claude_desktop_config.json:
{
"mcpServers": {
"archsmith": {
"command": "npx",
"args": ["-y", "@archsmith/mcp-server"]
}
}
}
Tools
get_schema, render, validate, list_registries, get_registry — mirror the CLI's own commands (same validate-before-render behavior, same family filter on get_registry). render defaults to embedFonts: false so the normal agent workflow stays compact; pass embedFonts: true deliberately when the exported SVG must include the bundled Arimo font and render identically without installed fonts. The embedded font is subset to just the glyphs that diagram's own text needs (see issue #55) rather than the whole font, so its size scales with the diagram instead of a fixed cost — still worth opting into deliberately, but no longer a blind tax regardless of content. The renderer library and CLI still embed fonts by default.
A render under 25,000 bytes of SVG (INLINE_THRESHOLD_BYTES in renderStore.ts) is returned as a single text content block, as above. A larger one — a big diagram, or embedFonts: true pushing an already-sizeable one over the line — is returned as a resource_link instead: a small { type: "resource_link", uri: "archsmith://render/<id>", size, ... } descriptor, fetchable via resources/read on that uri. This means the tool result itself never grows unbounded — unlike subsetting, which shrinks a fixed cost but still scales with diagram content, this has no ceiling on render size. A real Claude Code session tested against an equivalent-sized payload spent 3,279 tokens on the resource_link response versus 23,916 tokens inlining the same content directly — the model doesn't have to read bytes it doesn't need. archsmith://render/<id> entries live in a small in-memory cache bounded to the most recent 20 renders (MAX_ENTRIES); reading an evicted or unknown id returns a standard JSON-RPC -32002 ("Resource not found") error, not a tool error.
Render response sizes
Measured against the current fixtures as UTF-8 bytes, including a serialized JSON-RPC { jsonrpc, id, result } response envelope. "SVG" is the underlying render size regardless of shape; "MCP response" is what's actually returned — either that SVG inlined, or (marked link) a small resource_link descriptor pointing at it:
| Fixture | Fonts | SVG | MCP response |
|---|---|---|---|
minimal-valid |
omitted (default) | 9,014 B | 9,989 B |
minimal-valid |
embedded (subset) | 22,313 B | 23,289 B |
simple-3-tier-web-app |
omitted (default) | 12,555 B | 13,857 B |
simple-3-tier-web-app |
embedded (subset) | 26,130 B | 27,433 B |
ticket-booking |
omitted (default) | 23,441 B | 25,639 B |
ticket-booking |
embedded (subset) | 38,328 B | 355 B (link) |
Before subsetting, embedding cost a fixed ~40 KB regardless of fixture (two complete font weights) — enough to exceed common MCP client result limits even on a modest, everyday diagram like simple-3-tier-web-app, not just a maximal one (issue #55). Subsetting to each diagram's own text cuts that by roughly 40-55%, scaling with content instead of being a flat tax — but ticket-booking embedded is still 38,328 B, over the 25,000 B inline threshold, which is exactly the case the resource_link fallback above exists for: the tool response stays a small, constant-size descriptor no matter how large the underlying SVG is.
Before the response-shape fix in #50, the server also returned both SVG text and a duplicate base64 image block and embedded fonts by default; that made the ticket-booking response 149,897 B. The server now avoids duplicate payloads and keeps font embedding as an explicit, size-proportional portability tradeoff instead of hard-coding a particular client's result-size limit.
Real-host smoke test: Claude Code 2.1.153 with Claude Haiku 4.5 successfully rendered the full ticket-booking fixture through the stdio MCP server with embedFonts omitted. It received the SVG without an embedded @font-face.
get_schema returns the diagram IR JSON Schema — the same document as the archsmith://schema resource below, but as a tool the connected model can call on its own initiative before authoring an IR, rather than depending on the host client to surface a resource. validate and render name it (and get_registry) in their own descriptions, and again in their response content whenever the IR turns out to be invalid.
Resources
archsmith://schema and one archsmith://registries/<name> per governed registry — lets an agent authoring an IR read the live, current schema/registries directly instead of working from a stale copy baked into a prompt.
archsmith://render/<id> is a third, dynamic kind: render registers one whenever a render is too large to inline (see above). Deliberately not listed via resources/list — per the spec, a resource link returned by a tool isn't guaranteed to appear there — it's only reachable via the resource_link render itself returned, and it's evicted from the bounded in-memory store once 20 more renders have happened, so it doesn't survive a server restart or accumulate unbounded memory in a long session.
License
Apache-2.0
ArchSmith MCP questions
How do I add ArchSmith MCP to Claude Code?
Run claude mcp add archsmith -- npx -y @archsmith/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add ArchSmith MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does ArchSmith MCP provide?
It exposes 5 tools, including get_schema, validate, render, list_registries, get_registry.
How can I embed fonts in the rendered SVG?
You can pass embedFonts: true to the render tool to include a subsetted Arimo font that scales with the diagram's text.
What happens if the rendered SVG is very large?
If the SVG exceeds 25,000 bytes, the server returns a resource link instead of inlining the text to keep the response size small.
How can an AI agent access the latest diagram schema?
Agents can use the get_schema tool or access the archsmith://schema resource to read the live, current schema.