Merge pull request #57 from ChanMeng666/release/v1.24.0

release: v1.24.0 — curved geometry (Batch-2 finale) + mcp 0.2.3

Author: ChanMeng666

AGENTS.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.24.0] - 2026-07-26
+
 ### Added
 
 - **`arc (x,y) radius R [cw|ccw] [major]` — curved wall edges.** Written where a vertex goes
@@ -70,6 +72,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   legitimately reports no **`adjacent`** rooms (a circle meets a straight wall at a point, and
   `adjacent` has always meant a shared *run*) and carries its connectivity through its doors.
 
+### MCP shim (`@chanmeng666/archlang-mcp` 0.2.3)
+
+- **Its shipped context resources were five releases stale.** `archlang://spec`,
+  `archlang://context` and `archlang://grammar` are copied into the package at pack time, so the
+  published 0.2.2 described the **v1.19** language while its dependency range resolved to a current
+  core — an MCP-native agent was told nothing about `paper`/`scale`, `level`, `place`, `zone`,
+  `room polygon` or `arc`, and the GBNF grammar it was handed could not *decode* them at all. This
+  republish refreshes all five resources; the dependency range is now `^1.24.0`, so the range can
+  no longer promise a surface the installed core lacks.
+- **`compile` no longer answers a multi-storey plan with the ground floor alone.** It returns every
+  storey in `pages[]` (`{ level, name, output }`) and takes a `level` selector; `output` still holds
+  the lowest storey, so a level-unaware caller is unchanged, and a single-storey result carries no
+  `pages` key. An undeclared `level` comes back as an error naming the real `levels` — never a
+  silent substitution that would read as a successful render of the storey you asked for.
+- **The handshake reports the shim's real version.** It was a hardcoded `"0.2.0"` from 0.2.1 on, so
+  the server misintroduced itself to every host; it is now derived from `package.json` the way the
+  core CLI derives its own, and a test pins the two together.
+- Tool descriptions now name the current surface (the shape facts `floor_polygon` / `floor_circle`,
+  `zones`, `levels`, `vertical`, `bbox_outer`, `freedom`) instead of the v1.14 one.
+
 ### Diagnostics
 
 - **`E_ARC_RADIUS`** — a radius under half the chord describes no circle through the two

CHANGELOG.md

@@ -1,6 +1,6 @@
 {
   "name": "@chanmeng666/archlang",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "A small declarative language that compiles to professional SVG floor plans — like Typst/LaTeX, but for architecture.",
   "keywords": [
     "architecture",

package-lock.json

@@ -33,10 +33,11 @@ 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, and a `freedom` report of which positions are hand-authored vs resolver-derived) — verify intent without an image. |
+| `compile` | Render source (or `plan_json`) to SVG, or to zero-dep ASCII (`format:"txt"`). `accessible`, `overlay:"circulation"` opt-ins. Returns output + diagnostics. A multi-storey plan returns every storey in `pages[]`; `level` renders one. |
+| `describe` | Semantic facts (rooms, areas, adjacency, doors, circulation, zones, storeys, the exact `floor_polygon`/`floor_circle` shape, and a `freedom` report of which positions are hand-authored vs resolver-derived) — verify intent without an image. |
 | `lint` | Advisory `W_*` soundness warnings (may include the fix-carrying `W_ALIAS_MATCH` for a room use inferred from an indirect label alias); `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. |
+| `validate` | Parse + resolve + lint, the ship gate. `strict` fails on warnings; `graph` checks interior-door adjacency against an intended room graph; `intent` gates on a brief's contract (per `archlang://intent-schema`). |
+| `score` | The continuous intent METER: how much of a brief a plan satisfies (`satisfied`/`total`/`score`/`subscores`). Measures, never gates. |
 | `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 (each referencing its wall by a stable ref — an authored id or a unique category — or absolute coordinates, never a re-bindable positional id) to resolve unreachable rooms / windowless bedrooms — data, never applied. |
@@ -50,6 +51,7 @@ structured JSON. `compile` also accepts `plan_json` (the Plan-JSON / RPLAN shape
 | `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. |
+| `archlang://intent-schema` | JSON Schema (2020-12) for a brief's Intent — the shape `validate`'s `intent` and `score`'s `brief` take. |
 
 ## Install
 

package.json

@@ -1,8 +1,8 @@
 {
   "name": "@chanmeng666/archlang-mcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "mcpName": "io.github.ChanMeng666/archlang-mcp",
-  "description": "Model Context Protocol (MCP) server for ArchLang — compile, describe, lint, validate, score, repair, fix and suggest floor plans over stdio, plus the v1.14 intent channel (gate + continuous score against a brief). A thin shim over @chanmeng666/archlang; the CLI stays the primary, token-cheaper interface.",
+  "description": "Model Context Protocol (MCP) server for ArchLang — compile, describe, lint, validate, score, repair, fix and suggest floor plans over stdio, plus the intent channel (gate + continuous score against a brief). Covers the whole current language: multi-storey `level` plans with stairs, `place`d components, zones, scaled paper with dimension chains and room schedules, and non-rectilinear `room polygon` / `room circle` / `arc` walls. A thin shim over @chanmeng666/archlang; the CLI stays the primary, token-cheaper interface.",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -42,7 +42,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@chanmeng666/archlang": "^1.14.0",
+    "@chanmeng666/archlang": "^1.24.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.25.76"
   },

packages/mcp/README.md

@@ -1,8 +1,8 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.ChanMeng666/archlang-mcp",
-  "description": "Compile, describe, lint, validate, score and repair ArchLang floor plans (.arch to SVG) over stdio.",
-  "version": "0.2.2",
+  "description": "Compile, describe, lint, validate, score and repair multi-storey and curved ArchLang floor plans.",
+  "version": "0.2.3",
   "repository": {
     "url": "https://github.com/ChanMeng666/archlang",
     "source": "github",
@@ -14,7 +14,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@chanmeng666/archlang-mcp",
-      "version": "0.2.2",
+      "version": "0.2.3",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

packages/mcp/package.json

@@ -48,6 +48,29 @@ function readResource(flat: string, repoRel: string): string {
   return `(${flat} not found — run \`npm run mcp:build\`)`;
 }
 
+/**
+ * This shim's own version, for the MCP handshake — **derived, never retyped**. It was a
+ * hardcoded literal through 0.2.1–0.2.2, so the published server introduced itself as
+ * "0.2.0" and a host had no reliable way to tell which shim it was talking to. Mirrors the
+ * core's `readVersion()` (`src/cli/io.ts`): `../package.json` resolves from both `dist/`
+ * (the packed artifact — npm always includes package.json) and `src/` (the tests).
+ */
+function readShimVersion(): string {
+  for (const rel of ["../package.json", "../../package.json"]) {
+    const p = resolve(HERE, rel);
+    if (existsSync(p)) {
+      try {
+        const v = JSON.parse(readFileSync(p, "utf8")).version;
+        if (typeof v === "string") return v;
+      } catch {
+        /* fall through to the next candidate */
+      }
+    }
+  }
+  return "0.0.0";
+}
+export const SHIM_VERSION = readShimVersion();
+
 // ---------------------------------------------------------------------------
 // helpers
 // ---------------------------------------------------------------------------
@@ -103,14 +126,14 @@ function resolveSource(input: {
 
 /** Build the fully-configured ArchLang MCP server (tools + resources). */
 export function createServer(): McpServer {
-  const server = new McpServer({ name: "archlang", version: "0.2.0" });
+  const server = new McpServer({ name: "archlang", version: SHIM_VERSION });
 
   server.registerTool(
     "compile",
     {
       title: "Compile ArchLang → SVG or ASCII",
       description:
-        'Compile ArchLang `.arch` source (or a Plan-JSON object) to an SVG floor plan, or to a zero-dependency ASCII text plan (format:"txt"). Returns the rendered output plus diagnostics — each a byte span, line/col, catalogued E_/W_ code, and a machine-applicable fix. Errors are DATA, never exceptions: read `diagnostics` and correct the source.',
+        'Compile ArchLang `.arch` source (or a Plan-JSON object) to an SVG floor plan, or to a zero-dependency ASCII text plan (format:"txt"). Returns the rendered output plus diagnostics — each a byte span, line/col, catalogued E_/W_ code, and a machine-applicable fix. Errors are DATA, never exceptions: read `diagnostics` and correct the source. A MULTI-STOREY plan (`level <n> { … }`) is a set of drawings: `output` is the lowest storey and every storey comes back in `pages[]` ({ level, name, output }), so pass `level` to render just one.',
       inputSchema: {
         source: z.string().optional().describe('ArchLang source (a `plan "…" { … }`). Provide this OR plan_json.'),
         plan_json: z
@@ -120,21 +143,59 @@ export function createServer(): McpServer {
         format: z.enum(["svg", "txt"]).optional().describe("svg (default) or txt (zero-dependency ASCII)."),
         accessible: z.boolean().optional().describe("Emit <title>/<desc>/role/aria accessibility metadata (SVG only)."),
         overlay: z.enum(["circulation"]).optional().describe("Draw an opt-in circulation overlay (SVG only)."),
+        level: z
+          .number()
+          .int()
+          .optional()
+          .describe("Render only this storey of a multi-storey plan. An undeclared level is an error, not a guess."),
       },
     },
     async (a) => {
       const r = resolveSource(a);
       if ("diagnostics" in r) return json({ ok: false, diagnostics: r.diagnostics });
       const format = a.format ?? "svg";
-      const { svg, diagnostics, scene } = compile(r.source, {
+      const { svg, diagnostics, scene, pages } = compile(r.source, {
         noCache: true,
         ...(a.accessible ? { accessible: true } : {}),
         ...(a.overlay === "circulation" ? { overlays: ["circulation"] as const } : {}),
         ...(format === "txt" ? { annotate: true } : {}),
       });
       const diags = toJson(r.source, diagnostics);
       if (errorCount(diagnostics) > 0 || !scene) return json({ ok: false, format, diagnostics: diags });
-      return json({ ok: true, format, output: format === "txt" ? renderAscii(scene) : svg, diagnostics: diags });
+      const render = (pageSvg: string, pageScene: typeof scene) =>
+        format === "txt" ? renderAscii(pageScene) : pageSvg;
+      // A `level` this plan does not declare is refused with the real set — never silently
+      // answered with the ground floor, which would look like a successful render of it.
+      if (a.level !== undefined) {
+        const levels = pages?.map((p) => p.level) ?? [];
+        const want = pages?.find((p) => p.level === a.level);
+        if (!want)
+          return json({ ok: false, format, error: `no level ${a.level} in this plan`, levels, diagnostics: diags });
+        return json({
+          ok: true,
+          format,
+          level: want.level,
+          output: render(want.svg, want.scene),
+          levels,
+          diagnostics: diags,
+        });
+      }
+      return json({
+        ok: true,
+        format,
+        output: render(svg, scene),
+        // Present only for a genuinely multi-storey plan, so a single-storey result is unchanged.
+        ...(pages
+          ? {
+              pages: pages.map((p) => ({
+                level: p.level,
+                ...(p.name !== undefined ? { name: p.name } : {}),
+                output: render(p.svg, p.scene),
+              })),
+            }
+          : {}),
+        diagnostics: diags,
+      });
     },
   );
 
@@ -143,7 +204,7 @@ export function createServer(): McpServer {
     {
       title: "Describe a plan (facts, no render)",
       description:
-        "Semantic facts about a plan without rendering: rooms (areas, bboxes, adjacency, uses), doors (what they connect), windows, circulation (walk distance / bottleneck width / detour), and totals. The channel a text-only agent uses to VERIFY that a plan matches intent.",
+        "Semantic facts about a plan without rendering: rooms (areas, bboxes, adjacency, uses, and the exact shape — `floor_polygon` for a `room polygon`, `floor_circle` for a `room circle`, whose area is exact πR²), doors (what they connect), 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 vs resolver-derived), and totals. The channel a text-only agent uses to VERIFY that a plan matches intent.",
       inputSchema: { source: z.string().describe("ArchLang source.") },
     },
     async ({ source }) => {

packages/mcp/server.json

@@ -1,7 +1,8 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { describe, expect, it } from "vitest";
-import { createServer } from "../src/server.js";
+import pkg from "../package.json" with { type: "json" };
+import { createServer, SHIM_VERSION } from "../src/server.js";
 
 /** Link a fresh server to a client over the SDK's in-process transport. */
 async function connect(): Promise<Client> {
@@ -21,6 +22,17 @@ function payload(result: unknown): Record<string, unknown> {
 
 const TINY = 'plan "Smoke" {\n  room at (0,0) size 4000x3000 label "Room"\n}\n';
 
+/** Two storeys — the shape that used to come back as the ground floor alone. */
+const TWO_STOREY = `plan "Stack" {
+  level 1 "Ground floor" {
+    room at (0,0) size 4000x3000 label "Living"
+  }
+  level 2 "First floor" {
+    room at (0,0) size 4000x3000 label "Bedroom"
+  }
+}
+`;
+
 describe("archlang mcp server", () => {
   it("exposes the wrapping tools and resources", async () => {
     const client = await connect();
@@ -57,6 +69,46 @@ describe("archlang mcp server", () => {
     expect((out.diagnostics as unknown[]).length).toBeGreaterThan(0);
   });
 
+  it("introduces itself with its REAL version, not a hardcoded literal", async () => {
+    const client = await connect();
+    // The handshake version was frozen at "0.2.0" through 0.2.1–0.2.2; deriving it from
+    // package.json is what keeps it honest, so pin it to the package rather than to a string.
+    expect(SHIM_VERSION).toBe(pkg.version);
+    expect(client.getServerVersion()?.version).toBe(pkg.version);
+  });
+
+  it("compile returns every storey of a multi-storey plan, not just the ground floor", async () => {
+    const client = await connect();
+    const out = payload(await client.callTool({ name: "compile", arguments: { source: TWO_STOREY } }));
+    expect(out.ok).toBe(true);
+    const pages = out.pages as Array<{ level: number; name?: string; output: string }>;
+    expect(pages.map((p) => p.level)).toEqual([1, 2]);
+    expect(pages.map((p) => p.name)).toEqual(["Ground floor", "First floor"]);
+    // `output` stays the lowest storey, so a level-unaware caller is unaffected.
+    expect(out.output).toBe(pages[0]?.output);
+    // Each storey is its own drawing: the upper floor is not a copy of the ground floor.
+    expect(pages[1]?.output).not.toBe(pages[0]?.output);
+  });
+
+  it("compile --level renders one storey, and refuses one the plan lacks", async () => {
+    const client = await connect();
+    const one = payload(await client.callTool({ name: "compile", arguments: { source: TWO_STOREY, level: 2 } }));
+    expect(one.ok).toBe(true);
+    expect(one.level).toBe(2);
+    expect(one.pages).toBeUndefined();
+    const bad = payload(await client.callTool({ name: "compile", arguments: { source: TWO_STOREY, level: 7 } }));
+    expect(bad.ok).toBe(false);
+    expect(bad.levels).toEqual([1, 2]);
+    expect(bad.output).toBeUndefined();
+  });
+
+  it("a single-storey compile carries no pages key", async () => {
+    const client = await connect();
+    const out = payload(await client.callTool({ name: "compile", arguments: { source: TINY } }));
+    expect(out.ok).toBe(true);
+    expect(out.pages).toBeUndefined();
+  });
+
   it("describe returns rooms and totals", async () => {
     const client = await connect();
     const out = payload(await client.callTool({ name: "describe", arguments: { source: TINY } }));