AI 连接 (MCP)

AI 连接是让 Claude Desktop · Claude Code 等 MCP 客户端直接使用 NP Editor 的功能。AI 可以放置方块、截取画面查看结果、进行检查并导出。还可以用 AI 地图生成器（build_map）一次性生成包含地形、道路、建筑和村庄的地图。

AI 应用 ──(MCP)── NPEditorMcp.exe ──(127.0.0.1, 令牌)── NP Editor (已打开时为实时模式)
                        └── 没有编辑器时为文件模式: 直接打开并修改 .npworld

打开方式

内容	打开位置
开启/关闭	工具 › 开关 AI 连接(MCP)
复制设置片段	工具 › 复制 AI 连接设置(用于 Claude Desktop)
偏好设置	编辑 › 编辑器偏好设置…（`Ctrl`+`,`）› AI 连接
控制台	`mcp on` · `mcp off` · `mcp status`

快速使用

确认安装文件夹中有 mcp\NPEditorMcp.exe。
在编辑器中点击工具 › 复制 AI 连接设置(用于 Claude Desktop)。设置片段会被复制到剪贴板。
在 AI 应用中注册。
- Claude Desktop：粘贴到 %APPDATA%\Claude\claude_desktop_config.json 的 mcpServers 中，然后重新启动 Claude Desktop。
- Claude Code：claude mcp add npeditor -- "<安装文件夹>\mcp\NPEditorMcp.exe"
在编辑器中通过工具 › 开关 AI 连接(MCP) 开启。下次启动时也会记住。
对 AI 说「请检查一下编辑器状态」。
如果 AI 调用的 status 结果为 mode: live，则表示已连接。

安装包中还附带了技能 skills\np-editor-builder\SKILL.md，其中介绍了 AI 如何用好这些工具。在 Claude 应用中将其添加为账户技能；在 Claude Code 中将其复制到 ~/.claude/skills/np-editor-builder/SKILL.md。

自 0.9.3 起：NPEditorMcp 也需要有在编辑器中登录的账户才能启动。请先打开 NP Editor 并登录。

实时模式与文件模式

模式	何时	区别
实时	编辑器已打开且 AI 连接已开启时	AI 的编辑会立即显示在视口中。可以使用 `camera` · `screenshot`。着色器画面风格会立即应用到预览中。
文件	编辑器未运行时	直接打开并修改 `.npworld`。用 `map_image` · `view_image` 代替截图查看结果。着色器画面风格只存在于本次 MCP 会话中。

默认（--mode auto）在有编辑器时为实时模式，没有时为文件模式。
中途模式发生变化时，会在结果的第一行提示。

安全规则

规则	内容
默认关闭	只有在开启期间，AI 才能使用编辑器。
仅限本机	桥接只在 127.0.0.1 上开放，每次连接都会验证随机令牌（`%APPDATA%\NPEditor\mcp\bridge.json`）。
撤销	一次编辑 = 撤销 1 步 + 大纲中的 1 个 Actor。`build` 将多个操作合并为一步，出错时全部撤销。
不覆盖	保存 · 导出时如有同名文件，会附加 `_v2` · `_v3`。只有以 `overwrite=true` 保存当前打开的文件时才会覆盖。
保护未保存的更改	存在未保存的更改时，会拒绝 `world_new` · `world_open`。`discard_unsaved=true` 只在用户同意时使用。
尊重锁定	跳过已锁定的 Actor · 协作建造锁定的格子，并在结果中提示。
大小上限	一次最多可更改 800 万格，扫描最多 6,400 万格。

工具分组

工具名称和参数全部列在 MCP 工具列表中。

分组	工具
状态 · 世界	`status` · `world_new` · `world_open` · `world_save` · `undo` · `redo` · `actors` · `select`
读取	`inspect_region` · `read_blocks` · `surface` · `find_blocks` · `block_search` · `block_info` · `palette`
编辑	`set_blocks` · `fill` · `shape` · `replace` · `clear` · `transform` · `build` · `generate`
创作	`build_script` · `furnish` · `furnish_building` · `terrain_sculpt`
地形 · 自然	`terrain_water` · `terrain_shape` · `scatter` · `props`
AI 地图生成器	`blueprints` · `place_blueprint` · `build_map`
查看	`camera` · `screenshot` · `map_image` · `view_image` · `view_sheet`
着色器 · 资源包	`shader_looks` · `shader_look` · `shader_formulas` · `build_shaderpack` · `build_resourcepack` · `items` · `item_set` · `sky`
声音	`sounds` · `sound_set` · `sound_generate` · `block_sounds_set`
世界逻辑 · Actor	`scene_rules` · `scene_rule_set` · `anim_clips` · `anim_clip_set` · `meta_actor` · `actor_components`
设计	`bom` · `design_report` · `travel_times`
导出	`export`
网页 3D 查看	`world_info` · `world_chunks`

AI 地图生成器

工具	作用
`blueprints`	提供可建造的部件、风格、地图设计图的格式和示例。
`place_blueprint`	在现有地面上建造一个部件。部件包括房屋 · 塔 · 殿堂 · 城堡 · 道路 · 广场 · 喷泉 · 传送门 · 摊位 · 水井 · 路灯 · 桥 · 城墙 · 大台阶 · 树 · 岩石。
`build_map`	根据一份地图设计图（np-mapspec JSON），按地形 → 道路 → 建筑物 → 村庄（道路旁的房屋）→ 自然的顺序建造整张地图。最大 1024×1024。

细节级别（`detail`）	结果
`low`	仅体块（形态）
`medium`	普通的 Minecraft 建筑（`place_blueprint` 默认）
`high`	用原版方块所能达到的最高细节 — 内凹窗户 · 边框 · 挑檐层 · 室内 · 庭院
`max`	`high` + 装饰 — 风化 · 树篱 · 藤蔓 · 道具

风格（style）为 medieval · fantasy_kingdom · nordic · desert。
在设计图中写入 "terrain": "keep" 即可在现有地面上建造。
review=true 时会附加结果摘要（各类建筑数量 · 道路连通 · 被水淹没的道路 · 重叠的建筑等）。
一张地图 = 撤销 1 步。

示例：说「用 high 建一座中世纪村庄。中间有广场和一座城堡，还有一条河」，AI 会用 blueprints 查看格式，然后调用 build_map。

选项

编辑器偏好设置 › AI 连接

设置	默认	含义
启用 AI 连接 (MCP)	关	开启后打开桥接。
桥接端口	0（自动）	为 0 时选择空闲端口。无法打开指定端口时，改用空闲端口并记录到日志。

NPEditorMcp.exe 启动选项

选项	含义
`--mode auto\|live\|file`	固定模式（默认 auto）
`--jar <client.jar>`	要使用的 Minecraft 客户端 jar
`--no-jar`	既不查找也不读取 jar。与环境变量 `NPEDITOR_NO_JAR=1` 相同。
`--dir <文件夹>`	默认文件夹（默认 `文档\NPEditor`）
`--config`	输出 Claude Desktop 设置片段和 Claude Code 命令。
`--version`	版本号

--no-jar 优先于 --jar。需要 jar 的功能（palette 等）将不可用，颜色使用内置的近似色表。用于公开服务等无法使用 jar 的场合。
未指定 jar 时，按与编辑器相同的规则在启动器文件夹中查找 1.21.11 的 jar。
结果保存在默认文件夹下的 shaderpacks · resourcepacks · exports · looks 中。

快捷键

此功能没有默认快捷键。可以在工具 › 快捷键… 中为菜单项设置按键。

提示 / 注意

在大型操作之后，让 AI 用 screenshot 或 view_sheet 查看结果并进行修改，可以提高质量。
不满意时，在编辑器中用 Ctrl+Z 撤销。AI 的编辑也会记入同一撤销历史。
无法连接时，用 mcp status 查看开启状态 · 端口 · 调用次数。
复制设置时如果通知中出现「找不到 NPEditorMcp.exe」，请确认安装文件夹中 mcp\NPEditorMcp.exe 的路径。
区域触发器向导（一次性创建触发器 + 规则）目前仅能在编辑器中使用。