DEV Community

Cover image for Claude가 osFoundry 노트에서 슬라이드 탭을 헷갈리지 않고 출처도 두 번 안 넣는 원리, 파이썬으로 다시 만들어 봤다
BBT for BBT 한국어

Posted on

Claude가 osFoundry 노트에서 슬라이드 탭을 헷갈리지 않고 출처도 두 번 안 넣는 원리, 파이썬으로 다시 만들어 봤다

osFoundry 공개 MCP 엔드포인트에 인증 없이 tools/list를 찔러 보면(2026-11-09) 노트에 탭을 만드는 tool이 이렇게 나온다. 필요한 필드만 남겼다.

{"name": "create_note_tab",
 "description": "Create a new Slides or Sheet tab in an approved Note. Use the version from list_note_tabs; returns the exact new tab ID for later edits. An optional outline fills a Slides tab. A repeated idempotency key returns the first tab.",
 "inputSchema": {
   "required": ["note_id", "expected_version", "idempotency_key", "tab_type"],
   "properties": {
     "tab_type": {"enum": ["slides", "sheet"]},
     "label": {"type": "string"},
     "slides": {"type": "array", "minItems": 1, "maxItems": 20,
                "items": {"required": ["title"], "additionalProperties": false,
                          "properties": {"title": {}, "body": {}, "notes": {}}}}},
   "additionalProperties": false},
 "annotations": {"readOnlyHint": false, "destructiveHint": true},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}
Enter fullscreen mode Exit fullscreen mode

같이 쓰는 tool 두 개도 붙여 둔다.

{"name": "add_note_source",
 "description": "Add an HTTP or HTTPS citation to the Sources tab of an approved Note. Uses the Note version and an idempotency key; returns the new source ID.",
 "inputSchema": {"required": ["note_id", "expected_version", "idempotency_key", "title", "url"]}}

{"name": "list_note_tabs",
 "description": "List every tab instance and its type. A Note may have multiple Slides or Sheet tabs; use the exact tab ID returned here."}
Enter fullscreen mode Exit fullscreen mode

핵심 문장은 세 개다. "every tab instance", "returns the exact new tab ID", "a repeated idempotency key returns the first". 이 글에서는 이 tool들을 파이썬으로 작게 다시 만들고, 문장 하나하나가 뭘 막아 주는지 숫자로 세 봤다. 노트 버전 기반 낙관적 락은 다른 글에서 다뤘으니 여기선 탭 ID나 멱등 키랑 얽히는 부분에서만 나온다.

Claude는 슬라이드에 뭘 쓸 수 있나

데스크톱 앱 안의 어시스턴트보다 훨씬 적다. osFoundry 안에서는 노트용 slide_create_deck_from_outline, slide_add_slide(apps/web/src/screens/notes/lib/note-surface-tools.ts)가 레이아웃, 불릿, 2단 구성, 표, 이미지, 테마 5종까지 받는다. 반면 커넥터 쪽 아웃라인 한 장은 title, body, notes가 전부고 additionalProperties: false로 막혀 있다. edit_note_tab에는 한 장 넣는 slide_add와 배열로 넣는 slides_add_outline이 있는데 둘 다 같은 세 필드다.

code/note_store.py는 저장해 둔 tools/list 응답을 읽어서 required, enum, additionalProperties, minItems/maxItems만 보는 간이 validator로 페이로드를 검사한다. 모델이 보낼 법한 8가지를 넣어 봤다.

edit_note_tab    {"operation": "slide_add", "title": "Sources", "body": "3 links"}  -> ok
edit_note_tab    {"operation": "slide_add", "title": "Sources", "index": 0}         -> unexpected index
edit_note_tab    {"operation": "slides_add", "slides": [{"title": "a"}]}            -> operation: not in enum
edit_note_tab    {"operation": "slides_add_outline", "slides": [{... "bullets"}]}   -> slides: [0] unexpected bullets
create_note_tab  {"tab_type": "slides", "slides": "[21 items]"}                     -> slides: maxItems 20
create_note_tab  {"tab_type": "markdown"}                                           -> tab_type: not in enum
add_note_source  {"url": "https://example.org/report"}                              -> missing title
list_note_attachments {"kind": "sources", "limit": 100}                             -> ok
Enter fullscreen mode Exit fullscreen mode

마지막 건 간이 validator는 통과하지만 진짜 스키마에는 limit의 maximum: 50이 있어서 걸린다(다시 만든 쪽은 maximum을 안 본다). slide_add는 위치를 못 고르고, create_note_tab으로 Markdown 탭은 못 만들고, 21장 넘는 덱은 한 번에 못 보낸다. 스키마를 좁힌 건 덱 디자인을 누가 맡느냐의 선 긋기다. 커넥터는 내용을 쓰고, 테마와 레이아웃은 데스크톱 앱에서 사람이 입힌다.

왜 "슬라이드 탭"이 아니라 정확한 탭 ID일까

데스크톱 앱 자체가 아직 그 축약형을 받아 주고, 게다가 처음 맞는 걸 집어 오기 때문이다. apps/web/src/screens/notes/types.ts의 resolveTabInstanceId():

if (cfg.some((t) => t.id === rawTabId)) return rawTabId
const byType = cfg.find((t) => t.type === rawTabId)
if (byType) return byType.id
Enter fullscreen mode Exit fullscreen mode

이 fallback은 …/slides 같은 옛 링크를 살리려고 있는 거다. 에이전트 입장에서 보면 "슬라이드 편집"은 탭 줄에서 맨 앞에 있는 Slides 탭으로 간다는 뜻이다. 새 탭은 NotesContentPanel.tsx의 nextTabId()가 slides-9-mh8z1k2a 같은 ID를 붙이고, 고정 탭은 markdown, files, sources다. 사람은 Slides 탭을 몇 개든 추가하고, 드래그로 순서를 바꾸고, 이름도 바꿀 수 있다. handleRename은 앞뒤 공백만 자르니까 같은 이름 탭도 생긴다.

재현은 이렇게 했다. 노트에 라벨이 다른 Slides 탭을 K개 둔다. 스크립트 에이전트가 탭 목록을 받아 덱 하나를 목표로 정하고, 그걸 가리키는 손잡이를 들고 있는다. 손잡이는 네 종류다. 탭 줄에서의 위치, 타입, 라벨, ID. 에이전트의 다음 턴 전까지 사람이 탭 줄을 0~2번 랜덤하게 건드린다(이동 40%, Slides 탭을 라벨 5개 중 하나로 이름 변경 35%, Slides 탭 추가 25%). 그다음 에이전트가 목록을 다시 받아서 손잡이로 탭을 찾는다. K마다 10,000번, seed 7.

덱 수 K 손잡이 맞음 다른 덱 못 찾음
2 위치 83.7% 16.3% 0.0%
2 타입 50.7% 49.3% 0.0%
2 라벨 85.6% 2.1% 12.3%
2 ID 100% 0 0
5 위치 82.7% 17.3% 0.0%
5 타입 19.7% 80.3% 0.0%
5 라벨 92.1% 3.0% 5.0%
5 ID 100% 0 0

타입으로 찾으면 1/K만 맞는다. 예상대로다. 위치는 드래그가 목표 탭을 넘어가는 순간 틀리고 K랑은 거의 상관없다. 삽질 포인트는 라벨이다. 사람이 프롬프트에 쓰는 게 탭 이름이라 쓰고 싶어지고, 대부분은 맞는다. 근데 틀리는 2~3%가 제일 질이 나쁘다. 다른 덱이 그 라벨을 달고 있고, 에이전트는 에러 하나 없이 거기에 쓴다. "못 찾음"은 오히려 안전한 실패다. ID는 한 번 붙으면 재사용되지 않으니까 탭 줄에서 사람이 뭘 해도 같은 탭을 가리킨다.

버전 체크가 다른 탭에 쓰는 걸 막아 주지 않나

안 막는다. 위의 조작은 전부 노트 버전을 올리니까 오래된 버전으로 보낸 쓰기는 거절되고, 에이전트는 목록을 다시 받는다. 다시 받으면 버전은 최신이 되고, 그 상태에서 옛 손잡이를 새 목록에 대 본다. 재현에서는 엉뚱한 덱을 노린 것까지 포함해서 이런 쓰기 100%가 버전 체크를 통과했다. 버전이 증명하는 건 "최신 노트를 봤다"까지다. "그 안에서 맞는 탭을 찾았다"는 탭 ID가 맡는다.

멱등 키 확인은 버전 체크 앞일까 뒤일까

앞이어야 tool 설명의 약속이 지켜진다. 한 번 실행에 create_note_tab을 50번 부르고, 서버가 커밋한 뒤의 응답을 30% 떨어뜨렸다. 클라이언트 입장에선 호스트 타임아웃이랑 똑같다. 클라이언트는 같은 호출을 다시 보낸다. 클라이언트 정책 3개 × 서버 확인 순서 2개, seed 1~3.

서버 확인 순서 클라이언트 키 정책 생긴 탭 수(보낸 호출 수)
키 → 버전 호출마다 새 키 63 (76) / 75 (100) / 62 (74)
키 → 버전 재전송엔 같은 키 50 (67) / 50 (81) / 50 (62)
키 → 버전 충돌 뒤엔 새 키 50 (67) / 50 (81) / 50 (62)
버전 → 키 호출마다 새 키 63 (76) / 75 (100) / 62 (74)
버전 → 키 재전송엔 같은 키 50 (79) / 50 (98) / 50 (72)
버전 → 키 충돌 뒤엔 새 키 72 (94) / 73 (96) / 61 (72)

재전송에는 날아간 커밋 이전의 버전이 들어 있다. 버전을 먼저 보는 서버는 이걸 오래됐다고 보고 첫 결과 대신 충돌을 돌려준다. 충돌을 받은 클라이언트가 상식대로 다시 읽고, 다음 시도를 새 의도로 보고 새 키를 붙이면 덱이 하나 더 생긴다. 키를 그대로 쓰는 클라이언트도 호출이 16~21% 늘어난다. 키를 먼저 보면 버전이 뭐든 재전송엔 처음 만든 탭 ID가 돌아온다. "A repeated idempotency key returns the first tab"은 그런 뜻이어야 한다.

add_note_source 키에는 뭘 넣어야 할까

조사 세션을 300번 돌렸다. 세션당 3턴, 턴마다 8페이지 중 6페이지를 인용하고, 같은 페이지가 7가지 표기 중 하나로 나온다. 끝 슬래시, www., ?utm_source=…, #fragment, http://, 스킴 없음, 원래 그대로. 응답은 20% 떨어뜨리고 같은 키로 재전송한다.

키 저장된 출처 중복 세션당
인용마다 새 UUID(재전송엔 재사용) 5,400 3,038 10.13
적힌 그대로의 URL 해시 4,814 2,452 8.17
정규화한 URL과 노트 ID의 해시 2,362 0 0.00

인용마다 UUID를 붙이면 응답 유실만 막는다. 첫 줄의 중복 중에 재전송 때문에 생긴 건 하나도 없다. 조사하다 보면 다음 턴에도 같은 페이지를 또 인용하고, 턴이 바뀌면 키도 바뀐다. 적힌 그대로의 URL 해시는 완전히 같은 반복은 잡지만 ?utm_source=나 끝 슬래시 차이는 못 잡는다. 중복이 0이 된 건 키에 "이 페이지는 이 노트의 출처다"라는 의도를 담았을 때다. note_id와 정규화한 URL(https, 소문자에 www. 뺀 호스트, fragment 없음, utm_* 없음, 끝 슬래시 없음)을 묶어서 해시한다.

데스크톱 앱의 출처 추가 폼도 가볍게 같은 일을 한다. NotesSourcesTab.tsx는 입력한 링크를 new URL(...)로 정규화하고, 이미 붙어 있으면 "This source is already attached"로 거절한다. 재현에서 브라우저식 href 비교를 걸면 첫 줄의 중복 3,038건 중 725건이 걸렸다. 커넥터의 add_note_source는 URL 중복 확인을 내세우지 않으니까, 에이전트 쪽에서 키로 표현하는 수밖에 없다. URL로 만든 키엔 부작용이 하나 있다. 같은 페이지를 더 나은 설명으로 다시 넣어도 첫 줄이 돌아온다. 고치는 건 Sources 탭에서 할 일이다.

아웃라인으로 한 번에 만들까, 한 장씩 넣을까

12장짜리 덱을 만드는 비용이다. 요청은 전부 진짜 스키마로 검증했다.

방식 쓰기 요청 바이트 덱당 충돌
slides를 넣은 create_note_tab 1 1,673 0.070
빈 탭 생성 + slide_add × 12 13 5,237 0.817

충돌 열은 모델이지 osFoundry를 잰 값이 아니다. 에이전트가 읽고 쓰기까지 4초, 사람이 노트 어딘가를 평균 1분에 한 번 저장(지수 분포), 덱 2,000개 시뮬레이션이다. 쓰기마다 노트 단위 버전이 움직일 수 있는 창이 하나씩 열리니까, 한 장씩 만들면 다시 읽기가 대략 12배가 된다. 덱은 아웃라인에 넣고(20장까지), 나중에야 알게 된 한 장만 slide_add로 넣는 게 낫다.

하나 더 세 둘 게 있다. list_note_attachments의 limit은 최대 50이라 출처가 120개인 노트는 목록을 받는 데 3번 걸린다.

재현 조건

이 맥에는 Claude 실행 파일이 없다. code/run.py가 에이전트 역할을 하면서 code/note_store.py를 직접 부른다. 저장소는 락 하나로 감싼 메모리 구현이고 버전은 카운터다. tool 이름, 필수 필드, enum, 개수 제한은 code/tools_list.raw에 저장한 진짜 스키마에서, 탭 ID 모양은 nextTabId()에서 가져왔다. 에러 모양, 키의 범위(여기선 노트 단위), 멱등 키 확인 순서는 재현 쪽 선택이고, 두 번째 확인 순서는 뭐가 깨지는지 보여 주려고만 넣었다. Python 3.9.6, Apple Silicon, 실험 다섯 개를 합쳐 실측 1.0초. 출력은 code/run.out에 있다.

직접 붙인다면 정해 둘 것

  • 목록과 생성 호출은 항상 인스턴스별 ID를 돌려주고, 편집 tool은 그 ID를 필수로 받는다. UI URL에서 타입이나 라벨을 받아 주더라도 쓰기 경로에서는 풀어 주지 않는다
  • 멱등 키는 버전보다 먼저 확인한다. 응답이 날아간 뒤의 재전송은 무조건 옛 버전을 들고 온다
  • 키가 뭘 나타내야 하는지 tool 설명에 적는다. 출처라면 "이 문서의 이 URL"을 정규화한 걸로 하면 턴을 넘는 중복도 사라진다. 랜덤 UUID가 막는 건 재전송뿐이다
  • 커넥터의 슬라이드 모양은 작게(제목, 본문, 노트) 두고 디자인은 에디터의 사람에게 맡긴다. 필드가 적으면 모델이 틀릴 곳도 적다
  • 아웃라인을 한 번에 보낼 수 있게 하고 상한을 둔다(osFoundry는 20). 쓰기가 줄면 공유 문서에서 충돌 창도 준다
  • 에이전트 경로로는 첨부 메타데이터만 주고, 내용이나 서명된 링크는 주지 않는다. 링크는 그걸 받아 간 세션보다 오래 산다

사람 쪽에서 Sources 탭에 뭐가 들어가는지는 Sources 탭 페이지에, 밑바탕 프로토콜 요약은 osFoundry의 MCP 용어 설명에 있다.

Top comments (0)