Octofs: El servidor de archivos que impide que tu IA rompa tu código

Tu asistente de IA acaba de editar tres archivos. Dos están bien. El tercero tiene una función duplicada, le falta una llave de cierre, y la indentación está completamente mal. Parecía seguro de sí mismo. No lo estaba.

Esto sucede más de lo que nadie quiere admitir. Los agentes de IA son potentes editores de código — hasta que alucinan un número de línea, recuerdan mal la indentación, o incluyen contexto circundante en una sustitución que no debería estar ahí. La edición técnicamente tiene éxito. El archivo ahora está roto. No lo notaste hasta que la compilación falló.

Octofs es un servidor de sistema de archivos MCP construido para prevenir exactamente esto. Le da a tu agente de IA ojos, manos y una red de seguridad — la capacidad de leer, editar, crear y buscar archivos, con múltiples capas de protección contra los errores que los modelos de IA cometen cuando tocan código.

Hoy presentamos Octofs 0.4.0 — el estado actual de un proyecto que comenzó como un simple servidor de archivos y evolucionó hacia algo que creemos que todo agente de IA necesita.

Por qué construimos un servidor de sistema de archivos en primer lugar

No empezamos aquí. Empezamos con Octomind — un runtime para agentes de IA especializados. Ejecutas octomind run developer:general y obtienes un desarrollador senior completamente equipado en cinco segundos. El agente necesita leer código, editar archivos, ejecutar comandos, buscar en tu proyecto. Necesita acceso al sistema de archivos.

El ecosistema MCP ya tenía un servidor de sistema de archivos de referencia. Así que lo probamos. Funcionó — hasta que dejó de funcionar. La IA hacía referencia a números de línea que se desplazaban después de una edición anterior. Pasaba espacios en blanco ligeramente incorrectos a un reemplazo de cadena y obtenía una falta de coincidencia silenciosa. Duplicaba líneas en los bordes de un rango de reemplazo. Intentaba ejecutar grep a través del shell cuando existía una herramienta de búsqueda dedicada.

Cada fallo era pequeño. Cada uno requería intervención humana. A escala de agente — ejecutando cientos de ediciones en docenas de archivos — los pequeños fallos se acumulan en algo que deja de ser útil.

Así que escribimos el nuestro. No porque el acceso al sistema de archivos sea interesante. Porque los modos de fallo de la edición de archivos impulsada por IA son predecibles, y un buen servidor puede detectar la mayoría de ellos antes de que se conviertan en tu problema.

El problema de las alucinaciones de la IA al editar archivos

Esto es lo que realmente se rompe:

Números de línea incorrectos. El agente lee un archivo, planifica cinco ediciones, las ejecuta secuencialmente. La primera edición añade tres líneas. Ahora cada referencia de línea subsiguiente está desfasada por tres. El agente no lo nota porque está trabajando desde el modelo mental original.

Alucinación de indentación. El agente sabe el código que quiere escribir. Se equivoca ligeramente con la indentación — dos espacios en lugar de cuatro, o tabulaciones cuando el archivo usa espacios. La coincidencia exacta falla. La edición silenciosamente no hace nada, o peor, el agente reintenta con una versión aún más confusa.

Duplicación de contexto. El agente incluye una línea extra de contexto circundante en su texto de reemplazo. Ahora esa línea aparece dos veces en el archivo. Si es una llave de cierre, el código aún podría parsearse. Si es una línea significativa, tienes un bug sutil.

Coincidencias ambiguas. El agente pasa una cadena de tres líneas que aparece en cuatro lugares del archivo. ¿Cuál debería reemplazarse? Sin desambiguación, la edición o falla o impacta en la ubicación incorrecta.

Estos no son casos extremos. Son la experiencia predeterminada de ejecutar agentes de IA a escala. Y todos son resolubles — no haciendo a la IA más inteligente, sino haciendo al servidor de archivos más inteligente sobre los errores que sabe que la IA cometerá.

Cómo Octofs detecta los errores

Coincidencia progresiva de tres etapas

Cuando la IA llama a str_replace con un old_text que debería coincidir con algo en el archivo, Octofs no solo lo intenta una vez y falla. Ejecuta tres etapas:

Etapa 1: Coincidencia exacta. La cadena old_text coincide exactamente una vez en el archivo. Reemplázala. Listo. Este es el camino feliz — maneja la mayoría de las ediciones correctamente.

Etapa 2: Coincidencia difusa con normalización de espacios en blanco. La coincidencia exacta falla, así que Octofs normaliza los espacios en blanco tanto en el texto proporcionado como en el contenido del archivo — colapsando secuencias de espacios, recortando líneas — y lo intenta de nuevo. Si hay exactamente una coincidencia normalizada, ajusta automáticamente la indentación del texto de reemplazo para que coincida con el archivo real, aplica la edición, y le dice a la IA lo que sucedió mediante una pista. La IA aprende. La edición tiene éxito.

Etapa 3: Diagnóstico enriquecido. Ni la coincidencia exacta ni la difusa funcionan. En lugar de un error genérico de "no se encontró coincidencia", Octofs ejecuta una búsqueda de similitud por ventana deslizante en todo el archivo, encuentra las tres coincidencias más cercanas, y las devuelve con porcentajes de similitud, números de línea, un diagnóstico de por qué difieren (desajuste de indentación, solo espacios en blanco, o el contenido difiere), y una vista previa del texto candidato. La IA puede entonces usar batch_edit con el rango de líneas exacto — o corregir su old_text y volver a intentarlo.

Es lo que sucede cada vez que una edición falla, y es la mayor reducción individual en reintentos de ediciones fallidas que hemos visto.

Identificación de líneas basada en hash

Los números de línea son un identificador terrible para ediciones impulsadas por IA. Se desplazan. La IA lee un archivo de 500 líneas, planifica editar las líneas 142-156, pero una edición anterior insertó cuatro líneas en la línea 80. Ahora el objetivo está en 146-160. La IA no lo sabe a menos que vuelva a leer el archivo — lo cual podría no hacer.

Octofs ofrece una alternativa: identificadores de línea basados en hash. Cada línea recibe un hash hexadecimal de 4 caracteres derivado de su posición y contenido. A diferencia de los números de línea, los hashes son estables a través de las ediciones — el hash de una línea no cambia solo porque se haya insertado otra línea encima. La IA puede hacer referencia a las líneas por hash, e incluso después de múltiples ediciones, esas referencias siguen siendo válidas.

El algoritmo de hash usa FNV-1a plegado a 16 bits, con la clave "<posición>:<contenido>". La posición se incluye específicamente para manejar líneas duplicadas — dos líneas idénticas en diferentes posiciones siempre obtienen hashes diferentes, sin necesidad de resolución de colisiones.

Habilítalo con --line-mode hash y cada respuesta de herramienta devolverá hashes en lugar de números. La IA los usa para los rangos de batch_edit, los rangos de view, y diagnósticos. El desplazamiento de números de línea deja de ser un problema.

Detección de duplicados en los límites de reemplazo

Aquí va una sutileza. La IA planifica un reemplazo para las líneas 100-105. Incluye la línea 99 (la línea anterior al rango) en su contenido de reemplazo — no porque quiera cambiarla, sino porque está "proporcionando contexto". Ahora la línea 99 aparece dos veces. Si es una llave de cierre o una línea vacía, quizás no haya daño. Si es código real, tienes un bug.

Octofs comprueba cada reemplazo en busca de duplicación en los límites. Compara la primera línea del reemplazo con la línea inmediatamente anterior al rango objetivo, y la última línea con la línea posterior. Si alguna coincide, rechaza la edición con un mensaje específico: "Línea duplicada detectada en la operación 2: la primera línea del contenido coincide con la línea 99 (justo antes del rango de reemplazo [100-105]). NO incluyas líneas circundantes sin cambios."

El ruido estructural — llaves de cierre solitarias, líneas vacías — está exento de esta verificación. Aparecen legítimamente en los límites. Cierres compuestos como }); no están exentos. Llevan un significado semántico real.

Detección de conflictos para operaciones en lote

batch_edit permite a la IA realizar múltiples operaciones de inserción y reemplazo en un solo archivo de forma atómica. Pero ¿qué pasa si dos reemplazos se superponen? ¿Qué pasa si dos inserciones apuntan a la misma línea de anclaje?

Octofs valida cada operación contra todas las demás operaciones antes de tocar el archivo. Los rangos de reemplazo-vs-reemplazo que se superponen son rechazados. Inserción-vs-inserción en el mismo anclaje son rechazadas (ordenamiento ambiguo). Inserción-vs-reemplazo nunca entran en conflicto — operan en posiciones conceptualmente diferentes (el espacio después de una línea vs. el contenido de la línea).

Si hay un conflicto, el mensaje de error incluye los índices de las operaciones y los rangos de líneas específicos involucrados. La IA puede corregir su plan y reintentar. Sin corrupción parcial.

Escrituras atómicas con historial de deshacer

Cada edición pasa por atomic_write: escribe en un archivo temporal en el mismo directorio, luego renombra sobre el objetivo. El archivo nunca está en un estado parcial. Si el proceso se cuelga a mitad de la escritura, el original permanece intacto. El renombrado es el único paso destructivo, y es atómico a nivel de sistema de archivos.

Antes de cada escritura, Octofs guarda la versión anterior. Hasta diez niveles de deshacer por archivo. Si una edición sale mal, la IA puede llamar a undo_edit y el archivo se revierte. Sin restauración manual de git. Sin "ups, necesito arreglar lo que la IA acaba de hacer".

Detección de mal uso del shell

La IA tiene acceso al shell. Eso es necesario — necesita ejecutar compilaciones, pruebas, linters. Pero también a veces intenta usar cat para leer un archivo, o grep para buscar texto, o sed para editar una línea. Todas estas tienen herramientas dedicadas y mejores en Octofs.

Cuando la IA ejecuta un comando de shell que coincide con un patrón conocido de mal uso, Octofs lo detecta e inyecta una pista en la siguiente respuesta de herramienta: "Prefiere view para leer archivos (numerado por líneas, soporta rangos)." La IA ve la pista, ajusta su comportamiento, y usa la herramienta correcta la próxima vez.

Aplicación forzosa de shell no interactivo

Los comandos de shell se ejecutan con stdin=null, un grupo de procesos dedicado, y variables de entorno como GIT_TERMINAL_PROMPT=0 y PAGER=cat. La IA no puede generar accidentalmente un prompt interactivo que cuelgue la sesión. Git no pedirá credenciales. sudo no pedirá una contraseña. less no se invocará. El comando o tiene éxito o falla — sin tercer estado.

Al apagar, el grupo de procesos de cada hijo de shell en vuelo se mata con SIGKILL. Sin procesos huérfanos. Sin shells zombi consumiendo memoria.

El estado actual: 0.4.0

Octofs 0.4.0 no es un anuncio de lanzamiento — es donde está el proyecto ahora mismo, y es lo suficientemente estable como para depender de él. Esto es lo que ofrece la versión actual:

Vistas de archivo con múltiples rangos. Lee secciones no contiguas de un archivo en una sola llamada — [[1, 50], [200, 250], [400, 430]] — en lugar de tres solicitudes separadas. Menos viajes de ida y vuelta. Menos desperdicio de contexto.

Tipos estructurados de rango de líneas. Los rangos de líneas son ahora tipos de primera clase con validación adecuada — no arrays JSON brutos que la IA tiene que formatear correctamente. El servidor valida forma, límites y conteo antes de hacer cualquier cosa.

Aplicación forzosa de shell no interactivo. Los comandos de shell están garantizados como no interactivos. No más prompts colgados, no más diálogos de credenciales, no más salida basura invocada por paginadores.

Recorte fuera de límites. Los rangos de líneas que exceden la longitud del archivo se recortan, no se rechazan. ¿La IA pide las líneas 1-1000 en un archivo de 200 líneas? Obtiene las líneas 1-200. Sin error. Sin reintento.

Rangos de líneas por archivo en vistas multi-archivo. Al ver múltiples archivos a la vez, cada archivo puede tener su propio rango de líneas. paths: ["a.rs", "b.rs", "c.rs"] con lines: [[1,50], null, [10,30]] — el primer archivo muestra 1-50, el segundo muestra todo, el tercero muestra 10-30.

Bloqueo de archivos canonicalizado. Los bloqueos de archivo usan rutas canonicalizadas, así que ./src/main.rs, src/main.rs, y /absolute/path/to/src/main.rs todos resuelven al mismo bloqueo. Sin corrupción por escrituras concurrentes debido al aliasing de rutas.

Búsqueda pura en Rust. La búsqueda de contenido ya no llama a ripgrep a través del shell. Es una implementación pura en Rust que es lo suficientemente rápida, tiene cero dependencias externas, y funciona idénticamente en cada plataforma.

Las herramientas

Octofs expone siete herramientas MCP:

Herramienta	Lo que hace
view	Lee archivos, lista directorios, busca contenido. Soporta multi-archivo, multi-rango, IDs de línea basados en hash, búsqueda de contenido con líneas de contexto
text_editor	Crea archivos, reemplaza texto con coincidencia progresiva, deshace ediciones
batch_edit	Múltiples operaciones atómicas de inserción/reemplazo en un solo archivo, con detección de conflictos
extract_lines	Copia rangos de líneas de un archivo a otro
shell	Ejecuta comandos con soporte en segundo plano, detección de mal uso, aplicación forzosa no interactiva
workdir	Gestiona el contexto del directorio de trabajo

Todas las herramientas soportan tanto transporte STDIO como Streamable HTTP. Todas las herramientas son conscientes de gitignore durante el recorrido de directorios. Todas las herramientas responden con salida numerada por líneas (o identificada por hash) para que la IA tenga referencias estables para operaciones posteriores.

Cómo encaja: Octomind + Octofs

Octofs funciona con cualquier cliente compatible con MCP — Claude Desktop, Cursor, Windsurf, Zed. Pero está diseñado para Octomind.

Los agentes de Octomind leen tu base de código, planifican cambios, y ejecutan ediciones a través de Octofs. Octobrain — nuestro servidor de memoria — almacena lo que el agente aprende durante la sesión. Octolib maneja cada llamada al LLM. Juntos son un stack completo para el desarrollo impulsado por IA:

• Octolib habla con los modelos de IA
• Octobrain recuerda entre sesiones
• Octofs toca tus archivos de forma segura
• Octomind orquesta todo

Cada pieza es de código abierto. Cada pieza funciona de forma independiente. Juntas resuelven el problema de dar a un agente de IA acceso fiable y seguro a una base de código.

Código abierto, nativo de Rust

Octofs está en GitHub bajo Apache-2.0. Está construido en Rust — no porque fetichicemos el rendimiento, sino porque las operaciones de archivos se benefician de la corrección en tiempo de compilación, async de coste cero, y sin pausas de recolección de basura. El binario es pequeño, rápido, y tiene cero dependencias en tiempo de ejecución más allá del SO.

# Compilar desde el código fuente (requiere Rust 1.95+)
git clone https://github.com/muvon/octofs
cd octofs && cargo build --release

# O descarga un binario precompilado desde GitHub Releases

Añádelo a tu configuración de Claude Desktop:

{
	"mcpServers": {
		"octofs": {
			"command": "/path/to/octofs",
			"args": ["--line-mode", "hash"]
		}
	}
}

Usa el modo hash para cualquier agente que haga ediciones de múltiples pasos. Las referencias de línea estables eliminan toda una clase de fallos.

Preguntas frecuentes

¿Qué es Octofs?

Octofs es un servidor de sistema de archivos MCP de código abierto en Rust. Da a los agentes de IA acceso seguro y fiable para leer, editar, buscar y crear archivos — con protecciones integradas contra los modos de fallo que los modelos de IA exhiben al editar código.

¿Qué clientes de IA funcionan con Octofs?

Cualquier cliente compatible con MCP: Claude Desktop, Cursor, Windsurf, Zed, y el runtime de agentes de código abierto Octomind.

¿Cómo previene Octofs que las alucinaciones de la IA rompan archivos?

Cinco capas: (1) coincidencia progresiva de tres etapas para str_replace, (2) IDs de línea basados en hash que sobreviven a las ediciones, (3) detección de duplicados en los límites de reemplazo, (4) detección de conflictos para operaciones en lote, (5) escrituras atómicas con hasta 10 niveles de deshacer por archivo.

¿Qué son los IDs de línea basados en hash?

Cada línea recibe un hash hexadecimal de 4 caracteres derivado de su contenido y posición (FNV-1a plegado a 16 bits). A diferencia de los números de línea, los hashes son estables a través de las ediciones — el hash de una línea no se desplaza cuando otras líneas se insertan encima. Habilítalo con --line-mode hash.

¿En qué se diferencia Octofs del servidor de sistema de archivos MCP de referencia?

El servidor de referencia hace E/S de archivos directa. Octofs añade coincidencia difusa con auto-indentación, IDs hash, detección de duplicados en los límites, comprobaciones de conflictos en lote, escrituras atómicas, historial de deshacer, detección de mal uso del shell, y aplicación forzosa de shell no interactivo. Construido específicamente para los modos de fallo que los agentes de IA producen a escala.

¿Está Octofs listo para producción?

Sí. 0.4.0 es estable y se usa a diario dentro de Octomind. Apache-2.0, único binario de Rust, cero dependencias en tiempo de ejecución más allá del SO. Las escrituras atómicas garantizan que los archivos nunca terminen en un estado parcial.

¿Soporta tanto STDIO como HTTP?

Sí. Transporte STDIO para clientes de escritorio (Claude, Cursor, etc.) y Streamable HTTP para agentes remotos.

Lo que viene

Estamos trabajando en diagnósticos más inteligentes — cuando una edición falla, Octofs no debería simplemente decirle a la IA qué salió mal. Debería sugerir la solución. También estamos explorando la validación de ediciones basada en patrones: si la IA está editando una función de Rust, Octofs podría comprobar que el resultado todavía se analiza como Rust válido antes de escribirlo.

El servidor de archivos no es la parte emocionante de un stack de agentes de IA. Es la parte que tiene que funcionar perfectamente, cada vez, o todo lo demás se desmorona. Ese es el requisito en torno al cual está construido Octofs — y es código abierto en GitHub bajo Apache-2.0 si quieres profundizar.