nodered-mcp

Node-RED flows.json 파일을 읽고, 쿼리하고, 편집하는 MCP 서버입니다.

소개

Node-RED는 모든 플로우, 노드, 와이어, 그룹 상자를 하나의 큰 JSON 파일에 저장합니다. 이 파일을 손으로 — 또는 jq와 sed로 — 편집하다 보면 끊어진 와이어, 더 이상 자신의 노드를 덮지 않는 그룹 상자, 기존 노드 위에 겹쳐진 새 노드가 생기기 마련입니다.

이 서버는 해당 파일을 MCP 클라이언트에 형식을 이해하는 작은 도구 모음으로 노출합니다. 플로우 노드와 설정 노드의 차이를 알고, 와이어 경로를 추적할 수 있으며, Node-RED 편집기의 자체 지오메트리를 재현하여 그린 그룹 상자가 편집기가 그렸을 바로 그 상자가 되도록 합니다.

홈 오토메이션 저장소에서 Node-RED 변경을 스크립트하는 데 사용된 flows_util.py / layout_util.py 쌍을 포팅한 것으로, 파일 경로, 컨테이너 이름, 재시작 명령이 모두 구성 가능하도록 일반화했습니다.

Related MCP server: nr-mcp

기능

• 쿼리 — 탭, 그룹, 고아 노드, 서브플로우, 참조된 Home Assistant 엔티티, 플로우를 통한 와이어 추적.

• 편집 — 노드 생성, 업데이트, 삭제, 이름 변경, 복제; 와이어 연결 및 해제; 그룹 생성, 채우기, 스타일 변경; 노드 세트 가져오기 및 내보내기.

• 배치 — 좌표를 추측하는 대신 노드를 만들기 전에 빈 캔버스를 확보하고, 캔버스의 충돌을 린트하며, 겹침을 복구합니다.

• 의도적인 커밋 — 편집 내용은 메모리에 누적되고 요청할 때만 디스크에 기록되므로 여러 노드 빌드가 하나의 단위로 처리됩니다.

• 기본 스크립트에는 없던 두 가지 보호 장치: 새 충돌을 유발하는 쓰기를 거부하는 레이아웃 게이트와, 브라우저에서 누군가 배포한 flows.json을 덮어쓰지 않도록 방지하는 오래된 파일 검사.

요구 사항

• Python 3.11+

• 로컬 파일 시스템의 flows.json

• PATH의 Docker — 파일을 컨테이너에 복사하고 재시작하는 deploy 도구 전용

설치

git clone https://github.com/ljmerza/nodered-mcp
cd nodered-mcp
uv sync

사용법

flows.json 경로가 유일한 필수 설정입니다. 합리적인 기본값이 없으므로 서버는 경로 없이는 시작을 거부합니다.

uv run nodered-mcp --flows-path /path/to/nodered/data/flows.json

MCP 클라이언트에 등록

{
  "mcpServers": {
    "nodered": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/nodered-mcp", "nodered-mcp"],
      "env": {
        "NODERED_FLOWS_PATH": "/path/to/nodered/data/flows.json"
      }
    }
  }
}

더 자세한 예는 .mcp.json.example을 참조하세요.

구성

모든 설정은 CLI 플래그 > 환경 변수 > 기본값 순서로 해석됩니다.

Node-RED가 일반 Docker 이외의 도구로 관리되는 경우 --restart-cmd를 해당 도구로 지정하세요:

NODERED_RESTART_CMD="docker compose restart {container}"

도구

각각 op 인자로 동작하는 7개의 도구가 있습니다.

일반적인 빌드

nodered_query(op="tabs")                                   -> tab ids
nodered_layout(op="free_region", tab_id=TAB, w=800, h=200) -> {"x": 100, "y": 3240}
nodered_edit(op="create_node", tab_id=TAB, node_type="inject",
             name="tick", x=100, y=3240)                   -> node id
nodered_edit(op="create_node", tab_id=TAB, node_type="switch",
             name="gate", x=300, y=3240)                   -> node id
nodered_edit(op="wire", source_id=..., target_id=...)
nodered_group(op="create", name="My Flow", tab_id=TAB, node_ids=[...])
nodered_session(op="save")

위의 어떤 작업도 최종 save 전에는 flows.json을 건드리지 않습니다.

파일 보호 방법

레이아웃 게이트

save와 deploy는 편집 전후에 캔버스를 린트하고, 편집으로 인해 새로운 오류 수준 발견 사항이 발생하면 쓰기를 거부합니다:

이미 디스크에 존재하는 문제는 차단하지 않습니다. 오직 편집으로 인해 생성된 문제만 차단합니다. 게이트가 발동하면 일반적으로 다음 중 하나로 해결합니다:

• nodered_layout(op="free_region")으로 빈 캔버스를 확보한 후 배치

• nodered_group(op="refit", group_id=...)으로 노드 주위로 그룹 크기 조정

• 겹침이 의도된 경우 nodered_session(op="save", allow_overlap=true)

그룹 지오메트리는 정확합니다. 크기 조정 규칙이 Node-RED 편집기에서 포팅되었으므로 계산된 상자가 편집기가 그리는 것과 일치합니다. 노드 지오메트리는 Helvetica 메트릭에서 근사한 레이블 텍스트 너비를 제외하면 정확합니다. 이것이 노드 수준 발견 사항이 항상 경고인 이유입니다.

오래된 파일 검사

Node-RED는 브라우저에서 누군가 Deploy를 누를 때마다 flows.json을 다시 씁니다. 세션은 파일을 로드할 때 (mtime_ns, size)를 기록하고 모든 쓰기 전에 다시 확인합니다. 파일이 변경된 경우 해당 작업을 자동으로 되돌리는 대신 커밋을 거부합니다. reload 후 편집을 다시 하거나 force=true를 전달하세요.

os.path.getmtime 대신 나노초를 사용하는 이유: 부동 소수점 epoch는 약 1마이크로초까지만 해석되므로 로드와 같은 틱에 쓰기가 발생하면 동일하게 비교되어 검사를 통과할 수 있습니다.

독립 실행

두 엔진 모듈 모두 MCP와 무관하게 라이브러리 및 CLI로 작동합니다.

uv run python -m nodered_mcp.flows summary --flows-path /path/to/flows.json
uv run python -m nodered_mcp.layout --path /path/to/flows.json --fix boxes,move

from nodered_mcp.flows import Flows

f = Flows("/path/to/flows.json")
ox, oy = f.free_region(tab_id, w=1600, h=300)
f.create_node(tab_id, "inject", "tick", x=ox, y=oy)
f.save()

--fix boxes 단독으로는 상황을 악화시킵니다: 다시 맞추면 일부 상자가 이웃한 비멤버 노드를 삼킬 만큼 커집니다. boxes,move를 함께 실행하고 --apply를 전달하기 전에 건너뛰기 실행을 읽어보세요.

프로젝트 구조

src/nodered_mcp/
├── server.py       FastMCP server: the seven tools
├── session.py      in-memory session, stdout capture, staleness guard
├── config.py       CLI flags and environment resolution
├── flows.py        the Flows class, composed from the mixins below
├── constants.py    defaults, the group style, LayoutError
├── reports.py      ReadMixin      — summary, tab, group, search, trace
├── nodes.py        NodeEditMixin  — create/update/delete/wire nodes
├── groups.py       GroupMixin     — create and populate group boxes
├── placement.py    LayoutMixin    — claim free canvas, measure and refit boxes
├── transfer.py     TransferMixin  — import and export node sets
├── persist.py      PersistMixin   — save, deploy, and the layout gate
└── layout.py       canvas geometry and linter, ported from the NR editor

Flows가 믹스인을 구성하므로 공개 API는 f.summary(), f.create_node(), f.free_region(), f.save()처럼 평평하게 유지됩니다.

개발

uv sync --group dev
uv run pytest                    # 49 tests
uv run ruff check .
uv run ruff format --check .

테스트는 실제 flows 파일이 아닌 tests/fixtures/의 합성 픽스처에 대해 실행됩니다. 구성 우선 순위, 읽기 도구, 저장 시까지 메모리 유지 의미, 차단 및 재정의된 레이아웃 게이트, 오래된 파일 보호, 배포 명령 시퀀스, 그리고 어떤 도구도 stdout에 쓰지 않는지(잘못된 print는 MCP의 stdio 프레이밍을 손상시킬 수 있음)를 다룹니다.

CI는 ljmerza/misc-actions를 통해 동일한 검사를 실행합니다.

기여

이슈와 풀 리퀘스트를 환영합니다. ruff check, ruff format, pytest를 통과시켜 주세요.

감사의 말

• Node-RED — 여기의 캔버스 지오메트리는 편집기 클라이언트에서 포팅되어 그룹 상자가 편집기가 그리는 것과 일치합니다.

• FastMCP — MCP 서버 프레임워크.

라이선스

MIT. LICENSE를 참조하세요.