Archlang Mcp

@chanmeng666/archlang-mcp

A Model Context Protocol server for ArchLang — author, inspect, and repair architectural floor plans written as code, from any MCP-speaking host.

It is a thin stdio shim over the @chanmeng666/archlang library (no subprocess, no re-implementation): each tool wraps one pure, exported function. The core stays zero-dependency — the MCP SDK lives only in this package.

Try it

Floor plans as code. Your AI writes ArchLang; the compiler draws a precise, dimensioned plan and tells it what's wrong.

• ChatGPT, no install: ArchLang app in ChatGPT, then ask, for example: "Draw a two-bedroom flat of about 75 m² as an ArchLang plan, and check it."
• claude.ai, no install: add https://mcp.archlang.uk/mcp as a custom connector (the steps)
• Coding agent: claude mcp add --transport http archlang https://mcp.archlang.uk/mcp; locally, claude mcp add archlang -- npx -y @chanmeng666/archlang-mcp; skills, npx -y skills add ChanMeng666/archlang --yes (skills.sh)
• VS Code: Marketplace or Open VSX
• Playground, in the browser: https://playground.archlang.uk

Same source, plan and 3D preview. The 3D preview is extruded from the same .arch file by the separate archlang-3d package, and checked against the plan: every 3D element comes from the plan's elements, and every solid is closed. What the 3D preview shows →

3D preview: walls, openings, floors, stairs and furniture in flat colours; no pitched roofs yet, and no sections, elevations or BIM.

If your agent has a shell

ArchLang's primary agent interface is the agent-native archlang CLI, not this server. A CLI costs nothing in an agent's context window until it is called, whereas an MCP tool schema sits in the window permanently. If your agent already has a shell, prefer:

npx -y @chanmeng666/archlang context     # the whole language + workflow + CLI + errors, one callnpx -y @chanmeng666/archlang compile plan.arch -o out.svg --json

After npm i -g @chanmeng666/archlang the same calls are archlang context and archlang compile …. The package also installs an arch alias, but on Linux, macOS and Git Bash coreutils ships its own arch, so a bare arch there runs the wrong program.

This MCP server exists so MCP-native hosts can discover ArchLang through the registry and drive it without a shell. It is listed on the official MCP registry as io.github.ChanMeng666/archlang-mcp. It is the discoverability channel, not a replacement. See ADR 0012 (which amends ADR 0009's distribution-over-protocol stance).

Server instructions

At initialize the server sends a short instructions string, which hosts that support it add to the model's context: read the archlang://spec resource first, then write .arch → compile (and fix) → describe → validate with strict:true → finish before export. It is SKILL.md's loop, condensed, and a test holds the commands it names to the CLI manifest and to that loop's order.

Tools

Every tool takes ArchLang source (a plan "…" { … } string) and returns structured JSON. compile also accepts plan_json (the Plan-JSON / RPLAN shape). Every result of a call that passed source ends with source_hash, the SHA-256 (hex) of that input's UTF-8 bytes; repair, fix and finish, which return a rewritten source, add output_hash, the SHA-256 of exactly that returned text. The tools write no files. The hashes are for the CLI's --expected-hash, which refuses to rewrite a file whose bytes no longer hash to the value given (E_STALE_SOURCE): write the returned source to the file, then pass its output_hash. For a file that is valid UTF-8 and holds the text unchanged (a BOM and CRLF line ends included) the MCP hash and the CLI's agree.

What compile's accessible does here — and what it does not

accessible: true gives the SVG its <title>/<desc> pair and role="img" on the root, which is the whole of the option as this shim exposes it. The v1.36 element controls are not reachable through MCP. They need annotate alongside accessible, and this tool passes annotate only for format:"txt"; it also takes accessible as a boolean, so the { idPrefix } form that keeps several plans on one HTML page from sharing arch-title/arch-desc cannot be requested either.

A host that needs a keyboard- and screen-reader-operable drawing — data-arch-primary, role="button", aria-label on each element — has to call the library. The CLI cannot produce it either: annotate has no flag, so archlang compile --accessible stops at the <title>/<desc> pair too.

import { compile } from "@chanmeng666/archlang";compile(src, { annotate: true, accessible: { idPrefix: "plan-7" } });

The output contract, what an embedder still owns, and the known screen-reader limitations are in the language reference.

Resources

Install

Claude Code

claude mcp add archlang -- npx -y @chanmeng666/archlang-mcp

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{  "mcpServers": {    "archlang": {      "command": "npx",      "args": ["-y", "@chanmeng666/archlang-mcp"]    }  }}

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{  "mcpServers": {    "archlang": {      "command": "npx",      "args": ["-y", "@chanmeng666/archlang-mcp"]    }  }}

VS Code

Add to .vscode/mcp.json:

{  "servers": {    "archlang": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@chanmeng666/archlang-mcp"]    }  }}

License

MIT © Chan Meng