시나리오 스튜디오 툴별 제한 사항

시나리오 스튜디오 책에서는 두 가지 MCP 툴에 특정한 제한이 있습니다.

search_content: 구조화 파일은 기본 제외

시나리오 스튜디오 책에서 search_content 를 호출하면, 기본적으로 일반 마크다운만 검색합니다 — .scene / .character 같은 구조화 파일은 제외됩니다.

왜 그런가요

구조화 파일은 JSON 입니다. 텍스트 매칭이 실제 내용이 아니라 내부 스키마의 필드명에 걸리는 경우가 많습니다. 예를 들어 「name」을 검색하면 모든 *.character 파일의 name 필드가 전부 잡힙니다.

해결 방법

구조화 파일까지 포함하려면:

search_content({
  book_token: "...",
  query: "등대",
  include_structured: true
})

include_structured: true 를 붙이면 구조화 파일 안의 텍스트 속성까지 깊이 들어가서 검색합니다.

analyze_chapter: .scene 은 지원하지 않음

.scene 파일에 analyze_chapter 를 호출하면 → 400 UNSUPPORTED_FILE_TYPE 를 반환합니다.

왜 그런가요

analyze_chapter 는 서사 산문(소설 챕터)을 분석하도록 설계된 툴입니다. 씬 JSON 은 「챕터」가 아니므로 페이스, 문체, 대사 비트 같은 개념이 그대로 매핑되지 않습니다.

해결 방법

두 가지입니다.

1 · 씬 단위 분석을 활용하십시오

.scene 은 하나의 씬이고, 여러 씬이 모여 한 에피소드를 이룹니다. AI 툴은 씬 하나를 단위로 분석하며, 에피소드 전체를 한 번에 분석하는 툴은 아직 없습니다.

2 · 씬을 산문으로 변환하십시오

「이 씬의 감정 페이스」를 분석하고 싶다면:

1. 씬을 가져와서 → AI 에게 씬 JSON 을 마크다운 산문으로 다시 쓰게 합니다.
2. 그 산문에 analyze_chapter 를 실행합니다.

두 단계가 필요하지만, 목적은 달성할 수 있습니다.

파일당 토큰 제한

시나리오 파일은 분량이 길 수 있습니다 (스토리라인 하나가 수만 자에 달하기도 합니다) — read_file 에는 파일당 토큰 상한이 있습니다:

• 일반 마크다운: ~100K 토큰
• 구조화 파일: ~50K 토큰 (JSON 은 토큰을 더 많이 소모합니다)

상한을 넘으면 → 416 FILE_TOO_LARGE 와 함께 청크 분할(chunking) 권장 방안을 함께 반환합니다.

관련 문서

• 스튜디오별 MCP 동작
• 시나리오 스튜디오 구조 보호
• 파일 작업 툴