Pascal 3D Editor

@pascal-app/mcp

适用于 Pascal 3D 编辑器的 Model Context Protocol 服务。可通过任何兼容 MCP 的 AI 主机驱动 @pascal-app/core 场景图。

有关托管的 Pascal MCP 端点，以及 Claude Code、Codex、 Cursor 和 OpenClaw 的即用配置，请阅读连接 AI Agent。 托管端点会编辑 Pascal 账户中的项目；此软件包则是面向自定义主机和本地场景存储的 开源本地服务。

该服务可在 Node.js 22.13 或更高版本，或 Bun 中以无头模式运行，无需浏览器、 WebGPU、React 或外部数据库服务。它会将编辑器 UI 使用的相同场景变更操作（创建墙体、放置物品、切割开口、撤销等）作为 MCP 工具、 资源和提示词公开。

推荐的本地设置

若要让本地编辑器和 MCP 自动共享项目，请安装 Pascal CLI：

npx @pascal-app/cli editor
pascal mcp setup codex

pascal editor 会同时启动编辑器和经过身份验证的 MCP 服务。 pascal mcp connect 是稳定的 stdio 连接器，可发现动态回环端口， 因此 MCP 客户端配置无需包含会变动的端口或密钥。

若要嵌入 MCP 服务、自定义存储，或在不运行 Pascal 编辑器的情况下 运行 MCP，请直接使用此软件包。

直接安装软件包

bun add @pascal-app/mcp

@pascal-app/core 是一个对等依赖项。本地存储在 Bun 下使用 Bun SQLite，在 Node.js 下使用 Node 内置的 SQLite 驱动程序。

快速入门

用一行命令通过 stdio 启动服务：

bunx @pascal-app/mcp
# or
npm exec --package=@pascal-app/mcp -- pascal-mcp

从磁盘加载初始场景：

bunx @pascal-app/mcp --stdio --scene ./my-scene.json

通过回环 HTTP 公开服务：

bunx @pascal-app/mcp --http --port 8787

绑定非回环主机需要 bearer token：

PASCAL_MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  bunx @pascal-app/mcp --http --host 0.0.0.0 --port 8787 --cors-origin https://editor.example

本地场景存储

通过 MCP 保存的场景会存储在本地 SQLite 数据库中：

~/.pascal/data/pascal.db

如果要让 MCP 服务和运行中的编辑器共享其他目录，请设置 PASCAL_DATA_DIR； 如果需要指定确切的数据库文件路径，请设置 PASCAL_DB_PATH。存储采用 WAL 模式和事务性版本检查，因此不同的 本地进程可以保存并打开同一个场景数据库。

在工作区开发期间，让两端使用相同的数据目录运行：

# Terminal 1: run the editor
PASCAL_DATA_DIR="$HOME/.pascal/data" bun run dev

# Terminal 2 or an MCP host: run the server
PASCAL_DATA_DIR="$HOME/.pascal/data" bun packages/mcp/dist/bin/pascal-mcp.js

本地几何资源文件

脚本化对象的 GLB 和源代码会保存在本地 SQLite 场景数据库旁的 <database-path>.artifacts/<sha256> 中；场景也保存在这里（使用 --scene 时也一样，它只会初始化 第一个场景）。请将此目录与数据库一同保留。文件会经过哈希校验并且只写入一次，因此保存的场景和撤销历史会保留原始几何体。独立 编辑器读写的也是数据库旁的同一存储。

本地 MCP 编译需通过 PASCAL_SERVER_SCRIPT_COMPILE=1 明确启用。编译会在单独的 进程中运行，不会继承环境变量，并有截止时间；这并不是用于运行不可信代码的沙箱。Blender（bpy）模块会在 PASCAL_BLENDER 指定的 Blender 可执行文件中运行（blender -b），同样有上述注意事项；Blender 几何脚本 会介绍一个示例。无需启用编译，get_source 也能读取已保存的脚本。

编辑器实时更新

当编辑器和 MCP 服务共享同一个 PASCAL_DATA_DIR 时，MCP 对已加载的已保存场景所做的 变更会持久化到 SQLite，并记录到本地的 scene_events 流中。编辑器页面会通过服务器发送事件订阅 /api/scenes/:id/events，因此打开的浏览器标签页可以 在 Agent 编辑场景时应用场景图快照。

此流程刻意保持本地化和轻量：

1. 在编辑器中打开或创建场景，使其保存到本地数据库。
2. 通过 MCP 使用 load_scene 加载该场景。
3. 运行 MCP 变更工具，例如 create_room、add_door、furnish_room、 add_wall、place_items 或 set_zone。

每次变更都会在写入前检查已保存场景的版本。如果浏览器或 另一个 MCP 进程先保存了更新的版本，MCP 工具会返回 live_sync_version_conflict；请先使用 load_scene 重新加载场景， 再继续操作。

托管 CLI 客户端配置

Claude Desktop、Cursor 和兼容客户端推荐使用以下 JSON 配置：

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "pascal": {
      "command": "pascal",
      "args": ["mcp", "connect"]
    }
  }
}

Claude Code

通过 CLI：

pascal mcp setup claude

或在仓库根目录的 .mcp.json 中添加：

{
  "mcpServers": {
    "pascal": {
      "command": "pascal",
      "args": ["mcp", "connect"]
    }
  }
}

如需在不使用托管 CLI 的情况下测试软件包开发，请先构建，然后让 Claude Code 指向构建后的二进制文件：

{
  "mcpServers": {
    "pascal": {
      "command": "node",
      "args": ["/absolute/path/to/editor/packages/mcp/dist/bin/pascal-mcp.js"],
      "env": {
        "PASCAL_DATA_DIR": "/Users/you/.pascal/data"
      }
    }
  }
}

Codex CLI

通过 CLI：

pascal mcp setup codex

发布前进行本地工作区测试：

bun run --cwd packages/mcp build
codex mcp add pascal-dev \
  --env PASCAL_DATA_DIR="$HOME/.pascal/data" \
  -- node "$PWD/packages/mcp/dist/bin/pascal-mcp.js"

这会在 ~/.codex/config.toml 中写入类似以下内容的条目：

[mcp_servers.pascal-dev]
command = "node"
args = ["/absolute/path/to/editor/packages/mcp/dist/bin/pascal-mcp.js"]

[mcp_servers.pascal-dev.env]
PASCAL_DATA_DIR = "/Users/you/.pascal/data"

Cursor 配置

在 Cursor 设置（settings.json）中：

{
  "mcp.servers": {
    "pascal": {
      "command": "pascal",
      "args": ["mcp", "connect"]
    }
  }
}

编程方式使用

使用内存传输，在自己的 Node.js 或 Bun 进程中嵌入此服务。下面的示例会在单个脚本中运行完整的客户端/服务端对，适用于 Agent 框架和测试。

import { createPascalMcpServer, SceneBridge } from '@pascal-app/mcp'
import { Client, InMemoryTransport } from '@modelcontextprotocol/client'

const bridge = new SceneBridge()
// Or over a detached scene a host opened (`@pascal-app/core/runtime`): every tool then reads and
// writes that scene, with its ids, and the host turns it into a patch.
// const bridge = new SceneBridge({ runtime: openDetachedScene(snapshot, options) })
bridge.loadDefault()
const server = createPascalMcpServer({ bridge })

const [srvT, cliT] = InMemoryTransport.createLinkedPair()
const client = new Client({ name: 'my-agent', version: '0.1.0' })
await Promise.all([server.connect(srvT), client.connect(cliT)])

const tools = await client.listTools()
console.log('available tools:', tools.tools.map((t) => t.name))

const scene = await client.callTool({ name: 'get_scene', arguments: {} })
console.log(scene)

传入自有 operations 的宿主（createPascalMcpServer({ operations })）可以实现 runInScene(run)：每个工具处理程序都会在其中启动，并在 await 之后重新进入其中，因此工具生成的 ID 以及它计划执行的操作都在场景的同步作用域内。此方法是可选的；如果不实现，处理程序会像以往一样运行，使用随机 ID。基于独立场景进行计算的实现必须提供此方法，并委托给 SceneBridge.runInScene，否则其工具生成的 ID 将不属于该场景，重新计算后的效果也将不匹配。

请参阅 examples/embed-in-agent.ts，查看可编译版本。

插件工具与使用者的权限范围

插件的 'operation' 工具会与共享工具注册到同一个执行器：它会解析输入，将结果作为一个历史步骤应用，并以 achieved 和拒绝信息作答。注释由宿主提供，绝不会从插件的契约中读取。

import { createSceneOperations } from '@pascal-app/mcp/operations'
import { registerOperationTool } from '@pascal-app/mcp/tools/shared-tools'
import { signageAgentTools } from 'acme-signage/agent-tools'
import { signageAgentOperations } from 'acme-signage/agent-operations'

const operations = createSceneOperations({
  bridge,
  // The floor the person is viewing: a tool call that names no level reads it.
  // Leave it out on a host with no view, and the lowest storey is read.
  activeLevelId: () => myHost.viewedLevelId(),
})

for (const contract of signageAgentTools.tools) {
  if (contract.runsIn !== 'operation') continue
  registerOperationTool(server, operations, {
    contract,
    operation: signageAgentOperations[contract.name],
    annotations: { readOnlyHint: false, destructiveHint: false },
  })
}

契约结构、版本和信任规则见插件编写指南。

坐标约定

Pascal 使用右手坐标系场景，其中 X 和 Z 构成地面平面，Y 轴向上。长度单位为米；旋转单位为弧度，以 Euler [x, y, z] 元组存储。

平面图 → 世界坐标。 传入的每个二维点都是楼层／建筑局部的地面平面坐标 [x, z]——包括 wall.start／wall.end 以及 slab、zone 和 ceiling 的 polygon／holes 数组。使用默认的单位建筑变换时，它在世界空间中的位置如下：

[x, z]  →  (x, y, z)      // the 2nd component is world Z (depth), not "up"

存储约定中没有符号翻转：工具直接将第二个分量作为世界坐标 Z 使用。垂直坐标 y 从所属楼层的堆叠高度开始，该高度由楼层系统根据累积楼层高度计算，再加上元素自身的高度；此外，楼板还带有绝对标高。

在编辑器外计算坐标时请注意。 Pascal 的视口会在世界坐标轴基础上应用自身的旋转：二维平面图面板会按照用户的视角旋转内容（与北对齐时为 0°，基准为 FLOORPLAN_VIEW_ROTATION_DEG，北对应世界坐标 −Z）；三维“俯视”捕捉则会保留相机当前的方位角，因此从默认等轴测位置调用时，世界坐标轴与屏幕坐标轴会相差约 45°，直到你将视角旋转至与坐标轴对齐。因此，如果按“Y = 北，俯视”的方式创作布局——这在土地测量、北向上的场地平面图和二维绘图库中很常见——在 Pascal 中查看时，相对于源图会发生旋转（并且可能进一步镜像，具体取决于所用视口和相机状态）。编辑器自身的二维和三维工具与存储坐标在内部保持一致，因此这只会影响以编程方式创建的几何体。若要在信任外部计算的坐标前验证方向，请在已知锚点放置带比例的参考图，并检查对齐情况；根据需要应用旋转（或镜像），使其与创作端一致。

examples/coordinate-conventions-demo.md 和 examples/coordinate-conventions-demo.json 中提供了完整演示，涵盖与坐标轴对齐的基准、下方旋转 30° 的示例，以及用于说明外部坐标问题的“页面意图与世界结果”配对 L 形图。使用以下命令加载 JSON：

bunx @pascal-app/mcp --stdio --scene examples/coordinate-conventions-demo.json

示例——一块绕第一个角旋转 30° 的 6 × 4 m 楼板（坐标四舍五入至 3 位小数；边长约为 6 m／4 m；未与坐标轴对齐，因此实际展示了坐标映射）：

{
  "op": "create",
  "parentId": "<levelId>",
  "node": {
    "type": "slab",
    "elevation": 0.0,
    "polygon": [[0, 0], [5.196, 3.0], [3.196, 6.464], [-2.0, 3.464]]
  }
}

该楼板平放在地面上（Y = 0），沿相对 +X 轴偏转 30° 的方向延伸约 6 m，沿其垂直方向延伸 4 m——也就是说，直接占据世界坐标 (x, z)。

另一个需要注意的问题：附着于墙体的坐标是墙体局部坐标，而非平面图坐标。存储的门／窗 position[0] 表示沿墙的米数，附着于墙体的旋转也采用墙体局部坐标。

工具

所有工具都使用 Zod 验证其输入和输出。Zundo 的时间中间件会将变更工具记录为一个可撤销步骤。 工具的输入架构拒绝的参数会作为工具错误返回，JSON 文本为 { error, code: "invalid_input" }，就像其他拒绝一样会标明代码：参数的形状或类型不正确，因此请读取 error，修正参数后再调用。这是架构的拒绝，发生在工具运行之前；工具自身抛出的代码（apply_patch 的 invalid_update 和 invalid_parent，房间的 cannot_enclose）会以 { error, code, ...details } 的形式返回，而 apply_patch 还会添加 patchIndex 和 id。如果 Agent 编写的楼层没有 height（apply_patch 中的 create，或清除该值的更新），系统会根据楼层中的内容，赋予编辑器自行加载时推导出的高度：最高墙体或天花板的顶部高度；对于空楼层，则使用默认层高 2.5 m。apply_patch 会在 notes 中说明，每个补全的楼层占一行。add_level 接受可选的 height，并使用相同的默认值。

所有共享工具接受的长度和角度都采用一种记法：裸数字使用字段指定的单位（米、度、弧度），文本则自带单位，包括英寸、英尺和毫米。屋顶坡度可用度数或升高与水平跨度之比表示：

{ "wallHeight": "9 ft", "overhang": "18 in", "pitch": "6:12" }

"26.6"、"26.6°"、"0.46 rad"、"6/12"、"6 in 12" 和 "6 on 12" 也都可以解析。分钟和秒会被拒绝（'6"' 是建造行业中的英寸写法），像 "1/4 pitch" 这样的“坡度”分数也会被拒绝，因为它表示升高与总跨度之比。

名称	用途	关键输入	输出
get_scene	返回完整场景图。	—	{ nodes, rootNodeIds, collections }
get_node	按 ID 获取节点，完整返回，并附带场景为该节点计算出的内容（墙或天花板的 resolvedHeight 和 heightIsExplicit、墙的 resolvedThickness、门或窗的 resolvedOpening、楼层或楼板的 displayName）、按父级优先顺序列出的祖先，以及其饰面所用的场景材质；若节点不符合其架构，则仅返回已存储的内容，不返回派生信息。	{ id }	{ node, ancestorIds, missingChildIds?, materials? }，或拒绝 node_not_found
find_by_type	查找某一类型的所有内容：某类节点（任意核心或插件类型）、某类目中的项目、灯具，以及创作对象、窗和门中的类型化部件；可按楼层、父级、区域（在其楼层上，按平面点查找，排除孔洞）或导入源 ID（provenance.refs[].id 或旧版 metadata.sourceIds，精确匹配或前缀匹配）筛选；不指定类型时，返回符合筛选条件的所有节点。每个结果包含节点的 ID、名称、类型、楼层和父级，以及其元数据和来源信息（超过 1 KB 的内容会在 omitted 中标出）。	{ type?, levelId?, parentId?, zoneId?, sourceId?, sourceIdPrefix?, limit? }	{ type?, count, nodes, parts, results[], truncated?, hint? }，最多列出 limit（200）个结果；拒绝 unknown_type、level_not_found、node_not_found、zone_not_found、not_a_zone
list_levels	按楼层顺序列出每栋建筑的所有楼层及其角色（楼层、仅屋顶、支撑）、相对于地面线的位置（gradeStanding、isGroundLevel），并列出每栋建筑位于地面标高的楼层。	—	{ activeSceneId, activeLevelId, levelCount, occupiedStoryCount, supportLevelCount, roofLevelIds, groundLevels[], levels[] }
get_level_summary	简要汇总一个楼层：角色、数量、带开口的墙、带面积的区域、楼板、天花板、项目、楼梯、屋顶，以及按类型分类的其他内容。对于最低的楼层，可省略 levelId。	{ levelId?, level? }	{ levelId, role, counts, walls, zones, slabs, ceilings, items, stairs, roofs, other }
get_walls	列出楼层上的墙及其长度、存储高度和解析高度，以及子门窗。	{ levelId?, level? }	{ levelId, walls[] }
get_zones	返回房间／区域多边形及其孔洞、面积（扣除孔洞）、边界和地板选项。	{ levelId?, level? }	{ levelId, zones[] }
get_site	返回建筑所在场地的信息，使用建筑的楼层坐标（若地块上还没有建筑，则使用场地坐标）：地块及其面积，以及通常由房屋覆盖的占地面积（30% 至 45%）；退界范围内的可建区域及其中心、面积、每条边的临街宽度和进深以及正面边缘；临街一侧及地块的临街宽度和进深；北向；地面（倾斜、判定为平坦或未判定）；地址、地块和分区信息；地块是否为新建项目占位符；以及占地范围是否合适和院落情况。	{ building?, site? }	{ siteId, buildingId, pose, lot, placeholder, buildable, street, ground, northDeg, address, parcel, zone, footprint, others, summary }；拒绝 no_site、building_required、site_not_found、not_a_site、building_not_on_site
place_building	通过仅移动建筑节点（墙仍保留其楼层坐标），将建筑放置在场地上：将其占地范围、即将绘制的轮廓或现有墙体居中放在可建区域内，或按指定院落尺寸放置；已有墙体的房屋保留其旋转角度，除非指定 rotationDeg；尚无墙体的建筑则调整为与街道平行。	{ building?, outline?, yards?: { front?, rear?, left?, right? }, rotationDeg? }	{ buildingId, position, rotationDeg, moved, footprint, yards, fit, overhang, movedWithIt?, message }；拒绝 no_site、needs_footprint、other_building_on_site、no_street、yards_conflict、yards_infeasible、building_required
measure	测量两个节点世界空间参考点之间的距离（附属门、窗和项目会通过其宿主解析；适用于所有节点类型）；适用时还返回面积。	{ fromId, toId }	{ distanceMeters, fromPoint?, toPoint?, areaSqMeters?, units: 'meters' }
view_scene	从 Agent 选择的视点（罗盘方位、从房屋所在街道看到的一侧、街道高度的视线、照片相机视角、正对视角或俯视视角），在场景自身光照或照片光照下查看已完成的建筑、每个楼层和屋顶，并返回图像；若指定区域，还会一并返回照片裁剪图。interior: { zoneId } 会在房间内以视线高度（默认 1.6 m）站在离角落一步的位置并朝房间内看；interior: { levelId } 会查看某个楼层的内部：不显示其他楼层、屋顶和天花板，仅供图像使用，并在楼层高度的 0.65 处剖切该楼层上的所有内容（墙、开口、家具）。除非 maxPx（64 至 1920）要求缩小最长边，否则图像尺寸为 1920 × 1200。服务端没有渲染器：由宿主的 sceneViews（通过用户当前打开的编辑器标签页运行的托管应用）进行渲染。只读。	{ target?, interior?, from?, elevation?, eyeHeight?, position?, fov?, projection?, camera?, lighting?, maxPx?, photo? }	图像内容以及 { status, camera, size, tab, capturedAt }；拒绝 view_unavailable、no_project、which_building（指定街道一侧但未指定目标，且多个场地上有建筑）、no_current_camera（camera: 'current'：服务端无法查看用户的视角）、camera_and_viewpoint（Agent 自选视点与相机同时指定）、photo_crop_unavailable、interior_level_invalid、interior_hidden、interior_transform_unsupported、interior_target_elsewhere；在托管服务端还可能拒绝 editor_tab_required、editor_tab_hidden、editor_tab_busy（标签页已打开但正忙或仍在加载，未提供链接：等待几秒后再次调用，不要询问用户）、editor_tab_timeout（标签页已接管视图，随后停止响应）；拒绝信息中关于打开编辑器的说明取决于用户的“Agents may open the editor for me”设置（先询问、允许、禁止）
search_assets	搜索宿主的项目库（独立服务端使用内置列表），一次调用可执行多个查询；查询可匹配名称、ID、类目或标签。若查询没有结果，会提示使用 add_object 创建该项目。	{ queries: [{ query, category? }] }	{ groups: [{ query, total, results[] }], total, hint? }；拒绝 no_catalog
design_brief	将整个请求解读为一份设计简报，每个请求只处理一次：axes（逐项解读请求中的各个轴：action、size、pieces、openings、style、materials、dressing；每项都必须有界定——以用户原话作为 quote，并用简短语句说明解读，pieces 必须是 minimum 或 exact——或者采用开放式设计陈述，且至少三个词；缺少某个轴时拒绝 axis_missing，引用内容不在用户聊天消息中时拒绝 axis_quote_not_in_request，开放轴没有设计陈述时拒绝 axis_open_without_design；通过 MCP 调用时必须提供轴引用，且不作比对，因为没有消息可供比对），第八个轴 source（open、catalog、brand 并附带其 brand，或 existing）；开放式设计的 vision；逐层说明房间布置（beyond：纺织品、灯光、窗、墙、地板、植物、物品、小型家具；每项填写数量或 { none: why }；开放式 dressing 轴必须包含 8 项中的 6 项，否则拒绝 beyond_too_thin；有界定的轴不要求填写任何项目；以最低数量形式列出的项目不构成界定，拒绝 dressing_bounded_by_minimum；结果以 dressing 返回）；用户用于指定非 open 来源的原话（sourceQuote，必填：至少两个词，且须提及品牌、目录或已有内容；此处不与请求进行比对）；若来源为 open，还需提供按原样放置的技术设备（asIs：卫浴设备、家用电器、固定设施；每件都必须先通过 view_assets 展示，并附上理由；家具则需要制作）。布置或制作家具的工具都必须遵循设计简报：place_items、furnish_room、place_in_room（目录中的）和 add_object、place_design（制作的），包括在 run_batch 中调用时，若尚无设计简报，则在执行前拒绝 design_brief_required。search_assets 和 view_assets 仍可直接使用。来源 open 会开放制作项目，仅在 asIs 中明确列出时放置技术设备，并禁止使用 furnish_room（brief_source_open）；catalog、brand 和 existing 会开放目录工具，并允许为目录中缺少的内容进行创作。批处理中只要有一个调用被拒绝，整批就会被拒绝。设计简报适用于整个会话：加载或清除场景会开始新的会话，后续的 design_brief 会替换当前简报。不会更改场景。
view_assets	返回 1 至 6 个目录项目的图像，按 ID 查询；每个项目会标明尺寸、类目和可上色表面的名称（即其模型的 slot_<id> 材质；paint 会将其作为 role 使用），并以图像内容返回。调用前会读取图像和表面信息（托管服务端会获取缩略图并将其调整到最长边不超过 512 px；独立服务端的内置列表没有可供获取图像的宿主，因此只返回尺寸信息并说明没有图像）。选择加入：不调用时不会有任何变化。	{ ids: string[] (1 to 6) }	{ items: [{ id, name, category, dimensions, surfaces, picture, unavailable? }], shown, note? }，另为每个已展示项目返回一张带标签的图像；拒绝 unknown_asset、no_catalog
search_materials	搜索或浏览材质库，一次调用可执行多个查询：按材质库中的写法匹配词语（timber 对应 wood，render 对应 stucco）、色调和表面；不含词语的查询会按名称列出某一类型、表面或整个材质库。搜索每次列出 12 项，浏览每次列出 150 项；结果较多时会说明剩余数量（more）以及列出剩余项目时使用的偏移量（next）。读取 Pascal 的材质库以及宿主注册的材质（编辑器会注册其材质库；此服务端不会注册任何材质）。只读。	{ queries: [{ query?, kind?, surface?, offset? }] }	{ groups: [{ query?, kind?, surface?, offset?, results: [{ ref, label, kind, surfaces, color? }], missing?, more?, next? }] }
paint	一次调用即可为墙、楼板、天花板、屋顶以及所有其他带表面的部件（柱子、围栏、门、窗、楼梯、块体、橱柜、搁架……）指定饰面，方式与编辑器的 Paint 相同：指定颜色（最接近的库中颜色）、library: 或 scene: 引用、作为场景材质保留的原生材质（若存在相同材质则复用），或擦除饰面。role 用于选择表面（墙的 exterior／interior 面，按其房间确定，否则使用存储的墙面；若只有部分墙面有房间，则拒绝；也可按名称选择槽位；屋顶的 top／edge／wall 或 fascia，其中 fascia 是所有屋顶段共有的檐口板和斜边板；玻璃屋顶的 glazing-frame、glazing-glass 或 glazing-solid；若未指定角色，则应用于框架和实心面板，并保留玻璃）；屋顶会为每种表面显示一种饰面，因此对某个屋顶段设置饰面会应用于其所属屋顶，而对屋顶设置饰面会清除各屋顶段自己的饰面；墙面会整面上色，覆盖房间的墙面饰面，而已上色的部件保留自身饰面（会在 note 中标出）。	{ targets[], role?, color?, material?, materialName?, erase? }（一种饰面）	{ ok, painted[], finish, materialId?, material?, createdMaterial?, note?, achieved }；拒绝 target_not_found、unknown_role、side_unknown、unknown_material、materials_unavailable、not_paintable
create_story_shell	根据占地范围创建一个由楼层拥有的楼层外壳：周边墙体。楼板和天花板由封闭空间的房间派生；createSlab／createCeiling／slabElevation 作为房间意图记录。每个楼层使用一次。	{ levelId, footprint, wallHeight?, wallThickness?, createSlab?, createCeiling? }	{ wallIds, zoneIds, slabId, ceilingId, createdIds }
create_stair	按照编辑器楼梯工具的操作方式创建直梯、L 形或 U 形楼梯：从某个楼层通往其上方的下一层（若不存在则创建），并拥有其开凿的楼板开口；也可通往无楼层（toLevelId: null）。(x, z) 是底部第一级踏步的中心，rotation 以度为单位（0 表示朝 +Z 方向上升）。	{ x, z, levelId?, toLevelId?, rotation?, layout?, turn?, lowerSteps?, width?, length?, height?, steps?, railingMode?, railingStyle?, railingMaterial? }	{ stairId, segmentIds, upperLevelId, createdUpperLevel, layout, stepCount, rise, length, footprint, arrival, slabHoleCut, openingIds? }；拒绝 roof_level、not_above、level_not_found、slab_not_found／ceiling_not_found、slab_not_on_level／ceiling_not_on_level、stair_layout、stair_layout_required、no_level_above
measure_stair	读取实际踢面高度、行走线处的踏步深度、坡度、均匀度、到达位置、与楼层／天花板／楼梯主体的净空，以及设计目标诊断信息。	{ stairId, available?: { width, length } }	{ measurements, layouts }
fit_stair	在一次可撤销的编辑中，调整踢面高度使其均匀，或将楼梯链替换为直梯／L 形／U 形预设，并采用宽度合适的平台或四分之一转角扇形踏步。	{ stairId, fitRun?, targets?, layout?, turn?, width?, landingDepth?, turningStrategy?, innerGap?, walkingLineOffset?, division? }	{ stairId, measurements }
create_roof	在顶层上方按其占地范围加建屋顶（优先使用墙体轮廓，其次是楼板，再其次是房间）；每个矩形对应一个屋顶段；也可按自定义矩形建造（width、depth、center）。屋顶会放置在顶层上方的建筑屋顶楼层（复用现有屋顶楼层；若正上方的空楼层是唯一楼层则使用该楼层；否则创建并命名为 Roof），并支承在该楼层的墙顶上；手动屋顶工具遵循同一规则。roofType: "barrel" 会为每个屋顶段构建拱形（depth 是跨度，barrelRise 最大为跨度的一半，barrelSegments 指定 4 至 32 个面）；roofSystem: "glazed" 会将人字形、直线单坡或拱形屋顶构建为玻璃窗格和框架，由 glazing 设置（参见玻璃屋顶）。	{ levelId? (or level), roofType?, roofSystem? ('standard' | 'glazed'), glazing?, barrelRise?, barrelSegments?, pitch? (degrees, or rise over run: "6:12"), overhang? (the eaves' reach past the walls in plan), wallHeight?, wallThickness?, width?, depth?, center?, materialPreset?, fasciaHeight?, fasciaMaterialPreset?, name? }	{ roofId, roofLevelId, createdRoofLevelId, coveredLevelId, segmentIds, roofType, achieved }；拒绝 storey_above、roof_exists、building_required（有多栋建筑，且未指定楼层名称）、storey_without_building、conflicting_level、no_levels、no_rooms、rectangle_incomplete、unknown_material（屋顶或檐口饰面）
move_roofs_to_roof_level	将楼层上支承在自身墙体上的屋顶移至屋顶规则指定的楼层（顶层上方的建筑屋顶楼层；若不存在则创建；低层楼上的楼层），操作方式与手动拖动屋顶面板相同。每个屋顶保留原位、屋顶段、饰面和 ID。适用于旧版项目；当 verify_scene 报告 roof_mixed_in_storey 时使用。	{ levelId }	{ roofIds, roofLevelId, createdRoofLevelId, achieved }；拒绝 level_not_found、no_roof_on_walls
create_room	根据多边形创建房间：每条边建一面墙（若已有墙沿该边延伸，则复用该墙）并创建房间区域；也可在同一次调用中按边（wallIndex）和位置 t 声明门窗，并遵循 add_door 和 add_window 的规则放置，或将其列入 skippedOpenings。楼板和天花板由系统派生，不会直接创建。outdoor: true 会创建露台：没有墙的边界上会创建分隔线（编辑器的 Separator：无墙的房间边界），不创建自身墙体，也不创建天花板。若多边形的每条边都沿着已有墙延伸（无需建造），且多边形与这些墙围成的房间吻合，则调用会指向该房间，而不会在其上叠加第二个区域，并返回该房间的 zoneId。若该房间已有自定义名称（不是编辑器赋予的数字名称：只要不是编辑器给出的“Room N”，无论由谁命名），调用就会被拒绝（room_named_by_person，并在提示中显示房间名称）：仅当用户要求改名时才传入 rename: true；否则应先询问用户。绝不擅自重命名房间；如果房间仍用相同名称，则会提示无需创建。若在已完全围墙的庭院上绘制露台（outdoor: true），则会将该区域识别为室外。此拒绝机制仅适用于 Agent：编辑器自带的房间工具仍按原样运行（用户可直接查看并命名房间）。	{ name, polygon, levelId?, color?, wallHeight?, wallThickness?, outdoor?, rename?, doors?, windows? }	{ zoneId, slabId, ceilingId, wallIds, reusedWalls, areaSqMeters, doorIds, windowIds, skippedOpenings? }；拒绝 cannot_enclose、outdoor_room_overlap、room_named_by_person
add_door	按编辑器的放置规则在直墙上的 t 位置（沿墙方向 0..1）添加门，或添加不带门扇的通道（openingKind: "opening"）；门会滑动以保持在墙上，并报告 clamped。doorType、style 和轮廓（openingShape）用于匹配参考样式，code 用于创建无法匹配的样式，nodeId 用于重建脚本化门。	{ wallId, t?, width?, height?, openingKind?, hingesSide?, swingDirection?, doorType?, style?, openingShape?, code?, nodeId?, force? }	{ doorId, wallId, localX, t, clamped, achieved }；拒绝 wall_not_found、not_a_wall、curved_wall、wall_too_short、opening_overlap（除非指定 force）
add_window	按照 add_door 放置门的方式添加窗户；除非指定 sillHeight（窗户底边距地面的高度），否则窗户会在墙上垂直居中；windowType、columns／rows、style（固定窗的窗格样式；其他类型不支持，拒绝 style_needs_fixed_window）和轮廓用于匹配参考样式。	{ wallId, t?, width?, height?, sillHeight?, windowType?, columns?, rows?, style?, openingShape?, code?, nodeId?, force? }	{ windowId, wallId, localX, t, clamped, sillHeight, achieved }；拒绝原因与 add_door 相同
furnish_room	根据房间类型，使用宿主的项目目录为房间布置家具：主家具靠在朝向门的墙边，其余家具沿侧墙摆放。家具不会进入门的净空区域，也不会与其他物品重叠：无法放入的家具会调整位置，否则跳过；skipped 会说明原因。	{ zoneId?, polygon?, levelId?, roomType, doorWallIndex? }	{ placed, itemIds, skipped, doorWallIndex, doorsDetected }；拒绝 room_required、roof_level、level_not_found、no_catalog
add_corner_window	添加一扇包覆墙角的窗户：每面墙各有一扇窗，两扇都延伸至墙角并相连；固定窗的玻璃会融合，其他窗型则使用细立柱连接（其窗框会保留）；墙角角度可为 10° 至 170°（如直角、135° 的凸窗墙角或锐角）。corner 是 levelId 楼层上两面墙的交点（默认使用当前视图中的楼层；叠层楼层共享墙角点）；[x, z] 是 get_walls 返回的楼层平面坐标。width 指玻璃从墙角沿每面墙延伸的距离（默认 1.2 m），widths 可按墙 ID 分别指定；post 为 'none'（玻璃融合，仅固定窗支持且为默认值）或 'post'（其他窗型的默认值，也是唯一选项）；height 默认 1.5 m，窗户在墙上垂直居中，除非指定 sillHeight（窗户底边距地面的高度）；仅当墙角有三面以上的墙相交时才需要提供 wallIds（两个）；windowType 和 style 与 add_window 相同（样式要求使用固定窗）。手动操作：选择一扇延伸至墙角的窗户，并在窗户面板的 Corner 区域中进行设置（Wrap the corner、This side 和 Other side；固定窗可选择 Fused glass 或 Corner post；也可选择 Unwrap）。	{ corner: [x, z], levelId? (or level), wallIds?, width?, widths?, height?, sillHeight?, post?, windowType?, style? }	{ windowIds, wallIds, angle, post, achieved }；拒绝 no_corner（没有两面墙在该处相交）、corner_ambiguous（有两面以上的墙在该处相交：请传入 wallIds）、corner_angle（小于 10° 或大于 170°：请使用 add_window）、corner_not_fused（在非固定窗类型上指定 post: 'none'）、width_exceeds_wall、style_needs_fixed_window
merge_windows	将两扇已有窗户合并为一扇，操作方式与编辑器的 Merge windows 按钮相同；不会重新创建窗户。若窗户位于相交墙面上，且每扇窗距墙角不超过 0.30 m，则会将其合并为一扇转角窗（即 add_corner_window 的结果）：每扇窗都会滑至墙角并保留原宽度，玻璃会融合（固定窗）或以立柱相接（其他窗型）；两扇窗都会采用第一扇窗的高度、窗台高度和类型，因此应将想保留外观的窗户放在第一位。若墙角角度大于 170° 或小于 10°，则拒绝合并。若两扇窗位于同一面墙上，间距不超过 0.30 m 且中间没有任何内容，则会将其合并为一扇跨越两者的窗户（两扇重叠或一扇在另一扇内部时，取其并集），窗户从较低的窗台延伸至较高的顶部，并使用第一扇窗的类型和样式。用于合并已创建、可组成转角窗或宽窗洞的两扇窗；verify_scene 的 corner_unjoined 会首先列出可合并的一对窗户。add_corner_window 则用于新建一对窗户。手动操作：选择两扇窗户并在多选面板中使用 Merge windows；或者在已有窗户的墙角附近放置或拖动一扇窗户，然后单击或松开鼠标（按住 Alt 可直接放置，不进行转角合并）。	{ windowIds: [a, b] }	{ kind: 'corner' | 'same_wall', windowIds, removedIds, achieved }；拒绝 window_not_found、not_a_window、same_window、window_not_on_wall、window_already_joined（请先取消连接）、windows_already_joined、windows_not_adjacent、opening_between、walls_not_meeting、corner_angle、window_not_at_corner、height_exceeds_wall、opening_overlap
apply_patch	批量创建／更新／删除／移动，并在提交前进行验证和试运行。默认优先使用批量调用：在一个原子调用中提交某个建造步骤的所有创建／更新／删除操作（顺序固定，后续操作可引用之前创建的 ID）；不要循环调用只包含一个操作的请求。若创建时使用场景中已有的 ID，则拒绝（node_exists）；若要替换，请在同一补丁中先删除该节点。更新不能更改 id 或 type（identity_change）、object 或 children（immutable_field），不能将节点移至不存在或无子节点的父级下（invalid_parent），也不能引入架构问题（invalid_update）；删除操作会自动重新生成的默认排水槽和落水管只能在后续调用中访问（regenerated_default）。拒绝时会返回包含 JSON 文本 { code, patchIndex, id, message } 的工具错误。新建楼层时若未提供 height，或更新操作清除了该值，则会根据楼层内的内容应用编辑器加载时推导出的高度（空楼层为 2.5 m），并在 notes 中为每个楼层添加一行说明。补丁创建的屋顶或移动到支承其墙体所在楼层的屋顶，会放置在墙体上方的楼层；notes 中会为每个屋顶添加一行说明。若在屋顶楼层或更高处新建楼层，屋顶会向上移动。以下情况会被拒绝：在屋顶楼层放置楼层内容（roof_level）；将包含楼层内容的楼层声明为屋顶楼层（roof_level_holds_storey）；楼层索引将屋顶楼层置于某个楼层之下（roof_level_on_top）。	{ patches: Patch[] }	{ applied: number, notes?: string[] }
add_level	按照编辑器的操作方式向建筑添加一个空楼层：可添加在楼层顶部、屋顶楼层下方（屋顶楼层会随之上移），或添加在最低楼层下方作为地下室（所有现有楼层，包括地面层，位置保持不变）。若场景中只有一栋建筑，可省略 buildingId。	{ buildingId?, position?, name?, height? }	{ levelId, buildingId, floorIndex, height, shiftedLevelIds? }；拒绝 building_required、building_not_found、no_building
set_ground_level	将某楼层设为建筑的地面层，操作方式与楼层面板中的“Set as ground floor”相同：建筑会将其命名为地面层，并调整位置，使该楼层高于地面标高，方式与建筑基础施工时的定位方式相同；基础顶部高度为 8 in、0.203 m（砌块基础：默认值及美国标准），或 0.15 m（欧洲的现浇混凝土基础）；仅调整高度，不改变平面位置；楼层索引会重新编号，使该楼层为 0，其下方楼层则作为地下室。	{ levelId }	{ levelId, buildingId, floorElevation, aboveGrade, foundation { region, construction, basis }, movedBuildingBy, renumbered, unchanged? }；拒绝 level_not_found、not_a_level、no_building、not_a_storey
add_wall	在楼层上添加直墙，或通过 curveOffset 添加弧形墙。对于最低楼层，可省略 levelId。	{ start, end, levelId?, thickness?, height?, curveOffset? }	{ wallId, levelId, length }；拒绝 roof_level、wall_too_short、level_not_found
add_fence	根据楼层上的点添加围栏，每条边添加一段围栏；closed 会将围栏延伸回第一个点（围住地块边界）。除非 style 指定其他样式，否则使用隐私屏风板。	{ points, closed?, height?, style?, baseStyle?, materialPreset?, levelId? }	{ count, fenceIds, levelId, length, achieved }；拒绝 fence_too_short、roof_level、unknown_material、level_not_found
place_items	一次调用即可放置目录项目，每件项目单独放置或拒绝；位置为楼层 (x, z) 坐标：放在楼层地面上，或放在每件项目指定的宿主上（targetNodeId）：墙面（必须指定表示其底部高度的 y）、天花板，或放在地面上的项目。若地面项目位于门的净空范围内，则拒绝 blocks_door（并指出门的位置以及避开所有门的放置位置）；若项目无论如何旋转都无法放入房间，则拒绝 too_large_for_room。	{ items: [{ assetId, x, z, y?, targetNodeId?, rotation? }], levelId? }	{ levelId, items: [{ ok, itemId?, hostId?, restingOn?, code? }] }；逐项拒绝 asset_not_found、outside_rooms、blocks_door、too_large_for_room、height_required、item_too_tall、unsupported_host、host_not_found、host_not_on_level
place_design	创建一个通过 validate_design 验证的设计（程序化项目配方、对象或 JSON 字符串）。安装位置决定宿主：楼层／楼板／区域、设计表面（surfaceId）、直墙表面或天花板。仅支持创建；一次撤销操作；内联设计最大 24 KiB；拒绝时会返回代码。	{ design, hostId, position, rotation?, side?, surfaceId?, parameters?, slots?, name?, id? }	{ designId, parentId, surfaceId }
set_zone	在楼层上创建区域／房间多边形；若已有墙体围成房间，则此区域指向该房间，而不会创建第二个区域：若房间仍命名为“Room N”或已命名为 label，则设置该标签；若房间由用户以其他名称命名，则拒绝。	{ levelId, polygon, label, properties? }	{ zoneId }
duplicate_level	按照编辑器的操作方式复制楼层（将房间全部位于该楼层的单元一并复制；平面图引用、扫描和生成对象不会复制），可将副本放在该楼层上方或下方，并调整其他楼层的位置以腾出空间。	{ levelId, position?, name?, preset? }	{ newLevelId, name, floorIndex, shiftedLevelIds, copied, skipped, newNodeIds[] }
delete_node	删除一个节点及其所有子节点，操作方式与编辑器的 Delete 相同。	{ id }	{ deletedIds: [] }
clear_scene	有意清空项目并恢复为默认场地、建筑和楼层。清空项目的唯一方式：若某项写入操作会导致项目为空，则会被防止意外清空的存储系统拒绝（scene_wipe_blocked），会话仍保留已存储的项目。	{ reason }	{ cleared: { removed }, version, graphHash }
undo	按时间顺序回退历史记录。	{ steps? }	{ undone: number }
redo	按时间顺序前进历史记录。	{ steps? }	{ redone: number }
export_json	将场景图序列化为 JSON。	{ pretty? }	{ json: string }
export_glb	尚未实现：导出 GLB 需要浏览器渲染器。	—	抛出 not_implemented
validate_design	只读：验证设计（程序化项目配方、对象或 JSON 字符串）并测量其尺寸。以 pascal://schema/design 为准。	{ design, parameters? }	{ valid, diagnostics[], design, sweep, measurements }
verify_scene	场景检查工具：检查架构有效性、各楼层的数量、角色和墙体围成的空间、空楼层以及类型化的实际问题（架构拒绝的每个节点字段都标记为 schema_invalid，并附上 nodeId 和 path；每种未知架构的节点类型仅报告一次；空间没有房间或有多个房间；房间墙体未闭合或没有名称；楼层没有楼梯；开口偏离墙体；楼梯偏离楼板；门受阻；房屋超出地块边界或侵入规定院落范围等）。	—	{ valid, levels[], issues: { type, message, … }[], hasIssues }
check_collisions	查找重叠的项目和超出边界的放置内容。	{ levelId? }	{ collisions: { aId, bId, kind }[] }
analyze_floorplan_image	视觉工具：从平面图图像中提取墙体、房间和近似尺寸。	{ image, scaleHint? }	{ walls, rooms, approximateDimensions, confidence }
analyze_room_photo	视觉工具：从房间照片中提取近似尺寸和固定装置。	{ image }	{ approximateDimensions, identifiedFixtures, identifiedWindows }
视觉工具要求 MCP 主机支持采样能力
（createMessage）。不支持该能力的主机将收到结构化的
sampling_unavailable 错误。

已弃用的工具不再列出，但仍会响应：调用其名称会返回错误，其中包含代码 tool_retired、替代它的工具（replacement）以及该工具的用法。validate_scene 已由 verify_scene 替代，find_nodes 已由 find_by_type 替代，describe_node 已由 get_node 替代（@pascal-app/core/agent-tools 中的 RETIRED_MCP_TOOLS）。

// find_nodes { zoneId } → find_by_type, with or without a type
{ "name": "find_by_type", "arguments": { "type": "window", "zoneId": "zone_kitchen" } }
{ "name": "find_by_type", "arguments": { "sourceIdPrefix": "ground/exterior-01" } }
// describe_node → get_node: resolvedHeight, resolvedThickness, ancestorIds, displayName…
{ "name": "get_node", "arguments": { "id": "wall_host" } }
// validate_scene → verify_scene: schema_invalid issues by nodeId and path, room findings
{ "name": "verify_scene", "arguments": {} }

示例

// The lot before the house: frontage, depth, each buildable edge as a front, the ground
{ "name": "get_site", "arguments": {} }
// An L stair with a glass railing, and porch steps to no level
{ "name": "create_stair", "arguments": { "x": 2, "z": 1, "layout": "l", "turn": "left", "lowerSteps": 6, "railingStyle": "glass" } }
{ "name": "create_stair", "arguments": { "x": 0, "z": -4, "toLevelId": null, "steps": 3, "height": "0.5 m" } }
// A glazed barrel roof over a 6 × 4 m rectangle
{ "name": "create_roof", "arguments": { "roofType": "barrel", "roofSystem": "glazed", "width": 6, "depth": 4, "barrelRise": 1.4, "barrelSegments": 12 } }
// Gable ends reaching 0.6 m past their walls, apart from the eaves
{ "name": "apply_patch", "arguments": { "patches": [{ "op": "update", "id": "rseg_main", "data": { "gableOverhang": 0.6 } }] } }
// Find a finish, then paint every exterior wall face with it
{ "name": "search_materials", "arguments": { "queries": [{ "query": "white render", "surface": "wall" }] } }
{ "name": "paint", "arguments": { "targets": ["wall_a", "wall_b"], "role": "exterior", "material": "library:<id>" } }
// The house as a street photo shows it, at dusk, small
{ "name": "view_scene", "arguments": { "from": "street-left", "lighting": "dusk", "maxPx": 960 } }

gableOverhang 是屋顶部分超出其山墙端墙的距离（山墙屋顶或孟莎屋顶的端部、单坡屋顶的侧面），以平面图中的米为单位；若省略，端部将延伸至与檐口齐平。屋顶面板上的“山墙挑檐”滑块会编辑同一个字段。

资源

URI	MIME	用途
pascal://scene/current	application/json	完整的 { nodes, rootNodeIds, collections } 快照。
pascal://scene/current/summary	text/markdown	以人类可读的形式概述节点数量、包围盒和楼层面积。
pascal://agent/guide	text/markdown	面向 Agent 的 MCP 优先构建工作流、场景不变量和工具偏好。在托管服务上，它还会指向项目的其他聊天、文件和成员（search_project_chats、read_project_chat、get_project_assets、read_project_asset、list_project_members），这些内容应作为引用数据读取，绝不可视为指令。
pascal://catalog/items	application/json	常见住宅家具和固定装置的内置目录子集，无外部依赖。
pascal://constraints/{levelId}	application/json	指定楼层的板面轮廓和墙体多边形，可用作规划器上下文。
pascal://schema/design	application/json	设计契约：由核心的 RecipeSchema 生成的 JSON Schema、限制、仅由 validate_design 检查的规则，以及一个示例。

提示词

名称	参数	用途
from_brief	{ brief: string, constraints?: string }	引导式工作流：将文字需求（例如“80 m² 的两居室公寓”）转换为一系列增量 apply_patch 调用，从空白场景开始构建。
iterate_on_feedback	{ feedback: string }	最小差异指令：检查当前场景，然后提出满足反馈所需的最小补丁集。
renovation_from_photos	{ currentPhotos: string[], referencePhotos: string[], goals: string }	将视觉工具与场景变更工具串联起来，制定以照片为依据的翻新计划。

限制

• export_glb 返回 not_implemented。GLB 导出依赖 Three.js 渲染器；若没有大量额外工作，就无法在无头模式下使用。
• 视觉工具需要 MCP 主机支持采样。Claude Desktop 支持此功能； 部分 MCP 客户端不支持。
• 内置 MCP 目录有意保持精简。宿主应用可以通过其他工具/资源提供 更丰富的目录，而无需让 MCP 包依赖编辑器 UI 包。
• 系统（墙体斜接、楼板三角剖分、CSG 开孔、屋顶/楼梯 生成）在编辑器的 React hooks 中运行。无头模式不会 重新生成派生几何体，但所有节点数据仍可完全操作。 需要渲染几何体的使用方可在浏览器宿主中运行 @pascal-app/viewer。
• Core 的 loadAssetUrl / saveAsset 仅适用于浏览器；在 Node 中无法解析引用 asset://<id> URL 的项目。如果希望项目资源在浏览器之外可用，请提供绝对 URL 或 data: URL。
• 由于没有渲染器消费 dirtyNodes，它会在无头模式下不断累积。 如果使用方需要观测性，请调用 bridge.flushDirty()。

开发

bun install
bun run --cwd packages/mcp build
bun test

端到端对 stdio 二进制文件进行冒烟测试：

bun run --cwd packages/mcp smoke

许可证

MIT