image-reader-mcp: Un servidor MCP para manipulación inteligente de imágenes con IA

En los últimos años, la integración de modelos de lenguaje (LLMs) en flujos de trabajo ha evolucionado más allá del simple procesamiento de texto. Cada vez es más común que los agentes LLM necesiten interactuar con archivos de imagen: explorar directorios, acceder a imágenes específicas, procesarlas o incluso analizarlas de forma dinámica. Sin embargo, habilitar este tipo de interacción desde un entorno controlado y seguro no es trivial.

En este post quiero compartir el proceso de diseño y desarrollo de image-reader-mcp, un servidor MCP escrito en TypeScript que habilita a agentes LLM para explorar directorios locales y acceder de manera robusta al contenido de archivos de imagen. El servidor está construido sobre FastMCP, lo que facilita su integración en flujos de IA modernos y promueve una gestión eficiente de archivos. Puedes consultar el proyecto completo en GitHub.

Contexto y necesidad del proyecto

Trabajando con agentes LLM, especialmente en entornos como Cursor o flujos personalizados, noté una carencia importante: aunque los modelos de lenguaje avanzados cada vez soportan mejor la visión, la infraestructura para que un LLM pueda explorar un sistema de archivos local y manipular imágenes era limitada, poco segura o demasiado ad-hoc.

Las soluciones existentes tenían varios problemas:

• Acoplamiento excesivo: muchos agentes asumían rutas o formatos específicos.
• Falta de extensibilidad: difícil agregar soporte para nuevos formatos o tipos de procesamiento.
• Seguridad y robustez: riesgo de exposición de rutas sensibles o manejo inapropiado de archivos binarios.
• Integración con MCP: el protocolo MCP (Machine Control Protocol) se está convirtiendo en un estándar para orquestar agentes y servidores de herramientas, pero faltaban módulos para imágenes.

Por eso, diseñé image-reader-mcp con los siguientes objetivos:

• Permitir a un agente LLM explorar de forma controlada directorios locales de imágenes
• Facilitar el acceso seguro y eficiente al contenido de imágenes, preparado para IA
• Ser fácil de integrar en flujos MCP existentes
• Extensible y mantenible, usando buenas prácticas TypeScript

Arquitectura general

La arquitectura de image-reader-mcp es deliberadamente simple pero robusta, siguiendo la filosofía UNIX: cada componente hace una sola cosa, pero la hace bien.

Componentes principales:

1. Servidor FastMCP

El núcleo del proyecto es un servidor FastMCP, que expone herramientas (“tools”) accesibles por cualquier cliente MCP autorizado.

1. Tool: list_images

Permite listar todos los archivos de imagen soportados en un directorio especificado.

1. Tool: read_image

Lee un archivo de imagen dado y lo devuelve como una cadena base64, adecuada para display o análisis por parte de un agente de IA.

1. Sistema de resolución y validación de rutas

Asegura que solo se pueda acceder a rutas explícitamente permitidas y que no haya fugas de información sensible.

1. Extensibilidad mediante configuración

El sistema permite agregar nuevos formatos de imagen fácilmente, o adaptar la lógica a necesidades futuras (p.ej., thumbnails, OCR, etc.).

Diagrama de alto nivel

graph TD
    A[Cliente MCP (Agente LLM)] -->|Solicita| B[Servidor image-reader-mcp]
    B -->|list_images| C[Listado de archivos de imagen]
    B -->|read_image| D[Contenido base64 de imagen]
    C -->|Respuesta| A
    D -->|Respuesta| A

Approach técnico y decisiones clave

¿Por qué TypeScript y FastMCP?

• TypeScript: Ofrece tipado estático robusto, autocompletado y mejor mantenibilidad para proyectos de infraestructura. Ayuda a evitar errores sutiles, especialmente al manipular rutas y archivos binarios.
• FastMCP: Es un framework ágil para construir servidores MCP en Node.js, con una API clara para definir herramientas y manejar peticiones. Permite integración directa con clientes que ya usan MCP, como Cursor.

Manejo de rutas y seguridad

Uno de los retos principales es asegurar que los agentes LLM no puedan acceder a archivos arbitrarios del sistema. Para ello:

• Limité la exploración a rutas explícitas definidas en la configuración del servidor.
• Validé extensiones de archivo estrictamente.
• Saniticé los paths recibidos antes de acceder al sistema de archivos.

Ejemplo de validación de extensión:

1const SUPPORTED_EXTENSIONS = ['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp', '.svg'];
2 
3function isSupportedImage(fileName: string): boolean {
4  return SUPPORTED_EXTENSIONS.some(ext => fileName.toLowerCase().endsWith(ext));
5}

Base64 y helpers de FastMCP

La mayoría de agentes LLM trabajan mejor con imágenes codificadas en base64. Aproveché el helper imageContent de FastMCP para devolver la imagen en un formato automáticamente reconocible por el agente.

Snippet central para leer la imagen:

1import { imageContent } from 'fastmcp';
2 
3async function readImage(filePath: string) {
4  const imageBuffer = await fs.promises.readFile(filePath);
5  return imageContent(imageBuffer, path.extname(filePath));
6}

Interfaz MCP: herramientas como “tools”

FastMCP expone cada acción como una “tool” claramente definida, con parámetros y tipos de retorno bien documentados. Esto permite a los clientes descubrir y usar las capacidades del servidor de forma semántica.

Definición simplificada de una herramienta:

1server.tool('list_images', {
2  description: 'List image files in a specified directory.',
3  params: { directoryPath: 'string' },
4  async handler({ directoryPath }) {
5    // ... lógica para listar imágenes ...
6  }
7});

Desglose de componentes

1. Tool: list_images

• Entrada: directoryPath (string, ruta absoluta)
• Salida: Lista de nombres de archivos de imagen soportados, o mensaje si no hay imágenes.

Puntos clave:

• El escaneo es síncrono para minimizar riesgo de race conditions.
• Soporta extensiones comunes.
• Responde rápidamente incluso en directorios grandes.

Ejemplo de uso:

1{
2  "tool": "list_images",
3  "params": { "directoryPath": "/home/javier/images" }
4}

2. Tool: read_image

• Entrada: filePath (string, ruta absoluta)
• Salida: Objeto con la imagen en base64, listo para display o procesamiento.

Puntos clave:

• Valida la existencia y extensión del archivo antes de leerlo.
• Usa el helper de FastMCP para evitar errores de encoding.
• Ideal para agentes LLM con capacidades de visión.

3. Integración y configuración

Para integrar en un cliente MCP (ej. Cursor), se agrega la entrada correspondiente en la config:

1{
2  "mcpServers": {
3    "imageReader": {
4      "command": "npx",
5      "args": ["image-reader-mcp"],
6      "env": {}
7    }
8  }
9}

Nota: Actualmente, en Cursor, la funcionalidad vision solo está habilitada con Claude Sonnet (a junio de 2024).

Challenges técnicos y cómo los resolví

1. Manejo de rutas inseguras

El mayor riesgo era que un agente, malintencionado o no, pudiera navegar fuera del directorio permitido (path traversal). Para evitarlo:

• Implementé una función que valida que todo path recibido esté bajo un “root” permitido.
• Rechazo cualquier path que contenga patrones sospechosos como ../ o rutas relativas ambiguas.

2. Compatibilidad multiplataforma

Node.js maneja rutas diferente en Windows y Linux. Usé el módulo path de Node para normalizar rutas y evitar bugs cross-platform.

3. Performance en directorios grandes

Para evitar bloqueos, el escaneo de directorios es asíncrono y paginado si es necesario. Para la V1, la carga es suficiente, pero tengo pendiente optimizar para directorios con decenas de miles de archivos.

4. Soporte para diferentes modelos LLM

Descubrí que no todos los LLMs usados en Cursor soportan vision por igual. Por ahora, recomiendo Claude Sonnet, pero dejo la puerta abierta a otros modelos conforme vayan habilitando visión.

Resultados y métricas

• Integración exitosa en Cursor y otros entornos MCP: El servidor es plug-and-play para agentes LLM que ya usan FastMCP.
• Exploración y lectura de imágenes eficiente: Listar cientos de archivos y acceder a imágenes de hasta ~10MB es inmediato (<200ms en promedio).
• Sin incidentes de seguridad (hasta la fecha): Todas las rutas son validadas, y no se permite acceso fuera del scope definido.
• Extensible: Añadir nuevos formatos de imagen o herramientas es trivial gracias a la arquitectura modular.

Learnings y mejoras futuras

Lo que aprendí:

• La integración de agentes LLM con sistemas de archivos reales requiere un enfoque de seguridad “defense-in-depth”.
• FastMCP es una base sólida para construir servidores de herramientas IA, pero aún hay retos a nivel de interoperabilidad con diferentes clientes LLM.
• La experiencia de usuario mejora considerablemente cuando los agentes pueden “ver” y manipular imágenes del entorno.

Posibles mejoras:

• Soporte para thumbnails: Para acelerar previews, especialmente en directorios grandes.
• Filtros avanzados: Permitir queries por tamaño, fecha, tipo de imagen, etc.
• Procesamiento adicional: OCR, extracción de metadata, etc.
• UI web simple para debug: Facilitar pruebas fuera del flujo MCP.
• Mejoras en logging y métricas: Para monitoreo y troubleshooting en producción.

Conclusión

image-reader-mcp es un paso adelante para dotar a los agentes LLM de capacidades prácticas de manipulación de imágenes, todo bajo un framework seguro y extensible. La arquitectura basada en FastMCP y TypeScript permite fácil integración, buen rendimiento y una base sólida para extensiones futuras.

Si te interesa el proyecto o tienes feedback, te invito a revisarlo en GitHub o a contactarme. No hay nada más gratificante que ver cómo la IA se conecta de forma inteligente con el mundo real, ¡y este tipo de herramientas son clave para ese futuro! 🚀

¿Te gustaría ver una demo, integración con otros agentes, o tienes ideas para nuevas features? ¡Déjalo en los comentarios o abre un issue en el repo!