구조화 파일 보호: 거부 메시지 읽는 법

한 줄로: MCP의 거부 메시지를 읽는 법입니다. 어떤 것은 「도구를 바꾸면 된다」, 어떤 것은 「플랜이 필요하다」, 어떤 것은 「끝까지 안 된다」는 뜻입니다.

이 글이 해결하는 문제

거부는 전부 벽처럼 보이지만 벽이 아닙니다. Slima의 MCP 오류는 일부러 서로 다른 코드를 달고 옵니다. 다음에 해야 할 일이 완전히 다르기 때문입니다. 어떤 때는 다른 도구를 쓰는 것이고, 어떤 때는 작가에게 앱에서 해 달라고 부탁하는 것이고, 어떤 때는 구독입니다. 이걸 구분하지 못하는 AI는 가장 나쁜 선택을 합니다. 똑같은 호출을 한 번 더 보내는 것입니다.

구조화 파일을 왜 막아 두었는가

앱 안의 AI 코치가 .beats 파일에 통째 쓰기를 겨누면 프런트엔드가 곧바로 막습니다. 대가는 헛수고한 호출 한 번입니다.

MCP를 통하면 다릅니다. 같은 쓰기가 성공해 버립니다. .beats 한 장에는 막과 비트, 그리고 작가가 끌어다 놓은 챕터 카드가 들어 있습니다. AI는 그중 일부만 보고 문서 전체를 돌려보냅니다. 파일은 멀쩡히 열리고, 작가의 작업 한 덩어리가 사라져 있고, 오류는 하나도 나지 않았습니다.

그래서 이 관문은 도구 설명에만 적힌 것이 아니라 서버에 놓여 있습니다. 설명은 모델에게 주는 권고이고, 서버의 거부는 보장입니다.

만나게 될 네 가지 거부

오류 코드	상태	뜻	다음에 할 일
AI_READONLY_FILE_TYPE	403	이 종류는 AI가 통째로 쓸 수 있는 종류가 아닙니다	구조화 파일 다섯 종류라면 메시지가 대신 쓸 update_* 도구를 알려 줍니다. .character / .location / .json / .yaml은 대체 경로가 없습니다. 읽고 나서 권하는 변경을 말로 설명하십시오
SUBSCRIPTION_REQUIRED	403	이 기능은 구독 플랜에 속합니다	읽기는 제한되지 않습니다. 파일을 읽고 무엇을 어떻게 바꾸면 좋을지 분명히 말하십시오. 작가가 직접 고치거나, 구독한 뒤 AI에게 맡길 수 있습니다
INVALID_PATH	400	예전 시나리오 스튜디오 작품에서 기획 폴더 밖에 쓰려고 했습니다	.script_studio/planning/ 아래에 쓰거나 작가에게 넘기십시오
FOLDER_NOT_EMPTY	422	지우려는 폴더 안에 아직 내용물이 있습니다	정말 하위 전체를 지울 생각이라면 recursive: true를 붙여 다시 보내십시오. 권한 문제가 아니라 「말한 것보다 요청한 범위가 크다」는 문제입니다

두 개의 403이 서로 다른 코드를 쓰는 것은 의도된 설계입니다. 한쪽은 「업그레이드하면 열린다」이고 다른 쪽은 「무엇으로도 열리지 않는다」입니다. 코드가 하나였다면 AI는 구독을 언급해야 할지, 아니면 그만 조르고 말로 설명하는 쪽으로 돌아서야 할지 구분할 수 없습니다.

거부 메시지 자체가 답입니다

Slima의 MCP 오류는 AI가 추측하지 않고 메시지만 읽고 고칠 수 있도록 쓰여 있습니다.

• 없는 id를 보냈다 → 메시지가 진짜 id를 전부 나열합니다
• 없는 장소 계층을 보냈다 → 메시지가 진짜 계층을 나열합니다
• B 작업의 필드를 A 작업에 넣었다 → 메시지가 그 필드가 어느 작업의 것인지 알려 줍니다
• 가이드 slug를 잘못 짚었다 → 응답에 가이드 전체 목록이 붙어 옵니다
• intent가 너무 길다 → 그 값이 커밋 이름이 되므로 한 줄이어야 한다고 설명해 줍니다

이 관문이 하지 않는 일

• 파일을 읽기 전용으로 만들지 않습니다. 작가는 앱에서 얼마든지 고칩니다. 이것이 막는 것은 외부에서 오는 통째 쓰기뿐입니다.
• 읽기를 제한하지 않습니다. 구조화 파일 다섯 종류는 어떤 계정에서도 읽힙니다.
• 새로 만드는 것을 막지 않습니다. create_file은 그 확장자에도 동작합니다. 내용이 무시되고 서버가 빈 골격을 쓸 뿐입니다.
• 검토 단계가 아닙니다. MCP로 들어온 변경은 점선 카드 검토를 건너뜁니다. 하지만 그것들은 커밋입니다. 버전 기록에서 전부 보이고 전부 되돌릴 수 있습니다.

삭제는 쓰기와 같은 규칙입니다

.map을 지우는 일과 .map을 고치는 일에는 같은 기준이 적용됩니다. 둘 다 구독 플랜에 속합니다. 규칙이 하나면 외우기 쉽고, 실제로 우스운 상황 하나를 막아 줍니다. 무료 계정의 에이전트가 자기가 만들지도 고치지도 못하는 파일을 지우는 상황 말입니다.

예전 시나리오 스튜디오 작품

그런 작품이 아직 남아 있다면 별도의 규칙 체계를 따릅니다. 기준은 경로입니다. 쓸 수 있는 영역은 .script_studio/planning/ 트리뿐이고, series.json, *.character, *.scene, *.storyline, *.note, *.location은 MCP에서 전부 읽기 전용입니다. .script_studio/planning/.initialized 표식 파일도 마찬가지입니다.

그 planning 트리는 AI의 초안이 있어야 할 자리입니다. 시놉시스, 조사 메모, 제안서 같은 것들 말입니다. 신 자체를 고치고 싶다면 제안을 거기에 써 두고, 작가가 앱에서 반영하게 하십시오. 개별 작품의 정확한 규칙은 slima://books/{book_token}/schema 리소스를 읽으면 됩니다. schema 리소스로 정확한 권한 확인하기를 보십시오.

관련 문서

• Docs: 구조화 편집 도구
• Docs: MCP가 파일 종류별로 할 수 있는 일
• Docs: 쓰기가 거부될 때
• Docs: schema 리소스로 정확한 권한 확인하기