archlang-mcp

@chanmeng666/archlang-mcp

一个用于 ArchLang 的 Model Context Protocol 服务，可通过任何支持 MCP 的主机，以代码编写、检查和修复架构平面图。

它是一个基于 @chanmeng666/archlang 库的轻量 stdio 适配层（不启动子进程，也不重新实现）：每个工具都封装一个纯导出函数。核心保持零依赖——MCP SDK 仅存在于此软件包中。

何时优先使用 CLI

ArchLang 面向 Agent 的主要接口是原生支持 Agent 的 archlang CLI，而非此服务。CLI 在调用前不会占用 Agent 上下文窗口，而 MCP 工具架构则会永久占据窗口。如果你的 Agent 已有 shell，请优先使用：

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

执行 npm i -g @chanmeng666/archlang 后，相同的调用命令是 archlang context 和 archlang compile …。此软件包也会安装 arch 别名，但在 Linux、macOS 和 Git Bash 上，coreutils 自带同名的 arch，因此在这些环境中直接运行 arch 会调用错误的程序。

此 MCP 服务的用途是让原生支持 MCP 的主机能够通过注册表发现 ArchLang，并在没有 shell 的情况下驱动它。它已列入官方 MCP 注册表，名称为 io.github.ChanMeng666/archlang-mcp。它是用于提高可发现性的渠道，而非替代方案。参见 ADR 0012（该文档修订了 ADR 0009 中关于优先分发而非协议的立场）。

服务说明

在 initialize 时，服务会发送一段简短的 instructions 字符串，支持该功能的主机会将其添加到模型上下文中：先读取 archlang://spec 资源，再编写 .arch → compile（和 fix）→ describe → 使用 strict:true 执行 validate → 完成操作，然后再导出。这是 SKILL.md 中工作循环的精简版；测试会确保其中列出的命令与 CLI 清单一致，且顺序符合该循环。

工具

每个工具都接收 ArchLang source（plan "…" { … } 字符串），并返回结构化 JSON。compile 还接受 plan_json（Plan-JSON / RPLAN 结构）。

工具	功能
compile	将源代码（或 plan_json）渲染为 SVG，或渲染为零依赖的 ASCII（format:"txt"）、对象形式的 Plan JSON（format:"json"，结构与 plan_json 接受的相同），或 PNG 图像（format:"png"，使用 archlang preview 的宽度，除非 width 覆盖该值；宽度限制在指定范围内；需要可选依赖 @resvg/resvg-js，而 .mcpb bundle 不包含它）。可选启用 accessible、overlay:"circulation"。返回输出和诊断信息。多层平面图会在 pages[] 中返回每一层；level 可渲染其中一层。
describe	语义事实（房间、面积、相邻关系、门、流线、区域、楼层、精确的 floor_polygon/floor_circle 形状，以及说明哪些位置由用户手动编写、哪些由解析器推导的 freedom 报告）——无需图像即可验证意图。
lint	提供建议性的 W_* 正确性警告（可能包括用于推断房间用途的修复项 W_ALIAS_MATCH，该用途是从间接标签别名推断得出的）；profile 用于选择规则集。
validate	解析 + 推导 + lint，作为交付门槛。strict 会在出现警告时失败；graph 会根据预期的房间图检查室内门的相邻关系；intent 会根据概要的约定进行门控（见 archlang://intent-schema）。
score	连续型意图 METER：衡量平面图满足概要要求的程度（satisfied/total/score/subscores）。仅衡量，不设门槛。
repair	显式修正器：将家具移出墙体/门口/开启范围 → 新的 .arch 源代码 + 变更日志。不会添加门或窗。
finish	完成图纸：为没有家具的房间添加家具，然后补上缺失的 paper、scale、dims auto、title、schedule rooms 和 legend → 新的 .arch 源代码 + 变更日志。只补充缺失项；only 仅运行一个阶段（furnish 或 sheet）；reissue 可以替换 paper/scale。
fix	应用平面图诊断信息中可由机器应用的修复项（语法修正器；有界不动点）。unsafe 会将范围扩展到 maybe-incorrect。
suggest	提供建议性的门/窗语句（每条语句都通过稳定引用——用户编写的 ID 或唯一类别——或绝对坐标来引用墙体，绝不使用可重新绑定的位置 ID），以解决无法到达的房间/没有窗户的卧室问题——仅返回数据，不会应用。
complete	返回指定源字节偏移处、作用域内的 LSP 补全项。
link	返回两个 URL，可在浏览器中显示平面图且无需安装任何内容：playground（托管的编辑器，含渲染结果）和 embed（仅平面图，供 iframe 使用），以及压缩后平面图的大小 bytes，还有 ok（平面图无法编译时附带 errors 计数；仍会生成链接，页面会显示诊断信息）。平面图会放在 URL 片段中。需要导出 ./link 的 core；较旧版本会返回 ok:false 及所需版本。

此处 compile 的 accessible 有何作用——以及它不做什么

accessible: true 会为 SVG 添加 <title>/<desc> 对，并在根元素上设置 role="img"；这就是此兼容层所提供的全部选项。**v1.36 的元素控件无法通过 MCP 使用。**它们需要同时设置 annotate 和 accessible，而此工具只会在 format:"txt" 时传递 annotate；它还将 accessible 作为布尔值，因此也无法请求 { idPrefix } 这种形式来避免同一 HTML 页面上的多个方案共享 arch-title/arch-desc。

如果宿主需要绘图可通过键盘操作并兼容屏幕阅读器（每个元素上都有 data-arch-primary、role="button"、aria-label），就必须调用库。CLI 也无法生成这种绘图：annotate 没有对应的标志，因此 archlang compile --accessible 也只会生成 <title>/<desc> 对。

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

输出约定、嵌入方仍需负责的事项，以及已知的屏幕阅读器限制，详见语言参考。

资源

URI	内容
archlang://spec	完整语言规范，汇集于一个页面（spec.llm.md）。
archlang://context	完整的 Agent 上下文：规范 + 工作流 + CLI 参考 + 错误目录（llms-full.txt）。
archlang://schema	Plan-JSON 编译输入的 JSON Schema（2020-12）。
archlang://grammar	用于保证生成结果可解析的 GBNF 约束解码语法。
archlang://intent-schema	Brief 的 Intent 的 JSON Schema（2020-12）——即 validate 的 intent 和 score 的 brief 所采用的结构。

安装

Claude Code

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

Claude Desktop

在 claude_desktop_config.json 中添加（Settings → Developer → Edit Config）：

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

Cursor

在 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）中添加：

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

VS Code

在 .vscode/mcp.json 中添加：

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

许可证

MIT © Chan Meng