ファイル操作ツール

ひとことで：「パスを指して何かをする」ファイル系のツールのリファレンスです。読む、一部を差し替える、丸ごと上書きする、新しく作る、消す、末尾に足す、探す。

これで解決すること

MCPが本当に原稿に手を触れるのは、この一群です。共通点が2つあります。どれもpathを受け取ること、そして書き込みが毎回コミットを1つ作ることです。保存という段はなく、作者はバージョン履歴で、あなたのコミットを自分のコミットの隣に見ることになります。

ツール	何をするか	引数
read_file	ファイルを1つ読む	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で、最初の1か所だけを置き換えます。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を渡してください。

この防護があるのは、実際に起きた事故のためです。フォルダの行だけを消すと、その中身は親を失い、アプリはそのツリーを作品のいちばん外側に並べます。作者にはファイルが散らばって見えているのに、サーバーが返したのは成功でした。

削除もコミットです。ですからファイルはバージョン履歴に残っていて、そこから戻せます。作品全体を戻す・1ファイルだけ戻すをご覧ください。

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のようなありふれた語を引くと、フィールド名ばかりが1ページ返ってくることがあります。散文だけでいいときはfile_types: ["md"]と明示してください。古い脚本スタジオの作品は逆で、あちらでは構造化ファイルが既定で除外され、include_structured: trueで戻ってきます。ファイルによって挙動が変わるツールをご覧ください。

この一群が触れないファイル

• 散文（.md / .markdown / .txt） — この一群は全部使えます。
• 5つの構造化の型（.map / .beats / .timeline / .script / .geomap） — write_file、edit_file、append_to_fileはどれも拒否され、拒否のメッセージが代わりに使うupdate_*を名指しします。覚えておきたい例外が2つあります。create_fileは動きますが送った内容は無視されます（サーバーが空の骨組みを書きます）。delete_fileも動きます（削除は型ごとの方針を見ず、プランだけを見ます）。書き込みも削除も、どちらも有料プランの機能です。
• .character / .location / .json / .yaml — まったく書けませんし、フィールド単位の代わりの道もありません。

構造化ファイルを直すなら構造化編集ツールへ。根拠になる一覧は、いつでもget_capabilitiesが返す表です。

commit_messageは埋める価値があります

入れなければ自動で1行が作られますが、作者があとでバージョン履歴で読むのはその1行です。「港の場面の入りを引き締めた」は「Update file」よりずっと役に立ちます。

関連

• Docs：構造化編集ツール
• Docs：AIに関係マップを見せる
• Docs：MCPがファイル種別ごとにできること
• Docs：書き込みが拒否されたとき
• Docs：自動バージョンの規則