# archlang-mcp [Health: Active]

**Category:** 📐 Architecture & Design  
**Repository:** https://github.com/chanmeng666/archlang  
**GitHub Stars:** 35  
**npm Downloads (last month):** 3455  
**Views:** 8  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/archlang-mcp

## Description
Compile, describe, lint, validate, repair and fix ArchLang floor plans (.arch to SVG) over stdio.

## Tools
Capabilities this server exposes over MCP:

- **compile** — Compile ArchLang `.arch` source (or a Plan-JSON object) to an SVG floor plan, or with `format` to a plain-text ASCII plan ("txt"), Plan JSON ("json") or an image ("png"). Format "json" returns the plan as an object, with `schema` naming its JSON Schema; passed back as `plan_json` it compiles to the same drawing, unless the plan uses a part of the language Plan JSON does not carry (sheet tables, styles, circular rooms, roofs, storeys, `place`, accessibility metadata). Returns the output plus diagnostics; a diagnostic usually carries a byte span with line/col and an E_/W_ code, and often a fix, sometimes one the `fix` tool can apply. Errors come back as data, never as exceptions: read `diagnostics` and correct the source. A multi-storey plan (`level <n> { … }`) returns the lowest storey in `output` and every storey in `pages[]` ({ level, name, output }); pass `level` to render just one. format "png" returns the usual result as text, then the drawing (the lowest storey, or `level`) as image content, as wide as `width` says; it needs the optional renderer @resvg/resvg-js, and without it the call returns ok:false with an error saying how to install it.
- **describe** — Report a plan's facts without rendering, so you can check it against the brief without looking at an image. Returns rooms (area, bbox, adjacency, use, and the exact shape: `floor_polygon` for a `room polygon`, `floor_circle` for a `room circle`, whose area is exactly πR²), doors (what each connects), windows, circulation (walk distance, bottleneck width, detour), zones, storeys (`levels[i]` carries the same facts per floor) with the shafts that join them and which storeys stay reachable (`vertical`), the drawing extent (`bbox`, `bbox_outer`), `freedom` (which positions are hand-authored and which are derived), and totals.
- **lint** — List advisory architectural-soundness warnings (`W_*` codes) as data: unreachable room, windowless bedroom, too-narrow door, blocked doorway, furniture through a wall, circuitous path, and more. `profile` selects a ruleset ("residential-basic", "accessibility-advisory", …).
- **validate** — Check a plan in one pass without returning a drawing (parse, resolve and lint): the gate a plan passes before it ships. `strict:true` makes advisory warnings fail too. Optional `graph` checks the plan's interior-door adjacency against an intended room graph (`{ room: [neighbours] }`); a mismatch fails. Optional `intent` (a brief's expectations, shaped as the `archlang://intent-schema` resource describes) is checked against the plan: a missed gating assertion (room count, existence, area, total area, windows) fails, while adjacency and reachability are advisory and only score. `profile` lints under a named ruleset as well, and its warnings are the ones reported; `taste` scores the plan under a taste profile, which never fails it. `next` is the one item to fix first, chosen in a fixed order (an error, a compile warning, a validity warning, a drafting warning, the brief and the graph, a profile-only warning, then the lowest taste score), or null when nothing is left; a broken `soft` keep is not weighed here yet, so where the CLI's `validate` names it this returns a later item, or null. A malformed intent returns `{ ok:false, intentErrors }` and an unknown profile `{ ok:false, error }` as data, never an exception. Returns { ok, diagnostics, graph?, intent?, next }.
- **score** — Measure how much of a brief's intent JSON a plan satisfies, without gating. Returns { ok, satisfied, total, score, subscores, violations }, where `score` is satisfied/total in [0,1] (an empty intent scores 1); call it across edits to watch a plan approach the brief. The intent's shape is the `archlang://intent-schema` resource. A malformed intent returns `{ ok:false, intentErrors }` as data, never an exception.
- **repair** — Correct furniture placement and return the corrected `.arch` source with a change log. It pushes furniture out of walls, doorways and door swings, separates overlapping pieces, moves fixtures that sit in the wrong room, and snaps floating pieces to walls. A piece it may not rewrite is listed in `unresolved` with the reason. It never adds doors or windows (that is a design choice); use `suggest` for those.
- **fix** — Apply the machine-applicable fixes attached to a plan's compile diagnostics and return the edited source. It corrects source-level faults (an opening off its wall becomes the attachment form, an out-of-range position is clamped, …); furniture geometry is `repair`'s job. It runs at most 4 passes and rolls back a pass that raises the error count. `unsafe:true` also applies `maybe-incorrect` fixes. Returns { ok, passes, applied, skipped, source }.
- **finish** — Complete a plan for export by adding what it lacks; run it once `lint` is clean. Two stages. `furnish` puts furniture, by room use, in each rectangular room that holds none, on every storey (a furnished room is never touched, and one that lacks a piece its use requires is named in `unresolved` with the missing pieces, not filled; placement is `against wall` / `in <room> anchor`, never absolute). `sheet` adds the sheet statements the plan lacks (`paper`, `scale`, `dims auto`, `title`, `schedule rooms`, `legend`), choosing the finest standard scale on the smallest sheet that holds the drawing. It fills only what is missing and deletes nothing; `only` runs one stage; `reissue:true` may replace `paper`/`scale` (only those) when the drawing does not fit them. Returns { ok, changed, changes, unresolved, source }; a plan that does not compile comes back untouched with `ok:false`, and every room left empty (its use has no furniture row or is unknown, or furnishing it would raise a new diagnostic) and every sheet statement left out is named in `unresolved` with the reason; a note with `scope` set (`outside-table`) asks nothing of you unless that room should hold furniture.
- **suggest** — Suggest the doors and windows a plan's room graph needs, as data; nothing is applied. For a room with no path back, a building with no entrance, a bath reachable only through a bedroom, or a windowless bedroom, it returns ready-to-paste `door`/`window` statements with a rationale, for you to choose among and insert. Each names its wall by an authored id or a unique wall category, else by absolute `at (x, y)` coordinates. Door candidates avoid furniture in the door's approach; window candidates do not consider furniture.
- **complete** — List the completion items in scope at a source byte offset: keywords, element names, ids and enum values, the same items an editor's language server offers. For structured or assisted authoring.
- **link** — Make two URLs that show a plan in the browser with nothing to install, for handing to a person. `playground` opens it in the hosted editor, rendered; `embed` draws it alone, for an iframe. The plan travels inside the URL, after the `#`, so it is never sent to a server and the URL carries nothing else. A plan that does not compile still gets links, and the page shows its diagnostics; `ok` says whether it compiles, and `errors` counts the errors when it does not. `bytes` is the size of the compressed plan in the URL.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What archlang-mcp does

archlang-mcp gives an MCP-compatible agent access to ArchLang, a text-based language for describing floor plans. It supports the main loop of writing a `.arch` file, compiling it into an SVG drawing, inspecting the result, and correcting problems. The workflow is intended for floor-plan source that should remain editable and reviewable as code.

The server covers compilation, description, linting, validation, repair, and fixing. Validation can be run in strict mode, and JSON output is available for command workflows that need structured results. ArchLang’s source-driven model also supports repeatable output: changing a dimension or other value updates the corresponding drawing while keeping the rest of the plan derived from the same source.

## How it works

The MCP client starts the server as a stdio process. An agent can then use the exposed operations to work through a plan without opening a graphical editor. A typical sequence is:

1. Read the ArchLang language specification.
2. Write a floor plan to a `.arch` source file.
3. Compile the source to an SVG.
4. Describe the plan and run strict validation.
5. Apply repairs or fixes, then compile again.

Compilation errors carry information that can guide the next correction. The resulting SVG is the primary drawing format described for this MCP workflow. ArchLang itself also documents export paths including DXF, PDF, and PNG.

## Setup and configuration

Install and start the MCP package with `npx`:

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

The command registers a server named `archlang` for the Claude command-line client and runs the package without requiring a separate global installation. Other MCP clients can use the same package as a stdio server when configured with the equivalent command and arguments.

For agents that need language guidance before generating a plan, ArchLang provides specification and context commands through its CLI. The recommended authoring process reads the specification first, creates the `.arch` file, and then checks the generated plan before exporting it.

## Tools and capabilities

- Compile ArchLang `.arch` floor plans into SVG drawings.
- Describe the contents or structure of a floor-plan source file.
- Lint source plans for issues during authoring.
- Validate plans, including strict validation with structured JSON output.
- Repair or fix problems found in an ArchLang plan.
- Support an iterative text-to-drawing workflow for dimensioned floor plans.

## Limitations and notes

The server is focused on ArchLang floor-plan source and communicates over stdio. It is a fit for agents that can launch local MCP processes and work with files or command results. The workflow depends on ArchLang syntax, so agents should consult the language specification or context before generating nontrivial plans. SVG is the directly described MCP compilation result; additional formats are associated with the underlying ArchLang CLI.

_Full upstream README: https://allmcps.com/mcp/archlang-mcp/readme_