# 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

```bash
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.