Construye un MCP Server que lea, resuma y organice archivos locales: un asistente personal de organización.
El Asistente de Archivos es un proyecto que combina el poder de MCP con operaciones del sistema de archivos. Vamos a crear 4 herramientas que permiten a Claude interactuar con archivos y carpetas locales: leer contenido, buscar texto, generar estadísticas y organizar archivos automáticamente. Todo usando los módulos pathlib e os de la biblioteca estándar de Python.
Las 4 tools del Asistente de Archivos: ler_arquivo(caminho) — lee el contenido de un archivo de texto y lo devuelve con metadatos (tamaño, fecha de modificación); buscar_en_arquivos(pasta, texto) — busca una cadena en todos los archivos de una carpeta de forma recursiva y devuelve el archivo, la línea y el contexto; estatisticas_pasta(caminho) — cuenta los archivos por extensión, el tamaño total y los archivos más grandes y más pequeños; organizar_por_tipo(pasta) — mueve archivos a subcarpetas organizadas por extensión (.pdf para PDFs/, .jpg para Imágenes/, etc.). Todas usan pathlib.Path para manipular rutas de forma segura.
Usa pathlib.Path en lugar de os.path para todas las operaciones con rutas. pathlib ofrece una API más intuitiva y orientada a objetos: Path("pasta").iterdir() para listar, path.suffix para extensión, path.stat().st_size para el tamaño. Además, funciona correctamente en Windows, Linux y macOS sin ajustes manuales de barras.
La tool ler_arquivo es la más básica y poderosa de nuestro asistente. Lee el contenido de un archivo de texto y lo devuelve junto con metadatos útiles, como el tamaño y la fecha de modificación. Lo más interesante es que Claude resume naturalmente el contenido al presentárselo al usuario: no necesitas implementar una lógica de resumen, el modelo lo hace por sí solo.
La tool ler_arquivo(caminho: str) usa Path(caminho) para abrir el archivo, lee el contenido con path.read_text(encoding="utf-8") y recopila metadatos mediante path.stat(): tamaño en bytes/KB, fecha de la última modificación con formato. El resultado combina los metadatos y el contenido en una cadena organizada. Claude recibe todo esto y puede resumirlo, analizarlo o responder preguntas sobre el contenido, sin que tengas que agregar código de IA.
¡Limita el tamaño de la lectura! Si el usuario pide leer un archivo de 500MB, el servidor intentará cargarlo todo en la memoria y enviarlo como respuesta de la tool; esto puede bloquear el servidor o superar los límites del modelo. Define un límite seguro (p. ej., 10.000 caracteres) y, si el archivo es más grande, devuelve solo el comienzo con un aviso: "Archivo truncado: se muestran los primeros 10KB de 500MB."
La tool buscar_en_arquivos funciona como un "grep" inteligente: recibe una carpeta y un texto que buscar, y recorre todos los archivos de forma recursiva, indicando dónde se encontró el texto con contexto. Imagina pedirle a Claude: "Busca 'TODO' en todos los archivos de mi proyecto" — esta tool lo hace posible.
La tool buscar_em_arquivos(pasta: str, texto: str) usa Path(pasta).rglob("*") para iterar recursivamente sobre todos los archivos. Para cada archivo de texto, lee las líneas y verifica si aparece el texto buscado (sin distinguir entre mayúsculas y minúsculas con .lower()). El resultado incluye: nombre del archivo, número de línea e a línea con contexto (la línea encontrada, más una línea antes y otra después). Limita el número de resultados (p. ej., máximo 50) para no sobrecargar la respuesta.
Usa rglob("*") para la búsqueda recursiva (incluye subcarpetas) y filtra solo archivos con path.is_file(). Ignora los archivos binarios comprobando la extensión o usando un try/except al leer. Una buena lista de extensiones de texto: .txt, .py, .js, .md, .html, .css, .json, .yml, .toml, .cfg, .ini, .log. Ignorar carpetas como .git, __pycache__ e node_modules acelera mucho la búsqueda.
Comprobar que la ruta exista y sea un directorio con Path(pasta).is_dir(). Devolver un error claro si no lo es.
Usar rglob("*") para recorrer archivos, leer cada uno con try/except y verificar si el texto aparece en cada línea.
Armar una cadena con archivo:línea:contenido para cada coincidencia encontrada. Incluir el recuento total: "Se encontraron X coincidencias en Y archivos."
La tool estatisticas_pasta analiza una carpeta y devuelve un panorama completo: cuántos archivos hay, cómo se distribuyen por extensión, cuál es el tamaño total, cuál es el archivo más grande y el más pequeño, y cuándo se modificó el archivo más reciente. Es como una "radiografía" del directorio.
La tool estatisticas_pasta(caminho: str) recorre todos los archivos de la carpeta con Path(caminho).rglob("*"), recopilando información con path.stat() para cada archivo. Calcula: total de archivos, distribución por extensión (usando un diccionario/Counter), tamaño total en bytes/KB/MB, archivo más grande y más pequeño con sus nombres y tamaños, y fecha del archivo más reciente. El resultado es una cadena formateada que Claude presenta como un informe organizado.
Las herramientas de análisis de directorios son sorprendentemente útiles en el día a día. Los estudios muestran que el usuario promedio tiene más de 100.000 archivos en la computadora y tarda aproximadamente 2,5 horas por semana buscando y organizando archivos. Una tool que proporciona estadísticas rápidas permite identificar rápidamente las carpetas que necesitan limpieza, los archivos enormes que ocupan espacio y las extensiones inesperadas que pueden indicar problemas.
Usa collections.Counter para contar extensiones de forma elegante: Counter(p.suffix.lower() for p in pasta.rglob("*") if p.is_file()). Para mostrar los tamaños en un formato legible, crea una función auxiliar que convierta bytes a KB/MB/GB automáticamente. Ordena las extensiones por cantidad (las más comunes primero) para que el informe muestre la información más relevante al inicio.
La tool de mayor impacto de nuestro asistente: organizar_por_tipo analiza una carpeta y mueve cada archivo a una subcarpeta correspondiente a su extensión. Los archivos .pdf van a una carpeta "PDFs/", .jpg y .png a "Imagens/", .py a "Python/", y así sucesivamente. Pero atención: esta tool modifica el sistema de archivos, así que debe pedir confirmación antes de actuar.
La tool organizar_por_tipo(pasta: str, confirmar: bool = False) funciona en dos modos. Cuando confirmar=False (predeterminado), solo enumera los cambios planificados: "Mover relatorio.pdf a PDFs/relatorio.pdf", "Mover foto.jpg a Imagens/foto.jpg", etc. Cuando confirmar=True, realiza los cambios usando shutil.move(). El mapeo de extensiones a carpetas usa un diccionario: {".pdf": "PDFs", ".jpg": "Imagens", ".png": "Imagens", ".py": "Python", ...}. Las extensiones desconocidas van a "Otros/".
Nunca muevas archivos automáticamente sin la confirmación del usuario. El patrón de la tool debe ser confirmar=False, devolviendo solo la lista de cambios planificados. Claude le presentará esa lista al usuario y le preguntará si desea continuar. Solo cuando el usuario confirme, Claude volverá a llamar a la tool con confirmar=True. Este enfoque en dos pasos evita los movimientos accidentales de archivos importantes.
Con todas las tools implementadas, probaremos el Asistente de Archivos en escenarios reales. El objetivo es validar que Claude pueda entender solicitudes en lenguaje natural, elegir la tool correcta y presentar los resultados de forma útil. Cada escenario prueba una combinación distinta de tools y capacidades.
Configura el servidor en Claude Desktop y crea una carpeta de prueba con archivos variados (textos, PDFs, imágenes, código Python). Cuanto más diversa sea la carpeta de prueba, más escenarios podrás validar. Observa cómo Claude decide qué tool usar; a veces combina varias en secuencia, por ejemplo, primero llama a estatisticas_pasta para saber qué hay en la carpeta y luego a ler_arquivo para inspeccionar un archivo específico.
"¿Qué hay en mi carpeta Downloads?" — Claude debe llamar a estatisticas_pasta y presentar un resumen organizado con el conteo por tipo, el tamaño total, etc.
"Busca 'TODO' en todos los archivos de mi proyecto" — Claude debe llamar a buscar_em_arquivos y enumerar cada coincidencia con archivo, línea y contexto.
"Lee el archivo notas.txt y hazme un resumen" — Claude debe llamar a ler_arquivo y luego resumir el contenido naturalmente en la respuesta.
"Organiza los archivos de la carpeta Teste por tipo" — Claude primero debe mostrar el plan (confirmar=False), preguntar y solo después ejecutar (confirmar=True).
Crea una carpeta de pruebas dedicada con archivos de ejemplo antes de probar: nunca pruebes directamente en carpetas importantes. Usa mkdir pasta_teste && touch pasta_teste/doc.pdf pasta_teste/foto.jpg pasta_teste/notas.txt pasta_teste/script.py para crear rápidamente una estructura de prueba. Esto permite probar todas las tools sin riesgo de afectar archivos reales, especialmente la tool de organización que mueve archivos.
Siguiente Módulo: 4.4 — Integración con API REST