Herramientas de operaciones de archivo

En una línea: la referencia de las herramientas de archivo que actúan sobre una ruta — leer, editar en el sitio, sobrescribir, crear, borrar, añadir al final, buscar.

Qué resuelve

Este es el grupo que toca el borrador de verdad. Lo que tienen en común: todas aceptan un path y cada escritura produce un commit. No hay paso de guardar, y el autor va a ver tus commits al lado de los suyos en el historial de versiones.

Herramienta	Qué hace	Argumentos
read_file	Leer un archivo	book_token, path
edit_file	Buscar un pasaje y reemplazarlo	path, old_string, new_string, replace_all?, commit_message?
write_file	Reemplazar el archivo entero	path, content, commit_message?
create_file	Crear un archivo nuevo	path, content?, content_type?, commit_message?
delete_file	Borrar un archivo o una carpeta	path, recursive?, commit_message?
append_to_file	Añadir al final de un archivo	path, content, commit_message?
search_content	Búsqueda de texto	query, file_types?, limit?, include_structured?

Ver un mapa de relaciones es otra herramienta; mira Dejar que una IA vea un mapa de relaciones.

Para corregir, tira de edit_file

Es la más usada del grupo y la única escritura que falla a gritos en lugar de sobrescribir cuando el autor está editando el mismo archivo.

La coincidencia y el reemplazo ocurren en el servidor, dentro de un bloqueo, así que el número que te informa es lo que realmente se aplicó y no una estimación local. Cuando el texto no está, o aparece más de una vez y el objetivo queda ambiguo, la llamada falla y te dice qué hacer después: haz eso en lugar de reenviar los mismos argumentos.

replace_all viene en false y reemplaza solo la primera coincidencia. Pasa un new_string vacío para borrar el pasaje.

write_file lo reemplaza todo

Sirve para una reescritura completa de verdad. Se lleva por delante también lo que el autor tecleó hace un minuto, así que prefiere edit_file siempre que edit_file pueda con el trabajo.

create_file: content_type decide si las palabras cuentan

¿Vas a escribir un capítulo? Pasa content_type: "manuscript". Sin eso, un archivo nuevo hereda el tipo de la carpeta que lo contiene, y en la raíz el valor por defecto es reference: esas palabras no llegan al recuento del autor, ni a su racha, ni a la exportación del manuscrito. Los valores son manuscript, reference, character, location y storyline.

Las carpetas de la ruta que todavía no existen se crean solas, así que no hay un paso aparte para crear directorios. Mira Manuscrito vs. referencia.

delete_file: una carpeta con cosas dentro hay que decirla en voz alta

Borrar una carpeta que todavía tiene contenido se rechaza por defecto, y el mensaje te dice cuántos elementos hay dentro. Pasa recursive: true cuando de verdad quieras el subárbol completo.

La protección existe por un accidente real: si quitas solo la fila de la carpeta, su contenido pierde el padre y la app muestra todo el subárbol en el nivel superior del libro. El autor ve sus archivos desparramados, y el servidor respondió que todo fue bien.

Un borrado también es un commit, así que el archivo sigue en el historial de versiones y se puede restaurar desde ahí; mira Restaurar la obra completa o un solo archivo.

search_content: estos argumentos, y ningún scope

search_content({
  "book_token": "bk_...",
  "query": "horno de letras",
  "file_types": ["md"],
  "limit": 20
})

file_types acepta extensiones con punto o sin él (["md", ".txt"]).

En un libro 4.0, file_types importa más de lo que parece. El JSON en crudo de los archivos estructurados también se busca, así que una palabra corriente como name o title puede volver convertida en una página de nombres de campo. Pon file_types: ["md"] cuando quieras prosa. Los libros antiguos de Script Studio funcionan al revés: ahí los archivos estructurados quedan excluidos por defecto y include_structured: true los trae de vuelta. Mira Herramientas que se comportan distinto en ciertos archivos.

Qué no puede tocar este grupo

• Prosa (.md / .markdown / .txt): el grupo entero funciona.
• Los cinco tipos estructurados (.map / .beats / .timeline / .script / .geomap): write_file, edit_file y append_to_file se rechazan, y el rechazo nombra la herramienta update_* que toca usar. Hay dos excepciones que conviene recordar: create_file sí funciona, pero el contenido que envías se ignora (el servidor escribe un esqueleto vacío), y delete_file también funciona (el borrado no consulta la política de tipos, solo el plan). Escribir y borrar pertenecen los dos a los planes de suscripción.
• .character / .location / .json / .yaml: no se pueden escribir en absoluto, y tampoco hay vía a nivel de campo.

Para cambiar un archivo estructurado, pasa por Herramientas de edición estructurada. La lista autorizada es siempre la tabla que devuelve get_capabilities.

commit_message vale la pena rellenarlo

Si lo dejas fuera se genera uno, pero esa línea generada es lo que el autor va a leer más tarde en el historial de versiones. «Aprieto el arranque de la escena del puerto» sirve bastante más que «Update file».

Relacionado

• Docs: Herramientas de edición estructurada
• Docs: Dejar que una IA vea un mapa de relaciones
• Docs: Qué puede hacer MCP con cada tipo de archivo
• Docs: Escritura rechazada: qué hacer
• Docs: Reglas de versiones automáticas