특정 파일에서 다르게 동작하는 도구들

한 줄로: 특정 파일이나 특정 작품에서 예상과 다르게 동작하는 도구들, 그리고 그 차이마다의 대처법입니다.

이 글이 해결하는 문제

대부분의 MCP 도구는 모든 파일을 똑같이 다룹니다. 아래 도구들은 그렇지 않습니다. 오류를 내지도 않습니다. 그냥 예상하지 못한 것을 돌려줍니다. 그리고 예상하지 못한 성공은 분명한 실패보다 알아채기가 훨씬 어렵습니다.

read_file: 두 종류는 다른 모습으로 돌아옵니다

.map 관계도는 원본 JSON으로 돌아옵니다. 노드 id, 픽셀 좌표, 그룹 구성원 목록입니다. 기술적으로는 문제없지만 실무에서는 쓸 만하지 않습니다. 대신 view_relationship_map을 쓰십시오. 그림 한 장과 함께 인물과 관계를 전부 나열한 요약을 돌려줍니다. AI에게 관계도를 보여주기를 보십시오.

.geomap 세계 지도는 세 장의 지형 격자가 한 줄 설명으로 바뀐 상태로 돌아옵니다. 잘려 나간 것이 아니라 의도된 동작입니다. 지형은 기계용 인코딩이라 읽을 것이 없고, 그것을 바꾸는 작업은 격자 칸 단위로 돌아갑니다.

search_content: 무엇이 걸리는지는 작품의 나이에 달렸습니다

4.0 작품에서는 모든 파일이 검색 대상이며, 구조화 파일의 원본 JSON도 포함됩니다. 그래서 name이나 title 같은 흔한 단어를 찾으면 필드 이름만 잔뜩 걸릴 수 있습니다. 산문만 보려면 file_types: ["md"]를 넘기십시오.

예전 시나리오 스튜디오 작품에서는 반대로 동작합니다. *.character, *.scene, *.storyline, *.note, *.location, 그리고 .script_studio/ 아래의 *.json이 기본적으로 제외됩니다. 그 원본 JSON은 전문 검색에서 잡음이기 때문입니다. 함께 검색하려면 include_structured: true를 넘기십시오.

semantic_search: 커밋된 것만 봅니다

의미 검색은 작품의 가장 최근 커밋 내용을 색인합니다. 작가가 조금 전 앱에서 타이핑하고 아직 커밋에 들어가지 않은 단락은 거기에 없습니다.

분량이 크고 한 번도 색인된 적 없는 작품은 백그라운드 작업으로 넘어가고, 그 검색은 빈 결과로 돌아옵니다. 「없다」가 아니라 「아직 만들어지지 않았다」입니다. 잠시 뒤 다시 검색하십시오. 자세한 내용은 의미 검색과 전문 검색에 있습니다.

analyze_chapter: 산문을 겨누고 구조화 파일은 겨누지 마십시오

예전 시나리오 스튜디오 작품은 아예 지원되지 않습니다. 호출은 그대로 거부되고, 앱 안의 분석 기능을 안내하는 메시지가 옵니다.

4.0 작품에서는 여러분이 알아서 조심해야 합니다. file_path를 .script나 .beats로 지정하는 것을 막는 장치는 없습니다. 그렇게 하면 독자에게 JSON 문서를 읽어 달라고 부탁하는 셈입니다. 시키는 대로 하기는 할 텐데, 리포트가 이상해집니다. AI 베타 리더는 .md 원고 파일을 겨누십시오.

get_writing_stats: 네 종류는 항상 0입니다

.map, .beats, .timeline, .geomap의 글자 수는 계약상 0으로 고정됩니다. 작가가 쓴 산문이 아니기 때문입니다. .script는 반대입니다. 신 안의 글자를 계산하고 일일 글자 수와 연속 기록에도 반영됩니다.

그래서 작가를 위해 연표를 정리해도 통계에 가짜 성과가 남지 않습니다. 한 화를 집필하면 남습니다.

create_file: 구조화 확장자 다섯 종류에서는 보낸 내용이 무시됩니다

서버가 빈 골격을 쓰고, 파일 이름이 문서의 제목이 되며, 응답에 내용이 교체됐다고 분명히 적혀 옵니다. 넣으려던 것은 update_* 배치로 채워 넣으십시오. 구조화 편집 도구를 보십시오.

delete_file: 빈 폴더가 아니면 소리 내어 말해야 합니다

내용물이 남은 폴더를 지우는 요청은 기본적으로 거부됩니다(FOLDER_NOT_EMPTY). 정말 하위 전체를 지울 생각이라면 recursive: true를 붙여 다시 보내십시오.

이 방어 장치가 있는 이유는 실제로 벌어진 사고 때문입니다. 폴더 행만 지우면 그 아래 파일이 전부 작품 최상단으로 흩어지는데, 서버는 200을 돌려줍니다.

get_chapter와 read_file: 경로를 안다면 뒤쪽을 쓰십시오

get_chapter는 파일 이름만 준 것도 받고(01장 - 필사 소녀.md) 불완전한 경로도 받습니다. 못 찾으면 실제로 있는 파일들을 나열해 주기까지 합니다. 대가는 조회 몇 번이 더 든다는 점입니다.

경로가 이미 확실하다면 read_file이 같은 일을 더 곧바로 해냅니다.

관련 문서

• Docs: 파일 조작 도구
• Docs: 의미 검색과 전문 검색
• Docs: AI에게 관계도를 보여주기
• Docs: MCP가 파일 종류별로 할 수 있는 일
• Docs: AI 베타 리더 도구