sketchbord-mcp

Русская версия

AI 에이전트가 Sketchbord 화이트보드에 작업을 시각화하고 — 사람이 그린 내용을 포함해 보드를 다시 읽을 수 있게 해주는 MCP 서버입니다.

요점은 "순서도 그리기"가 아닙니다. 에이전트는 작업을 몇 개의 섹션으로 설명합니다 — 라벨이 붙은 화살표로 연결된 기둥들로 그려진 시스템, 체크리스트, 마인드맵, 퍼널, 피시본, 시퀀스 다이어그램, 로드맵, 스티키 벽, 때로는 플로우 — 그러면 서버가 이를 포스터처럼 배치해서, 한눈에 작업이 설명되게 합니다.

페이지 트리가 아니라 한 장의 그림입니다. 보드는 한때 드릴다운 단계로 자라났습니다: 자식을 가진 블록이 그 자체로 한 단계가 되고, 최상위 단계는 거의 아무것도 말하지 않았으며, 무언가를 설명하는 부분은 아무도 보지 않는 두 단계 아래에 있었습니다. lanes 섹션은 한 화면으로 모든 것을 말합니다 — 부품들이 나란히 있고, 각각이 내부에서 하는 일, 그리고 그 사이를 오가는 것이 화살표에 쓰여 있습니다.

네 가지가 이 서버를 단순한 드로잉 API 이상으로 만듭니다:

• 구조를 결정하는 것은 작업의 종류가 아니라 콘텐츠입니다. 보드 템플릿이 없습니다: pick_form은 가진 것의 형태 — 순서, 계층, 비교, 루프, 원인 집합 — 를 그것을 담는 형식에 매핑하고, 각 형식이 언제 잘못된 선택인지 말해줍니다. 두 작업에 대한 두 보드는 서로 닮지 않아야 하며, 이웃 섹션을 반복하는 섹션은 독자가 헛되이 두 번 읽어야 하는 섹션입니다.

• 보드 전체로 그립니다. 보드 자체 카탈로그의 픽토그램(list_icons — 붙여넣은 이미지가 아니라 같은 손으로 그린 것), 부품별 색상, 화살표를 따라 이동하는 것을 말해주는 화살표, 그리고 설명하는 화면을 스케치하는 카드(ui: 검색 필드, 버튼, 목록의 세 행)를 사용합니다. 모든 요소가 단어가 들어간 사각형인 그림은 독자가 읽어야 하는 그림입니다.

• 편집은 증분 방식입니다. mode: merge의 visualize_task는 이름을 지정한 섹션만 다시 작성합니다 — 다른 모든 것은 제자리를 유지하며, 사용자 자신의 스티키와 화살표도 포함됩니다. read_board는 그러한 사용자 추가 사항을 다시 보고합니다(userMarks), 그래서 에이전트는 사람이 스케치한 것에 반응할 수 있습니다, 예를 들어 코드 변경으로 전환할 수 있습니다.

• 그림을 다시 읽어줍니다. 에이전트는 눈이 멀어 그립니다: 자신의 그림이 네 개의 쌓인 불릿 목록으로 나왔다는 것, 화살표의 절반이 아무것도 말하지 않는다는 것, 캡션이 문장으로 자라났다는 것을 결코 알지 못합니다. 그래서 모든 그리기는 그림이 측정 가능하게 무엇인지로 답합니다 — 그리고 그 외에는 아무것도 아닙니다, 왜냐하면 규칙("보드는 다섯 개의 섹션을 가져야 한다")은 작업이 무엇이든 반복되는 형태이며, 그것이 모든 보드가 결국 똑같아지는 방식이기 때문입니다. 비고는 작업별로 수용하거나 무시할 관찰이며, 비고할 가치가 없는 보드는 전혀 비고를 받지 않습니다.

도구

Related MCP server: Excalidraw MCP Server

설정

sketchbord.ru의 API 키(bord_sk_…)가 필요합니다:

• 계정 키 (권장) — Мои доски → API-ключи → 보드를 선택하지 않고 키 생성. 작업별로 보드를 생성하고 편집할 수 있는 모든 보드에 그릴 수 있습니다.

• 보드 키 — 보드가 선택된 같은 페이지, 또는 보드 내부: 메뉴 (☰) → «Интеграции с ИИ». 하나의 보드에 바인딩되므로 boardId가 필요 없습니다.

MCP 클라이언트 구성

서버는 stdio를 통해 MCP를 사용합니다. 키가 전체 구성입니다 — 호스팅된 Sketchbord가 하나 있고 서버는 그 위치를 알고 있습니다.

Claude Code / Claude Desktop (.mcp.json 또는 claude_desktop_config.json):

{
  "mcpServers": {
    "sketchbord": {
      "command": "npx",
      "args": ["-y", "sketchbord-mcp"],
      "env": {
        "BORD_API_KEY": "bord_sk_xxx"
      }
    }
  }
}

클론에서 대신:

npm install
npm run build
# then "command": "node", "args": ["/path/to/sketchbord-mcp/dist/index.js"]

환경

두 종류의 키

• 계정 키 (보드 없음) — 계정을 대신하여 작동하므로 에이전트가 작업별로 보드를 생성할 수 있고 (create_board, 또는 newBoard가 있는 visualize_task), 편집할 수 있는 모든 보드에 그릴 수 있습니다. 하나의 프로젝트를 기본으로 하려면 BORD_BOARD_ID를 설정하세요.

• 보드 키 — 단일 보드에 바인딩되며, 키에서 유추됩니다.

섹션 구조

모든 섹션에는 안정적인 id(증분 편집을 가능하게 하는 요소), kind, title이 있으며, 그 다음에 해당 종류가 사용하는 필드가 옵니다:

• items (note / tag / color / done / span / children) — 목록, 단계, 체크리스트, 트리, 마인드맵, 스티커 메모, 카드, 타임라인, 지표, 퍼널의 밴드(가장 넓은 것부터) 또는 피라미드(정점부터), 사이클의 단계, 벤 다이어그램의 집합, 피시본의 원인 범주;

• groups — lanes 포스터의 기둥(id / subtitle / icon / color, 왼쪽 가장자리의 사람 열을 위한 bare), 칸반 열, 4분면, proscons의 양면(첫 번째는 찬성, 두 번째는 반대), roadmap의 레인;

• links — lanes 전용: 기둥 사이의 화살표(from / to는 레인 id, 위치 또는 제목으로 지정, label은 이를 따라 이동하는 것, both, dashed);

• nodes + edges — 흐름/상태, 그리고 sequence에서 노드는 참가자이고 엣지는 메시지입니다;

• columns + rows — table; roadmap의 경우 columns는 기간이고 각 항목의 span은 막대가 덮는 기간을 지정합니다;

• text — note의 문단, fishbone 머리의 효과, venn 겹침 부분의 캡션.

모든 항목, 그룹 또는 섹션은 icon을 가질 수 있습니다 (list_icons의 id; 다른 것은 플레이스홀더로 그려지지 않고 버려집니다). lanes 섹션의 카드는 children 대신 ui를 가질 수 있습니다 — field / button / row / chip — 이는 설명하는 인터페이스를 스케치합니다.

width는 narrow / normal / wide — 비율에 대한 힌트이며, lanes에서는 한 기둥의 너비를 설정합니다. 플랜의 accent는 보드의 색상을 설정하므로 두 보드가 같아 보일 필요가 없습니다.

플로차트 노드 유형: process (단계), decision (분기 — 레이블이 있는 엣지 사용), error (실패), start/end (터미널).

토큰 비용

이 서버가 게시하는 도구 정의는 약 21 KB (~6 000 토큰)이며, 모든 요청에서 에이전트의 컨텍스트에 상주합니다. 대부분은 visualize_task의 스키마로, 에이전트가 왕복 없이 채울 수 있는 DSL의 대가입니다. 나머지는 의도적으로 얇게 유지됩니다: 어떤 형식을 선택할지에 대한 긴 지침은 pick_form과 sketch_board에 있으며, 호출되기 전까지 비용이 들지 않고, read_board는 답변을 60 000자로 제한하여 하나의 보드가 컨텍스트 창을 채울 수 없게 합니다.

보드 읽기는 신뢰 경계입니다

read_board는 다른 사람이 작성한 텍스트를 반환합니다. 서버는 이를 명시적인 "신뢰할 수 없는 데이터" 구분 기호로 감싸고 크기를 제한합니다. 그 내용이 지침과 동일한 컨텍스트에서 모델에 도달하기 때문입니다 — "이전 지침을 무시하세요"라고 적힌 스티커 메모는 프롬프트 인젝션 시도이며, 명령이 아니라 사용자가 화이트보드에 쓴 것으로 읽어야 합니다.

예시 프롬프트

서비스가 어떻게 구성되어 있는지 보드에 설명하세요: 프론트엔드, API, 워커, Postgres 및 S3.

lanes 섹션: 각 부분에 기둥 하나, 각 작업에 카드 하나, 각 카드에 아이콘, 그리고 "HTTP request", "SQL", "file URL"을 전달하는 기둥 사이의 links. 엔드투엔드 경로를 설명할 가치가 있다면 그 아래에 process 스트립, 독자가 팀원이 아니라면 glossary 스트립. 프론트엔드 카드의 ui는 "검색 화면이 있다"를 화면 그림으로 바꿉니다.

작업을 그리세요: CSV에서 카탈로그로 가격표 가져오기.

고정된 답은 없습니다. 에이전트는 독자가 알아야 할 것을 묻고 부분별로 형식을 선택합니다: 가져오기의 각 단계에서 손실된 행은 note에 숫자가 있는 funnel; 여러 무관한 실패 원인은 fishbone; 코드에서 건드릴 부분은 tree; CSV, 파서, 카탈로그 사이에서 어떤 순서로 일어나는지는 sequence. 그런 다음 작업을 위한 checklist — 실제 체크박스로, 수행하는 사람이 체크합니다.

보드에 화살표와 스티커를 그렸습니다 — 코드를 보고 고치세요.

read_board는 userMarks를 반환합니다. 예를 들어 flow 섹션에 있는 "여기 재시도 필요!" 스티커와 두 블록을 연결하는 손으로 그린 화살표. 에이전트는 이를 바탕으로 행동한 다음 visualize_task (mode: merge) 또는 add_sticky 연산으로 결정을 반영합니다 — 보드의 나머지는 그대로 둡니다.

플랜을 교체하고 범례를 제거하세요.

mode: merge와 하나의 plan 섹션이 있는 visualize_task, 그 다음 removeSections: ["legend"]가 있는 update_visual. plan 카드는 제자리에 다시 그려집니다; 나머지는 모두 위치를 유지합니다.

개발

npm install
npm run build      # tsc → dist/
npm run typecheck
BORD_API_KEY=bord_sk_… BORD_API_URL=http://localhost:4000 npm start

라이선스

MIT — LICENSE 참조.