rootr-cli

Rootr(마크다운 지식협업 SaaS) 공식 CLI + MCP 서버. 에이전트나 사람이 Rootr 문서를 로컬 파일처럼 읽고/쓰고/검색할 수 있게 해줍니다.

• rootr CLI: ls, read, write, append, edit, search, ws, ask, config

• rootr mcp: stdio 기반 MCP 서버 (Claude Code / Claude Desktop 등에 등록해서 사용), 도구 27종 — 문서 6종 + 워크스페이스/스캐폴딩 4종 + LOG 데이터스토어 5종 + RCA ask 1종 + 이슈 6종 + 웹훅 3종 + 문서버전/삭제 2종

순수 Node.js ESM, 빌드 과정 없음. Node 18 이상 필요(내장 fetch 사용).

링크

• 소스: https://github.com/gwmage/rootr-cli

• npm: https://www.npmjs.com/package/rootr-cli

• 원격 커넥터(설치 없이 바로 연결): https://rootr.io/mcp — Claude Code/Desktop 등에서 로컬 CLI 설치 없이 원격 MCP 엔드포인트로 바로 연결할 수 있습니다. 로컬 CLI(rootr mcp)와 기능은 동일하며, 자체 인프라에 CLI를 두고 싶을 때만 이 저장소를 설치하면 됩니다.

• 라이선스: MIT (LICENSE 참고)

Related MCP server: mcp-server-markdown

설치

이 저장소 안에서 바로 실행하거나, 전역 설치할 수 있습니다.

cd cli
npm install

# 방법 1: 직접 실행
node bin/rootr.js --help

# 방법 2: 전역 설치 (심볼릭 링크로 rootr 명령 사용)
npm install -g .
rootr --help

설정

우선순위: 환경변수 > ~/.rootr/config.json

설정 파일에 저장하기:

rootr config --api-key rootr_xxxxxxxxxxxxxxxx --workspace ws_123
# 필요하면 온프레미스/개발 서버용 base-url도 지정 가능
rootr config --api-key rootr_xxx --workspace ws_123 --base-url https://dev.rootr.io/api/v1

~/.rootr/config.json은 chmod 600으로 생성됩니다.

키 2종

Rootr API 키는 두 종류가 있고, 도구별로 요구하는 종류가 다릅니다.

• 워크스페이스 키: 특정 워크스페이스 안에서만 동작. 스코프는 docs:read/docs:write/graph:read/ask/webhooks:manage 중 일부. 대부분의 문서/LOG/이슈/웹훅/ask 도구는 이 키로 충분합니다.

• 계정 키 (PAT): 사용자 계정 전체로 동작. workspaces:create 스코프가 있으면 새 워크스페이스를 만들 수 있습니다 (rootr_create_workspace). 워크스페이스 키로 워크스페이스 생성을 시도하면 403과 함께 계정 키가 필요하다는 힌트가 출력됩니다.

현재 설정 확인 (API 키는 앞 12자만 표시):

rootr config
# config file: /home/you/.rootr/config.json
# apiKey:      rootr_abcd...
# workspace:   ws_123
# baseUrl:     https://rootr.io/api/v1

CLI 사용법

경로 인자 규칙: /로 시작하면 경로로 취급되어 by-path API로 노드 id를 알아냅니다 (워크스페이스 설정 필요). /로 시작하지 않으면 노드 id로 취급합니다.

트리 조회

rootr ls                # 전체 트리
rootr ls /notes         # /notes 하위만

출력: TYPE\tpath 형식, 경로 정렬.

문서 읽기

rootr read /notes/todo.md          # 마크다운 원문을 stdout으로
rootr read /notes/todo.md --json   # 메타데이터 포함 JSON 전체
rootr read <nodeId>                # id로도 가능

문서 쓰기 (전체 교체, 없으면 생성)

echo "# 제목" | rootr write /notes/new.md
rootr write /notes/new.md --file ./local.md
rootr write <nodeId> --file ./local.md --if-match "\"abc123\""   # 낙관적 동시성 제어

경로가 아직 없으면 자동으로 문서를 생성합니다(createParents: true). --if-match를 지정했는데 그 사이 문서가 바뀌었으면 412 오류와 함께 "문서가 그 사이 변경됨: 다시 읽고 재시도" 힌트가 출력됩니다.

안전하게 추가 (append) — 충돌 걱정 없는 기본 수단

rootr append /notes/log.md "오늘 배포 완료"
rootr append /notes/log.md "- 항목 하나 더" --heading "## 할 일"
cat diff.md | rootr append /notes/log.md
rootr append /notes/log.md --file ./chunk.md

--heading을 지정하면 해당 헤딩 섹션 끝에 추가되고, 없으면 문서 끝에 추가됩니다. append는 전체 내용을 다시 쓰지 않으므로 다른 프로세스와 동시에 써도 충돌하지 않습니다.

텍스트 치환 (edit)

rootr edit /notes/todo.md --find "- [ ] 배포" --replace "- [x] 배포"
rootr edit /notes/todo.md --find "TODO" --replace "DONE" --all

--find한 텍스트가 없거나 여러 번 나타나면(고유하지 않으면) 서버가 409를 반환하고 그 이유가 그대로 출력됩니다. --all을 주면 모든 일치 항목을 치환합니다.

검색

rootr search "배포 절차"

출력: path — snippet 목록.

워크스페이스 목록

rootr ws

출력: id\tname 목록 (계정 키면 소속된 전체 워크스페이스, 워크스페이스 키면 그 워크스페이스만).

RCA 질의응답 (ask)

rootr ask "지난주 배포 후 지연이 왜 늘었어?"
rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123

워크스페이스의 지식그래프(GraphRAG)에 질문하고 답변 본문 + 인용(문서 경로: 인용문)을 출력합니다. ask 스코프가 필요합니다. --workspace를 생략하면 설정된 기본 워크스페이스를 사용합니다.

MCP 서버로 사용하기

rootr mcp는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 27종:

문서 (workspace 키, docs:read/docs:write)

에이전트에게는 가능하면 rootr_append/rootr_edit을 우선 사용하고, rootr_write는 정말 전체를 다시 쓸 때만 (가능하면 ifMatch와 함께) 쓰도록 각 도구 설명에 명시되어 있습니다.

워크스페이스 / 스캐폴딩

LOG 데이터스토어 (docs:read/docs:write)

RCA 질의응답 (ask 스코프)

이슈 트래커 (docs:read/docs:write)

웹훅 (webhooks:manage 스코프)

문서 버전 / 삭제

프레젠테이션 (현재 REST 전용 — 전용 MCP 도구는 예정)

프레젠테이션(PRESENTATION) 노드는 아직 전용 MCP 도구가 없고, 같은 API 키로 REST를 직접 호출해 저작합니다 (x-api-key 헤더, docs:write):

# 덱 생성 (슬라이드 포함 가능)
curl -X POST "$BASE/workspaces/$WS/presentations" -H "x-api-key: $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"제안서","slides":[{"id":"SLD-001","kind":"cover","title":"..."}]}'

# 슬라이드 부분 수정(머지) / 추가 / 순서 변경
curl -X PATCH "$BASE/presentations/$ID/slides/SLD-001" -H "x-api-key: $KEY" \
  -H 'Content-Type: application/json' -d '{"slide":{"notes":"발표 대본"}}'
curl -X POST "$BASE/presentations/$ID/slides"  -d '{"slides":[...]}' ...
curl -X POST "$BASE/presentations/$ID/reorder" -d '{"order":["SLD-002","SLD-001"]}' ...

고품질 덱을 만들 때는 슬라이드 html 필드에 1280×720 완결 HTML을 직접 구워 넣는 방식을 권장합니다 — 뷰어가 기본 템플릿 대신 그대로 렌더합니다(완전 자유 디자인). 필수 규칙(외부 요청 차단이라 전부 인라인, 이미지=data URI 내장, 폰트 폴백 스택, <span class="pn">=페이지번호, 그래프용 텍스트(title/blocks/notes/alt) 병행 유지)은 /llms.txt의 "Presentations" 섹션에 정리돼 있습니다 — 저작 전에 꼭 읽어보세요. AI 이미지 생성은 POST /v1/workspaces/:ws/images/generate(AI 크레딧 차감)를 사용합니다.

모든 도구 설명은 영어(에이전트가 소비하는 스키마)로 작성되어 있고, JSON을 반환하는 도구는 보기 좋게 들여쓴 JSON 텍스트로 응답합니다. workspace 인자를 받는 도구는 생략 시 ROOTR_WORKSPACE/설정파일의 기본 워크스페이스를 사용하며, 그것도 없으면 명확한 에러를 반환합니다.

Claude Code / Claude Desktop에 등록하기

~/.claude.json(Claude Code) 또는 Claude Desktop의 MCP 설정 파일에 다음을 추가:

{
  "mcpServers": {
    "rootr": {
      "command": "node",
      "args": ["/path/to/rootr/backend/cli/bin/rootr.js", "mcp"],
      "env": {
        "ROOTR_API_KEY": "rootr_xxxxxxxxxxxxxxxx",
        "ROOTR_WORKSPACE": "ws_123"
      }
    }
  }
}

전역 설치했다면 command를 "rootr", args를 ["mcp"]로만 써도 됩니다.

에러 처리

API가 비-2xx를 반환하면 응답 본문의 message(있으면)를 stderr에 출력하고 exit code 1로 종료합니다. 상황별 힌트:

• 401/403 → API 키/워크스페이스 스코프 확인 안내

• 412 → "문서가 그 사이 변경됨: 다시 읽고 재시도" 안내 (If-Match 불일치)

• 409 → 서버가 준 이유 메시지를 그대로 표시 (예: edit의 find 불일치/중복)

개발 메모

• 의존성: @modelcontextprotocol/sdk(MCP 서버), zod(도구 입력 스키마). CLI 자체(bin/rootr.js, lib/config.js, lib/client.js, lib/resolve.js)는 외부 의존성 없이 동작합니다.

• 빌드 스텝 없음 — 순수 ESM 자바스크립트.

• 파일 구성:

  • bin/rootr.js — 엔트리포인트, 명령 디스패치

  • lib/config.js — 설정 로드/저장

  • lib/client.js — Rootr REST API 클라이언트(문서/워크스페이스/스캐폴딩/LOG/ask/이슈/웹훅)

  • lib/resolve.js — path/id 타겟 해석 공통 로직

  • lib/mcp.js — MCP stdio 서버 진입점, 도구 모듈 조립

  • lib/mcp-tools/shared.js — MCP 도구 공통 헬퍼(textResult/jsonResult/errorResult/makeClient/requireWorkspace)

  • lib/mcp-tools/documents.js — 문서 도구 6종

  • lib/mcp-tools/workspaces.js — 워크스페이스/스캐폴딩 도구 4종

  • lib/mcp-tools/logs.js — LOG 데이터스토어 도구 5종

  • lib/mcp-tools/ask.js — RCA ask 도구 1종

  • lib/mcp-tools/issues.js — 이슈 트래커 도구 6종

  • lib/mcp-tools/webhooks.js — 웹훅 도구 3종

  • lib/mcp-tools/misc.js — 문서버전/삭제 도구 2종