9. MCP 도구 17개

v3 의 MCP 표면은 17 개 도구로 정착했습니다 (v3.1.1 에서 일부 통합 도구를 다시 분리). 여기서는 한 줄씩 훑고, 대표적인 사용 흐름 두 가지를 코드로 보여줍니다.

9.1 도구 카탈로그

저장 / 편집 (6)

• save_raw — 원본 노트 저장. 분류 안 함.
• create_page_from_raw — 원본에서 토픽-스코프 페이지 추출. 한 원본에 여러 번 호출 가능.
• update_raw_item — 원본 본문/요약 갱신. 거의 안 씁니다 (원본은 불변에 가까움).
• update_note — 페이지 필드 갱신 (title, body, summary, topicId, pageTypeId).
• mutate_blocks — 페이지 안의 블록 단위 편집. op: 'append' | 'replace' | 'edit' 세 가지.
• update_workspace_overview — 홈 화면 1–3 단락 인덱스 저장.

조회 (6)

• recall — 위 8 절 참조.
• get_note — 페이지 한 개 + 백링크/멘션/형제 페이지.
• get_raw_item — 원본 한 개.
• list_recent_notes — 최근 페이지 목록.
• list_raws — 최근 원본 목록.
• workspace_events — 특정 시각 이후 변경된 페이지 목록 (대화 시작할 때 호출).

카탈로그 (4)

• list_topics_catalog — 토픽 트리 조회. 분류 전에 반드시 호출.
• list_page_types — 페이지 타입 카탈로그 조회. 분류 전에 반드시 호출.
• create_topic — 새 토픽 생성. userApproved: true 필수 — 사용자가 채팅에서 명시 승인한 다음에만.
• create_page_type — 새 페이지 타입 생성. userApproved: true 필수.

점검 (1)

• lint_workspace — 일관성 스캔. SCAN-ONLY (절대 mutate 안 함).

9.2 사용 흐름 1 — 새 노트 → 페이지 두 개

사용자: "방금 한 카파시 LLM Wiki 얘기 저장해줘"

AI 흐름:
  1. recall(query="카파시 LLM Wiki", mode="titles")
       → 기존에 비슷한 페이지가 있나 확인
  2. list_topics_catalog()
  3. list_page_types()
       → 기존 분류 카탈로그 살핌
  4. save_raw({
       title: "카파시 LLM Wiki 패턴 토론",
       body: "<verbatim transcript>",
       summary: { ko: "...", en: "..." },
     })
       → rawItemId 받아옴
  5. create_page_from_raw({
       rawItemId, topicId: <인물/karpathy>, pageTypeId: <인물 프로필>,
       title: "Karpathy",
       body: "... [LLM Wiki 가이드](/notes/8b3a-...-uuid) ...",
     })
  6. create_page_from_raw({
       rawItemId, topicId: <기술/llm-wiki>, pageTypeId: <가이드>,
       title: "LLM Wiki 가이드",
       body: "... 원작자 [Karpathy](/notes/c4f1-...-uuid) ...",
     })

9.3 사용 흐름 2 — 점검 후 정리

사용자: "이번 주에 정리한 거 한 번 점검해줘"

AI 흐름:
  1. lint_workspace()
       → broken_mentions / orphan_notes / note_conflicts
  2. 결과를 사용자에게 묶어서 보여주고 우선순위 묻기
  3. 사용자가 고른 항목별로:
       - broken: get_note(id) 후 mutate_blocks(op:'edit') 로 칩 교체
       - orphan: 토픽 / 페이지 타입 부여 — update_note({ topicId, pageTypeId })
       - conflict: 두 페이지를 비교해서 사용자에게 합칠지 분기 유지할지 질문
  4. 마지막에 update_workspace_overview 로 홈 인덱스 갱신

---