# ChanMeng666/archlang [Health: Active]

**Category:** 📐 Architecture & Design  
**Repository:** https://github.com/ChanMeng666/archlang/tree/main/packages/mcp  
**GitHub Stars:** 89  
**npm Downloads (last month):** 7798  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/chanmeng666-archlang

## Description
Compile floor plans from declarative .arch source to SVG or PNG, and read a plan back as rooms, areas, adjacency and an access graph — with linting and geometric validation, so an AI agent can check its own plan from the compiler's diagnostics. Install via NPM: npx -y @chanmeng666/archlang-mcp

## 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_m2`, measured on the wall centrelines; `net_area_m2`, the floor no wall stands on, absent when it cannot be computed exactly; 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 (`floor_area_m2` on centrelines, `net_floor_area_m2` beside it, absent when any room's net area is).
- **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": {
    "command": "npx",
    "args": ["-y","@chanmeng666/archlang-mcp"]
  }
}
```

## Documentation

## What ChanMeng666/archlang MCP server does

ChanMeng666/archlang connects MCP hosts to the `@chanmeng666/archlang` library for authoring and checking architectural floor plans as code. Plans use ArchLang source in a `plan "…" { … }` structure; `compile` also accepts the library's Plan-JSON shape.

The server supports both visual output and semantic inspection. It can render SVG, zero-dependency text, PNG, or JSON representations, while other tools report rooms, areas, doors, adjacency, circulation, zones, storeys, floor geometry, and which positions were authored versus derived by the resolver.

## How it works

The package is a thin stdio MCP adapter. Each tool calls an exported library function, and the server does not launch a subprocess or write files. At initialization it provides a short workflow hint: read the `archlang://spec` resource, create or edit `.arch` source, compile and fix it, describe the result, then validate with `strict: true` before finishing or exporting.

Tool calls that receive source include a SHA-256 `source_hash` in their result. Rewriting tools—`repair`, `fix`, and `finish`—also return an `output_hash` for the exact replacement text. These hashes support stale-source checks when the returned text is written back through the CLI.

## Setup and configuration

Run the local server with npm and npx:

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

A hosted MCP endpoint is also available at `https://mcp.archlang.uk/mcp`. Claude-compatible coding agents can add either the HTTP endpoint or the local stdio command. The package is intended for MCP-speaking hosts; VS Code also provides an ArchLang extension through its Marketplace and Open VSX listings.

## Tools and capabilities

- `compile` renders source or Plan-JSON as SVG, text, JSON, or PNG. Multi-storey plans return all levels in `pages[]`, or one level when `level` is selected. `accessible` adds SVG title, description, and image role metadata, while `overlay: "circulation"` adds a circulation overlay.
- `describe` returns semantic plan facts without requiring image interpretation.
- `lint` emits advisory soundness warnings, with selectable profiles.
- `validate` combines parsing, resolution, and linting. It can enforce warnings as failures, check an intended room graph, evaluate an intent contract, and report the next item to address.
- `score` measures how much of a brief the plan satisfies without acting as a gate.
- `repair` moves furniture away from walls, doorways, and door swings, but does not add doors or windows.
- `finish` furnishes empty rooms and adds missing sheet elements such as paper, scale, dimensions, title, room schedule, and legend.
- `fix` applies machine-applicable diagnostic fixes; `suggest` proposes door or window statements without applying them.
- `complete` provides language-server completion items, and `link` creates browser URLs for the hosted playground and standalone embedded plan.

## Limitations and notes

PNG output requires the optional `@resvg/resvg-js` package; the `.mcpb` bundle excludes it. The MCP accessibility option only adds root SVG title, description, and image-role metadata. It does not expose the library's element-level keyboard and screen-reader controls or the multi-plan `idPrefix` option.

The 3D preview belongs to the separate `archlang-3d` package rather than this MCP server. Its documented scope excludes pitched roofs, balcony railings, sections, elevations, and BIM. For agents that already have shell access, the ArchLang CLI is described as the primary interface and can compile files directly; this MCP package is intended for MCP-native hosts and discovery.

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

