도구 레퍼런스

코멧 MCP가 AI 앱에 제공하는 도구 26개를 정리했습니다.
도구는 AI가 알아서 고르기 때문에 이름을 외울 필요는 없습니다. 다만 "검사만 해 줘", "저장하지 마" 처럼 원하는 범위를 알려 주면 AI가 더 정확하게 움직입니다.

묶음도구권한
계정과 환경whoami list_models list_storage list_usable_templates get_skill읽기
작품 읽기list_works get_work read_lorebook read_macro preview_work읽기
검사validate check_lorebook check_regex check_macro읽기
작품 전체 저장save_draft update_work저장
부분 수정로어북 3개, 로어북 트리거 3개, 매크로 3개, 시작 세션 1개저장

계정과 환경

whoami 연결된 계정 읽기 · works:read

연결된 코멧 계정의 닉네임과 허용된 권한을 확인합니다. 연결이 제대로 됐는지 볼 때 씁니다.
이메일, 전화번호, 사용자 ID 같은 개인정보는 돌려주지 않습니다.

list_models 모델 목록 읽기 · works:read

작품의 기본 모델로 쓸 수 있는 모델 목록입니다. 시네마챗은 canCinema가 true인 모델만 쓸 수 있고, 목록에 없는 모델을 넣으면 저장할 때 첫 번째 모델로 바뀝니다.

list_storage comet-storage 이미지 목록 읽기 · works:read

사이트에서 comet-storage 에 올려 둔 이미지를 경로순으로 50개씩 봅니다. 이미지마다 주소와 크기(가로·세로·용량)가 함께 옵니다.
작품에 넣을 이미지는 여기서 고른 주소나 그 작품에 이미 있던 이미지만 쓸 수 있습니다. MCP로 이미지를 새로 올리는 기능은 없습니다.

query string 경로·파일 이름에 이 글자가 들어간 이미지만 봅니다.
cursor string 다음 쪽을 볼 때 이전 응답의 nextCursor 를 넣습니다.
list_usable_templates 시네마챗에 쓸 수 있는 템플릿 읽기 · works:read

내가 만들었거나 구매한 템플릿과 그 변수 정보입니다. 시네마챗을 만들 때 어떤 템플릿을 쓸지, 시작 세션의 기본값에 어떤 변수가 필요한지 확인합니다.
변수마다 종류(global 전역변수, system 시스템 변수, userInput 유저 입력)와 AI가 대화 중에 값을 바꾸는지(auto)가 표시됩니다.
구매한 템플릿은 변수 정보만 보여 주고 스크립트·레이어는 보여 주지 않습니다.

get_skill 스킬 읽기 읽기 · works:read

AI가 작품을 쓰거나 고치기 전에 읽는 안내 문서(스킬) 를 가져옵니다. 코멧이 권장하는 작업 순서가 적혀 있어, AI는 작업을 시작할 때 맞는 스킬을 먼저 읽고 그대로 따릅니다.
지금은 작품을 읽고 고쳐 저장하는 기본 순서를 담은 workflow 스킬이 있습니다. 사용자가 따로 요청할 필요는 없습니다.

names string[] 필수 읽을 스킬 이름 (1~20개)

작품 읽기

list_works 내 작품 목록 읽기 · works:read

내가 만든 작품을 최근 수정순으로 20개씩 봅니다. 작품마다 ID, 제목, 공개 범위, 수정 시각이 옵니다. 구매하거나 공유받은 템플릿은 포함하지 않습니다.

kind template | novel | cinema 필수 볼 작품 종류
cursor string 다음 쪽을 볼 때 이전 응답의 nextCursor
get_work 작품 읽기 읽기 · works:read

내 작품 하나를 통째로 읽습니다. 응답에는 hash와 편집기로 바로 가는 editorUrl이 들어 있습니다.
2000자가 넘는 긴 칸은 앞 500자만 잘려서 오고(truncatedFields에 경로 표시), 필요한 칸만 fields로 전문을 다시 받습니다. 고치지 않을 긴 칸은 잘린 표시 그대로 저장 도구에 돌려주면 저장본 값이 유지됩니다.

kind template | novel | cinema 필수 작품 종류
id string 필수 작품 ID (list_works 결과)
format ai | stored 기본값 ai
fields string[] 전문을 받을 칸의 경로 (최대 20개). 예: rawNovel.prompt, rawNovel.lorebooks.0.content
read_lorebook 로어북 읽기 읽기 · works:read

작품 전체를 읽지 않고 로어북만 봅니다. index 없이 부르면 번호·제목·내용 길이·트리거 수만 담긴 목록이, index를 주면 그 로어북 하나의 전문과 트리거가 옵니다.
응답의 hash는 로어북·트리거 부분 수정 도구의 baseHash로 씁니다.

kind novel | cinema 필수 작품 종류
id string 필수 작품 ID
index number 읽을 로어북 번호 (0부터). 생략하면 목록
read_macro 매크로 읽기 읽기 · works:read

노벨챗의 매크로만 봅니다. index 없이 부르면 목록이 오는데, 40자가 넘는 칸은 앞 40자만 보여 주고 전체 길이를 cut에 적어 줍니다. index를 주면 그 매크로 하나의 전문이 옵니다.
매크로는 노벨챗에만 있어 kind를 받지 않습니다.

id string 필수 노벨챗 ID
index number 읽을 매크로 번호 (0부터). 생략하면 목록
preview_work 작품 미리보기 읽기 · works:read

작품을 사이트 편집기 미리보기와 같은 모양으로 채팅 안에 띄웁니다. id나 work 중 하나는 있어야 하고, 둘 다 주면 그 작품을 고친 초안으로 보고 그립니다.
화면을 띄우지 못하는 앱에서는 첫 화면의 글과 경고(찾지 못한 이미지, 자리 표시로 나오는 외부 이미지, 남아 있는 검사 오류 수)를 글로 돌려줍니다. "보여 줘"처럼 직접 요청할 때만 씁니다.

kind template | novel | cinema 필수 작품 종류
id string 저장된 작품 ID
work object 저장 전 초안
format ai | stored work 의 형식. 기본값 ai
session 0 ~ 9 보여 줄 시작 세션 번호 (기본 0)

검사

검사 도구는 아무것도 저장하지 않습니다. 검사에 걸리는 것은 오류가 아니라 정상적인 결과로, AI가 목록을 보고 고친 뒤 다시 검사합니다.

validate 저장 전 검사 읽기 · works:read

저장하지 않고, 사이트에 저장할 때와 같은 검사를 돌립니다. 걸린 항목이 최대 50개까지 한 번에 오므로 한꺼번에 고친 뒤 다시 검사합니다.
id를 주면 그 작품을 수정하는 것으로 보고, 잘린 긴 칸을 저장본 값으로 채워 검사합니다. 이미지도 저장할 때와 같은 규칙(foreignimage)으로 함께 봅니다.
proMode가 true면 프로 모드에서만 쓸 수 있는 분량이라는 뜻입니다.

kind template | novel | cinema 필수 작품 종류
work object 필수 get_work 로 읽은 것과 같은 형식의 작품
id string 기존 작품을 고친 것이라면 그 ID
format ai | stored 기본값 ai
check_lorebook 로어북 검사 읽기 · works:read

로어북만 따로 검사합니다. 로어북 하나의 길이 상한은 시네마챗 5000자, 노벨챗 7500자(공백 제외)입니다. 트리거 정규식은 서버와 같은 RE2 엔진으로 판정하므로 역참조·전후방 탐색은 쓸 수 없습니다.

kind cinema | novel 필수 로어북이 들어갈 작품 종류
lorebooks array 필수 로어북 배열 (최대 1000개)
check_regex 매크로 정규식 검사 읽기 · works:read

노벨챗 매크로의 정규식이 사이트에서 실행될 수 있는지 판정합니다. 문법 오류(invalid)나 백트래킹 위험(unsafe)이 있으면 사이트는 그 매크로를 건너뜁니다. 통과하면 캡처 그룹 수를 알려 줍니다.

patterns string[] 필수 검사할 정규식 (1~100개)
check_macro 매크로 실행 읽기 · works:read

노벨챗 매크로를 사이트 렌더러와 같은 순서로 텍스트에 적용해 봅니다. 단계마다 어떤 매크로가 적용됐고 결과가 어떻게 바뀌었는지, 건너뛴 매크로는 왜 건너뛰었는지 보여 주므로 매크로 순서 문제를 찾을 때 유용합니다.
실행이 1초를 넘으면 timeout으로 중단합니다.

macros array 필수 적용할 매크로 (최대 100개)
text string 필수 시험할 텍스트 (최대 10000자)
user string {user} 자리에 넣을 이름

작품 전체 저장

save_draft 새 작품 초안 저장 저장 · works:draft

새 작품을 비공개 초안으로 저장합니다. 공개 범위는 항상 비공개, 썸네일은 "MCP 초안" 이미지로 고정됩니다.
저장 전에 검사를 돌려, 걸리면 저장하지 않고 오류 목록을 돌려줍니다. 저장되면 새 작품의 ID와 hash, editorUrl이 옵니다.

kind template | novel | cinema 필수 작품 종류
work object 필수 작품 내용
format ai | stored 기본값 ai
idempotencyKey string 재시도해도 한 번만 저장되게 하는 키
update_work 작품 수정 저장 저장 · works:draft

내 작품을 고친 내용으로 통째로 저장합니다. 그사이 편집기나 다른 앱에서 작품이 바뀌었다면 덮어쓰지 않고 conflict로 멈춥니다.
공개 중인 작품(공개·링크 공개)은 저장하는 순간 플레이어에게 보이므로, AI가 먼저 확인을 받은 뒤 저장합니다. 공개 범위·썸네일·가격은 보내도 바뀌지 않습니다.
저장하면 바뀌기 전 상태(before)가 첨부 파일로 함께 돌아오므로 되돌릴 수 있습니다.

kind template | novel | cinema 필수 작품 종류
id string 필수 고칠 작품 ID
work object 필수 고친 작품 전체
baseHash string 필수 get_work(또는 직전 저장)의 hash
confirmLive boolean 공개 중인 작품이면 사용자 확인 뒤 true
format ai | stored 기본값 ai
idempotencyKey string 재시도용 키

부분 수정

로어북·트리거·매크로·시작 세션을 번호로 하나씩 고치는 도구입니다. 작품 전체를 주고받지 않아 빠르고, 긴 작품에서 다른 부분을 실수로 건드릴 일이 없습니다.
저장 과정은 update_work와 같습니다. 저장 전에 작품 전체를 검사하고, 읽은 뒤에 작품이 바뀌었으면 conflict, 공개 중이면 확인(needsconfirm)을 거칩니다.

로어북

add_lorebook 로어북 추가 저장 · works:draft

로어북 하나를 원하는 자리에 넣어 저장합니다.

lorebook object 필수 title, content, useDefault, triggers(생략하면 없음)
after number 이 번호 뒤에 넣습니다.
edit_lorebook 로어북 수정 저장 · works:draft

로어북 하나에서 준 칸만 바꿔 저장합니다. triggers를 주면 그 로어북의 트리거 전체가 바뀌므로, 트리거 하나만 고칠 때는 edit_lorebook_trigger를 씁니다.

index number 필수 고칠 로어북 번호
lorebook object 필수 바꿀 칸만: title, content, useDefault, triggers
delete_lorebook 로어북 삭제 저장 · works:draft

로어북 하나를 빼고 저장합니다. 뒤 로어북의 번호가 하나씩 당겨집니다.

index number 필수 뺄 로어북 번호

로어북 트리거

트리거는 종류(keyword 키워드, regex 정규식, turn 턴, dice 주사위)와 동작(apply 적용, pass 통과, block 차단)으로 이루어집니다.
키워드·정규식은 keyword와 감지 범위(watchUserChat, watchPrevChat)를, 턴·주사위는 from·to·remainder(주사위는 diceIndex도)를 씁니다.

add_lorebook_trigger 로어북 트리거 추가 저장 · works:draft

로어북 하나에 트리거를 추가해 저장합니다. 트리거는 위에서부터 순서대로 판정되므로 넣는 자리가 중요합니다.

lorebook number 필수 트리거를 넣을 로어북 번호
trigger object 필수 type, action 과 그 종류에 필요한 칸
after number 이 번호 뒤에 넣습니다.
edit_lorebook_trigger 로어북 트리거 수정 저장 · works:draft

트리거 하나에서 준 칸만 바꿔 저장합니다.

lorebook number 필수 로어북 번호
index number 필수 고칠 트리거 번호
trigger object 필수 바꿀 칸만. 종류를 바꾸면 그 종류에 필요한 칸도 함께
delete_lorebook_trigger 로어북 트리거 삭제 저장 · works:draft

트리거 하나를 빼고 저장합니다.

lorebook number 필수 로어북 번호
index number 필수 뺄 트리거 번호

매크로 (노벨챗)

add_macro 매크로 추가 저장 · works:draft

노벨챗에 매크로 하나를 넣어 저장합니다. 매크로는 순서대로 적용되므로 넣는 자리에 따라 결과가 달라집니다.

macro object 필수 type(str_str | regex_str | regex_regex), from, to, prefix, suffix
after number 이 번호 뒤에 넣습니다.
edit_macro 매크로 수정 저장 · works:draft

매크로 하나에서 준 칸만 바꿔 저장합니다.

index number 필수 고칠 매크로 번호
macro object 필수 바꿀 칸만: type, from, to, prefix, suffix
delete_macro 매크로 삭제 저장 · works:draft

매크로 하나를 빼고 저장합니다. 뒤 매크로의 번호가 하나씩 당겨집니다.

index number 필수 뺄 매크로 번호

시작 세션

edit_start_session 시작 세션 수정 저장 · works:draft

시작 세션 하나에서 준 칸만 바꿔 저장합니다. 시네마챗의 defaults는 { 변수명: 처음 값 } 모양이고, 준 변수만 바뀝니다.
시작 세션을 새로 만들거나 지우는 것은 update_work로 합니다.

index number 필수 고칠 시작 세션 번호
session object 필수 바꿀 칸만. 노벨챗: sessionTitle, initDesc, initChat / 시네마챗: sessionTitle, initDesc, defaults, logs

저장 규칙 한눈에 보기

재시도와 중복 저장 방지

네트워크 문제로 AI 앱이 같은 저장을 다시 보내도 한 번만 저장되도록, 저장 도구는 idempotencyKey를 받습니다.
같은 키·같은 내용으로 24시간 안에 다시 부르면 첫 저장 결과를 그대로 돌려주고(replayed), 같은 키로 다른 내용을 보내면 거절합니다.

자주 보는 결과 코드

코드의미대처
notfound작품이 없거나 내 작품이 아님목록을 다시 확인합니다.
wrongkind내 작품이지만 종류가 다름알려 준 종류(kind)로 다시 부릅니다.
invalidinput매개변수가 올바르지 않음 (없는 번호, 잘못된 cursor 등)알려 준 칸(path)을 고칩니다.
conflict읽은 뒤에 작품이 바뀜다시 읽고 고친 내용을 다시 적용합니다.
needsconfirm공개 중인 작품이라 확인이 필요"바로 반영해도 돼"라고 답하면 저장합니다.
foreignimage허용되지 않은 이미지 주소comet-storage 이미지를 고르거나 편집기에서 올립니다.
nostoragecomet-storage 가 없음이미지 없이 저장하고 편집기에서 올립니다.
storageblockedcomet-storage 가 이용 정지 상태이미지를 쓸 수 없습니다.
truncatedneedsid잘린 긴 칸이 있는데 작품 ID 가 없음id를 함께 주거나 그 칸의 전문을 받아 넣습니다.
truncatedmismatch잘린 긴 칸이 저장본과 다름작품을 다시 읽습니다.
truncatedbadmarker잘린 칸 표시가 손상됨작품을 다시 읽습니다.
scripterror템플릿 스크립트를 블록으로 바꿀 수 없음알려 준 줄 번호의 구문을 고칩니다.
modelreplaced쓸 수 없는 모델이라 다른 모델로 저장됨 (경고)필요하면 모델을 다시 고릅니다.
timeout정규식·매크로 실행이 1초를 넘음백트래킹이 많은 정규식을 고치거나 텍스트를 줄입니다.
idempotencykeyreused같은 재시도 키로 다른 내용을 보냄새 저장에는 새 키를 씁니다.
idempotencyinprogress같은 저장을 처리하는 중잠시 후 다시 시도합니다.
ratelimited호출 한도 초과안내된 시간(초) 뒤에 다시 시도합니다.
internal서버 오류한 번 다시 시도하고, 계속되면 문의해 주세요.

검사 오류(validate)의 코드는 사이트 편집기에서 저장할 때 나오는 오류와 같습니다. 예를 들어 titletoolong(제목 20자 초과), lorebooktoolong(로어북 길이 초과), illegalregex(트리거 정규식 오류) 같은 식입니다.

↑↓ 이동 Enter 열기