파일 조작 도구

한 줄로: 경로를 대상으로 동작하는 파일 도구 묶음의 참고서입니다. 읽기, 부분 수정, 통째 덮어쓰기, 새로 만들기, 삭제, 이어 붙이기, 검색.

이 글이 해결하는 문제

원고에 실제로 손을 대는 것이 이 묶음입니다. 공통점이 두 가지입니다. 전부 path를 받는다는 것, 그리고 쓰기 한 번이 커밋 하나를 만든다는 것입니다. 따로 저장하는 단계는 없고, 작가는 버전 기록에서 자기 커밋 옆에 나란히 놓인 여러분의 커밋을 봅니다.

도구	하는 일	인자
read_file	파일 하나 읽기	book_token, path
edit_file	한 대목을 찾아 바꾸기	path, old_string, new_string, replace_all?, commit_message?
write_file	파일 전체를 교체	path, content, commit_message?
create_file	새 파일 만들기	path, content?, content_type?, commit_message?
delete_file	파일이나 폴더 삭제	path, recursive?, commit_message?
append_to_file	파일 끝에 덧붙이기	path, content, commit_message?
search_content	전문 검색	query, file_types?, limit?, include_structured?

관계도를 「보는」 일은 다른 도구가 합니다. AI에게 관계도를 보여주기를 보십시오.

고쳐 쓸 때는 edit_file을 집으십시오

이 묶음에서 가장 많이 쓰는 도구이며, 작가가 같은 파일을 고치고 있을 때 덮어쓰지 않고 요란하게 실패해 주는 유일한 쓰기 방식입니다.

대조와 치환은 서버에서, 잠금 안에서 일어납니다. 그래서 응답이 알려 주는 치환 횟수는 로컬의 추측이 아니라 실제로 반영된 횟수입니다. 찾으려는 글이 없거나, 여러 번 나와서 어느 것인지 정할 수 없을 때는 호출이 실패하면서 다음에 할 일을 알려 줍니다. 같은 인자를 다시 보내지 말고 그 안내대로 하십시오.

replace_all의 기본값은 false이고, 첫 번째 자리만 바꿉니다. new_string에 빈 문자열을 넘기면 그 대목이 지워집니다.

write_file은 전부 갈아 끼웁니다

정말로 전면 재집필을 할 때 맞는 도구입니다. 작가가 조금 전에 타이핑한 것까지 함께 사라지므로, edit_file로 해낼 수 있는 일이라면 edit_file을 쓰십시오.

create_file: 글자 수에 잡히는지는 content_type이 정합니다

챕터를 쓴다면 content_type: "manuscript"를 넘기십시오. 지정하지 않으면 새 파일은 상위 폴더를 따라가고, 최상단에서는 reference가 기본값이 됩니다. 그 글자들은 작가의 글자 수와 연속 기록, 원고 내보내기에 들어가지 않습니다. 값은 manuscript, reference, character, location, storyline입니다.

경로 중간에 없는 폴더는 알아서 만들어지므로 디렉터리를 먼저 만드는 단계는 없습니다. 원고와 참고 자료를 보십시오.

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

내용물이 남은 폴더를 지우는 요청은 기본적으로 거부되고, 메시지가 안에 몇 개가 있는지 알려 줍니다. 정말 하위 전체를 지울 생각이라면 recursive: true를 넘기십시오.

이 방어 장치가 있는 이유는 실제로 벌어진 사고 때문입니다. 폴더 행만 지우면 그 안의 파일들이 부모를 잃고, 앱은 그 하위 전체를 작품 최상단에 펼쳐 놓습니다. 작가는 파일이 흩어진 화면을 보는데 서버는 성공을 돌려준 상황입니다.

삭제도 커밋입니다. 그래서 파일은 버전 기록에 남아 있고 거기서 되살릴 수 있습니다. 버전이나 파일 하나 되살리기를 보십시오.

search_content: 인자는 이것뿐이고 scope는 없습니다

search_content({
  "book_token": "bk_...",
  "query": "글자 용광로",
  "file_types": ["md"],
  "limit": 20
})

file_types는 확장자를 받으며 점을 붙여도 되고 빼도 됩니다(["md", ".txt"]).

4.0 작품에서는 file_types가 보기보다 중요합니다. 구조화 파일의 원본 JSON도 검색되므로, name이나 title 같은 흔한 단어는 필드 이름만 한 페이지 걸려 옵니다. 산문만 보려면 file_types: ["md"]라고 명시하십시오. 예전 시나리오 스튜디오 작품은 반대입니다. 그쪽에서는 구조화 파일이 기본 제외이고 include_structured: true가 그것들을 다시 불러옵니다. 특정 파일에서 다르게 동작하는 도구들을 보십시오.

이 묶음이 손대지 못하는 파일

• 산문 파일(.md / .markdown / .txt) — 이 묶음 전체가 동작합니다.
• 구조화 파일 다섯 종류(.map / .beats / .timeline / .script / .geomap) — write_file, edit_file, append_to_file은 거부되고, 거부 메시지가 대신 쓸 update_* 도구를 지목합니다. 예외 두 가지를 기억해 두십시오. create_file은 동작하지만 보낸 내용이 무시됩니다(서버가 빈 골격을 씁니다). 그리고 delete_file도 동작합니다(삭제는 종류 정책을 보지 않고 플랜만 봅니다). 쓰기와 삭제는 둘 다 구독 플랜에 속합니다.
• .character / .location / .json / .yaml — 전혀 쓸 수 없고, 필드 단위 우회로도 없습니다.

구조화 파일을 고치려면 구조화 편집 도구로 가십시오. 최종 목록은 언제나 get_capabilities가 돌려주는 표입니다.

commit_message는 채워 둘 값어치가 있습니다

빼면 자동으로 한 줄이 만들어지지만, 나중에 작가가 버전 기록에서 읽는 것이 바로 그 자동 문장입니다. 「항구 신의 도입부를 조였음」이 「Update file」보다 훨씬 쓸모가 있습니다.

관련 문서

• Docs: 구조화 편집 도구
• Docs: AI에게 관계도를 보여주기
• Docs: MCP가 파일 종류별로 할 수 있는 일
• Docs: 쓰기가 거부될 때
• Docs: 자동 버전 규칙