kuik-fileshare-mcp

Servidor MCP que da a un agente de KUIK Agent acceso a una carpeta compartida on-premise (SMB/CIFS) de un Windows Server, autenticándose con las credenciales del propio empleado — de modo que el fileserver aplica en vivo las ACLs que correspondan a ese usuario.

No monta nada ni duplica datos: habla SMB en espacio de usuario con rclone (backend smb), por lo que no requiere mount, FUSE ni capabilities extra en el contenedor.

Herramientas

Tool	Descripción
list_files	Lista archivos y carpetas de un directorio del share
list_shares	Lista los shares que el administrador ha configurado
stat_item	Metadatos (tipo, tamaño, fecha) o existencia de un ítem
read_file	Lee un archivo de texto (los ofimáticos → download_file + portal_read_document)
search_files	Busca por nombre (subcadena) bajo una ruta
write_file	Crea/sobrescribe un archivo de texto
make_dir	Crea una carpeta (y sus padres)
move_item	Mueve/renombra dentro o entre shares
copy_item	Copia dentro o entre shares
delete_item	Borra un archivo; carpeta no vacía requiere recursive=true
download_file	Trae un archivo del share al espacio local del agente (~/temp, ~/files)
upload_file	Sube un archivo local al share

Todas las operaciones están acotadas por los permisos del empleado en el fileserver.

Variables de entorno

Las inyecta server/lib/fileshare-service.js de KUIK Agent en getMcpEntry:

Variable	Obligatoria	Descripción
FILESHARE_HOST	sí	Host o IP del fileserver
FILESHARE_USER	sí	Usuario de Windows/AD del empleado
FILESHARE_PASS	sí	Contraseña (en claro; se "obscurece" en memoria, nunca se escribe en disco)
FILESHARE_DOMAIN	no	Dominio AD (NetBIOS), si aplica
FILESHARE_PORT	no	Puerto SMB (default 445)
FILESHARE_SHARES	no	Lista CSV de shares autorizados; si se define, restringe el acceso a esos
FILESHARE_TIMEOUT_MS	no	Timeout por operación rclone (default 60000)
FILESHARE_MAX_READ_BYTES	no	Límite de read_file como texto (default 1048576)
RCLONE_BIN	no	Ruta a rclone (default rclone, ya presente en la imagen)
HOME	sí	Home del empleado; acota las rutas locales de download/upload

Desarrollo

npm install
npm run build
# requiere rclone en el PATH y un servidor SMB de prueba
FILESHARE_HOST=127.0.0.1 FILESHARE_USER=ana FILESHARE_PASS=secret \
FILESHARE_SHARES=Comun,Direccion HOME=/tmp/agent node dist/index.js

Seguridad

• La contraseña llega en claro por env y se transforma con rclone obscure en memoria; nunca se persiste en disco en claro.
• download_file/upload_file solo pueden tocar rutas dentro de HOME.
• Las rutas con .. se rechazan; los separadores Windows (\) se normalizan.
• El borrado recursivo exige recursive=true explícito.