FileX

Conversor universal de archivos, local-first, que se entrega como servidor MCP + CLI + watcher de carpetas + API HTTP local. Sobre Windows con Docker/WSL2, aprovechando una RTX 3060 de 12 GB.

Cubre 12 categorías: ofimática↔PDF, markup, operaciones PDF, ebooks, imágenes normales y especiales, vídeo, audio, documento→texto para LLM, OCR, datos tabulares y audio/vídeo→texto.

Estado: los siete hitos, hechos. Este repositorio contiene la auditoría de 22 repositorios del ecosistema —leídos a nivel de código y ejecutados en la máquina real—, el plan de construcción que sale de ella, y el producto: registro, grafo con coste por arista, confinamiento, invocación disciplinada, y cuatro superficies —CLI, MCP, watcher de carpetas y API HTTP local—, con la verificación DENTRO de la conversión.

22 módulos, biblioteca estándar, cero dependencias. 18 ficheros de pruebas. Suite verificada el 03/09/2026 con .venv-mcp-filex/Scripts/python.exe (win32, 3.11.9) y Docker levantado: 460 passed · 3 skipped · 0 failed · 130 subtests en 243,58 s, con la máquina despejada. Los tres saltados van declarados: uno pide un ráster que hay que generar, otro la tarjeta (FILEX_PRUEBAS_SIDECAR=1) y el tercero dos volúmenes de disco distintos que esta máquina no tiene. (Bajo carga de dos carriles trabajando en paralelo, una pasada previa dio 4 fallos intermitentes — carreras ya documentadas como N30, trampa 101 de CLAUDE.md: no son una regresión, son el mismo hallazgo reproduciéndose.) Un recuento de suite declara su intérprete, su entorno, el estado de la máquina y qué quedó fuera, o no dice qué se ejecutó.

$ filex convertir corpus/video/patologico_2pistas.mkv salida.mp4
salida.mp4   [ok]
  mkv→mp4 [ffmpeg]  rc=0  3672 ms  contrato 6/6 → ok
      [informativo] N9: el fichero declarado lleva el 100.0 % de los bytes escritos

Ese fichero tiene dos pistas de audio, y salen dos. ConvertX y SnapOtter entregan una y declaran éxito.

La tesis

No es «convierte más cosas más rápido» — eso resultó ser discutible y en parte replicable. Es:

Es el único que garantiza que lo que te entrega es lo que pediste.

Siete fallos independientes, en seis proyectos distintos, todos del mismo tipo: el software declara éxito sobre un resultado incorrecto. Un .avif que es un PNG entregado con estado «Done». Una pista de audio perdida en silencio. 16 bits degradados a 8 sin avisar. Una cadena vacía con isError: false.

Ninguno de los seis orquestadores analizados verifica su propia salida. Y verificarla cuesta el 0,032 % de lo que cuesta convertir.

Related MCP server: overtooled-mcp

Por dónde empezar

Dos públicos distintos, dos puertas de entrada. La tabla los separa; no mezcles el orden.

Si sólo quieres usar FileX (convertir ficheros, nada de tocar código):

Si vas a tocar código, medir algo o entender la investigación:

Integración continua, y lo que NO cubre

Esto va primero, porque una CI verde que no cubre lo que importa es peor que no tener CI: es un falso verde, y este repositorio tiene medido lo que cuesta uno (trampas 94 y 101).

Lo que sólo corre en la máquina del proyecto, y es casi todo el valor:

• Las pruebas win32 — os.replace como cerrojo, el mutex Global\, la DACL, los nombres 8.3. Un runner alojado de GitHub no tiene NTFS.

• La GPU — el lock, los seis motores de OCR, el sidecar. No hay RTX 3060 en la nube de Actions.

• Los contenedores locales — filex-c13, SnapOtter, ConvertX, Gotenberg.

• El corpus — 254 MB en Git LFS, y la cuota gratuita es de 1 GB de ancho de banda al mes: cuatro ejecuciones con lfs: true la agotan. Los flujos bajan el repositorio sin LFS, a propósito.

Un ✅ de GitHub dice que la documentación es coherente y que el código sigue importando en Linux. No dice que la medición esté bien. Eso lo declara quien abre el PR, con las cuatro declaraciones que pide la plantilla.

Se ejecutan igual en local, y tardan segundos:

python3 ci/integridad.py           # las nueve comprobaciones
python3 ci/integridad.py --lista   # qué comprueba cada una y por qué

Estructura

analysis/    Un documento por repositorio auditado, más los transversales
bench/       Mediciones reproducibles: informes, scripts y arneses
corpus/      20 ficheros de prueba con los casos patológicos (en Git LFS)
docker/      Compose de los competidores levantados para medirlos

Los binarios de salida no se versionan. Cada carpeta excluida conserva un MANIFIESTO.md con nombre, sha256, tamaño y la orden exacta que la reproduce — bench/salidas-referencia/referencia.json guarda 39 de ellas. La evidencia sigue siendo verificable sin arrastrar el peso.

Requisitos para reproducir las mediciones

Verificado en la máquina de referencia: RTX 3060 12 GB (compute 8.6), Windows 10, 12 núcleos, Docker + WSL2, Python 3.11.

Nativos: ffmpeg (con --enable-gpl --enable-libx264 --enable-libx265 --enable-cuda-llvm), ImageMagick 7 Q16-HDRI, Ghostscript 10. Lo que falta va en contenedor, no instalado a mano.

git clone https://github.com/edicius2002/FileX.git && cd FileX
git lfs pull          # el corpus vive en LFS

Convención de los documentos

Cada afirmación va marcada MEDIDO (hay un dato en bench/ que la respalda) o PENDIENTE (no se ha comprobado). Donde un resultado contradice a un documento anterior, se dice y se señala cuál en vez de corregirlo en silencio. Varias de las conclusiones más útiles del repositorio son autocorrecciones.

Licencia

MIT.

Los repositorios auditados en repos/ no forman parte de este proyecto y conservan sus propias licencias — varias son AGPL, y el análisis distingue explícitamente qué se puede copiar, qué se puede leer y qué no se puede tocar. Ver analysis/00-licencias.md.