ファイルによって挙動が変わるツール

ひとことで：特定のファイルや特定の作品で予想と違う動きをするツールと、その違いへの対処です。

これで解決すること

MCPのツールはたいてい、どのファイルにも同じようにふるまいます。下に挙げるものは違います。どれもエラーにはなりません。ただ、予想していなかったものを返します。そして予想外の成功は、はっきりした失敗よりずっと気づきにくいものです。

read_file：2つの型は姿が変わって返ってきます

.map関係マップは生のJSONで返ってきます。ノードのid、ピクセル座標、グループの構成員リスト。技術的には問題ありませんが、実務では使えたものではありません。代わりにview_relationship_mapを使ってください。図と、人物と関係を全部並べた要約が返ってきます。AIに関係マップを見せるをご覧ください。

.geomap世界地図は、3枚の地形グリッドが1行の説明に置き換わって返ってきます。切り詰められたのではなく、意図したものです。地形は機械向けの符号化なので読むところがありませんし、地形を変える操作はマス目の座標で動きます。

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の文書を読み上げてくださいと読み手に頼むようなものです。読み手は言われたとおりにしますし、レポートは奇妙なものになります。Beta Readerは.mdの原稿ファイルに向けてください。

get_writing_stats：4つの型は常に0

.map、.beats、.timeline、.geomapの文字数は、取り決めとして0です。どれも作者が書いた散文ではありません。.scriptは逆で、シーンの中の文字を数え、1日の文字数と連続記録に入ります。

だから作者のために年表を整えても、統計に嘘の成果は残りません。1話ぶんの脚本を書けば残ります。

create_file：5つの構造化の拡張子では、送った内容は無視されます

サーバーが空の骨組みを書き、ファイル名がそのまま文書の名前になります。内容が差し替わったことは、返答にはっきり書かれます。入れたかったものは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：Beta Readerのツール