ClassCAD

@classcad/mcp

适用于 ClassCAD CAD 引擎的模型上下文协议服务。开箱即用：它会自行运行 ClassCAD 引擎（WASM），无需搭建服务。

支持 MCP 的宿主（Claude Code、Claude 桌面应用、VS Code Copilot、Cursor，……）可以通过脚本驱动实时 ClassCAD 会话：构建零件和装配体、检查结构树、渲染快照，以及保存和加载 STEP、STL 和 OFB。

会话由多方共享。CAD 应用 Buerligons 会接入会话：用户可以旋转、选择和编辑与 Agent 构建的同一个模型。会话链接可以发送给同事，或在另一台设备上打开（通过共享中继）；Agent 也可以加入用户已打开的应用会话。

---

工作原理

 Claude tab 1 ── stdio ──► classcad-mcp (shim) ──┐
 Claude tab 2 ── stdio ──► classcad-mcp (shim) ──┤ HTTP (MCP Streamable HTTP, 127.0.0.1:9097)
 VS Code      ── stdio ──► classcad-mcp (shim) ──┘
                                                 ▼
                                   classcad-mcp daemon (ONE per machine)
                                     session (one per host connection), its drawings (one per model):
                                       drawing d-… ── worker thread ──► ClassCAD WASM (the MCP's own engine)
                                       drawing d-… ── WebSocket ─────► ClassCAD worker (classcad-cli, optional)
                                       drawing d-… ── WebSocket ─────► a session an app shares (by invite)
                                     127.0.0.1:9098  ◄── the app, docked into a drawing · apps that host a session of their own
                                     wss, dialled out ──► share relay (Cloudflare) ◄── the app on any other machine, by share link

• 开箱即用。 MCP 自带引擎：运行在守护进程工作线程中的已发布 ClassCAD WASM 构建。无需配置服务或密钥：引擎密钥随一次 classcad.ch 免费账户登录一起提供。首次使用时会下载发布资源（约 16 MB）并缓存。
• 每个宿主都会将 MCP 作为 stdio 子进程启动（npx -y @classcad/mcp@latest）。该进程是一个轻量 shim：它会在 127.0.0.1:9097 查找守护进程；如果没有运行，就启动它，并将宿主的 JSON-RPC 转发给它。第一个标签页会启动守护进程，之后的每个标签页都会复用它。
• 守护进程才是真正的 MCP。它为每个宿主连接持有一个会话，其中为每个绘图持有一个 MCP 服务实例（独立的引擎、缓存、工具队列和邀请；参见绘图），并持有一个供会话加入的监听器（127.0.0.1:9098）：应用会接入 MCP 在此处提供的会话；在自有页面中运行引擎的应用也会在此处提供其会话。如果已没有会话，且没有此类应用在等待，守护进程会在 CLASSCAD_DAEMON_IDLE_MS（60 秒）后自行退出。无需安装或管理：它是此软件包的一部分（dist/daemon.js），只会在使用期间运行。
• 为什么需要守护进程：MCP 会监听一个端口，而一个端口只能属于一个进程。有了一个守护进程，每个会话的应用链接都使用相同地址，查找 MCP 的应用也能找到它。
• 与用户共享。 每个绘图都有一个接入同一引擎的实时 CAD 应用：参见应用。会话协议与 ClassCAD 服务使用的协议相同，因此任何 buerli 应用都能以相同方式加入：参见共享。
• 与其他设备共享。 会话也会发布到共享中继（packages/relay，一个 Cloudflare Worker），因此应用链接可在任何设备上使用。MCP 会向中继发起连接；设备上不会有任何端口监听外部连接。参见其他地方的人加入。
• 可选引擎。 如果可连接到 classcad-cli worker（CLASSCAD_WS_URL，默认为 ws://localhost:9094/），默认策略 auto 会使用它，而不是本地引擎。参见引擎。
• 引擎会在绘图首次调用工具时按需启动，因此空闲会话不会产生开销；未使用的绘图会释放其引擎（进入休眠，参见绘图）。
• 回退机制：如果 127.0.0.1:9097 被非 classcad 守护进程占用，shim 会在进程内提供 MCP（使用自己的监听器；若 9098 已被占用，则使用空闲端口），并在 stderr 中说明情况。

---

前置条件

• Node.js 20+（node、npx）
• 首次使用时需要联网（软件包来自 npm，引擎来自 awvstatic.com；之后可离线使用）
• 一个免费的 classcad.ch 账户，每台设备登录一次（Google、GitHub 或邮箱）。MCP 会在首次使用时自动提示登录；参见登录。

无需其他条件：无需 ClassCAD 服务或密钥。

---

安装

无需克隆或构建。每个宿主只需运行一条命令即可启动服务：

npx -y @classcad/mcp@latest

@latest 会让 npx 获取最新版本，而不是重复使用缓存版本；-y 会跳过安装提示。npx 可能会警告未运行 sharp 的安装脚本；这没关系，sharp 附带预构建的二进制文件。

**Windows（原生环境，不是 WSL）：**宿主无法直接启动 npx。将 cmd 用作命令，并使用参数 /c npx -y @classcad/mcp@latest，例如 claude mcp add classcad --scope user -- cmd /c npx -y @classcad/mcp@latest，或者在 JSON 配置中设置 "command": "cmd", "args": ["/c", "npx", "-y", "@classcad/mcp@latest"]。（下方的 Claude Code 插件无需此项更改。）

仅在无法访问 npm 时从源代码安装：git clone https://github.com/awv-informatik/classcad-ai.git && cd classcad-ai && npm install && npm run build，然后使用 node /abs/path/to/classcad-ai/packages/mcp/dist/server.js 替代 npx 命令（echo "$PWD/packages/mcp/dist/server.js" 会打印路径）。

---

配置宿主

每个宿主都需要上面的命令和一个新会话（或重启），以便启动服务。无需设置环境变量。

Claude Code（CLI 和桌面应用的 Code 标签页）

该插件包含 MCP 服务和 ClassCAD 技能，适用于 macOS、Linux 和 Windows：

claude plugin marketplace add awv-informatik/classcad-ai
claude plugin install classcad@classcad

或者只添加 MCP 服务（二选一，不要同时添加）：

claude mcp add classcad --scope user -- npx -y @classcad/mcp@latest

--scope user 会写入 ~/.claude.json（适用于所有项目）；--scope project 则会将 .mcp.json 写入当前仓库。使用 claude mcp list 验证，条目应显示 ✔ Connected。工具会在下一个会话中显示（每个会话都会启动自己的 MCP 进程）；在正在运行的会话中，使用 /mcp 重新连接。

在 ~/.claude.json / .mcp.json 中手动配置的等效写法：

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

Claude 桌面应用（Chat / Cowork）

桌面应用的聊天端有自己的配置，不会读取 ~/.claude.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加上面相同的 mcpServers 配置块。该应用为所有聊天共用一个 MCP 连接；每个聊天操作的都是自己的图形（参见图形），因此一个聊天绝不会触及另一个聊天的模型。该应用不是从 shell 启动的，因此没有 PATH：如果它无法启动 npx，请将 npx 的绝对路径设为 command（which npx 会告诉你路径；macOS Homebrew 路径为 /opt/homebrew/bin/npx）；如果接着找不到 node，则添加 "env": { "PATH": "<the folder that holds node>:/usr/bin:/bin" }。退出并重新打开应用——它只会在启动时启动 MCP 服务。随后，服务会显示在 Settings → Developer 下，聊天中会内嵌显示快照图像。

Codex

~/.codex/config.toml：

[mcp_servers.classcad]
command = "npx"
args = ["-y", "@classcad/mcp@latest"]

VS Code — GitHub Copilot Chat（Agent 模式）

命令面板 → MCP: Add Server，或编辑 .vscode/mcp.json（工作区）/用户 MCP 配置：

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

（顶层键为 servers，并且需要显式指定 "type": "stdio"。）将 Copilot Chat 切换到 Agent 模式；随后即可选择 classcad 工具。

Cursor

~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：使用 Claude Code 部分中的 mcpServers 配置块。

OpenCode

opencode.json：

{
  "mcp": {
    "classcad": { "type": "local", "command": ["npx", "-y", "@classcad/mcp@latest"] }
  }
}

其他宿主

大多数宿主都接受 Claude 风格的 mcpServers JSON 配置。

首次测试

在新会话中，让 Agent 创建一个盒子。首次使用时会显示登录链接：打开链接并登录，Agent 随后会自行继续。然后它应该会调用 run_script 并返回体积，同时应用中会显示盒子（在桌面应用的 Browser 窗格中，或在浏览器中）；使用答案中提到的图形调用 session_info 时，会显示 "transport": "wasm"（如果正在运行 worker，则显示 "ws"）。首次调用会稍慢一些，因为需要下载 WASM 资源。

---

图纸

每个针对模型运行的工具都需要一个 drawing。首次调用模型时传入 "new"：MCP 会打开一张图纸——一个独立的引擎会话，拥有自己的工具队列、检查点和应用——并在回答中给出其 ID（d-k3v9q2xa）。此后每次调用该模型时都传入这个 ID。另一个无关的模型对应另一张图纸。docs、list_methods、describe_method、login 和 account 无需图纸，而不带图纸的 session_info 会返回整个 MCP 的信息。

原因。 有些宿主会通过一个连接处理多个对话：Claude 桌面聊天应用和 Cowork 会为所有对话启动一个 MCP 进程，Cursor 和 VS Code 则会为每个窗口启动一个。请求中没有任何信息表明它来自哪个对话。如果每个连接只有一张图纸，一个对话的 clear 或 load 就会导致另一个对话丢失模型。图纸的 ID 是随机的，只有打开它的对话会收到该 ID，因此其他对话无法访问它。不带 ID，或带有此连接不认识的 ID 的调用会被拒绝，且不会更改任何内容。各张图纸会并行运行：两个对话的脚本不会互相等待。

图纸会随会话（宿主的连接）结束而终止。若要在此后保留模型，请将其 save（OFB 会保留其特征）。

闲置图纸会休眠。 本地引擎会占用内存：守护进程中的第一个引擎约占用 850 MB，此后每个约占用 350 MB。某张图纸在 CLASSCAD_DRAWING_IDLE_MS（10 分钟）内无人使用后，会释放其引擎：图纸以 OFB 的形式留在守护进程中；下一次调用它，或停靠在其中的应用执行下一条命令时，都会启动引擎并重新加载图纸，沿用原有的 ID 和检查点。同一连接最多有 CLASSCAD_DRAWINGS_AWAKE（3）张图纸保持运行；最近最少使用的图纸会最先休眠。唤醒需要一两秒。工作器上的图纸属于工作器的会话，不会休眠。

应用

每个绘图都有一个实时 CAD 应用：Buerligons，也就是 buerli CAD 应用，嵌入绘图自己的引擎中。此软件包内含它的构建版本，并自行提供服务，因此无需安装，也能离线使用。

• 创建绘图的第一个模型时，应用就会启动，并实时显示 Agent 所做的每项更改。应用打开的位置由宿主决定：在 Claude 桌面应用（Code 标签页）中，它会显示在应用自己的 Browser 面板里，位于对话旁边——Agent 会在此处打开应用；在其他所有环境中，MCP 会打开用户的默认浏览器。创建第一个模型的脚本执行结果会以链接（App: …）结尾，每个绘图仅出现一次：Agent 不会在每条回复中重复提供该链接。session_info 会指出链接，view 会返回链接并再次打开应用（除非用户已经打开了应用：每个绘图一个标签页就够了）。
• 用户也可以在应用中操作。 旋转和缩放、测量、选择；编辑特征的值、绘制草图并添加约束、添加或删除特征、重新开始或打开文件。双方操作的是同一个模型：用户所做的更改会出现在 Agent 下一次读取的特征树中，而 Agent 创建的内容会立即显示在应用中。应用发出的命令会等待正在运行的脚本完成，因此两者绝不会在同一脚本中交错执行。
• 指示对象。 Agent 可以通过 get_selection 读取用户在应用中选中的对象（“倒圆角处理这条边”）；使用 set_selection，Agent 可以为用户高亮显示对象。
• 文件。 应用的 File 菜单可以将模型保存为 OFB（ClassCAD 自有格式，包含特征）、STEP 或 STL 文件，也可以将此类文件打开到当前会话中。
• 每个绘图一个链接，链接可随处使用。 链接会邀请用户加入恰好一个绘图的会话，因此多个绘图（对话、标签页、宿主）可以并行运行，各自拥有独立的应用。默认情况下，链接是一个共享链接，https://<relay>/?invite=…：同一链接可供同事使用，也可在用户的平板电脑上使用（见其他人从别处加入）。当中继不托管该会话时，或设置了 CLASSCAD_SHARE=ask 或 off 时，链接会指向此机器：http://127.0.0.1:9098/?invite=…。会话结束或迁移到另一引擎时，应用会显示提示，并提供重新加入的选项。
• 模型所在的位置。 会话及其引擎始终留在用户的机器上。MCP 会在 127.0.0.1:9098 上提供应用服务（CLASSCAD_VIEWER_PORT；若该端口已被占用，则使用另一个空闲端口），并且只响应将其指定为主机的请求：从此处打开时，模型数据不会离开这台机器。通过共享链接打开时，应用的帧会经过中继，但中继不会保留任何帧。邀请是加入会话的密钥，因此链接是机密：持有共享链接的任何人都能加入。

CLASSCAD_VIEWER_OPEN 用于指定应用打开的位置：browser（用户的默认浏览器）、host（Agent 在宿主自己的浏览器面板中打开应用——适用于任何带有此类面板的宿主），或 0（不在任何地方打开：Agent 会提供链接）。未设置时，在 Claude 桌面应用中默认为 host，在其他所有环境中默认为 browser。CLASSCAD_APP_URL 用于指定托管在其他位置的应用，以替代此软件包中的应用：链接会变为 <url>?invite=…，而应用必须通过 ws://127.0.0.1:9098/session 加入该邀请（页面中为此引擎构建的 Buerligons 已支持此功能）。只有在浏览器允许的情况下，公共网站上的页面才能访问 127.0.0.1：见下文浏览器必须允许的条件。CLASSCAD_VIEWER=readonly 会显示只读 3D 视图，而非应用（这是一个只能旋转模型和导出模型的页面；不含应用的软件包构建版本也提供此视图）；CLASSCAD_VIEWER=off 则不显示任何内容。

---

登录

MCP 适用于已登录的 classcad.ch 账号，每台机器登录一次即可。安装 Agent 会在最后一步登录（login，或在终端中运行 classcad-mcp login）；否则，在尚未登录的机器上首次调用引擎工具时，会先启动登录流程，而不是执行工具。

1. 登录页面会自动在用户的浏览器中打开（使用 open / xdg-open / start；在没有显示器的远程 shell 中，或设置了 CLASSCAD_AUTH_NO_BROWSER=1 时不会自动打开），Agent 也会显示同一个链接作为备用：https://classcad.ch/connect?port=…&state=…。与此同时，MCP 会在 127.0.0.1:<port> 上监听，等待此次登录（15 分钟）。
2. 用户打开页面并登录或创建账号（Google、GitHub 或邮箱）。如果已登录 classcad.ch，只需点击一次“Continue”。
3. 页面会将登录信息交回 http://127.0.0.1:<port>/callback（令牌位于 URL 片段中，服务器无法看到）。MCP 会通过 Firebase 验证，并将其存储在 ~/.classcad-mcp/auth.json 中。
4. 与此同时，Agent 会在 login 工具中等待；登录信息到达后，该工具会立即返回。浏览器标签页会提示用户返回 Agent。

此后，该机器上的每个会话都会保持登录状态。MCP 最多每小时通过 Firebase 重新验证一次账号；如果账号被撤销或停用，该机器将退出登录；如果没有网络连接，则最近一次验证结果在 14 天内仍有效。session_info 会显示账号信息。文档工具（list_methods、describe_method、docs）无需登录即可使用。

在终端中也可以执行相同流程及更多操作（在代码检出目录中运行 node dist/server.js <command>）：

• classcad-mcp login 会打印链接并等待用户访问
• classcad-mcp whoami 会显示登录信息
• classcad-mcp logout 会让该机器退出登录（也可以使用 logout: true 调用 login 工具）

---

环境变量

变量	用途
CLASSCAD_WS_URL	可选 ClassCAD 工作器的 WebSocket URL。默认值为 ws://localhost:9094/；无法连接时 → 使用本地 WASM 引擎。任何可连接的工作器均可（wss://…）。
CLASSCAD_SNAPSHOT_DIR	调用未传入 outDir 时，snapshot 写入 PNG 文件的位置。默认值为 <tmpdir>/classcad-snapshots。
CLASSCAD_SKILL_PATH	从技能目录（代码库检出版本的 packages/skill）实时读取文档，而不是使用已安装的 @classcad/skill 中的捆绑文档：编辑后无需重新构建即可生效。
CLASSCAD_MCP_PORT	守护进程在 127.0.0.1 上的 HTTP 端点端口。默认值为 9097。适配器和守护进程必须一致（适配器启动守护进程时会传入此值）。
CLASSCAD_MCP_URL	使用完整的守护进程 URL，而不是 http://127.0.0.1:<port>（很少需要）。
CLASSCAD_DAEMON_IDLE_MS	守护进程在没有任何会话、也没有任何可提供自身会话的应用时，闲置多久后退出。默认值为 60000。
CLASSCAD_DRAWING_IDLE_MS	本地引擎上的图纸在未使用时保持唤醒的时长，超过后会释放其引擎（图纸）。默认值为 600000（10 分钟）。
CLASSCAD_DRAWINGS_AWAKE	同一连接中可让本地引擎持续运行的图纸数量；超出此数量时，最近最少使用的图纸将进入休眠。默认值为 3。
CLASSCAD_MCP_LOG	守护进程日志文件。默认值为 <tmpdir>/classcad-mcp/daemon.log（适配器启动时会在 stderr 中打印路径）。
CLASSCAD_ENGINE	未通过令牌或 URL 指定时采用的引擎策略：auto（默认：使用工作器，否则使用本地 WASM 引擎）、drogon（仅工作器）、wasm（仅本地引擎）。
CLASSCAD_VIEWER	会话向用户显示的内容。默认值：应用。readonly：只读 3D 视图。off：不显示任何内容。
CLASSCAD_VIEWER_PORT	会话加入的监听端口，位于 127.0.0.1。默认值为 9098；若该端口已被占用，则使用空闲端口（0：始终使用空闲端口）。托管自身会话的应用会在 9098 上查找 MCP。
CLASSCAD_VIEWER_OPEN	首个模型打开时应用的显示位置：browser（用户的默认浏览器）、host（Agent 在宿主自身的浏览器面板中打开）、0（不打开；提供链接）。默认值：Claude 桌面应用的 Code 标签页中为 host，其他情况下为 browser。按会话设置。
CLASSCAD_APP_URL	应用托管在其他位置时，要嵌入会话的应用（例如 https://buerligons.io/）；链接将变为 <url>?invite=…。默认值为此软件包中的应用。
CLASSCAD_RELAY_URL	用于共享会话的中继服务（https://…；packages/relay）。off：从不共享会话。默认值为 https://classcad-share.it-5ca.workers.dev（src/share/relay.ts 中的 DEFAULT_RELAY_URL）。
CLASSCAD_SHARE	会话何时获得可在其他设备上使用的链接：always（默认值——从首个模型开始即共享，且应用通过该链接打开）、ask（用户通过 share 工具请求时共享；应用自身的链接仍使用 127.0.0.1）、off（从不共享）。
CLASSCAD_BACKEND	classcad（默认值）：规划后端，在 classcad.ch 上登录。develop：相同的后端，在 classcad.ch 的开发构建版本上登录（http://localhost:9090）。staging：在 https://staging01.classcad.ch 上登录。
CLASSCAD_TOKEN	用于无需登录的机器（CI）的秘密访问令牌（ccsk_…，在 classcad.ch/account 上创建）：使用该令牌获取引擎密钥，而不是通过登录获取。
CLASSCAD_AUTH_URL	登录页面。默认值为 https://classcad.ch/connect（设置 CLASSCAD_BACKEND=develop 时为 http://localhost:9090/connect）。
CLASSCAD_AUTH_FILE	登录信息的存储位置。默认值为 ~/.classcad-mcp/auth.json。
CLASSCAD_AUTH_NO_BROWSER	1：不在浏览器中打开登录页面；由 Agent 显示链接（设置了 CI 时也会如此）。
CLASSCAD_WASM_KEY	用于本地引擎的自有密钥，代替从后端获取的密钥：适用于没有互联网连接的机器或合同场景。其他情况下不需要。
CLASSCAD_WASM_ORIGIN	本地引擎声明的运行来源。默认值为 http://localhost，供本地使用的密钥允许使用任意端口。
CLASSCAD_WASM	off：不使用本地引擎（仅使用工作器）。
CLASSCAD_KEY_URL、CLASSCAD_KEY_FILE	令牌交换端点（默认为规划后端的 /api/v1/key），以及引擎密钥的存放位置（默认为 ~/.classcad-mcp/engine-key.json）。
CLASSCAD_WASM_VERSION	要托管的 ClassCAD 版本。默认值为 21.2.0（buerli 应用加载的版本）。
CLASSCAD_WASM_DIR	发行资源的缓存位置。默认值为 ~/.classcad-mcp/wasm/<version>。
CLASSCAD_WASM_URL	下载基址覆盖项。默认值为 https://awvstatic.com/classcad/download/release/<version>/wasm。
无需设置任何内容。在宿主的 MCP 配置 env 块中设置这些变量；shim 会将它们传递给其启动的守护进程。CLASSCAD_WS_URL、CLASSCAD_ENGINE 和 CLASSCAD_VIEWER_OPEN 按会话生效——守护进程会在每个新会话中收到这些变量，因此两个标签页可以指向不同的工作进程；Claude 桌面应用中的标签页会在窗格中显示其应用，而终端中的标签页则会打开浏览器。

守护进程的实际使用

• 进程说明： classcad-mcp 垫片进程是宿主启动的进程（dist/server.js），每个标签页一个，标签页关闭时随之退出。dist/daemon.js 是唯一的长驻进程；GET http://127.0.0.1:9097/health 会显示其 pid、版本、活动会话数、会话中的图纸（drawings）以及其中有引擎运行的图纸数量（awake）、会话中的应用数（apps）、会话加入的地址（join）和日志文件。
• 多个标签页： 每个标签页都是同一守护进程中的一个会话，其中包含该对话打开的图纸。会话和图纸彼此独立（某个图纸中的脚本不会影响其他图纸的引擎或缓存）。带有图纸的 session_info 会显示该图纸连接到哪里。
• 生命周期： 最后一个会话关闭一分钟后，守护进程会退出；但如果某个应用仍提供自己的会话，则不会退出（页面中运行着引擎的 buerli 应用会让它保持运行，因此下一个标签页可以立即加入）。此类应用会在 5 s 内自行找到重启后的守护进程；use_session 会等待 8 s。宿主关闭 stdin 或发送 SIGTERM 时，垫片进程会退出；守护进程会立即移除该会话，嵌入其中的应用会提示会话已结束。
• 升级： 执行 npm run build（或更新软件包）后，下一个垫片进程会检测版本或构建标记不匹配（/health 会报告两者；标记取自守护进程启动时的状态，涵盖 dist/daemon.js 以及 @classcad/renderer 和 @classcad/script 的构建）。空闲的旧守护进程会关闭并由新进程取代。繁忙的守护进程（还有其他标签页）会收到排空指令——不再接受新会话，并在最后一个标签页关闭时退出；与此同时，新标签页会在进程内运行当前构建（为其应用在空闲端口上启动自己的监听器）。旧标签页会继续使用旧代码，直到重新启动。
• 日志： 垫片进程会在每次会话开始和结束时向 stderr 写入一行（可在宿主的 MCP 日志中查看）；守护进程会写入 CLASSCAD_MCP_LOG。手动运行以查看日志：CLASSCAD_MCP_DAEMON=1 node dist/daemon.js（未设置 CLASSCAD_MCP_LOG 时，日志会写入 stderr）。
• 故障排除： curl http://127.0.0.1:9097/health——无响应表示没有守护进程（下次调用工具时会启动一个）；join 地址的端口不是 9098，表示该端口被其他程序占用（通常是旧版 MCP 进程——请关闭那个标签页）：应用链接仍可使用，但托管自身会话的应用将无法找到 MCP；name 不是 classcad-mcp，表示 9097 被其他程序占用（请设置 CLASSCAD_MCP_PORT）。classcad-mcp stop 可停止空闲的守护进程（见下文）。端口：9094 worker（ws）、9095 worker（wss）、9097 守护进程、9098 应用和会话——除 worker 外，均监听 127.0.0.1。共享中继通过出站 WebSocket（443）连接；session_info 会在 shared 下显示该中继是否持有会话。
• 停止／重启： 软件包二进制文件也可作为轻量 CLI 使用（在检出目录中运行 node dist/server.js <command>）：
  • classcad-mcp status — 查看运行中守护进程的 /health（pid、构建版本、会话、图纸、应用、日志文件）。
  • classcad-mcp stop — 在没有活动会话时停止守护进程；否则拒绝执行（退出码为 1）。
  • classcad-mcp stop --force — 无论是否有会话都发送 SIGTERM（5 s 后发送 SIGKILL），例如，立即加载重新构建的渲染器。每个已连接的标签页都会失去其图纸；其垫片进程会在下次调用工具时重新连接——它会启动一个新的守护进程，并重放宿主的 initialize，因此宿主无需重启。
• 安全性： 守护进程绑定到 127.0.0.1，并拒绝（403）所有带有 Origin 标头或 Host 不是 127.0.0.1／localhost／[::1] 的请求——网页无法驱动它，甚至无法通过 DNS 重绑定实现。9098 上的监听器面向浏览器应用：它只响应将其指定为主机的请求；只有在已登录的机器上，使用邀请凭证（122 位随机令牌）才能加入会话。在机器之外共享会话不会开放端口：MCP 会向中继发起出站连接；中继仅接受来自已登录机器的会话提议，并允许持有该会话共享邀请凭证的人加入——这是独立的邀请凭证，监听器不接受它，share 会将它取回。

---

工具

每个作用于模型的工具都需要传入 drawing："new"，或之前某个回答命名的 ID（参见绘图）。

工具	用途
run_script	执行媒介：使用 api.v1.*、api.tree()、api.graphic() 执行 JavaScript。脚本之间的状态会保留；后续脚本会附加到现有模型。
tree / find / inspect	结构树（缓存，按需提取）、按类名/名称搜索、带父级链的完整节点详情
snapshot	将绘图渲染为 PNG（等轴测/顶视/正视/…、剖切、四视图图纸、带隐藏线的工程图、突出显示、标记）
list_methods / describe_method / docs	方法索引、各方法参考资料（包含面向 LLM 的注意事项）、操作指南
account	已登录账户的套餐及其允许的操作：商业用途、导出、Web 应用可运行的位置（localhost、已注册域名）、应用页面的公开访问令牌。只读；是 recipes/buerli-app 的第一步
view	会话的应用：返回其链接并打开应用（宿主的浏览器窗格或用户的浏览器），除非用户已经打开。local: true：本机上的链接，适用于分享链接无法加载的情况
share	可从任何位置访问的会话应用链接，供其他机器上的用户使用；stop: true 会撤销该链接
get_selection / set_selection	用户在应用中选中的对象（面、边、顶点、树对象），以及 API 调用使用的 ID；还可在应用中选中对象以指出它
save / load / clear / checkpoint / restore	save 将 STEP、STL、GLB 或 OFB 写入磁盘上的 path（或返回 base64）；使用 analytic 时，STEP 会将平面、圆柱面和圆锥面保存为对应类型，而非 B 样条曲面。load 从磁盘上的 path（或 base64 内容）读取 OFB / STEP / STL。checkpoint / restore 是保存在 MCP 内存中的撤销点。
login	登录或退出此机器的账号（登录时返回链接，然后等待用户访问）
session_info / use_session	状态（引擎、应用链接、shared 下的分享链接、会话中的其他参与者、登录状态）；切换引擎，或使用应用的邀请链接加入其会话

snapshot 会以行内图像块的形式返回 PNG，供模型使用，并将其写入 CLASSCAD_SNAPSHOT_DIR。Claude Code 和桌面应用的 Code 标签页不会向用户显示工具结果图像——工具结果会说明这一点并提供保存文件的名称，以便模型将文件交给用户（Claude Code：SendUserFile）。桌面应用的聊天界面会直接渲染图像。Claude Code 只会预览位于会话自身文件夹（scratchpad 或项目）中的已发送文件——其他位置的文件会显示为灰色占位卡片，因此工具会指示模型将 outDir 设为 scratchpad。

同一绘图的工具调用会串行执行。 同一绘图的所有工具共用一个引擎连接，因此服务一次只会运行该绘图的一个工具调用（文档查询除外）。与 run_script 并行发出的 snapshot 会等待脚本完成，而不是渲染尚未构建完成的模型。其他绘图不会等待。若子 Agent 使用父 Agent 的绘图，则会共用该绘图的队列。

---

引擎：worker 或本地 WASM

MCP 在两种引擎之一上运行自己的会话；由引擎策略决定使用哪种引擎。（加入应用的会话并非选择引擎：引擎由应用决定，参见共享。）

引擎	说明	MCP 如何连接
Local WASM	已发布的 ClassCAD WASM 构建，由 MCP 在守护进程的工作线程中托管。无需服务端或浏览器，资产缓存后即可离线运行。	无需配置（密钥随登录一起获取）；通过策略（auto/wasm）或 use_session(engine="wasm") 选择。
Worker (Drogon)	classcad-cli worker——在本机、Docker 中或托管环境中运行的服务。	设置 CLASSCAD_WS_URL，并使用策略（auto/drogon）或 use_session(sessionId)。

策略。 CLASSCAD_ENGINE（默认为 auto）和 use_session 的 engine 参数：

• auto — 如果 worker 可访问，则使用它；否则使用本地引擎。“连接 MCP 并创建一个方块”无需其他设置：运行 worker 时会使用它；没有 worker 时，MCP 会使用自己的引擎进行建模，并在 session_info 中说明（transport: "wasm"）。
• drogon — 仅使用 worker。“将 MCP 连接到我的 Drogon/ClassCAD 服务。”不会回退；如果 worker 无法访问，会如实报告。
• wasm — 仅使用本地引擎。“连接到 WASM／在本地工作／离线工作。”

该选择在会话中保持不变，直到 use_session 更改它；只要使用某个会话，邀请链接就会覆盖该选择。仅当 worker 无法访问（连接被拒、超时）时才会触发回退——成功连接后出现的错误绝不会被掩盖；显式指定会话 ID 时也绝不会回退。会话切换到另一个引擎后，会从该引擎的（空白）绘图开始；已停靠在该会话中的应用会收到通知，并使用同一链接重新加入。

本地引擎所需条件。

• 密钥。 引擎仅在取得 ClassCAD 密钥后才会启动，并会自行验证。MCP 不携带密钥：登录后，MCP 会向后端请求密钥（src/engine/key.ts）；后端会根据账户套餐允许的内容签发密钥，适用于任意端口上的 localhost；MCP 会声明自己运行在 http://localhost，这确实属实。密钥会保存在 ~/.classcad-mcp/engine-key.json 中，直到临近过期时才会更新；更新会提前进行。后端无法访问期间，未过期的已保存密钥仍可用于启动引擎。在 CI 上，CLASSCAD_TOKEN（秘密访问令牌）可代替登录。CLASSCAD_WASM_KEY 可用于指定自有密钥。套餐规定的导出格式适用于 save 和应用的下载：Free 可导出 STL（以及同样为三角网格的 GLB）；Solo 及以上套餐还可导出 STEP、OFB 和 JSON。
• 发布资产（约 16 MB：glue、主模块、三个侧模块、class 文件、filter 配置）。首次使用时会从 awvstatic.com 下载到 CLASSCAD_WASM_DIR——首次调用需要引擎的工具时会稍慢一些，守护进程日志会显示进度。之后，每个会话启动引擎约需一秒（每个引擎的堆内存约为 130 MB；每个会话使用一个引擎，会话结束时引擎也随之结束）。
• Node ≥ 20，用于 worker_threads 和 fetch——与软件包其余部分的要求相同。

本地引擎的不同之处。 它与浏览器应用中的引擎相同：只有一个绘图，且没有逐连接的发射配置（run_script 运行时不会抑制载荷——对于 MCP 会话能处理的数据量来说没有问题）。snapshot、tree、find、inspect、save/load、checkpoint/restore 均可正常使用。服务端围绕引擎提供的会话层功能（邀请、访客、在线状态）由 MCP 自行提供：参见共享。 本地引擎发生故障时。 引擎错误的返回方式与 worker 相同（maxLevel 为 51，附带消息，因此 run_script 会抛出错误），其中也包括 WASM 引擎只在嵌套的 result 中报告，或作为单独的 ErrorMessage 帧报告的错误；没有值也没有级别的 Result 是错误，绝不是空成功。引擎崩溃、在命令执行中途陷阱或未在请求超时前响应时，会被弃用：该命令会因相应原因失败，下一条命令则会启动一个新引擎，并使用空白绘图（检查点仍然有效——restore 会将它们加载到新引擎中）。use_session(engine="wasm"|"auto") 会对运行中的引擎进行健康检查，如果没有响应就替换它；健康的引擎会连同其绘图一起保留（clear 会清空绘图）。

---

共享：一个会话，多个参与者

一个会话可以有多个参与者：Agent、应用中的用户、另一台机器上的同事、另一个 Agent。他们共享一个引擎和一个模型；一方的每次更改都会立即发送给其他人。协议采用 ClassCAD 服务的会话共享机制（邀请、访客、在线状态，以及扇出转发的每条命令的帧；ClassCAD 源码中的 SessionSharing.md 对此有说明，@buerli.io/classcad 的 WSClient 是客户端）。会话的所有权取决于引擎运行的位置，而 MCP 会参与以下三种情况：

引擎运行位置……	会话由谁托管	其他人如何加入
在 MCP 中（本地 WASM）	MCP：src/share/hub.ts 是为其自身引擎提供服务的会话层	使用会话邀请链接 ws://127.0.0.1:9098/session/?invite=…——应用的链接会执行此操作
在 ClassCAD worker 上	服务端	使用 worker URL 上的服务端邀请链接；MCP 会话的应用会转交给它，因此链接相同
在应用的页面中（WASMClient）	应用（@buerli.io/classcad 中的 session/host.ts）	由 MCP 介绍加入：页面提供邀请链接 ws://127.0.0.1:9098/session/?host=…，访客通过 ?invite=… 加入，监听器负责连接双方

同事或另一台设备上的用户，可以通过共享中继加入由 MCP 托管的会话：参见其他地方的人加入。

Agent 托管，用户加入

默认情况下，每个会话的应用都会停靠到该会话中（参见应用）；view 会返回链接。

其他地方的用户加入

127.0.0.1 上的链接只在用户自己的机器上有效，其他地方都打不开。因此，系统也会在共享中继上提供会话；如果中继接管了会话，应用就会改为通过该链接启动——只有一个链接（App: https://<relay>/?invite=…），用户打开后可以发送给同事，也可以在平板电脑上打开：

view()               → the app's link: the share link, or the one on 127.0.0.1 while the relay does not hold the session
view(local=true)     → the link on 127.0.0.1, whatever the relay does
share()              → the share link again
share(stop=true)     → the share link stops working, whoever has the app open under it is disconnected

这不会中断会话。 第一个脚本运行时，系统会向中继发起请求。如果中继在模型就绪前拒绝了请求，系统不会等待；如果中继尚未应答，则再等待 6 s。无论哪种情况，第一个模型都会带着 127.0.0.1 上的链接启动——不会报错。如果中继之后不可用，并导致用户的应用也无法访问，下一个结果会再次提供本机上的应用；如果 Agent 发现共享链接无法加载，就会调用 view，并设置 local: true。后台会持续重新发起共享请求，直到中继接管会话。CLASSCAD_SHARE=ask 会让应用保持在 127.0.0.1 上，只有用户主动请求时才共享会话（此时 share 会返回第二个链接）；设为 off 则永不共享。

任何打开共享链接的人都会进入同一个应用，并接入同一个会话：他们可以看到 Agent 构建模型的过程，也可以旋转、选择和编辑模型。会话仍保留在原处。MCP 会像页面在监听器上为自身提供会话一样，在共享中继（packages/relay，一个 Cloudflare Worker）上提供会话——建立一个持续连接，声明“这个邀请属于我”，并为每位访客再建立一个连接——区别在于它会主动拨出连接（src/share/relay.ts）。机器上无需监听外部连接，也不需要 Node 以外的任何东西；即使位于 NAT 和防火墙之后也能使用。

• 独立的邀请。 共享链接携带的邀请与 127.0.0.1 上的链接不同，后者的监听器不会接受该邀请。撤回邀请（调用带有 stop 的 share）会断开所有通过该邀请加入的人——如果用户的应用正通过它打开，用户也会被断开；127.0.0.1 上的链接不受影响。再次共享会生成一个新邀请。
• 用户的应用也会通过中继传输，前提是用户通过共享链接打开应用：每一帧都会经由 Cloudflare 往返传输。CLASSCAD_SHARE=ask 会让应用保留在本机上。
• 持有链接的人都能加入，权限与应用中的用户相同（view 角色仅供参考，参见 src/share/protocol.ts）。Agent 只会把链接交给用户。
• 中继能看到什么。 中继只接受已登录机器发来的邀请（登录时的 Firebase ID token，会使用 Google 的密钥进行验证），只负责在主机和访客之间传递帧，不会保存任何内容。中继还会向访客提供应用——即随此软件包一同提供、并与中继一起部署的构建版本。
• 连接断开时（例如笔记本进入睡眠状态，或切换到另一个网络），MCP 会自动重新提供邀请，链接仍可使用。session_info 会在 shared 下显示链接（中继未接管会话时为 null），并在 peers 下显示访客。
• 限制。 每个会话最多 16 位访客；单帧最大为 32 MiB（Cloudflare 的限制——超大型模型的完整图像可能无法传输）。

CLASSCAD_RELAY_URL 用于指定一个与内置中继不同的中继；设为 off 则会话仅保留在本机：没有 share 工具，Agent 也不会收到相关信息。

用户托管，Agent 加入

在应用中打开 Sessions → Create，并将链接交给 Agent：

use_session(url="https://app.example/?invite=…")     # the link of the app, wherever its engine runs
use_session(url="wss://cad.example/?invite=…")       # or a server's URL directly

MCP 会以访客身份加入该会话，并在应用中的模型上工作；应用会显示每一项更改。链接不会说明会话使用的是哪种引擎：如果邀请由本机上的应用提供，MCP 就在此加入；其他邀请则会应用到工作进程（CLASSCAD_WS_URL）。如果引擎位于应用页面中，应用必须保持打开状态，且必须在本机运行。session_info 会报告会话及其参与者；不带参数调用 use_session() 会返回 Agent 自己的会话。第二个 Agent 可以用相同的方式加入第一个 Agent 的会话，使用的链接是 view 提供给第一个 Agent 的链接。

命名会话（ClassCAD-Session-Id 模型，仅限工作进程）：use_session(sessionId="test-session")。

浏览器需要允许什么

本软件包中的应用由 127.0.0.1 提供服务，并在同一地址加入会话：无需允许任何内容。由其他位置提供服务、且需要连接此计算机上的监听器（ws://127.0.0.1:9098/session）的应用则是另一种情况：包含引擎并提供会话的页面、加入此类会话的第二个页面，或由 CLASSCAD_APP_URL 指定的应用。浏览器会将连接到 127.0.0.1 的公共页面视为访问本地网络：基于 Chromium 的浏览器会请求用户授权（或者在无法询问用户的情况下拒绝访问，例如嵌入式浏览器窗格），没有授权时，页面就无法找到 MCP。由 localhost（开发服务器）提供服务的应用不受影响，在 ClassCAD 服务上运行会话的应用也不受影响。

参与者彼此可见的信息

除了模型外，参与者还会以 在线状态 的形式发布少量自身信息——会话会将这些小型帧转发给其中所有参与者，并为后来加入的参与者保留这些信息。buerli 软件包定义了这些通道（@buerli.io/classcad 中的 session/selection.ts、session/identity.ts；@buerli.io/react-cad 中的 session/sessionClient.ts），MCP 负责使用这些通道（src/share/protocol.ts），它们在三种会话中都以相同方式工作：

通道	谁	内容
client	所有人	参与者的身份：{ app, version, name, kind: 'app' | 'agent' }。session_info 会列出其他参与者。
selection	应用	每当选中内容发生变化时，发布选中内容：{ items: [{ kind, objectId, prodRefId, containerId, graphicId, type, name }], total }。get_selection 可读取此信息。
select	Agent	选择 items 的请求（按 graphicId 或 objectId）；set_selection 会发送此请求，并报告应用随后实际选中的内容。
config	主机	会话向访客提供的内容；适用于仅提供部分功能的主机：{ saveFormats: ['STP', 'STL'] }。应用会隐藏未提供的内容。MCP 自己的会话不会保留任何内容，也不会发布此通道。
view、cursor	应用	应用相互显示的摄像机和指针。

选中的面、边或顶点会携带其 graphicId：API 调用此对象时使用的 ID（例如 v1.sketch.create({ planeId })），其有效性取决于模型的当前状态。应用通过调用 syncSelection(client) 来共享其选中内容。

发出模型

在 worker 上，引擎会为每个连接保留一份发出配置（GetEmissionConfig/SetEmissionConfig）。MCP 会将自己的连接保持在引擎默认设置，因此，共享会话的应用会持续收到模型中所有内容的结构和图形数据。运行 run_script 时，仅针对该脚本关闭负载（只返回结果——包含 100 条命令的脚本会返回 100 条简短回复），之后再恢复；MCP 会在每个脚本运行后拉取一次数据，以便应用及其自身的缓存保持一致。脚本内的 api.tree() / api.graphic() 会按需拉取数据，并缓存到下一次变更为止。

本地引擎始终会生成命令所更改的全部内容。因此，MCP 托管的会话会在每次变更发生时将其发送给每位参与者，并按照各自连接所请求的形式发送（向应用发送流式帧，向运行脚本的 Agent 仅发送结果）；任何人的发出配置都不会影响其他参与者。

开发

npm install                      # monorepo root
npm run build                    # skill → script → renderer → mcp (+ buerli-ai)
cd packages/mcp
npm run build:app                # the app: packages/app (Buerligons from npm, @buerli.io/buerligons) built → app/
npm run build                    # tsc, app/ → dist/app/; postbuild runs the contract tests (emission, daemon, sign-in, sharing, the relay)
npm test                         # + the live tests: the local WASM engine, and a worker on CLASSCAD_WS_URL if one runs
node dist/server.js              # the stdio shim by hand (starts/uses the daemon)
CLASSCAD_MCP_DAEMON=1 node dist/daemon.js   # the daemon in the foreground, logging to stderr
CLASSCAD_SHARE_DEBUG=1 …                    # … with every command a docked app sends: how long it waited, how long it ran
npm run dev -w @classcad/relay              # the share relay on http://127.0.0.1:8787, with the app build:app made (no Cloudflare account needed) …
CLASSCAD_RELAY_URL=http://127.0.0.1:8787 …  # … and sessions shared on it
npm test -w @classcad/relay                 # the relay's contract, in wrangler's local runtime (Node 22+)

测试不会打开浏览器（CLASSCAD_VIEWER_NO_BROWSER=1、CLASSCAD_AUTH_NO_BROWSER=1），并会通过替身进行登录（test/fake-auth.mjs：CLASSCAD_AUTH_TOKEN_URL、CLASSCAD_AUTH_PROJECT、CLASSCAD_AUTH_API_KEY）。

源代码索引：src/server.ts（stdio 适配层：查找/启动守护进程、代理、进程内回退）、src/daemon.ts（HTTP 端点、会话、空闲退出）、src/mcp-server.ts（MCP 服务：连接到一个引擎客户端的工具——会话的定义）、src/client.ts（引擎客户端：通过 WebSocket 连接工作进程，或连接本地引擎）、src/share/（共享：hub.ts 是本地引擎的会话层，server.ts 是应用和会话的监听器，relay.ts 是通过共享中继提供的会话，session.ts 记录有哪些参与者、他们指向什么，以及相关链接，protocol.ts）、src/engine/wasm.ts + wasm-worker.ts（本地 WASM 引擎：资源下载、工作线程、origin/XHR 适配层）、src/tools/、src/queue.ts（每个会话的工具队列）。test/daemon.mjs 定义了守护进程的契约：两个适配层 → 一个守护进程和两个独立会话、空闲退出、端口被占用时的回退。test/share.mjs 定义了共享的契约，不涉及引擎：以服务端提供内容的方式向访客提供服务（流式传输和打包）、在线状态、仅主机可执行的操作、通过监听器加入由页面托管的会话，以及通过中继提供的会话（监听器代替中继；packages/relay 测试中继本身）。test/wasm-live.mjs（属于 npm test；首次运行时会下载资源；需要提供引擎密钥的方式——CLASSCAD_TOKEN 中的秘密访问令牌、CLASSCAD_LIVE_AUTH_FILE 中来自 login 的登录信息及其 CLASSCAD_BACKEND，或 CLASSCAD_WASM_KEY——没有密钥时会跳过）覆盖本地引擎：wasm 策略、工作进程不可用时 auto 的回退、drogon 不回退、通过 use_session 切换、通过 run_script 显示引擎错误、替换崩溃、挂起或卡死的引擎，以及共享：将应用停靠到 MCP 的引擎中（双向同步更改和选区），以及第二个 Agent 加入第一个 Agent 的会话。

发布

发布流程在 GitHub Actions 中运行（release.yml），无需令牌或 2FA 提示：

0. 该应用是 Buerligons，来自 npm：@buerli.io/buerligons，使用 package.json 固定的版本（一个 devDependency），并以其 mcp 模式（dist/mcp）构建。Buerligons 在 buerli 仓库中开发，每次推送到 next 都会发布一个 beta 版本（npm view @buerli.io/buerligons dist-tags）。要发布其他版本，请更改固定版本。npm run build:app 会将其复制到 packages/mcp/app/（app/SOURCE.txt 中记录了版本），工作流也会执行此操作；如果发布时缺少该应用，release-check 会阻止发布。
1. 在所有标明 MCP 版本的位置更新版本：package.json、src/mcp-server.ts 中的 VERSION、server.json（version 和 packages[0].version），以及 Claude 插件（plugins/classcad/.claude-plugin/plugin.json 和 plugins/classcad/launch.mjs 中的 PACKAGE）。该插件从此仓库的 master 安装，并运行其固定的包版本：其 README 和技能文件都介绍该版本，因此，此步骤应一并更新发布对用户带来的变化，而非提前更新。如果 @classcad/skill、script 或 renderer 也有更改，请同时更新其版本。
2. 在仓库根目录运行 node scripts/release-check.mjs mcp-vX.Y.Z，检查各处版本是否一致，并列出 npm 上新增的内容。
3. 提交、推送，然后运行 git tag mcp-vX.Y.Z && git push origin mcp-vX.Y.Z。

工作流会构建并测试该标签，通过 npm 的可信发布（附带 provenance）发布所有尚未发布到 npm 的 @classcad 包（依次为 skill、script、renderer、mcp），并以 io.github.awv-informatik/classcad 为名称将 server.json 发布到官方 MCP Registry（使用工作流的 GitHub OIDC 身份登录）。

每个 npmjs.com 包只需设置一次：Settings → Trusted publishing → GitHub Actions，组织为 awv-informatik，仓库为 classcad-ai，工作流为 release.yml。

已发布版本线的补丁应在其发布分支上制作（0.2.x 对应 release/mcp-0.2），在该分支上打标签，然后再合并到 master；只有 npm 上已有该版本后才推送 master，因为从该分支安装的插件会固定使用该版本。

共享中继不属于发布流程：它会单独部署（npm run deploy -w @classcad/relay，参见其 README），并向访客提供此包附带的应用。如果某次发布更改了应用，请再次部署中继。

构建失败和取消行为

run_script 会拒绝引擎错误；当调用方提供 MCP 进度令牌时，会报告进度。请求的取消信号会阻止后续 CAD 调用；已经开始运行的原生操作仍可能完成。在此类操作完成前，绘图工具会返回忙碌错误；文档和会话信息仍可用。系统不会自动重试或回滚。 传输超时后，必须重新连接并检查图纸，然后才能重试修改操作。

快照默认不重新生成，会返回捕获元数据，并报告刷新错误。只有在需要重建几何体时才显式设置 recalc:true；同时使用 quality:'fine' 可进行自适应细化。对于注入的实体，请保持禁用重新生成。共享的 api.inspect 辅助函数详见 packages/script/README.md。