@cocrates/elk-mcp

elkjs 기반 그래프 레이아웃을 MCP로 제공하는 TypeScript 패키지입니다.

에이전트는 노드/엣지 구조만 넘기고, 좌표·엣지 경로는 이 서버가 계산합니다. 렌더링은 포함하지 않습니다.

패키지	@cocrates/elk-mcp
바이너리	elk-mcp
런타임	Node.js 18+
전송	MCP stdio (JSON-RPC)

---

MCP 도구

Tool	설명
layout_graph	graph + options로 레이아웃 → 노드 좌표·엣지 sections
validate_graph	레이아웃 전 검증 (중복 id, parent, endpoint 등)
list_algorithms	등록된 ELK 알고리즘 목록
list_layout_options	알려진 레이아웃 옵션 (query로 필터)
list_layout_categories	레이아웃 카테고리

layout_graph 입력

• graph: 구조만 (nodes, edges)
• options: algorithm, direction, layoutOptions 등 (그래프와 분리)

options.algorithm은 ELK layout algorithm id(예: layered, mrtree, force)이고, options.direction은 RIGHT/LEFT/UP/DOWN 형태 문자열입니다.

계층은 둘 중 하나:

• flat: node.parent

• nested: node.children
  (같은 노드에 둘 다 쓰지 말 것)

• leaf 노드(자식이 없는 노드)의 width/height는 가능하면 제공하세요. 미제공이면 서버에서 기본값 80x40을 사용합니다.

• edges의 엔드포인트는 노드 id 또는 포트 id가 될 수 있습니다(노드의 ports[]로 포트를 선언한 경우).

• edges[]는 graph.edges에 모두 모아도 됩니다. 서버가 엣지 양끝의 LCA(최저 공통 조상) 노드 아래에 배치합니다.

• edges[]는 id가 필요합니다. 또한 source/target 또는 sources/targets 형태로 엔드포인트를 줄 수 있습니다.

{
  "graph": {
    "nodes": [
      { "id": "svc", "label": "Service" },
      { "id": "A", "parent": "svc", "label": "API", "width": 120, "height": 40 },
      { "id": "B", "parent": "svc", "label": "DB", "width": 100, "height": 40 },
      { "id": "C", "label": "Client", "width": 90, "height": 40 }
    ],
    "edges": [
      { "id": "e1", "source": "A", "target": "B" },
      { "id": "e2", "source": "C", "target": "A" }
    ]
  },
  "options": {
    "algorithm": "layered",
    "direction": "RIGHT"
  }
}

출력

출력은 options.absoluteCoordinates에 따라 좌표계가 달라집니다.

• options.absoluteCoordinates가 true(기본): nodes[].x/y와 edges[].sections[].startPoint/endPoint/bendPoints가 모두 단일(전역) 좌표계 기준입니다.
• options.absoluteCoordinates가 false: 값들은 렌더링 프레임에서 바로 쓰기 어렵습니다(노드/엣지의 로컬 좌표계 기준으로 내려옵니다). 일반적인 캔버스 렌더링에는 기본값인 true를 권장합니다.

절대좌표(기본) 기준 flat JSON의 주요 필드:

• nodes[]: id, label?, x, y, width, height, parent?, children?
  • x,y: 노드 바운딩박스의 좌상단 기준 좌표(ELK 결과 기준)
  • ports?: 각 포트의 id, x,y, width,height
  • labels?: 각 라벨의 id?, text?, x,y, width,height
• edges[]: id, sources, targets, sections[], junctionPoints?
  • sections[]는 ELK extended edge 라우팅이 분해된 구간 목록입니다.
  • 각 sections[] 항목은 startPoint, endPoint, bendPoints[]로 구성되며, bendPoints는 폴리라인 중간 정점(순서대로 연결)입니다.
  • junctionPoints는 하이퍼엣지 등에서 분기/합류점이 계산된 경우에만 내려옵니다.

---

클라이언트 설정

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

로컬 빌드:

{
  "mcpServers": {
    "elk": {
      "command": "node",
      "args": ["/path/to/elk-mcp/dist/mcp/index.js"]
    }
  }
}

---

개발

npm install
npm run build
npm test
npm run start:mcp

프로그램에서 코어 API를 직접 쓸 수도 있습니다:

import { layoutGraph } from "@cocrates/elk-mcp";

const result = await layoutGraph(
  {
    nodes: [
      { id: "A", width: 120, height: 40 },
      { id: "B", width: 100, height: 40 },
    ],
    edges: [{ id: "e1", source: "A", target: "B" }],
  },
  { algorithm: "layered", direction: "RIGHT" },
);

---

GitHub Release · npm 배포

패키지 이름: @cocrates/elk-mcp (scoped). npm에 퍼블리시하려면 해당 scope 권한이 필요합니다.

1. 버전 올리기

npm version patch   # 0.1.0 → 0.1.1
# 또는 minor / major
npm run build

2. npm 배포

npm login
npm publish --access public

files 필드에 dist, README.md, LICENSE만 포함되므로 publish 전에 반드시 npm run build 하세요. (dist/는 gitignore일 수 있습니다.)

3. GitHub Release

git push origin main --follow-tags

gh release create v0.1.1 \
  --title "v0.1.1" \
  --notes "$(cat <<'EOF'
## Changes
- …

## Install
npm install -g @cocrates/elk-mcp@0.1.1
EOF
)"

태그/릴리스는 npm version이 만든 git tag와 버전을 맞추면 됩니다.

권장 순서

1. PR 머지 → main
2. npm version + npm run build + npm publish
3. git push --follow-tags + gh release create

CI에서 publish하려면 Node 18+, NPM_TOKEN, (선택) GITHUB_TOKEN을 시크릿으로 두면 됩니다.

---

참고

• elkjs 인터페이스: docs/elkjs.md
• ELK JSON Format
• ELK Layout Options