@chanmeng666/archlang-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Chan Meng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,109 @@
+# @chanmeng666/archlang-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for
+[ArchLang](https://github.com/chanmeng666/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.
+
+## When to prefer the CLI
+
+ArchLang's primary agent interface is the agent-native **`arch` 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:
+
+```bash
+npx @chanmeng666/archlang context     # the whole language + workflow + CLI + errors, one call
+npx @chanmeng666/archlang compile plan.arch -o out.svg --json
+```
+
+This MCP server exists so MCP-native hosts can **discover** ArchLang through the
+registry and drive it without a shell. It is the discoverability channel, not a
+replacement. See [ADR 0012](https://github.com/chanmeng666/archlang/blob/main/docs/adr/0012-mcp-shim-discoverability.md)
+(which amends [ADR 0009](https://github.com/chanmeng666/archlang/blob/main/docs/adr/0009-ai-first-context-and-distribution.md)'s distribution-over-protocol stance).
+
+## Tools
+
+Every tool takes ArchLang `source` (a `plan "…" { … }` string) and returns
+structured JSON. `compile` also accepts `plan_json` (the Plan-JSON / RPLAN shape).
+
+| Tool | What it does |
+|------|--------------|
+| `compile` | Render source (or `plan_json`) to SVG, or to zero-dep ASCII (`format:"txt"`). `accessible`, `overlay:"circulation"` opt-ins. Returns output + diagnostics. |
+| `describe` | Semantic facts (rooms, areas, adjacency, doors, circulation) — verify intent without an image. |
+| `lint` | Advisory `W_*` soundness warnings; `profile` selects a ruleset. |
+| `validate` | Parse + resolve + lint, the ship gate. `strict` fails on warnings; `graph` checks interior-door adjacency against an intended room graph. |
+| `repair` | Explicit corrector: furniture out of walls/doorways/swings → new `.arch` source + change log. Never adds doors/windows. |
+| `fix` | Apply the machine-applicable fixes on a plan's diagnostics (syntactic corrector; bounded fixpoint). `unsafe` widens to `maybe-incorrect`. |
+| `suggest` | Advisory door/window statements (attachment form) to resolve unreachable rooms / windowless bedrooms — data, never applied. |
+| `complete` | LSP completion items in scope at a source byte offset. |
+
+## Resources
+
+| URI | Content |
+|-----|---------|
+| `archlang://spec` | The whole language in one page (`spec.llm.md`). |
+| `archlang://context` | Full agent context: spec + workflow + CLI reference + error catalog (`llms-full.txt`). |
+| `archlang://schema` | JSON Schema (2020-12) for the Plan-JSON compile input. |
+| `archlang://grammar` | GBNF constrained-decoding grammar for guaranteed-parseable generation. |
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add archlang -- npx -y @chanmeng666/archlang-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "archlang": {
+      "command": "npx",
+      "args": ["-y", "@chanmeng666/archlang-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "archlang": {
+      "command": "npx",
+      "args": ["-y", "@chanmeng666/archlang-mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "archlang": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@chanmeng666/archlang-mcp"]
+    }
+  }
+}
+```
+
+## License
+
+MIT © Chan Meng

package/dist/archlang.gbnf

@@ -0,0 +1,119 @@
+# ArchLang GBNF grammar — a constrained-decoding grammar for llama.cpp-style samplers.
+#
+# GENERATED by scripts/gen-gbnf.ts from src/grammar/tokens.ts (keywords/operators)
+# plus USE_KINDS / FURNITURE_ANCHORS from src/ast.ts. Do NOT edit by hand — run
+# `npx tsx scripts/gen-gbnf.ts`; CI checks drift (test/gbnf-drift.test.ts).
+#
+# Feed it to a constrained sampler (llama.cpp `--grammar-file`, or the `grammar`
+# field of a server completion) to force a model to emit syntactically well-formed
+# ArchLang. This is a PRACTICAL grammar: intentionally a superset / approximation of
+# the hand-written parser (src/parser.ts) — it constrains the keyword-first
+# statement shapes and enum vocabularies but accepts some token spacings and
+# attribute orders the parser is stricter about. It must never REJECT a valid .arch;
+# the parser + its catalogued diagnostics remain the source of truth for validity.
+# Deterministic bytes (no version / date).
+
+root ::= ws "plan" rws string ws "{" ws ( plan-stmt ws )* "}" ws
+plan-stmt ::= setting | title-stmt | acc-stmt | theme-stmt | style-stmt | component-stmt | import-stmt | strip-stmt | block-stmt
+block-stmt ::= element | let-stmt | for-stmt | if-stmt | while-stmt | set-stmt | instance-stmt | assign-stmt
+element ::= wall-stmt | room-stmt | door-stmt | window-stmt | opening-stmt | furniture-stmt | dim-stmt | column-stmt
+setting ::= units-stmt | grid-stmt | scale-stmt | north-stmt | dims-stmt
+units-stmt ::= "units" rws "mm"
+grid-stmt ::= "grid" rws number
+scale-stmt ::= "scale" rws number ws ":" ws number
+north-stmt ::= "north" rws north-dir
+north-dir ::= "up" | "down" | "left" | "right" | number
+dims-stmt ::= "dims" rws "auto" ( rws dims-mode )?
+dims-mode ::= "overall" | "rooms" | "walls" | "all"
+acc-stmt ::= ( "accTitle" | "accDescr" ) rws string
+title-stmt ::= "title" ws "{" ws ( title-field ws )* "}"
+title-field ::= ( "project" | "drawn_by" | "date" ) rws string
+theme-stmt ::= "theme" ( rws "from" rws string | rws ident ( ws theme-block )? | ws theme-block )
+theme-block ::= "{" ws ( theme-entry ws )* "}"
+theme-entry ::= ident ws ":"? ws config-value
+style-stmt ::= "style" rws ident ws "{" ws ( style-entry ws )* "}"
+style-entry ::= ident ws ":"? ws config-value
+config-value ::= string | number
+component-stmt ::= "component" rws ident ws "(" ws param-list? ws ")" ws block
+param-list ::= ident ( ws "," ws ident )*
+import-stmt ::= "import" rws string ws ":" ws import-items
+import-items ::= "*" | import-item ( ws "," ws import-item )*
+import-item ::= ident ( rws "as" rws ident )?
+let-stmt ::= "let" rws ident ( ws "(" ws param-list? ws ")" )? ws "=" ws expr
+for-stmt ::= "for" rws ident rws "in" ws expr ws block
+if-stmt ::= "if" ws expr ws block ( ws "else" ws block )?
+while-stmt ::= "while" ws expr ws block
+set-stmt ::= "set" rws element-kw ws "(" ws set-entries? ws ")"
+element-kw ::= "wall" | "room" | "door" | "window" | "opening" | "furniture" | "dim" | "column"
+set-entries ::= set-entry ( ws "," ws set-entry )*
+set-entry ::= ident ws ":" ws expr
+instance-stmt ::= ident ws "(" ws ( expr ( ws "," ws expr )* )? ws ")"
+assign-stmt ::= ident ws "=" ws expr
+block ::= "{" ws ( block-stmt ws )* "}"
+strip-stmt ::= "strip" rws strip-dir rws "at" ws point rws "gap" ws expr ( rws strip-cross )? ws "{" ws ( strip-room ws )* "}"
+strip-dir ::= "right" | "left" | "down" | "up"
+strip-cross ::= ( "height" | "width" ) ws expr
+strip-room ::= "room" rws id-opt "size" ws strip-size ( ws room-label )? ( ws room-uses )?
+strip-size ::= expr ( ws "x" ws expr )?
+wall-stmt ::= "wall" rws id-opt ident rws "thickness" ws expr ( ws wall-material )? ws "{" ws ( point ws )* ( "close" ws )? "}"
+wall-material ::= "material" rws ident ( rws ( "scale" | "angle" ) ws expr ){0,2}
+room-stmt ::= "room" rws id-opt room-pos ws "size" ws dims ( ws room-label )? ( ws room-uses )?
+room-pos ::= "at" ws point | rel-dir rws ident ( rws "align" rws ident )? ( rws "gap" ws expr )?
+rel-dir ::= "right-of" | "left-of" | "below" | "above"
+room-label ::= "label" ws string
+room-uses ::= "uses" rws use-kind ( rws use-kind )*
+use-kind ::= "living" | "kitchen" | "dining" | "bedroom" | "bath" | "wc" | "hall" | "circulation" | "storage" | "utility" | "office" | "entry"
+door-stmt ::= "door" rws id-opt opening-target ws "width" ws expr ( ws door-clause )*
+door-clause ::= "wall" rws ident | "hinge" rws hinge-val | "swing" rws swing-val
+hinge-val ::= "near" rws ( "start" | "end" ) | "left" | "right"
+swing-val ::= "into" rws ident | "in" | "out"
+window-stmt ::= "window" rws id-opt opening-target ws "width" ws expr ( ws "wall" rws ident )?
+opening-stmt ::= "opening" rws id-opt opening-target ws "width" ws expr ( ws "wall" rws ident )?
+opening-target ::= "at" ws point | "on" rws ident rws "at" ws attach-pos
+attach-pos ::= "center" | number ws "%" | number
+furniture-stmt ::= "furniture" rws id-opt ident rws furn-pos ( ws furn-clause )*
+furn-pos ::= "against" rws "wall" rws ident ( ws against-opt )* | "in" rws ident rws in-place | "at" ws point
+against-opt ::= "segment" ws expr | "offset" ws expr | "side" rws ident
+in-place ::= "centered" | "anchor" rws anchor ( ws "inset" ws expr )?
+anchor ::= "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right"
+furn-clause ::= "size" ws dims | "label" ws string | "rotate" ws expr | "in" rws ident
+dim-stmt ::= "dim" ws point ws "->" ws point ( ws "offset" ws expr )? ( ws "text" ws string )?
+column-stmt ::= "column" rws id-opt "at" ws point ws "size" ws dims
+id-opt ::= ( "id" ws "=" ws ident rws )?
+point ::= "(" ws expr ws "," ws expr ws ")"
+dims ::= expr ws "x" ws expr
+expr ::= or-expr
+or-expr ::= and-expr ( ws "||" ws and-expr )*
+and-expr ::= eq-expr ( ws "&&" ws eq-expr )*
+eq-expr ::= cmp-expr ( ws eq-op ws cmp-expr )*
+eq-op ::= "==" | "!="
+cmp-expr ::= range-expr ( ws cmp-op ws range-expr )*
+cmp-op ::= "<=" | ">=" | "<" | ">"
+range-expr ::= add-expr ( ws ".." ws add-expr )*
+add-expr ::= mul-expr ( ws add-op ws mul-expr )*
+add-op ::= "+" | "-"
+mul-expr ::= unary-expr ( ws mul-op ws unary-expr )*
+mul-op ::= "*" | "/" | "%"
+unary-expr ::= unary-op ws unary-expr | postfix-expr
+unary-op ::= "-" | "+" | "!"
+postfix-expr ::= atom ( ws "[" ws expr ws "]" )*
+atom ::= number | string | array | if-expr | call | ref | "(" ws expr ws ")"
+call ::= ident ws "(" ws ( expr ( ws "," ws expr )* )? ws ")"
+ref ::= ident
+array ::= "[" ws ( expr ( ws "," ws expr )* )? ws "]"
+if-expr ::= "if" ws expr ws "{" ws expr ws "}" ws "else" ws "{" ws expr ws "}"
+number ::= digits frac?
+digits ::= [0-9]+
+frac ::= "." digits
+ident ::= [a-zA-Z_] [a-zA-Z0-9_]*
+string ::= "\"" str-char* "\""
+str-char ::= str-plain | str-esc | interp
+str-plain ::= [^"\\{}\n]
+str-esc ::= "\\" ( [^\n] | "\n" )
+interp ::= "{" ws expr ws "}"
+ws ::= sp cont*
+rws ::= sp1 ws
+sp ::= [ \t\r]{0,80}
+sp1 ::= [ \t\r] | comment "\n" | "\n"
+cont ::= comment "\n" sp | "\n" sp
+comment ::= "#" [^\n]*