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 면 연결된 것입니다.

설치본에는 AI 가 이 도구를 잘 쓰는 법을 담은 스킬 skills\np-editor-builder\SKILL.md 가 같이 들어 있습니다. 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 가 에디터를 쓸 수 있습니다.
내 PC 만	다리는 127.0.0.1 에만 열리고, 연결마다 무작위 토큰을 확인합니다(`%APPDATA%\NPEditor\mcp\bridge.json`).
되돌리기	편집 하나 = 되돌리기 1단계 + 아웃라이너 액터 1개입니다. `build` 는 여러 작업을 한 단계로 묶고, 오류면 전부 되돌립니다.
덮어쓰지 않음	저장 · 내보내기는 같은 이름이 있으면 `_v2` · `_v3` 를 붙입니다. 지금 연 파일을 `overwrite=true` 로 저장할 때만 덮어씁니다.
저장 안 한 변경 보호	저장 안 한 변경이 있으면 `world_new` · `world_open` 을 거부합니다. `discard_unsaved=true` 는 사용자가 동의했을 때만 씁니다.
잠금 존중	잠긴 액터 · 함께 짓기 잠금 칸은 건너뛰고 결과에 알립니다.
크기 한도	한 번에 바꿀 수 있는 칸은 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`
월드 로직 · 액터	`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`	보통 마인크래프트 건축(`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>`	쓸 마인크래프트 클라이언트 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 경로를 확인합니다.
구역 트리거 마법사(트리거 + 규칙 한 번에)는 아직 에디터에서만 됩니다.