코멧 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개 | 저장 |
계정과 환경
연결된 코멧 계정의 닉네임과 허용된 권한을 확인합니다. 연결이 제대로 됐는지 볼 때 씁니다.
이메일, 전화번호, 사용자 ID 같은 개인정보는 돌려주지 않습니다.
작품의 기본 모델로 쓸 수 있는 모델 목록입니다. 시네마챗은 canCinema가 true인 모델만 쓸 수 있고, 목록에 없는 모델을 넣으면 저장할 때 첫 번째 모델로 바뀝니다.
사이트에서 comet-storage 에 올려 둔 이미지를 경로순으로 50개씩 봅니다. 이미지마다 주소와 크기(가로·세로·용량)가 함께 옵니다.
작품에 넣을 이미지는 여기서 고른 주소나 그 작품에 이미 있던 이미지만 쓸 수 있습니다. MCP로 이미지를 새로 올리는 기능은 없습니다.
내가 만들었거나 구매한 템플릿과 그 변수 정보입니다. 시네마챗을 만들 때 어떤 템플릿을 쓸지, 시작 세션의 기본값에 어떤 변수가 필요한지 확인합니다.
변수마다 종류(global 전역변수, system 시스템 변수, userInput 유저 입력)와 AI가 대화 중에 값을 바꾸는지(auto)가 표시됩니다.
구매한 템플릿은 변수 정보만 보여 주고 스크립트·레이어는 보여 주지 않습니다.
AI가 작품을 쓰거나 고치기 전에 읽는 안내 문서(스킬) 를 가져옵니다. 코멧이 권장하는 작업 순서가 적혀 있어, AI는 작업을 시작할 때 맞는 스킬을 먼저 읽고 그대로 따릅니다.
지금은 작품을 읽고 고쳐 저장하는 기본 순서를 담은 workflow 스킬이 있습니다. 사용자가 따로 요청할 필요는 없습니다.
작품 읽기
내가 만든 작품을 최근 수정순으로 20개씩 봅니다. 작품마다 ID, 제목, 공개 범위, 수정 시각이 옵니다. 구매하거나 공유받은 템플릿은 포함하지 않습니다.
내 작품 하나를 통째로 읽습니다. 응답에는 hash와 편집기로 바로 가는 editorUrl이 들어 있습니다.
2000자가 넘는 긴 칸은 앞 500자만 잘려서 오고(truncatedFields에 경로 표시), 필요한 칸만 fields로 전문을 다시 받습니다. 고치지 않을 긴 칸은 잘린 표시 그대로 저장 도구에 돌려주면 저장본 값이 유지됩니다.
작품 전체를 읽지 않고 로어북만 봅니다. index 없이 부르면 번호·제목·내용 길이·트리거 수만 담긴 목록이, index를 주면 그 로어북 하나의 전문과 트리거가 옵니다.
응답의 hash는 로어북·트리거 부분 수정 도구의 baseHash로 씁니다.
노벨챗의 매크로만 봅니다. index 없이 부르면 목록이 오는데, 40자가 넘는 칸은 앞 40자만 보여 주고 전체 길이를 cut에 적어 줍니다. index를 주면 그 매크로 하나의 전문이 옵니다.
매크로는 노벨챗에만 있어 kind를 받지 않습니다.
작품을 사이트 편집기 미리보기와 같은 모양으로 채팅 안에 띄웁니다. id나 work 중 하나는 있어야 하고, 둘 다 주면 그 작품을 고친 초안으로 보고 그립니다.
화면을 띄우지 못하는 앱에서는 첫 화면의 글과 경고(찾지 못한 이미지, 자리 표시로 나오는 외부 이미지, 남아 있는 검사 오류 수)를 글로 돌려줍니다. "보여 줘"처럼 직접 요청할 때만 씁니다.
검사
검사 도구는 아무것도 저장하지 않습니다. 검사에 걸리는 것은 오류가 아니라 정상적인 결과로, AI가 목록을 보고 고친 뒤 다시 검사합니다.
저장하지 않고, 사이트에 저장할 때와 같은 검사를 돌립니다. 걸린 항목이 최대 50개까지 한 번에 오므로 한꺼번에 고친 뒤 다시 검사합니다.
id를 주면 그 작품을 수정하는 것으로 보고, 잘린 긴 칸을 저장본 값으로 채워 검사합니다. 이미지도 저장할 때와 같은 규칙(foreignimage)으로 함께 봅니다.
proMode가 true면 프로 모드에서만 쓸 수 있는 분량이라는 뜻입니다.
로어북만 따로 검사합니다. 로어북 하나의 길이 상한은 시네마챗 5000자, 노벨챗 7500자(공백 제외)입니다. 트리거 정규식은 서버와 같은 RE2 엔진으로 판정하므로 역참조·전후방 탐색은 쓸 수 없습니다.
노벨챗 매크로의 정규식이 사이트에서 실행될 수 있는지 판정합니다. 문법 오류(invalid)나 백트래킹 위험(unsafe)이 있으면 사이트는 그 매크로를 건너뜁니다. 통과하면 캡처 그룹 수를 알려 줍니다.
노벨챗 매크로를 사이트 렌더러와 같은 순서로 텍스트에 적용해 봅니다. 단계마다 어떤 매크로가 적용됐고 결과가 어떻게 바뀌었는지, 건너뛴 매크로는 왜 건너뛰었는지 보여 주므로 매크로 순서 문제를 찾을 때 유용합니다.
실행이 1초를 넘으면 timeout으로 중단합니다.
작품 전체 저장
새 작품을 비공개 초안으로 저장합니다. 공개 범위는 항상 비공개, 썸네일은 "MCP 초안" 이미지로 고정됩니다.
저장 전에 검사를 돌려, 걸리면 저장하지 않고 오류 목록을 돌려줍니다. 저장되면 새 작품의 ID와 hash, editorUrl이 옵니다.
내 작품을 고친 내용으로 통째로 저장합니다. 그사이 편집기나 다른 앱에서 작품이 바뀌었다면 덮어쓰지 않고 conflict로 멈춥니다.
공개 중인 작품(공개·링크 공개)은 저장하는 순간 플레이어에게 보이므로, AI가 먼저 확인을 받은 뒤 저장합니다. 공개 범위·썸네일·가격은 보내도 바뀌지 않습니다.
저장하면 바뀌기 전 상태(before)가 첨부 파일로 함께 돌아오므로 되돌릴 수 있습니다.
부분 수정
로어북·트리거·매크로·시작 세션을 번호로 하나씩 고치는 도구입니다. 작품 전체를 주고받지 않아 빠르고, 긴 작품에서 다른 부분을 실수로 건드릴 일이 없습니다.
저장 과정은 update_work와 같습니다. 저장 전에 작품 전체를 검사하고, 읽은 뒤에 작품이 바뀌었으면 conflict, 공개 중이면 확인(needsconfirm)을 거칩니다.
로어북
로어북 하나를 원하는 자리에 넣어 저장합니다.
로어북 하나에서 준 칸만 바꿔 저장합니다. triggers를 주면 그 로어북의 트리거 전체가 바뀌므로, 트리거 하나만 고칠 때는 edit_lorebook_trigger를 씁니다.
로어북 하나를 빼고 저장합니다. 뒤 로어북의 번호가 하나씩 당겨집니다.
로어북 트리거
트리거는 종류(keyword 키워드, regex 정규식, turn 턴, dice 주사위)와 동작(apply 적용, pass 통과, block 차단)으로 이루어집니다.
키워드·정규식은 keyword와 감지 범위(watchUserChat, watchPrevChat)를, 턴·주사위는 from·to·remainder(주사위는 diceIndex도)를 씁니다.
로어북 하나에 트리거를 추가해 저장합니다. 트리거는 위에서부터 순서대로 판정되므로 넣는 자리가 중요합니다.
트리거 하나에서 준 칸만 바꿔 저장합니다.
트리거 하나를 빼고 저장합니다.
매크로 (노벨챗)
노벨챗에 매크로 하나를 넣어 저장합니다. 매크로는 순서대로 적용되므로 넣는 자리에 따라 결과가 달라집니다.
매크로 하나에서 준 칸만 바꿔 저장합니다.
매크로 하나를 빼고 저장합니다. 뒤 매크로의 번호가 하나씩 당겨집니다.
시작 세션
시작 세션 하나에서 준 칸만 바꿔 저장합니다. 시네마챗의 defaults는 { 변수명: 처음 값 } 모양이고, 준 변수만 바뀝니다.
시작 세션을 새로 만들거나 지우는 것은 update_work로 합니다.
저장 규칙 한눈에 보기
재시도와 중복 저장 방지
네트워크 문제로 AI 앱이 같은 저장을 다시 보내도 한 번만 저장되도록, 저장 도구는 idempotencyKey를 받습니다.
같은 키·같은 내용으로 24시간 안에 다시 부르면 첫 저장 결과를 그대로 돌려주고(replayed), 같은 키로 다른 내용을 보내면 거절합니다.
자주 보는 결과 코드
| 코드 | 의미 | 대처 |
|---|---|---|
notfound | 작품이 없거나 내 작품이 아님 | 목록을 다시 확인합니다. |
wrongkind | 내 작품이지만 종류가 다름 | 알려 준 종류(kind)로 다시 부릅니다. |
invalidinput | 매개변수가 올바르지 않음 (없는 번호, 잘못된 cursor 등) | 알려 준 칸(path)을 고칩니다. |
conflict | 읽은 뒤에 작품이 바뀜 | 다시 읽고 고친 내용을 다시 적용합니다. |
needsconfirm | 공개 중인 작품이라 확인이 필요 | "바로 반영해도 돼"라고 답하면 저장합니다. |
foreignimage | 허용되지 않은 이미지 주소 | comet-storage 이미지를 고르거나 편집기에서 올립니다. |
nostorage | comet-storage 가 없음 | 이미지 없이 저장하고 편집기에서 올립니다. |
storageblocked | comet-storage 가 이용 정지 상태 | 이미지를 쓸 수 없습니다. |
truncatedneedsid | 잘린 긴 칸이 있는데 작품 ID 가 없음 | id를 함께 주거나 그 칸의 전문을 받아 넣습니다. |
truncatedmismatch | 잘린 긴 칸이 저장본과 다름 | 작품을 다시 읽습니다. |
truncatedbadmarker | 잘린 칸 표시가 손상됨 | 작품을 다시 읽습니다. |
scripterror | 템플릿 스크립트를 블록으로 바꿀 수 없음 | 알려 준 줄 번호의 구문을 고칩니다. |
modelreplaced | 쓸 수 없는 모델이라 다른 모델로 저장됨 (경고) | 필요하면 모델을 다시 고릅니다. |
timeout | 정규식·매크로 실행이 1초를 넘음 | 백트래킹이 많은 정규식을 고치거나 텍스트를 줄입니다. |
idempotencykeyreused | 같은 재시도 키로 다른 내용을 보냄 | 새 저장에는 새 키를 씁니다. |
idempotencyinprogress | 같은 저장을 처리하는 중 | 잠시 후 다시 시도합니다. |
ratelimited | 호출 한도 초과 | 안내된 시간(초) 뒤에 다시 시도합니다. |
internal | 서버 오류 | 한 번 다시 시도하고, 계속되면 문의해 주세요. |
검사 오류(validate)의 코드는 사이트 편집기에서 저장할 때 나오는 오류와 같습니다. 예를 들어 titletoolong(제목 20자 초과), lorebooktoolong(로어북 길이 초과), illegalregex(트리거 정규식 오류) 같은 식입니다.