# Servidor MCP del Gestor de archivos

Conecta tu asistente al Gestor de archivos: buscar, leer por páginas, crear documentos, ordenar carpetas y crear enlaces públicos aprobados en el móvil.

El servidor MCP del Gestor de archivos (`utilia-files`) conecta tu asistente de IA con los archivos y las carpetas de la empresa: encontrarlos, leerlos por páginas, mirar sus imágenes y sus hojas de cálculo, crear documentos, traerlos de internet, ordenarlos, vincularlos a una ficha y crear enlaces públicos que la persona aprueba en su móvil. Ve exactamente lo que la persona ve en la aplicación, ni un archivo más. Sustituye a las herramientas `fm_*` que estaban en el servidor del CRM: cómo pasar de unas a otras está en [Si tu integración llamaba desde el CRM](#si-tu-integración-llamaba-desde-el-crm).

La guía de uso está en [Usar el gestor de archivos](https://os.utilia.ai/docs/guides/files/overview).

| Dato | Valor |
| - | - |
| Dirección | `https://os.utilia.ai/api/mcp/files` |
| Nombre en «Conecta tu IA» | Gestor de archivos |
| Metadatos de descubrimiento | `GET /.well-known/mcp-files.json` |
| Scopes | `files:*`, los acompañantes de las fichas y los del plan, los avisos y el soporte |

## Cómo se conecta

Desde [Conecta tu IA](https://os.utilia.ai/dashboard/settings/connect-ai) autorizas tu cliente MCP con OAuth o generas una clave de conexión para este servidor. En Claude Code:

```bash
claude mcp add --transport http utilia-files https://os.utilia.ai/api/mcp/files
```

El token se emite para `/api/mcp/files` y solo sirve ahí: un token del CRM no entra por esta dirección, ni uno de archivos por la del CRM. El proceso completo, con el descubrimiento y la primera llamada, está en [Primeros pasos con MCP](https://os.utilia.ai/docs/developers/mcp/quickstart).

## Qué comprueba en cada operación

**Qué comprueba el servidor de archivos**

1. **Gestor de archivos en el plan** (Tu organización): Con una ficha, además el aplicativo de esa ficha. Si no: MODULE_NOT_ENABLED; ningún permiso lo abre.
2. **Scope de la operación** (El token): Una escritura nunca se ejecuta con un scope de lectura. Si no: INSUFFICIENT_SCOPE, con grantUrl para concederlo.
3. **Archivos avanzados, si lo pide** (La capacidad): Versiones, vínculos a fichas y enlaces públicos. Si no: CAPABILITY_NOT_ENABLED, o el bloque se omite.
4. **Permiso de la operación** (Tu usuario): El mismo que pide la pantalla equivalente. Si no: PERMISSION_DENIED con el permiso que falta.
5. **Está en el Gestor para ti** (El archivo): Carpetas que ves, lo tuyo en Inicio y lo vinculado a fichas que ves. Si no: FILE_NOT_FOUND, igual que si no existiera.

El último paso es el perímetro del servidor, y es el mismo para el listado y para cada operación por `id`. Un archivo está en el Gestor para la persona si está en una carpeta que ve (también por herencia o por su departamento), si es suyo y está en Inicio, o si está vinculado a una ficha que ve y la conexión lleva el [acompañante](#acompañantes-de-las-fichas) de esa ficha.

Lo que solo se alcanza desde otro módulo queda fuera aunque la persona lo abra en la aplicación: los justificantes de gastos y de ausencias, los adjuntos de tickets y de mensajes directos y los documentos de RRHH. Responden `FILE_NOT_FOUND`, con una pista que dice dónde se leen. Los adjuntos de un ticket o de un elemento de trabajo se leen con el mismo lector desde su herramienta, con `read_attachment`: [`tickets`](https://os.utilia.ai/docs/developers/mcp/tickets#tickets) (o `my_tickets`, si el ticket es tuyo, también desde este servidor), [`utilia_support`](https://os.utilia.ai/docs/developers/mcp/utilia-support#leer-un-adjunto) para un ticket al soporte de UTILIA OS e `issues`, en `utilia-work`. Lo compartido en una conversación se lee con `chat_conversations` `get_file`, en `utilia-chat`, y el justificante de un gasto se descarga con `expenses` `document_get`, en `utilia-finance`. Lo que tiene bloqueado el acceso de la IA y las claves privadas responden también como si no existieran.

## Herramientas

| Herramienta | Para qué sirve |
| - | - |
| `files` | Encontrar, leer y mirar archivos: el listado con filtros, la ficha del archivo, el texto por páginas, buscar dentro, las páginas de un PDF, las hojas de cálculo, las versiones, «Eliminados recientemente», las etiquetas y los enlaces de un archivo. Solo lectura. |
| `files_manage` | Subir, crear, traer de internet, descargar, renombrar, mover, copiar, editar, eliminar, recuperar, etiquetar, vincular a una ficha y crear o anular enlaces públicos. |
| `folders` | El árbol de carpetas, lo que hay en una carpeta, encontrar una carpeta por su ruta y quién tiene acceso. Solo lectura. |
| `folders_manage` | Crear carpetas y rutas, cambiarlas, moverlas, eliminarlas y dar o quitar acceso. |
| [`search`](https://os.utilia.ai/docs/developers/mcp/search-and-notifications) | Encontrar un archivo o una carpeta por su nombre o por lo que dice dentro, con el fragmento. |
| `users` | El identificador de una persona, para darle acceso a una carpeta. |
| `org_plan`, `notifications`, `my_tickets` y [`utilia_support`](https://os.utilia.ai/docs/developers/mcp/utilia-support) | El plan, los avisos, los tickets propios y el soporte de UTILIA OS, como en los demás servidores. |

`files` y `folders` se anuncian como solo lectura, así que los clientes no piden permiso en cada consulta. La descarga temporal (`download_url`) está en `files_manage` a propósito: es una llave para bajar el archivo, y tu cliente pide confirmación antes de usarla. `files_manage` se ve con cualquiera de los cinco scopes, y descargar pide uno de los tres de archivos (`files:items:view`, `files:items:manage` o `files:items:delete`).

## Scopes

Son cinco, separados por lo que hacen. La columna central es el texto que ve la persona en la [pantalla de consentimiento](https://os.utilia.ai/docs/developers/oauth/consent-screen).

| Scope | Lo que consiente la persona | Segundo paso al concederlo |
| - | - | - |
| `files:items:view` | Ver los archivos y carpetas del Gestor de archivos y su contenido | No |
| `files:items:manage` | Subir, crear, traer de internet, editar, mover, copiar y organizar archivos y carpetas, vincularlos a fichas y crear enlaces para que alguien suba archivos | No |
| `files:items:delete` | Eliminar archivos y carpetas, también para siempre | Sí |
| `files:folders:share` | Dar y quitar a personas y departamentos el acceso a carpetas | Sí |
| `files:links:share` | Crear enlaces públicos a archivos, que abre cualquiera sin iniciar sesión; cada uno se aprueba en tu móvil | Sí |

- **Ninguno entra en un conjunto** (`crm:full`, `dev:full`, `admin:full`...): se piden por su nombre.
- **`files:links:share` no va nunca en una clave de conexión** ni en los conectores de los directorios de Claude y ChatGPT: solo en una autorización por navegador.
- **Quién puede concederlos.** `files:items:manage` lo concede quien tenga cualquiera de estos permisos: «Subir archivos», «Crear carpetas», «Editar carpetas», «Gestionar etiquetas», «Restaurar versiones» o «Vincular CRM». `files:items:delete`, «Eliminar carpetas» o «Gestionar lo que eliminan otros». Concederlo no abre nada más: cada operación sigue pidiendo su propio permiso.
- **Operaciones que piden dos scopes.** Editar sin conservar la versión anterior, quitar la última carpeta o el último vínculo de un archivo y eliminar una versión piden además `files:items:delete`, porque el archivo o la versión se pierden.

### Acompañantes de las fichas

Para filtrar por una ficha, guardar en su carpeta o vincular un archivo a ella, la conexión de archivos lleva además el scope que ya pide esa ficha en su propio servidor. Viajan por `/api/mcp/files` como acompañantes, por una lista cerrada, y solo sirven para eso: no abren ninguna otra herramienta del otro dominio.

| Ficha (`entity.type`) | Para ver | Para escribir |
| - | - | - |
| `client`, `contact`, `lead`, `project`, `opportunity`, `budget`, `interaction` | `crm:files:view` | `crm:files:upload` |
| `supplier` | `finance:suppliers:view` | `finance:suppliers:update` |
| `supplier_contact` | `finance:supplier-contacts:view` | `finance:supplier-contacts:manage` |
| `dev_project` (cuenta o proyecto de trabajo) | `dev:projects:view` | `dev:projects:update` |
| `dev_issue` (elemento de trabajo) | `dev:issues:view` | `dev:issues:update` |

Sin el acompañante, la llamada responde `INSUFFICIENT_SCOPE` con `requiredScopes` y, en una conexión OAuth, `grantUrl`, el enlace para que la persona lo conceda sin volver a conectar.

## `files`: encontrar, leer y mirar

| Operación | Qué hace | Permiso | Capacidad |
| - | - | - | - |
| `search` | El listado con filtros. | Ver archivos; con `entity`, además ver la ficha | Los vínculos de una ficha, Archivos avanzados |
| `get` | La ficha técnica del archivo (tamaño, páginas, resolución, duración y códecs), de uno o de varios (`ids`, hasta 20). | Ver archivos | Las versiones y los vínculos, Archivos avanzados |
| `read` | El texto por páginas; una imagen, para verla. | Ver archivos; con `version`, además «Ver versiones» | Con `version`, Archivos avanzados |
| `find` | Dónde sale una palabra o una frase dentro del archivo. | Igual que `read` | Igual que `read` |
| `view` | Páginas de un PDF como imagen. | Ver archivos | — |
| `table` | Hojas de cálculo XLSX, CSV, XLS y ODS. | Ver archivos | — |
| `versions` | Las versiones, con quién y cuándo. | «Ver versiones» | Archivos avanzados |
| `compare` | Lo que cambió entre dos versiones. | «Ver versiones» | Archivos avanzados |
| `trash` | «Eliminados recientemente», con sus propios filtros. | Ver archivos; lo de otras personas, «Gestionar lo que eliminan otros» | — |
| `tags` | Las etiquetas que ve la persona. | Ver archivos | — |
| `share_links` | Los enlaces públicos de un archivo, sin la dirección. | «Compartir con un enlace» | — |
| `favorites` | Los favoritos de la persona, archivos y carpetas, en el orden de su barra lateral, con su ruta. | Ver archivos | — |

Todas aceptan cualquiera de los cinco scopes, y todas pasan por el perímetro.

### Encontrar un archivo

Dos herramientas, para dos preguntas distintas:

**files search o search**

#### files search (El listado con filtros)

Casa las palabras con el nombre del archivo y con los nombres de sus carpetas visibles, sin tildes. Filtra por carpeta, tipo, fecha, etiqueta, ficha y tamaño.

#### search (Encontrar)

Encuentra por el nombre o por lo que dice dentro, con el fragmento que casa. Lo de dentro necesita la Búsqueda por dentro encendida en la empresa.

`files search` admite `query` (hasta 200 caracteres; casa también con el nombre que tiene el archivo en cada carpeta que la persona ve), `folderId` o `path` con `includeSubfolders` (por defecto `true`), `entity` con `includeRelated`, `kinds` (`image`, `pdf`, `document`, `spreadsheet`, `presentation`, `video`, `audio`, `archive` y `other`), `extensions`, `mimeTypes` (exactos, como `image/png`), `owner` (`me` u `others`: no se filtra por una persona concreta), `tags` (hasta 10, por nombre o id), `from` y `to` (fechas incluidas) con `dateField` (`modified` o `uploaded`), `largerThan` y `smallerThan` en bytes, `orphan` (los sueltos de Inicio, sin carpeta ni ficha), `sort` y `order`. Devuelve 20 por página, 50 como mucho.

```json
{
  "name": "files",
  "arguments": {
    "operation": "search",
    "query": "contrato marco",
    "path": "Clientes/Acme",
    "kinds": ["pdf", "document"],
    "from": "2026-01-01"
  }
}
```

```json
{
  "items": [
    { "id": "cmf1a2b3c", "name": "Contrato marco Acme.pdf", "kind": "pdf", "size": 2483011, "modifiedAt": "2026-10-20T16:40:00Z", "path": "Clientes/Acme/Contratos", "matchedBy": "name" }
  ],
  "pageInfo": { "nextCursor": "eyJvIjoyMH0", "hasMore": true, "pageSize": 20, "responseFormat": "concise" },
  "totalAtLeast": 21
}
```

- `matchedBy` dice si casó por el nombre del archivo (`name`) o solo por el de una carpeta (`folder`, con la carpeta en `matchedFolder` y el aviso `MATCHED_BY_FOLDER`); los que casan por el nombre van primero. `path` es la primera ubicación visible, o `null`.
- `total` solo llega cuando es exacto; si no, `totalAtLeast`. Una página solo llega vacía con `nextCursor` si se agotó la exploración sin nada que la persona pueda ver, y entonces lo dice el aviso `SCAN_LIMIT`: sigue con el cursor o afina la búsqueda. Fuera de ese caso, `hasMore` solo es cierto si queda algo: la página siguiente nunca llega vacía.
- Con `response_format: "detailed"`, cada fila añade el tipo, quién lo subió, la versión, las etiquetas y, si ya se conocen, `totalPages` y `ranges`.

Con `entity`, la búsqueda trae lo vinculado a esa ficha y lo que la ficha tiene como propio (el logotipo, la foto, el PDF del presupuesto, los adjuntos de la interacción, los documentos del proyecto); cada fila dice de dónde sale en `source`. Los vínculos necesitan Archivos avanzados: sin la capacidad llega solo lo propio, con el aviso `OMITTED_BY_PLAN`. `includeRelated` suma las fichas relacionadas (los contactos, proyectos, oportunidades, presupuestos e interacciones de un cliente; los presupuestos e interacciones de una oportunidad; los elementos de una cuenta de trabajo...), cada una con su permiso y su acompañante. La que no los tiene, no entra, sin error.

### La ficha del archivo

`get` es la ficha técnica: los datos comunes (nombre, tipo, tamaño, quién lo subió y cuándo, ubicaciones visibles), dónde se usa, si el cliente lo ve en su portal, las etiquetas, si está en los favoritos de la persona (`favorite`), los enlaces activos, cómo se lee y los datos de su tipo: dimensiones, resolución y espacio de color de una imagen; duración, resolución y códecs de un vídeo o un audio; páginas, tamaño de página y si está cifrado un PDF; palabras, caracteres y tablas de un Word; diapositivas de una presentación, y hojas con sus filas y columnas de un libro. Esta es una respuesta real:

```json
{
  "file": {
    "id": "cmw8gxq6o008ph1yvhhtwz7xl",
    "name": "contrato-marco-acme.pdf",
    "extension": "pdf",
    "kind": "pdf",
    "mimeType": "application/pdf",
    "size": 66994,
    "sizeLabel": "65,4 KB",
    "uploadedBy": { "id": "cmvnvgh1r005sufyvletsr4kn", "name": "Prueba Alta" },
    "uploadedAt": "2026-11-08T23:33:41.712Z",
    "modifiedAt": "2026-11-08T23:34:03.109Z",
    "paths": ["Pruebas MCP archivos/Contratos"],
    "versionsCount": 0,
    "portalVisible": false,
    "activeShareLinks": 0,
    "reading": { "method": "text", "totalPages": 40, "totalChars": 88944, "scanned": false, "ranges": ["1-12", "13-24", "25-36", "37-40"] },
    "pdf": { "pages": 40, "encrypted": false }
  },
  "openInApp": "https://os.utilia.ai/dashboard/file-manager/files/cmw8gxq6o008ph1yvhhtwz7xl",
  "nextSteps": [
    { "tool": "files", "operation": "read", "why": "Para resumirlo, lee todas sus partes a la vez, una llamada por rango.", "args": "id: 'cmw8gxq6o008ph1yvhhtwz7xl' y pages: \"1-12\", \"13-24\", \"25-36\", \"37-40\", una llamada por rango" },
    { "tool": "files", "operation": "find", "why": "Para una pregunta concreta, busca dentro y lee solo las páginas donde sale.", "args": "id: 'cmw8gxq6o008ph1yvhhtwz7xl', query y, si quieres, terms con sinónimos" }
  ]
}
```

- **Cada bloque sale solo con su permiso**: dónde se usa (`usedIn`), con el de cada ficha y su acompañante; lo de Finanzas, solo como señal (`usedIn.finance`, sin datos) con el paso a `utilia-finance`; `portalVisible`, con el de ver al cliente; `activeShareLinks`, con «Compartir con un enlace», como `share_links`; las versiones (`versionsCount`), con «Ver versiones». Un archivo sin cambios tiene `versionsCount: 0`.
- **Sin Archivos avanzados**, las versiones y los vínculos se omiten y la respuesta lo dice en `omittedByPlan`, con el plan que los incluye y `upgradeUrl`.
- **`locations`** (`[{ path, name }]`) llega cuando el archivo se llama distinto en alguna de sus carpetas.
- **Hojas de cálculo**: `office.sheetList` da cada hoja con `name`, `rows`, `columns` y `hidden` si está oculta. `rows` cuenta filas de datos, sin la de títulos, igual que el `rowCount` de `table`, y `headerRow: true` dice que la hay; lo mismo `text.rows` de un CSV. Solo las 20 primeras hojas de un libro traen filas y columnas; las demás, su nombre.
- **Word y OpenDocument**: `office.words` y `office.characters` (con espacios) se cuentan aunque el documento no los guarde, sin lo borrado con control de cambios, los códigos de campo ni los comentarios. `office.tables` sale siempre, también con 0. `office.pages` solo llega si el propio documento la guarda.
- **Lo que no se puede leer desde aquí** lo dice `reading`: `method: "none"`, el motivo en `reason` y qué hacer en `note`. Un documento o un libro de más de 20 MB da sus cifras y sus hojas con `reason: "too_large"`; una imagen que el servidor no sabe abrir (un BMP o un PSD), `reason: "unsupported"`, y su `note` propone que la persona la abra en la aplicación o descargarla. Una foto HEIC o HEIF del iPhone se puede ver (`method: "image"`) siempre que el servidor pueda convertirla en ese momento; si no, sale con `reason: "unsupported"` y la ficha se vuelve a calcular en unos minutos.
- **Un escaneado** lleva `reading.scanned: true`; en un PDF con páginas escaneadas y páginas con texto, `reading.scannedPages` dice cuáles gastan el cupo de OCR («12-40»). Si sus páginas ya se han leído enteras hace poco, volver a leerlas no gasta cupo y la ficha lo dice con `alreadyRead: true` y su `totalChars`; sigue diciendo `scanned: true`, porque el documento sigue siendo un escaneado.
- **Con `ids`**, la ficha técnica se calcula para el primero y para los que ya la tenían; los demás llevan `technicalPending: true` y el aviso `TECHNICAL_INFO_DEFERRED` dice cuáles: pídeles su `get`.
- **`antivirus`** llega en la ficha solo cuando hay algo que saber, igual que en `versions`: `infected` (en cuarentena: no se lee, ni se descarga, ni se restaura), `pending` (se está analizando: su ficha sale sin lectura, con `reading: { method: "none" }`, y leerlo o descargarlo responde `FILE_SCAN_PENDING`) o `unverified` (el antivirus no ha podido analizarlo y lo volverá a intentar: se lee y se descarga, pero no sale de la empresa por un enlace público, el portal del cliente ni el correo de un presupuesto hasta que se analice).
- **`openInApp`** es la ficha del archivo en la aplicación y va junto a `file`, no dentro. Llega en `get`, en lo recién guardado (`create`, `import_url`, `confirm_upload`, `move`, `copy` y `add_to_folder`) y en los errores cuyo siguiente paso es de la persona. En `folders get` es la carpeta en la aplicación.

### Leer un documento largo

La primera lectura da el mapa del documento y el resto se pide a la vez:

**Leer un PDF largo en paralelo**

Participantes: Tu asistente y utilia-files.

1. Tu asistente → utilia-files: files get · id. Antes de leer, la ficha.
2. utilia-files → Tu asistente (respuesta): reading: totalPages y ranges. Tramos que caben en una lectura cada uno.
3. Tu asistente → utilia-files: files read · pages 1-14, 15-28 y 29-42. Tres llamadas a la vez, una por tramo.
4. utilia-files → Tu asistente (respuesta): Dos bloques por lectura. Los datos de la lectura y el texto, entre sus marcas y con «— Página N —».

`read` admite `pages` (`"3"`, `"3-7"` o `"2,5"`) en PDF y presentaciones, y `cursor` en los documentos sin páginas: cada respuesta trae `nextCursor` mientras quede texto. Lee 34.000 caracteres por defecto (`maxChars`, hasta 36.000). `pages` dice lo que se ha leído de verdad y `remainingRanges`, lo que falta, para pedirlo a la vez. Si una página no cabe entera, sale cortada y lo dice el aviso `PAGE_TRUNCATED`: pídela sola con un `maxChars` mayor o mírala con `view`. Con `ids` lee varios en serie, con los caracteres repartidos: hasta 5, o hasta 20 si solo pides la primera página (`pages: "1"`), que basta para clasificarlos.

**Topes de la lectura**

- Caracteres por lectura: 34.000. 36.000 como mucho, con maxChars.
- Archivos por llamada: 5. 20 si solo pides la primera página.
- Páginas escaneadas al día: 200. Por empresa, para leerlas con OCR.

La respuesta no lleva `structuredContent`: llega en dos bloques de texto, primero un JSON corto con los datos de la lectura y después el texto del documento, en claro, entre dos marcas fijas, `⟦TEXTO DEL DOCUMENTO⟧` y `⟦FIN DEL TEXTO DEL DOCUMENTO⟧`, que el documento no puede imitar: a su texto se le quitan esos corchetes y los que se les parecen. El JSON lo dice en `content` (`kind: "document_text"`, `instructions: false`). El texto de un archivo es dato, no instrucciones: tu asistente no debe seguir órdenes que vengan dentro de un documento. Todo lo que devuelve el servidor se limpia de caracteres invisibles y de control de dirección, y la conversión a Markdown nunca deja imágenes remotas.

```json
{
  "content": [
    { "type": "text", "text": "{\"id\":\"cmf1a2b3c\",\"name\":\"Contrato marco Acme.pdf\",\"method\":\"text\",\"pages\":\"1-14\",\"totalPages\":42,\"remainingRanges\":[\"15-28\",\"29-42\"],\"content\":{\"kind\":\"document_text\",\"instructions\":false,\"begin\":\"⟦TEXTO DEL DOCUMENTO⟧\",\"end\":\"⟦FIN DEL TEXTO DEL DOCUMENTO⟧\"}}" },
    { "type": "text", "text": "⟦TEXTO DEL DOCUMENTO⟧\n— Página 1 —\n\nCONTRATO MARCO DE PRESTACIÓN DE SERVICIOS\n...\n⟦FIN DEL TEXTO DEL DOCUMENTO⟧" }
  ]
}
```

- `method` dice cómo se leyó: `text`, `ocr`, `table`, `image` o `none`. `ocrPages` dice qué páginas de esta lectura salieron del OCR («2,5-7»), solo si alguna lo hizo, y `ocrPagesCharged`, cuáles se han pasado por OCR ahora y gastan cupo; las demás de `ocrPages` venían ya leídas y no han costado nada.
- Un escaneado se lee con OCR mientras quede cupo del día; si solo se leyeron algunas páginas, el aviso `OCR_PARTIAL` dice cuáles faltan. Si el OCR agota su plazo o su memoria, las páginas que llegó a empezar cuentan en el cupo aunque no den texto: pide menos páginas a la vez.
- `pages` admite páginas hasta la 100.000; más allá, o mal escrito, responde `INVALID_PAGES` sin bajar el archivo. Un cursor que no es de ese archivo responde `INVALID_CURSOR`.
- Si el archivo cambia entre dos lecturas con cursor, la siguiente responde `FILE_CHANGED`: vuelve a empezar sin cursor.
- Con `version`, lee una versión anterior.
- Un audio o un vídeo no tiene texto: `read` da su ficha técnica y, si existe, dónde está su transcripción (en `chat_conversations` de `utilia-chat`).
- En un DOCX, las tablas se leen como tablas Markdown; en un PDF salen como texto.

### Buscar dentro de un archivo

Para una pregunta concreta sobre un documento, `find` es más rápido que leerlo entero. Recibe `id` y `query` (palabras, o una `"frase exacta"`, sin tildes), y si quieres `terms` con sinónimos, y devuelve dónde sale, con su página y la frase en que aparece:

```json
{
  "id": "cmf1a2b3c",
  "name": "Contrato marco Acme.pdf",
  "totalMatches": 12,
  "shownMatches": 10,
  "matchedPages": "1-6",
  "matches": [
    { "page": 1, "offset": 1420, "context": "…la duración del contrato será de doce meses, prorrogables…" }
  ],
  "complete": true,
  "_notices": {
    "items": [
      { "code": "MORE_MATCHES", "message": "Hay 12 coincidencias y aquí van 10. Las páginas donde salen todas están en matchedPages: léelas con read o sube maxMatches (hasta 30).", "totalMatches": 12, "shownMatches": 10 }
    ]
  }
}
```

- **`matchedPages`** trae todas las páginas con alguna coincidencia, también las de las que no se enseñan. Para responder «¿en qué páginas sale?», usa `matchedPages`, no las páginas de `matches`.
- **`shownMatches`** y el aviso `MORE_MATCHES` solo llegan si hay más coincidencias de las que se enseñan: 10 por defecto y 30 como mucho (`maxMatches`).
- **`complete: true`** quiere decir que se ha buscado en todo el documento.
- Cada `context` es la frase de la coincidencia; dos coincidencias seguidas de la misma página no repiten texto.
- Busca en el mismo texto que lee `read`, y `nextSteps` propone leer enteras las páginas de `matchedPages`.

### Ver imágenes y páginas

- **Una imagen** se ve con `read`: devuelve un bloque `image` con la variante de 1.440 px (`variant: "md"`, por defecto), la miniatura (`thumb`) o el original si pesa menos de 1,5 MB, y un JSON con lo que se devuelve (`preview`: anchura, altura, formato y variante) y las medidas de la imagen real (`original`).
- **Una foto HEIC o HEIF del iPhone** se ve igual, con su variante `md` o `thumb`, en WebP, derecha y sin los datos de la cámara ni la ubicación: el servidor la convierte. Su original no se entrega por aquí (`variant: "original"` responde `NOT_READABLE`); para el archivo tal cual, `files_manage` `download_url`. Si el servidor está ocupado convirtiendo otra, responde `EXTRACTOR_BUSY` con `retryAfterSeconds`.
- **Las páginas de un PDF**, como planos o escaneados, se ven con `view`: hasta 5 por llamada en `thumbnail` o `medium` (por defecto) y 2 en `high`.

### Hojas de cálculo

`table` lee XLSX, CSV (con el separador y la codificación que tenga), XLS y ODS. Sin `mode`, da en una sola llamada las hojas, las columnas con su tipo (`number`, `date`, `text` o `boolean`), las 20 primeras filas y el recuento.

| `mode` | Qué devuelve |
| - | - |
| `sheets` | Las hojas con sus dimensiones. |
| `rows` | Filas, con `columns`, `filters` (todas se cumplen), `sortBy` y `order`, `offset` y `limit` (100 por defecto, 500 como mucho). |
| `aggregate` | Agrupado por `groupBy` (hasta 5: una columna, o `{ "column": "Fecha", "by": "month" }` para agrupar fechas por `day`, `month`, `quarter` o `year`), con `metrics`: `sum`, `avg`, `min`, `max`, `count` (sin `column`, cuenta filas) y `count_distinct`. Admite `limit` y `offset`. |
| `stats` | Por cada columna numérica, el mínimo, el máximo, la media, la suma y las vacías. |

Los filtros admiten `eq`, `ne`, `contains`, `not_contains`, `starts_with`, `ends_with`, `gt`, `gte`, `lt`, `lte`, `between` (con `[mínimo, máximo]`), `empty` y `not_empty`. Un filtro con un valor que no es del tipo de su columna (un texto contra una cifra o una fecha) no casa con nada y lo dice el aviso `FILTER_VALUE_INVALID`. La hoja se pide por su nombre o por su posición desde 0 (`sheet`). Las columnas se nombran sin importar tildes ni mayúsculas (una que no existe responde `COLUMN_NOT_FOUND` con `missing` y las que hay), y los números con formato español (coma decimal y punto de miles) llegan como números. Todas las salidas llevan arriba el `id` y el `name` del archivo. Las filas viajan en formato compacto, con la cabecera una sola vez, y `shownRows` y `hasMore` dicen cuántas van y si quedan:

```json
{ "columns": ["Fecha", "Cliente", "Importe"], "rows": [["2026-10-01", "Acme", 1250.5]], "rowCount": 412, "shownRows": 1, "hasMore": true }
```

Una hoja XLS u ODS muy grande puede llegar cortada: `truncated: true` (solo entonces) y el aviso `TABLE_TRUNCATED`. Sobre ella, `aggregate` y `stats` se niegan, porque darían cifras falsas. De cualquier hoja se leen como mucho 200 columnas, con nombres de hasta 100 letras. Cada respuesta tiene un tope de 36.000 caracteres: si no caben las filas pedidas, salen las que caben, con `hasMore: true` y el aviso `TABLE_CHARS_LIMIT`.

### Versiones, Eliminados recientemente, etiquetas y enlaces

- **`versions`** lista los contenidos que ha tenido el archivo, con quién, cuándo, la nota del cambio que produjo cada uno y el tamaño (20 por página, hasta 50, con `pageInfo` y `total`). Es el mismo historial que ve la persona en la aplicación. Lo vivo puede salir como entrada propia (`version: "current"`), `current` marca dónde están los bytes vivos, `original` el contenido con que se subió (solo la versión 1, o lo vivo si nunca cambió), con la fecha de alta y quién lo subió; si ese contenido se sustituyó antes sin guardar historial, ya no lleva `original` ni fecha, persona o nota, porque no se sabe quién lo cambió; `sameAs` otra versión con los mismos bytes y `sameAsCurrent` una que guarda lo mismo que lo vivo (restaurarla no cambiaría nada). `antivirus` solo llega cuando hay algo que saber, con los mismos tres valores que en `get`: `infected`, en cuarentena (no se lee, ni se descarga, ni se restaura); `pending`, se está analizando (leerla o descargarla responde `FILE_SCAN_PENDING`), o `unverified`, el antivirus no ha podido analizarla y lo volverá a intentar (se lee y se descarga). Si se borró la versión anterior a una, esa va sin nota, fecha ni persona: no se sabe qué cambio la produjo y no se inventa. Un archivo sin versiones guardadas responde `items: []`, `total: 0` y `note`: «Este archivo no tiene versiones anteriores: solo su contenido actual.». **`compare`** da las líneas añadidas y quitadas, con su página, entre `version` y `toVersion` (por defecto, lo vivo, `to: "current"`); sin `version`, compara lo vivo con la versión más reciente que es distinta. Hasta 200 líneas. Si no hay diferencias, responde `{ id, name, from, to, identical: true }`. Las dos piden Archivos avanzados. La guía de uso del historial está en [Historial de versiones](https://os.utilia.ai/docs/guides/files/versions).
- **`trash`** recorre «Eliminados recientemente», de lo más reciente a lo más antiguo: lo de la persona siempre y lo de otras con «Gestionar lo que eliminan otros», dentro de su alcance. Filtra por `query` (el nombre), `kind` (`file` o `folder`), `from` y `to` (cuándo se eliminó) y `owner` (quién lo eliminó: `me` u `others`); los filtros de `search` y `dateField` no valen aquí y responden `VALIDATION`. Cada fila dice cuándo se eliminó y quién, cuántos días le quedan y de dónde salió, con la ruta entera. Con `hasMore`, la página siguiente trae algo seguro.
- **`tags`** da las etiquetas que la persona ve, las suyas y las de toda la empresa, con cuántos archivos llevan de los que ella ve (`files`).
- **`favorites`** da los favoritos de la persona, archivos y carpetas, en el orden de su barra lateral: los que sigue viendo en el Gestor. Cada uno trae `kind` (`file` o `folder`), `id`, `name` y `path`, la ruta visible de la carpeta o de la carpeta donde está el archivo (`null` si está en Inicio o solo en una ficha); un archivo, además, `mimeType` y `size`. Admite `kind` para pedir solo archivos o solo carpetas (otro valor responde `VALIDATION`), y `limit` (20 por defecto, 50 como mucho) con `cursor`. Recorre hasta 500 favoritos: con más, `truncated: true` y `total` es un mínimo. Si un archivo está en favoritos lo dice también `favorite` en `get`.
- **`share_links`** da los enlaces públicos de un archivo, activos y terminados en los últimos 30 días, sin la dirección: solo se entrega al crearlo. Arriba, el `id` y el `name` del archivo. Si no se puede crear uno, `createBlockedReason` dice por qué y, si es del plan, cuál lo incluye y `upgradeUrl`.

## `files_manage`: guardar y cambiar

| Operaciones | Qué hacen | Scope | Permiso |
| - | - | - | - |
| `request_upload`, `confirm_upload`, `abort_upload` | Subir desde el disco en dos pasos. | `files:items:manage` | «Subir archivos» |
| `create_upload_link` | Un enlace para que la persona suba desde su navegador. | `files:items:manage` | «Subir archivos» y editar la carpeta |
| `create`, `import_url` | Un archivo nuevo desde texto o desde internet. | `files:items:manage` | «Subir archivos» |
| `download_url` | Una descarga temporal. | `files:items:view`, `files:items:manage` o `files:items:delete` | Ver archivos |
| `rename`, `move` | Cambiar el nombre y mover. | `files:items:manage` | «Editar carpetas» |
| `copy`, `add_to_folder`, `remove_from_folder` | «Hacer una copia», «Añadir también a…» y «Quitar de esta carpeta». | `files:items:manage` | «Subir archivos» |
| `edit`, `patch` | «Editar contenido»: el texto entero o un fragmento. | `files:items:manage` | «Editar carpetas» |
| `restore_version`, `delete_version` | Volver a una versión o eliminarla. | `files:items:manage`; eliminarla, `files:items:delete` | «Restaurar versiones» |
| `delete`, `restore`, `purge` | Eliminar, recuperar y «Eliminar definitivamente». | `files:items:delete`; recuperar, `files:items:manage` o `files:items:delete` | «Eliminar carpetas»; recuperar, ver archivos |
| `tag`, `untag`, `tag_update`, `tag_delete` | Etiquetas. | `files:items:manage` | «Gestionar etiquetas» |
| `link`, `unlink` | Vincular a una ficha o quitar el vínculo. | `files:items:manage` y el acompañante | «Vincular CRM» y editar la ficha |
| `share_link_create`, `share_link_revoke` | Crear un enlace público o «Anular el enlace». | `files:links:share` | «Compartir con un enlace» |
| `favorite`, `unfavorite` | Marcar o quitar favoritos, archivos y carpetas, por `id` o `ids` (el servidor sabe si cada uno es un archivo o una carpeta) o con `items: [{ kind, id }]`. Cada fila dice `outcome`: `added`, `already`, `removed` o `not_favorite`; marcar lo que ya lo está, o quitar lo que no, no es un fallo. | `files:items:manage` | Ver archivos |

Los lotes admiten hasta 50 elementos (`ids` o `items`) y 20 en las subidas. Todos responden igual: un resultado por elemento, en el orden en que los pediste, y el resumen, así que un fallo no tumba el resto:

```json
{
  "results": [
    { "index": 0, "id": "cmf1a2b3c", "ok": true, "outcome": "trashed" },
    { "index": 1, "id": "cmf9z8y7x", "ok": false, "errorCode": "FILE_NOT_FOUND", "message": "No hay ningún archivo con ese id en el Gestor de archivos a tu alcance.", "hint": "Comprueba el id con files search." }
  ],
  "summary": { "total": 2, "ok": 1, "failed": 1 },
  "_notices": {
    "items": [
      { "code": "NOT_FOUND_ELSEWHERE", "message": "Si es un adjunto de un ticket, léelo con read_attachment de tickets (utilia-crm o utilia-work) o, si el ticket es tuyo, de my_tickets; …", "ids": ["cmf9z8y7x"] }
    ]
  }
}
```

- **`index`** es la posición del elemento en tu petición; un id repetido cuenta una vez.
- **`id`** solo llega si el elemento existe: un documento o una carpeta que no se ha podido crear no tiene `id`, y lo reconoces por su `index` y su `name`.
- **Una fila que falla** trae siempre `errorCode`, `message` y `hint`, y su pista dice «repite solo este elemento»: reintenta solo esas filas, nunca el lote entero.
- **Los avisos de una fila** (un `rename` que conservó la extensión, por ejemplo) llegan en `_notices.items`, con el `index` y el `id` de su fila.
- **La pista de «no encontrado»**: cada fila `FILE_NOT_FOUND` dice «Comprueba el id con files search.». En los lotes de lectura (`get` y `read`), dónde se lee lo que no es del Gestor llega una sola vez en el aviso `NOT_FOUND_ELSEWHERE`, con sus `ids`.
- **`createdFolders`** (`id` y `path`) llega arriba siempre que `ensurePath` ha creado carpetas: en `request_upload`, `create`, `import_url`, `move`, `copy` y `add_to_folder`.

> **Atención: La forma de los lotes cambió el 9 de noviembre**
>
> Las filas ya no traen `success` ni `fileId`, y las respuestas ya no traen `succeeded`, `failedItems` ni `operation`. Lee `ok` e `id` en cada fila, y `summary` arriba. El detalle está en [Cambios de las integraciones](https://os.utilia.ai/docs/developers/changelog/integrations#2026-11-09).

`request_upload`, `create`, `import_url`, `copy` y `folders_manage` `create` admiten `idempotencyKey`: la misma clave con los mismos datos devuelve el resultado de la primera vez, y con otros datos responde `IDEMPOTENCY_KEY_REUSED`. Repetir con `confirm: true` y la misma clave es la misma alta, y una respuesta que no ha escrito nada (pedir confirmación, un argumento que no vale) no gasta la clave. Para reintentar solo las filas que fallaron de un lote, usa una clave nueva.

### Dónde va un archivo

Las operaciones que guardan (`create`, `import_url`, `request_upload` y `move`) reciben el destino de una de tres formas. Con la persona se habla con rutas; con la herramienta, con identificadores:

**¿Cómo le dices dónde va?**

¿Va a la carpeta de una ficha, como un cliente o un presupuesto?

- Sí: **entity** (`{ type, id }`). La carpeta de esa ficha, creada si falta; además, el archivo queda vinculado a ella.
- No: ¿Te ha dado la persona una ruta?
  - Sí: **path** (`Clientes/Acme`). Con ensurePath crea lo que falte de la ruta.
  - No: **folderId**. El identificador de la carpeta, o null en move para Inicio.

* Las rutas van por tramos con «/» (`Clientes/Acme/Contratos`); al entrar se acepta también « › ». Las respuestas las dan siempre con «/».
* `ensurePath` admite `allowSimilar: true`, en la llamada o dentro de cada `to` (`files[].to`, `documents[].to` y `moves[].to`), para crear la ruta pedida aunque haya una carpeta casi igual.
* `ensurePath` crea lo que falte de la ruta solo si la persona tiene el permiso «Crear carpetas» y, dentro de otra carpeta, el nivel «Gestionar» en ella; si no, responde `PERMISSION_DENIED` sin crear nada. Cada tramo se valida como un nombre de carpeta en la aplicación: sin caracteres de control ni invisibles, sin `: * ? " < > | #` y sin punto al final. Donde la operación admite `ensurePath`, la pista de `PATH_NOT_FOUND` dice que repitas con `ensurePath: true` si la persona quiere crear la ruta.
* `entity` es `{ type, id }` o `{ type, name }`. Con un nombre que casa con varias fichas responde `ENTITY_AMBIGUOUS` con las candidatas, para que preguntes cuál.
* Con `entity` y `path`, la ruta va dentro de la carpeta de la ficha. Los clientes, los contactos, los proyectos comerciales, los presupuestos y las interacciones tienen carpeta propia; en las demás fichas el archivo queda vinculado sin carpeta, con el aviso `ENTITY_HAS_NO_FOLDER`.
* Guardar con `entity` pide Archivos avanzados, «Vincular CRM», poder editar la ficha y el acompañante de escritura.
* Si el destino lo ve más gente que el origen (también por el departamento dueño de la carpeta o por la ficha de una carpeta anclada), alguien con un rol externo o el cliente en su portal, la operación pide `confirm: true`, y sin él dice quién lo vería («Lo verán además 12 personas del departamento Ventas y el cliente en su portal»).

### Subir desde el disco

La subida es en dos pasos y el archivo nunca viaja dentro de la llamada:

1. `request_upload` con `files` (hasta 20), cada uno con `filename` y `fileSize`, el tamaño exacto en bytes, y opcionalmente `mimeType`, `to` (cada archivo a su sitio, también una ruta; con `ensurePath` crea las carpetas que falten) y `versionOf`. Cada archivo puede pesar hasta 2 GB. Devuelve una fila por archivo con su `id` (el de la reserva, que se pasa a los pasos siguientes), `uploadUrl`, `relayUploadUrl` y las cabeceras, válidos 15 minutos. Si `ensurePath` ha creado carpetas, la respuesta las trae en `createdFolders` (`id` y `path`) con el aviso `FOLDERS_CREATED`.
2. Un `PUT` de cada archivo a su `uploadUrl`, con su `Content-Type`. Si falla por la red, el mismo `PUT` a `relayUploadUrl`.
3. `confirm_upload` con `ids`, o con `files: [{ id, sha256 }]` para comprobar además la huella (`fileId` sigue valiendo en lugar de `id`; si mandas los dos y no coinciden, responde `VALIDATION`). Verifica el tamaño y el tipo real y deja el archivo en su carpeta; si no cuadra, lo descarta. Cada fila trae el nombre, el tipo, el tamaño y `openInApp` (y `placed: false`, `linkedTo` o `linkError` según el caso); arriba, el resumen y el siguiente paso. Si era una versión nueva, `id` es el archivo, `uploadId` la reserva, `version` el número que ha quedado, y el tamaño y el tipo son los de lo que acabas de subir. Una subida que ya se está confirmando responde `UPLOAD_IN_PROGRESS`. Una fila con `ok: true` quiere decir que el archivo está guardado y terminado: es la que te deja borrar tu copia. Si la confirmación no lo deja terminado, o no se puede comprobar, la fila responde `ok: false` con `UPLOAD_NOT_FINISHED`: no borres tu copia y confirma ese `id` otra vez pasados unos segundos, sin volver a hacer el `PUT`. Una fila con `ok: false` y `STORAGE_UNAVAILABLE` («El archivo todavía se está guardando») quiere decir que el archivo ya llegó y su reserva sigue: repite `confirm_upload` con ese `id` pasados unos segundos, sin volver a hacer el `PUT` ni reservarlo otra vez.

   Lo que se acaba de subir pasa por el antivirus, que suele tardar unos segundos. Mientras tanto la fila lleva `antivirus: "pending"` y la respuesta trae el aviso `SCAN_PENDING` con sus `ids` y `retryAfterSeconds`: hasta que termine, ese archivo no se puede leer, descargar ni compartir. Espera ese tiempo antes de usarlo y, si tras tres intentos sigue igual, no insistas: díselo a la persona. El análisis sigue solo y no hace falta volver a subir el archivo.

Mientras no se confirma, la reserva ya está en su carpeta como **subida sin terminar**: solo la ve quien la subió, la aplicación la enseña atenuada con «Continuar» y «Descartar», y `files get`, `files search` y `folders list` la marcan con `uploadPending: true`. No tiene contenido: leerla o descargarla responde `FILE_UPLOAD_PENDING`. Cada reserva sin confirmar ocupa uno de 20 huecos durante 24 horas: `abort_upload` los libera, y un id que no es una reserva tuya pendiente responde `UPLOAD_NOT_FOUND` en su fila. Si las carpetas a las que iba la subida se quedan vacías, también las de encima que se crearon para ella, la respuesta las nombra en `emptyFolders` con el aviso `FOLDERS_LEFT_EMPTY`, para que las elimines si se crearon solo para la subida. Si no quedan huecos, las filas que no se llegaron a reservar responden `TOO_MANY_UPLOAD_RESERVATIONS`. Con `versionOf`, lo subido es una versión nueva de ese archivo: pide Archivos avanzados, «Restaurar versiones» con un alcance que llegue a quien subió el archivo y poder editarlo, lo mismo que restaurar; si no, `PERMISSION_DENIED` antes de reservar nada. Si tu entorno no puede hacer peticiones, como ChatGPT en la web, `create_upload_link` con `folderId` o `path` da un enlace de 24 horas para que la persona suba desde su navegador. Las dos salidas y sus errores están en [Subir un archivo cuando el PUT no llega](https://os.utilia.ai/docs/developers/mcp/reference#subir-un-archivo-cuando-el-put-no-llega). Para subir a la ficha que pide un `fileId` en otro servidor (un gasto, una factura, un elemento de trabajo), está [`file_uploads`](https://os.utilia.ai/docs/developers/mcp/file-uploads) de ese servidor.

### Crear un documento

`create` guarda un archivo nuevo desde texto: `name` con su extensión y `content`, hasta 2 MB; o varios a la vez con `documents: [{ name, content, to? }]` (hasta 10). Los `.md`, `.txt`, `.csv`, `.json`, `.html`, `.xml`, `.yaml` y los de código se guardan tal cual. En `.docx` y `.pdf`, `content` es Markdown y UTILIA OS genera el documento. Lo que vaya a leer una persona, mejor en `.docx`; en `.md`, solo si lo pide.

```json
{
  "name": "files_manage",
  "arguments": {
    "operation": "create",
    "name": "Resumen de la reunión con Acme.docx",
    "path": "Clientes/Acme/Reuniones",
    "content": "# Reunión con Acme\n\n## Acuerdos\n\n- Entrega el 15 de diciembre.\n- Revisión quincenal.",
    "idempotencyKey": "resumen-acme-2026-11-08"
  }
}
```

Devuelve el archivo con su ruta, `openInApp` y el siguiente paso. En `.docx` y `.pdf`, `content` admite hasta 300.000 caracteres; el autor del `.docx` es la empresa. Crear un `.pdf` o un `.docx` y traer de internet van de uno en uno por persona (y tres a la vez por empresa): con otro en curso responde `FILES_MANAGE_BUSY`, con `retryAfterSeconds`. Lo creado pasa por las mismas comprobaciones que una subida (antivirus, almacenamiento, tipos de riesgo), queda marcado como creado por un asistente de IA, así que tu asistente puede leerlo después, y no suma puntos de gamificación.

### Traer de internet

`import_url` guarda en el Gestor un archivo de una dirección `https` pública, hasta 25 MB, con `name` opcional. El tipo se decide por el contenido, no por la extensión ni por la cabecera. Una dirección que no es `https`, con credenciales o con un puerto que no es el 443, o un tipo de riesgo, responde `IMPORT_URL_BLOCKED`; una que no responde, pasa de 25 MB o lleva a una red interna, `IMPORT_URL_UNREACHABLE`. Con `versionOf`, lo traído es una versión nueva de ese archivo, con las mismas puertas que restaurar comprobadas antes de descargarlo. El asistente de la aplicación no trae archivos de internet.

### Ordenar

- **`rename`**: `id` y `name` (o varios con `renames: [{ id, name }]`, hasta 50), como «Renombrar» en la web: dentro de una carpeta cambia el nombre que tiene ahí y, fuera de carpetas, el del archivo. Si está en varias carpetas, `fromFolderId` dice en cuál; sin él, `AMBIGUOUS_SOURCE`. Sin extensión se conserva la real (aviso `EXTENSION_KEPT`); con otra extensión, `EXTENSION_MISMATCH`. Responde el nombre guardado, releído.
- **`move`**: `ids` y el destino, o `moves: [{ ids, to }]` para varios destinos (`to`, una carpeta o `null` para Inicio). Si un archivo está en varias carpetas, `fromFolderId` dice de cuál sale; sin él responde `AMBIGUOUS_SOURCE` con sus rutas. Con `dryRun: true` devuelve lo que haría sin tocar nada (y `createsFolders` si crearía carpetas); si algo llegaría a más gente, la fila lleva `widensAudience` y arriba va `confirmReason`, por qué al hacerlo pedirá `confirm: true`. Sin `fromFolderId`, el origen es una carpeta del Gestor de la persona, nunca una del sistema ni de una conversación. Cada elemento responde su nombre, de dónde salió, adónde fue y `openInApp`.
- **`copy`**: «Hacer una copia» en el destino, solo de lo que está en el Gestor para la persona. Cada fila trae la copia (`copy: { id, name }`) y su `openInApp`.
- **`add_to_folder` y `remove_from_folder`**: `ids` y la carpeta en `to`, `folderId` o `path`. Quitar de una ficha no es esto: es `unlink`. Quitar la última carpeta de un archivo lo lleva a «Eliminados recientemente»: pide `confirm: true` y `files:items:delete`, y la fila responde `outcome: "trashed"` en vez de `"removed"`.
- **`dryRun`** solo existe en `move` y en `folders_manage` `ensure_path`. En cualquier otra escritura responde `VALIDATION` y no hace nada: para saber qué pasaría, llama sin `confirm`.

### Editar el contenido

`edit` sustituye el texto entero (`content`). `patch` cambia un trozo: `old_string` es el texto exacto, copiado de `read`; `new_string`, lo que lo sustituye; y `replace_all: true` lo cambia todas las veces que sale. Un `edit` con `old_string` responde `VALIDATION` y manda a `patch`. Solo en archivos de texto de hasta 5 MB: todo lo que se edita se lee, pero no todo lo que se lee se edita. Se conservan la codificación (UTF-8, UTF-16 o Windows-1252), la marca BOM y los saltos de línea; si el cambio trae un carácter que no cabe en la codificación del archivo, `NOT_EDITABLE` dice cuál. Los dos admiten `expectedVersion`, la versión que leíste: si alguien la cambió después, responden `VERSION_CONFLICT`. También lo responden, sin `expectedVersion`, si otra persona cambia el archivo mientras se guarda: vuelve a leerlo y aplica el cambio sobre lo nuevo.

**Editar con o sin Archivos avanzados**

#### Con Archivos avanzados (Se conserva la anterior)

Responde con el nombre, savedAsVersion (la versión en la que quedó guardado lo de justo antes) y undo, la llamada exacta a restore_version que vuelve a ello.

#### Sin Archivos avanzados (No se conserva)

Pide además files:items:delete y confirm: true, porque el texto anterior se pierde, y avisa con PREVIOUS_VERSION_NOT_KEPT, que nombra el plan que sí lo conserva.

Si el cliente ve el archivo en su portal, la edición pide `confirm: true` y la respuesta lo avisa con `PORTAL_VISIBLE`. `restore_version` vuelve a una versión por su número sin perder lo vivo: si ninguna versión lo guarda, antes lo guarda como «Antes de restaurar la versión N», y su `undo` vuelve a ello. La web hace lo mismo. Responde `restoredFrom`, la versión de la que es copia lo vigente; si la pedida ya era lo vigente, `unchanged: true` y no cambia nada. Una versión en cuarentena no se restaura: `FILE_INFECTED`. `delete_version` elimina una que no sea la vigente (la marcada `current` en `versions`), con `confirm: true`; su contenido se borra para siempre si ningún otro archivo ni otra versión lo usa. Las dos piden Archivos avanzados.

### Eliminar y recuperar

- **`delete`** (`ids`, `confirm: true`) lleva los archivos a «Eliminados recientemente» durante 30 días. Cada elemento responde `outcome`: `trashed` o `in_use`. Si el archivo sigue en uso en un sitio que la persona no puede editar, no se toca y `referencedBy` dice dónde.
- **`restore`** (`items: [{ kind, id }]`, con `kind` `file` o `folder`, hasta 50) devuelve cada elemento a su carpeta o a su ficha si siguen existiendo y la persona puede editarlas; si no, a Inicio. Cada fila responde `outcome: "restored"` con `restoredTo` (la ruta entera o «Inicio») y `alsoRestoredTo` si vuelve a más carpetas, o `outcome: "failed"` con su código. Basta `files:items:manage` o `files:items:delete`: quien puede eliminar puede deshacerlo.
- **`purge`** («Eliminar definitivamente», `items` y `confirm: true`) no se puede deshacer. Sin `confirm`, el ensayo dice cuánto se borra para siempre (subcarpetas, archivos y versiones anteriores, sin contar la vigente), qué va dentro de otra carpeta del lote y qué no se eliminará y por qué. Cada fila responde `purged`, `queued` (se borra en segundo plano) o `failed`. Lo que va dentro de una carpeta del mismo lote se borra con ella y su fila sale bien, con `withFolder` (el id de esa carpeta).

**Eliminar todo**, el botón que vacía «Eliminados recientemente», no está por MCP: lo hace una persona en la aplicación. La guía de uso está en [Eliminar y recuperar archivos](https://os.utilia.ai/docs/guides/files/recently-deleted).

| `errorCode` | Cuándo |
| - | - |
| `TRASH_ITEM_NOT_FOUND` | No está en «Eliminados recientemente» o la persona no puede verlo. Responde igual en los dos casos, también en el ensayo, sin nombre. |
| `TRASH_ITEM_EXPIRED` | Se le acabó el plazo y se está borrando. |
| `TRASH_ITEM_INSIDE_FOLDER` | Se eliminó con su carpeta: restaura o borra la carpeta (si la carpeta va en el mismo `purge`, se borra con ella). |
| `TRASH_ITEM_CONTENT_GONE` | Su contenido ya no existe y no se puede restaurar. |
| `TRASH_RESTORE_NO_DESTINATION` | Su carpeta ya no existe o no se puede editar, y la persona no puede crear carpetas en Inicio. |
| `TRASH_RESTORE_CONFLICT` | Otro archivo activo usa ya el mismo contenido. |
| `TRASH_PURGE_FORBIDDEN` | Solo quien lo subió, el Super Administrador o quien gestiona lo que eliminan otros lo borra antes de tiempo. |

### Etiquetas y fichas

- **`tag`** pone etiquetas (`ids` y `tags`, por nombre o id) y crea como personales las que falten; las de toda la empresa se crean en la aplicación. Un id que no es de una etiqueta que la persona ve, también uno mal copiado, no crea nada: responde `TAG_NOT_FOUND` con las de id parecido. **`untag`** las quita. **`tag_update`** cambia el nombre o el color (`#RRGGBB`) de una, y **`tag_delete`**, con `confirm: true`, la quita de todos los archivos que la llevan; sin él, dice cuántos y cuáles la llevan de los que ve la persona.
- **`link`** y **`unlink`** vinculan `ids` a una `entity` o quitan el vínculo. Piden Archivos avanzados, «Vincular CRM», poder editar la ficha y el acompañante de escritura. Quitar el último vínculo de un archivo sin carpeta lo lleva a «Eliminados recientemente», con `confirm: true` y `files:items:delete`.

### Descargar

`download_url` da una dirección para que tu asistente baje el archivo ahora: de un solo uso, caduca a los 5 minutos (`expiresInMinutes`, hasta 15) y admite `version`, que entrega siempre esa versión. `fileName` es el nombre que ve la persona. No sirve para dársela a una persona: para eso, `openInApp` o un enlace público. Las claves privadas y los certificados no se descargan por aquí. Tiene la misma puerta del antivirus que leer: un archivo (o la versión pedida) que aún se está analizando responde `FILE_SCAN_PENDING` y uno en cuarentena, `FILE_INFECTED`.

### Lo que pide confirmación

Lo que borra o expone, sin `confirm: true`, no hace nada y responde qué pasaría, con lo afectado (hasta 20 nombres) y su recuento. Enséñaselo a la persona y repite la misma llamada con `confirm: true` solo si lo confirma:

```json
{
  "error": {
    "code": "VALIDATION",
    "message": "Eliminar 3 archivos los lleva a Eliminados recientemente durante 30 días. Cuéntaselo a la persona y, si lo confirma, repite la llamada con confirm:true.",
    "retryable": true,
    "details": {
      "errorCode": "CONFIRMATION_REQUIRED",
      "operationKey": "files_manage:delete",
      "affectedCount": 3,
      "affected": [{ "id": "cmf1a2b3c", "name": "Contrato marco Acme.pdf" }]
    }
  }
}
```

Lo piden `delete`, `purge`, `delete_version`, `tag_delete`, quitar la última carpeta o el último vínculo, `share_link_revoke`, las ediciones sin versión conservada o visibles en el portal, todo lo que manda un archivo a un destino con más público y, en `folders_manage`, `delete`, `share`, `unshare` y mover una carpeta a una madre con más público. En `share` y `move` de carpetas, `details.affectedPeople` nombra a quienes la verían y hoy no. `share_link_create` no lo pide: lo aprueba la persona en el móvil.

## Enlaces públicos aprobados en el móvil

`share_link_create` crea un enlace a un archivo que abre cualquiera con la dirección, sin iniciar sesión, en una página con el nombre y el logotipo de la empresa. Es lo mismo que «Compartir con un enlace…» en la aplicación, con dos diferencias: cada enlace lo aprueba la persona en su móvil, y por aquí caduca como mucho a los 30 días.

**Crear un enlace público**

Participantes: Tu asistente, UTILIA OS y La persona.

1. Tu asistente → UTILIA OS: share_link_create · id y expiresInDays. Comprueba todo antes de pedir nada.
2. UTILIA OS → Tu asistente (respuesta): APPROVAL_REQUIRED con approvalId y number. Aún no hay enlace.
3. Tu asistente → La persona: «Elige el número 42 en tu móvil». Y termina su turno.
4. La persona (por su cuenta): Ve el archivo, su carpeta y las condiciones, y elige el número.
5. Tu asistente → UTILIA OS: La misma llamada con twoFactorApprovalId. Cuando la persona avisa.
6. UTILIA OS → Tu asistente (respuesta): link con url, status y expiresAt. La dirección, solo esta vez.

Los parámetros son los del diálogo de la aplicación: `id` del archivo, `expiresInDays` (1, 7 o 30), `allowDownload`, `password` opcional (de 8 a 64 caracteres, nunca se devuelve) y `label`, una nota para reconocerlo (120 caracteres) que no sale en la página pública. No lleva `confirm`: la aprobación en el móvil es la confirmación. Pide el enlace solo cuando la persona te lo haya pedido.

- **La aprobación cubre ese archivo con esas condiciones.** Si cambia algo entre la petición y el canje (el archivo, su versión, su nombre, su carpeta, la caducidad, la descarga, la contraseña o la nota), responde `APPROVAL_MISMATCH` y hay que pedir otra.
- **La dirección se entrega una sola vez**, en la respuesta del alta. `share_links` la omite siempre; para volver a copiarla, la persona en la aplicación.
- **La persona recibe un aviso** en la aplicación cada vez que se crea un enlace por esta vía, con «Anular el enlace» a un toque. Si el archivo es de otra persona, también lo recibe ella.

No se crea un enlace por MCP:

- de un archivo que una IA ha creado, cambiado, movido o renombrado en las últimas 24 horas, desde cualquier servidor (`AI_RECENTLY_CHANGED`): la persona puede crearlo en la aplicación, desde `openInApp`. La misma regla, y `confirm: true` con el nombre del archivo, valen para poner una imagen del Gestor como portada de la página de reservas o en los correos de Marketing;
- con una clave de conexión (`SHARE_LINK_NEEDS_OAUTH`: conecta el asistente por OAuth y cada enlace se aprobará en el móvil) ni desde el copiloto de UTILIA OS (`PERSONAL_SESSION_REQUIRED`);
- si la persona no tiene un móvil al que preguntar o no tiene activada la verificación en dos pasos (`APPROVAL_UNAVAILABLE`);
- pasado el cupo diario de enlaces creados por MCP (`SHARE_LINK_DAILY_LIMIT`), además de los topes de la aplicación;
- sin Archivos avanzados contratada, ni durante la prueba (esto se dice primero, antes que cualquier problema de la conexión, con el plan que lo incluye), ni en una sesión de soporte, ni de lo que la aplicación tampoco deja compartir (adjuntos de chat y tickets, justificantes, grabaciones de llamadas, documentos protegidos, claves privadas y tipos de riesgo).

Mientras un archivo tiene un enlace activo, por MCP no se cambia su contenido ni su nombre: `edit`, `patch`, `rename`, `restore_version` y las subidas o importaciones con `versionOf` responden `FILE_HAS_PUBLIC_LINKS`. Quien abre el enlace ve siempre lo que la persona aprobó.

`share_link_revoke` («Anular el enlace», `linkId` y `confirm: true`) lo corta al momento, también las descargas empezadas. Ver y anular enlaces no piden Archivos avanzados: tras bajar de plan se siguen pudiendo revisar y cortar.

| `errorCode` | Cuándo | Qué hacer |
| - | - | - |
| `APPROVAL_REQUIRED` | Se ha pedido la aprobación; `details.approval` trae `approvalId`, `number` y `expiresAt`. | Termina el turno pidiendo a la persona que elija el número y te avise; después repite la misma llamada con `twoFactorApprovalId`. |
| `APPROVAL_PENDING` | Se ha repetido antes de que la persona respondiera. | Lo mismo: pídele que elija el número y espera a que te avise. |
| `APPROVAL_REJECTED` | La persona la ha rechazado. | No la vuelvas a pedir salvo que ella te lo diga. |
| `APPROVAL_EXPIRED` | Caducó sin respuesta. | Si la persona sigue queriéndolo, repite sin `twoFactorApprovalId` para pedir otra. |
| `APPROVAL_MISMATCH` | El archivo o las condiciones han cambiado desde que se pidió. | Enséñaselo a la persona y, si quiere, pide otra. |
| `APPROVAL_UNAVAILABLE` | No hay móvil al que preguntar o falta la verificación en dos pasos. | Que la persona lo cree en la aplicación: menú del archivo › «Compartir con un enlace…». |
| `AI_RECENTLY_CHANGED` | Una IA tocó el archivo en las últimas 24 horas. | Que lo cree la persona en la aplicación (`details.openInApp`). |
| `SHARE_LINK_DAILY_LIMIT` | Se ha llegado al cupo del día. | Al día siguiente se puede de nuevo. |
| `SHARE_LINK_NEEDS_OAUTH` | La llamada viene de una clave de conexión. | Conectar el asistente por OAuth, o que lo cree la persona en la aplicación (`details.openInApp`). |
| `PERSONAL_SESSION_REQUIRED` | La llamada viene del copiloto. | Que lo cree la persona en la aplicación. |
| `FILE_SHARE_LINK_*` | Los mismos rechazos que en la aplicación: tipo bloqueado, antivirus, contraseña débil, prueba gratuita, sesión de soporte, demasiados enlaces en el archivo o un enlace que ya no existe o no está activo. | Sigue la pista de la respuesta. |

## `folders`: ver cómo está organizado

| Operación | Qué hace |
| - | - |
| `tree` | El árbol desde `id`, `path` o las raíces, con `depth` 2 por defecto (hasta 5) y 150 carpetas como mucho (`maxNodes`). Cada nodo trae `id`, `name`, cuántas carpetas y archivos tiene, sus hijas y `truncated` si se cortó. |
| `list` | Lo que hay en una carpeta (`id`, `path` o `entity`) o, sin nada, en Inicio: arriba la carpeta listada (`folder`, con su ruta), y después primero las subcarpetas y luego los archivos, con `sort` (`name`, `modified` o `size`), `kinds` y 50 por página (hasta 100). |
| `get` | La carpeta: ruta, descripción, dueño, departamento, recuentos, la ficha a la que está anclada y qué puede hacer la persona en ella (`can`: subir, editar, eliminar y compartir), con `openInApp`. |
| `resolve` | Una ruta a su carpeta: `found`, `ambiguous` con las candidatas (nunca elige una) o `not_found`, que trae `candidates` si hay carpetas que se llaman así o casi. |
| `permissions` | Quién tiene acceso: quién la creó, su departamento, de dónde hereda y, por cada persona o departamento, su nivel, su fecha de fin (`expiresAt`, y `expired` si ya pasó) y si llega a las subcarpetas (`inheritToChildren`), con una frase (`summary`) de quién la ve. |

Todo lo que la persona no ve queda fuera, también de las rutas y de los recuentos: `resolve` no atraviesa una carpeta intermedia oculta, y lo oculto responde igual que lo que no existe. Las carpetas del sistema, las de conversaciones y las que tienen bloqueado el acceso de la IA no salen en el árbol.

## `folders_manage`: crear y organizar

| Operación | Qué hace | Scope | Permiso | `confirm` |
| - | - | - | - | - |
| `create` | Una carpeta (`name` y `parentId` o `parentPath`) o un lote en `folders`, hasta 20, con `parentIndex` para colgar una de otra anterior del lote. Admite `description`, `color`, `entity` (anclarla a una ficha), `departmentId` (departamento dueño) e `inheritPermissions` (por defecto `true`); en un lote, llegan a todas. | `files:items:manage` | «Crear carpetas» | No |
| `ensure_path` | Crea lo que falte de una ruta (`path`, o `paths` hasta 20) y devuelve, como un lote, una fila por ruta con el `id` de la carpeta final, su `path` y lo que ha creado (`created`); en el ensayo, sin `id` y con `existing`, la carpeta más honda de la ruta que ya existe. Con `entity`, dentro de la carpeta de la ficha; con `dryRun`, sin crear nada; con `allowSimilar: true`, crea el nombre pedido aunque haya uno casi igual. | `files:items:manage` | «Crear carpetas» | No |
| `update` | Nombre, descripción y color; o varias carpetas con `updates` (hasta 20). | `files:items:manage` | «Editar carpetas» | No |
| `move` | A `parentId` (`null`, la raíz) o `parentPath`; varias a la vez con `ids` (hasta 20). | `files:items:manage` | «Editar carpetas» | Si la nueva madre la ve más gente |
| `delete` | A «Eliminados recientemente» 30 días, con `cascade` lo que contiene; varias a la vez con `ids` (hasta 20), con una sola confirmación. Sin `cascade`, una carpeta con algo dentro no se elimina (`FOLDER_NOT_EMPTY`), y el ensayo lo avisa antes. La devuelve `files_manage` `restore` con `kind: "folder"`. | `files:items:delete` | «Eliminar carpetas» | Sí |
| `share`, `unshare` | Dar o quitar acceso a `userIds` (hasta 50) o a un `departmentId`. Al dar, `level`, y opcionales `expiresAt` e `inheritToChildren`. `unshare` quita el acceso directo, no el heredado. | `files:folders:share` | «Compartir» | Sí |

`ensure_path` no duplica carpetas por una mayúscula o una tilde: si ya existe «contratos» y pides «Contratos», usa la que hay y lo avisa con `PATH_REUSED`. Si hay una casi igual, responde `PATH_SIMILAR_EXISTS`, con la carpeta en el mensaje y todas en `items`, para que preguntes: si la persona quería esa, usa su ruta o su id; si quiere el nombre nuevo, repite con `allowSimilar: true`. Lo que numera no cuenta como errata: «2025» y «2026», «Fase 1» y «Fase 2», «v1» y «v2» o «Enero» y «Febrero» son carpetas distintas y se crean sin preguntar. Si la ruta casa con varias, `PATH_AMBIGUOUS`, sin crear nada.

**Anclar carpetas a una ficha pide Archivos avanzados.** `create` y `ensure_path` con `entity`, o dentro de una carpeta que ya está anclada a una ficha, necesitan la capacidad: sin ella no se crea ninguna y la respuesta es `CAPABILITY_NOT_ENABLED`, con el plan que la incluye y `upgradeUrl`. Con carpeta madre y `entity`, la madre tiene que ser de esa ficha.

**Dar acceso.** Los niveles son `VIEW` (ver: abrir y descargar), `EDIT` (editar: además subir, cambiar, renombrar y quitar archivos), `MANAGE` (gestionar: además crear subcarpetas, mover y eliminar) y `FULL` (control total: además dar y quitar acceso a otras personas). Sin `level` responde `VALIDATION` con esa explicación. `expiresAt` es una fecha `AAAA-MM-DD` (vale hasta el final de ese día, en la zona de la empresa), una fecha y hora, o `null` para quitar la fecha de fin; `inheritToChildren: false` deja el acceso solo en esta carpeta. Si no los pasas, quien ya tenía acceso directo conserva su fecha de fin y su herencia. Sin `confirm: true`, la respuesta dice qué cambia o se conserva de cada acceso, si había caducado y quién la vería que hoy no.

El acceso de la IA y la Búsqueda por dentro de una carpeta no se cambian por MCP: solo una persona en la aplicación.

## Avisos y siguiente paso

Los avisos que cambian lo que debe hacer tu asistente llegan en `_notices.items`, cada uno con su `code` y su `message`, junto a los de siempre (`ignoredFields`, `deprecatedOperation`, `reauthorization`). Nunca citan texto del archivo.

| `code` | Cuándo |
| - | - |
| `OCR_PARTIAL` | Del escaneado solo se leyeron algunas páginas (`pagesRead`, `pagesPending`). |
| `OCR_DAILY_QUOTA` | Se acabó el cupo de páginas escaneadas del día a mitad de la lectura. |
| `OMITTED_BY_PLAN` | Una parte del resultado necesita Archivos avanzados; trae el plan que la incluye y `upgradeUrl`. |
| `ENTITY_HAS_NO_FOLDER` | La ficha no tiene carpeta: el archivo queda vinculado a ella, sin carpeta. |
| `PATH_REUSED` | `ensure_path` usó una carpeta que ya existía con otra grafía (`requested`, `used`). |
| `PORTAL_VISIBLE` | Lo editado o movido lo ve el cliente en su portal. |
| `PREVIOUS_VERSION_NOT_KEPT` | Se editó sin Archivos avanzados y no se guardó la versión anterior; trae el plan que las conserva y `upgradeUrl`. |
| `TABLE_TRUNCATED` | La hoja llegó cortada. |
| `EXTENSION_KEPT` | `rename` sin extensión: se ha conservado la real (`extension`). |
| `TECHNICAL_INFO_DEFERRED` | `get` de varios: la ficha técnica de los de `ids` está pendiente; pídela con `get` de cada uno. |
| `PAGE_TRUNCATED` | Una página no cabía entera y falta su final (`page`, `charsRead`). |
| `FILTER_VALUE_INVALID` | Un filtro de `table` compara con algo que no es del tipo de su columna (`column`). |
| `TABLE_CHARS_LIMIT` | `table` da menos filas de las pedidas para no pasar de 36.000 caracteres (`maxChars`); si ni una cabe entera, sus textos largos acaban en «…» (`cellsShortened`). Pide las siguientes con `offset` o menos columnas con `columns`. |
| `MATCHED_BY_FOLDER` | Algunos resultados de `search` casan solo por estar en una carpeta con ese nombre. |
| `SCAN_LIMIT` | Se agotó la exploración y quedan más sin revisar: la página sale vacía o, en `trash`, con lo encontrado. Sigue con `nextCursor`. |
| `MORE_MATCHES` | `find` encontró más coincidencias de las que enseña (`totalMatches`, `shownMatches`): las páginas de todas están en `matchedPages`. |
| `NOT_FOUND_ELSEWHERE` | En un lote de `get` o `read`, dónde se lee lo que no es del Gestor, una vez para todas las filas `FILE_NOT_FOUND` (`ids`). |
| `FOLDERS_CREATED` | `request_upload` creó carpetas con `ensurePath` (están en `createdFolders`): si no subes nada, se quedan vacías. |
| `FOLDERS_LEFT_EMPTY` | `abort_upload` dejó vacías las carpetas de la subida y las que se crearon encima para ella (`emptyFolders`): si se crearon solo para la subida, elimínalas con `folders_manage` `delete`. |
| `SCAN_PENDING` | `confirm_upload`: el antivirus aún está analizando lo recién subido (`ids`, `retryAfterSeconds`). Hasta que termine no se lee, ni se descarga, ni se comparte; si tras tres intentos sigue igual, díselo a la persona. |

`nextSteps` sugiere el paso siguiente, también en otro servidor (por ejemplo, preparar un presupuesto con `crm_budgets` de `utilia-crm`), solo si el plan y los permisos lo permiten. Llega en `get` y en lo recién guardado (`confirm_upload`, `create`, `import_url`), tras `find` (leer esas páginas), en la ficha de un escaneado (mirarlo con `view`) o de un vídeo o un audio (descargarlo).

## Errores

Todos llegan como resultado de la herramienta, con `error.details.errorCode` y una `hint` que dice qué hacer ahora. Ningún mensaje cita texto del archivo ni nombra lo que la persona no ve. Los de plan, permiso y scope son los comunes, en [Errores con motivo](https://os.utilia.ai/docs/developers/mcp/reference#errores-con-motivo). El límite de peticiones de la conexión es la excepción: llega como HTTP `429` con `RATE_LIMITED` y `retryAfterSeconds`, en [Límite de peticiones](https://os.utilia.ai/docs/developers/mcp/quickstart#límite-de-peticiones).

### Al encontrar

| `errorCode` | Cuándo | Qué hacer |
| - | - | - |
| `FILE_NOT_FOUND` | No existe, no se ve, tiene bloqueado el acceso de la IA o es de otro módulo. | Comprueba el id con `files search`. Si es un adjunto de un ticket, léelo con `read_attachment` de `tickets` (`utilia-crm` o `utilia-work`) o, si el ticket es tuyo, de `my_tickets`; el de un ticket al soporte de UTILIA OS, con `read_attachment` de `utilia_support`, y el de un elemento de trabajo, con `read_attachment` de `issues` (`utilia-work`). Lo compartido en una conversación se lee con `chat_conversations` (`utilia-chat`); del justificante de un gasto, `expenses` (`utilia-finance`) da su enlace de descarga con `document_get`, y los documentos de RRHH se abren en la aplicación. |
| `FOLDER_NOT_FOUND` | Igual, con una carpeta. | Comprueba la carpeta con `folders resolve` o `folders tree`. |
| `PATH_NOT_FOUND` | Ninguna carpeta visible tiene esa ruta; si hay alguna que se llama así o casi, trae las candidatas (`details.items`). | Pregunta si es alguna de ellas; si no, enseña las carpetas que hay o crea la ruta con `ensure_path` si te lo piden. |
| `PATH_AMBIGUOUS` | Varias rutas visibles casan (`details.items`). | Pregunta cuál es y repite con su id. |
| `PATH_SIMILAR_EXISTS` | `ensure_path` o `ensurePath` encuentran una carpeta casi igual (el mensaje la nombra; todas, en `items`). | Pregunta a la persona: si es esa, repite con su id; si quiere la nueva tal cual, repite con `allowSimilar: true`. No elijas tú. |
| `ENTITY_NOT_FOUND`, `ENTITY_AMBIGUOUS` | La ficha no existe, no se ve o casa con varias (`details.candidates`). | Compruébala con `search`, o pregunta cuál es y repite con su id. |
| `TAG_NOT_FOUND` | Una etiqueta pedida no existe entre las visibles; trae las parecidas. | Usa una de ellas o pide el nombre exacto. |
| `WRONG_TOOL` | La operación es de otra herramienta del servidor: «La operación X es de Y, no de Z.» (`details.operationKey`). | Repite con esa herramienta y los mismos datos. |

### Al leer

| `errorCode` | Cuándo | Qué hacer |
| - | - | - |
| `NOT_READABLE` | `details.reason`: `scanned` (sin texto y sin cupo de OCR), `encrypted`, `unsupported` o `too_large`. | Un escaneado, míralo con `view`; uno con contraseña, que lo abra la persona; uno demasiado grande, léelo por `pages`. |
| `PAGE_OUT_OF_RANGE` | `pages` fuera del documento. | Pide páginas entre 1 y el `totalPages` de `files get`. |
| `INVALID_PAGES` | `pages` mal escrito o con una página por encima de 100.000. | Repite con `pages` como `"3"`, `"3-7"` o `"2,5"`. |
| `INVALID_CURSOR` | El cursor no es de ese archivo o ya no vale. | Vuelve a leerlo desde el principio, sin cursor. |
| `INVALID_QUERY` | `find` sin `query` ni `terms`. | Repite con unas palabras o una `"frase exacta"`. |
| `FILE_CHANGED` | El archivo cambió desde que se emitió el cursor. | Vuelve a leerlo desde el principio, sin cursor. |
| `NOT_COMPARABLE` | `compare` con versiones sin texto o de tipos distintos. | Enseña sus fichas con `versions`. |
| `SHEET_NOT_FOUND`, `COLUMN_NOT_FOUND` | La hoja o la columna no existen; trae las que hay (y `missing`, las columnas que fallaron). | Usa uno de esos nombres. |
| `TABLE_TRUNCATED` | `aggregate` o `stats` sobre una hoja cortada. | Lee filas con `mode: "rows"` o que la abra la persona. |
| `EXTRACTOR_BUSY`, `EXCEL_READ_BUSY` | El lector está ocupado (`retryAfterSeconds`). | Reintenta una vez pasado ese tiempo. |
| `EXTRACTOR_UNAVAILABLE` | Ahora no se puede leer (con `retryAfterSeconds` si es un escaneado y no se puede contar su cupo). | Reintenta pasado ese tiempo; si la persona lo necesita ya, que lo abra en la aplicación. |
| `STORAGE_UNAVAILABLE` | El almacenamiento de archivos no responde (`retryAfterSeconds`). El archivo existe. | Reintenta pasado ese tiempo; si sigue sin responder, díselo a la persona. |
| `OCR_DAILY_QUOTA` | El escaneado necesita OCR y no queda cupo hoy. | Míralo con `view` o vuelve a intentarlo mañana. |
| `READ_RATE_LIMITED` | Ya hay una lectura en curso en la empresa o se ha pasado el cupo de la hora (`retryAfterSeconds`). | Espera y lee menos a la vez. |
| `FILE_SCAN_PENDING` | El antivirus aún lo está analizando (`retryAfterSeconds`). También en `download_url`. | Vuelve a intentarlo pasado ese tiempo; si tras tres intentos sigue igual, no insistas y díselo a la persona: el análisis sigue solo y no hace falta volver a subir el archivo. |
| `FILE_INFECTED` | Está en cuarentena: el antivirus ha encontrado una amenaza. También en `download_url`. | No se puede leer, descargar ni reenviar, y no sirve reintentarlo. Díselo a la persona; en la ficha del archivo verá qué puede hacer con él. |
| `FILE_UPLOAD_PENDING` | Es una subida sin terminar: la reserva está en su carpeta, pero el contenido no llegó. También en `download_url`. | Dile a la persona que la continúe o la descarte en su carpeta, o súbelo otra vez con `request_upload` si tienes el fichero. |
| `PRIVATE_KEY_RESTRICTED` | Es una clave privada o un certificado. | La persona lo descarga desde la aplicación. |

### Al cambiar

| `errorCode` | Cuándo | Qué hacer |
| - | - | - |
| `CONFIRMATION_REQUIRED` | Falta `confirm: true`. | Enseña lo que va a pasar y repite la misma llamada si la persona lo confirma. |
| `NAME_CONFLICT` | Ya hay algo con ese nombre en el destino. | Elige otro nombre con la persona y repite con él. |
| `NOT_EDITABLE` | `edit` o `patch` sobre algo que no es texto, pasa de 5 MB o no se puede reescribir en su codificación sin estropearlo. | Sube una versión nueva con `request_upload` o `import_url` y `versionOf`; si es un carácter que no cabe, escribe el cambio sin él. |
| `PATCH_NO_MATCH`, `PATCH_MULTIPLE_MATCHES` | `old_string` no aparece, o aparece varias veces. | Vuelve a leer y cópialo exacto, amplíalo para que sea único o usa `replace_all`. |
| `AMBIGUOUS_SOURCE` | `move` o `rename` de un archivo que está en varias carpetas, sin `fromFolderId`. | Pregunta de qué carpeta sale (o en cuál se renombra) y repite con `fromFolderId`. |
| `EXTENSION_MISMATCH` | `rename` a un nombre con otra extensión que la real. | Usa la extensión real, o ninguna; para otro formato, crea una copia con `create`. |
| `FILES_MANAGE_BUSY` | Ya se está creando un `.pdf` o un `.docx`, o trayendo un archivo de internet (`retryAfterSeconds`). | Espera y repite; de uno en uno. |
| `UPLOAD_NOT_PREPARED`, `UPLOAD_IN_PROGRESS`, `VERSION_UPLOAD_FAILED` | No se pudo preparar la subida (nada reservado), ya se está confirmando, o no se pudo guardar como versión nueva. | Pide la subida otra vez en unos minutos; o espera y confírmala de nuevo; o sigue la pista. |
| `STORAGE_UNAVAILABLE` en una fila de `confirm_upload` | El archivo ha llegado, pero todavía se está guardando o el almacenamiento no responde. La reserva sigue. | Repite `confirm_upload` con ese `id` pasados unos segundos. No hagas otra vez el `PUT` ni reserves de nuevo. |
| `UPLOAD_NOT_FINISHED` en una fila de `confirm_upload` | La confirmación no ha dejado la subida terminada (el archivo seguiría como subida sin terminar), o no se ha podido comprobar. El contenido ya llegó. | No borres tu copia. Repite `confirm_upload` con ese `id` pasados unos segundos, sin volver a hacer el `PUT`; si vuelve a pasar, díselo a la persona. |
| `VERSION_CONFLICT` | `expectedVersion` no es la vigente (`details.currentRevision`), u otra persona lo ha cambiado mientras se guardaba. | Vuelve a leerlo y aplica el cambio sobre la versión nueva. |
| `FILE_INFECTED` | `restore_version` de una versión en cuarentena. | Elige otra versión: `versions` marca las que están en cuarentena con `antivirus: "infected"`. |
| `FOLDER_NOT_EMPTY` | `folders_manage` `delete` sin `cascade` de una carpeta con algo dentro. | Cuéntale a la persona lo que contiene y, si quiere eliminarlo también, repite con `cascade: true`. |
| `TOO_MANY_UPLOAD_RESERVATIONS`, `UPLOAD_NOT_FOUND` | No quedan huecos para reservar más subidas, o el id no es una reserva tuya pendiente. | Termina o libera las reservas con `abort_upload` y repite solo esas filas; o comprueba el id que dio `request_upload`. |
| `PERMISSION_DENIED` en `path` | `ensurePath` tendría que crear carpetas y la persona no tiene «Crear carpetas» o el nivel «Gestionar» donde irían. | Guárdalo en una carpeta que ya exista o díselo a la persona; no repitas con `ensurePath`. |
| `FILE_HAS_PUBLIC_LINKS` | El archivo tiene un enlace público activo. | Que la persona anule el enlace o haga el cambio en la aplicación. |
| `FILE_IS_WORM_PROTECTED`, `FILE_IS_SYSTEM_GENERATED`, `FOLDER_IS_SYSTEM`, `FILE_IS_ISSUED_INVOICE_ORIGINAL`, `FILE_IS_VAT_ACCREDITATION_EVIDENCE`, `HR_SYSTEM_FILE_PROTECTED`, `FILE_PROTECTED` | El archivo está protegido: se conserva sin cambios por ley, lo mantiene UTILIA OS, es el original de una factura emitida (se corrige con una rectificativa en `utilia-finance`), es la prueba de una acreditación fiscal, es un documento de RRHH (en `utilia-rrhh`) o está en retención. | No se cambia por aquí; díselo a la persona. |
| `IMPORT_URL_BLOCKED`, `IMPORT_URL_UNREACHABLE` | La dirección no es `https`, lleva credenciales o un puerto raro, el tipo es de riesgo, o no se alcanza. | Usa una dirección pública; si el archivo está en el disco, súbelo con `request_upload`. |
| `QUOTA_EXCEEDED_STORAGE` | No queda espacio. | La persona puede liberar espacio o pedir más con `org_plan`. |

## Si conecta alguien de la asesoría

Una persona de la asesoría entra en este servidor solo si la empresa le comparte el área «Documentos», y su asistente tiene las mismas reglas que ella en la aplicación:

**La asesoría por MCP, según su nivel**

| Acción | Ver y descargar | También subir |
| - | - | - |
| Leer, mirar y descargar | Sí | Sí |
| Subir, crear, ordenar y editar (Solo en su carpeta compartida) | No | Sí |
| Eliminar y recuperar (Solo lo que subió o metió ella) | No | Propios |
| Dar acceso a carpetas | No | No |
| Crear o anular enlaces públicos | No | No |

Alcances:

- **Propios**: Lo que ha creado.

Nada sale de su carpeta compartida: mover fuera, o a Inicio, se niega. `ADVISOR_DELETE_NOT_ALLOWED` y `ADVISOR_FILE_READ_ONLY` explican la negativa sobre lo que ella ve; lo de la empresa que no ve responde como si no existiera.

## Si tu integración llamaba desde el CRM

Las herramientas `fm_*` y `fm_virtual_folders` salen del servidor `utilia-crm`. Por su nombre viejo responden `MOVED_TO_FILES`, con la sustituta exacta en `details.replacement` (`server`, `path`, `tool` y `operation`). Las conexiones del CRM autorizadas antes del cambio que llevan `dev:files:*` siguen pudiendo llamarlas, lecturas y escrituras, hasta el 31 de diciembre de 2026, sin anunciarse y con el aviso `_notices.reauthorization`; después se retiran. Mientras tanto se comportan como este servidor en lo que importa: solo alcanzan lo que está en el Gestor para la persona, también al escribir, y no cambian el contenido ni el nombre de un archivo con un enlace público activo. Las escrituras que aceptaban las herramientas de lectura (`fm_files`, `fm_folders`, `fm_organization`) responden `MOVED_TO_FILES` desde el primer día.

| Herramienta del CRM | Sustituta en `utilia-files` |
| - | - |
| `fm_files` | `get` → `files get`; `get_content` → `files read`; `get_download_url` → `files_manage download_url`; `get_versions` → `files versions`; `search` → `files search` (por dentro, `search`); `list_trash` → `files trash` |
| `fm_files_manage` | Las subidas (también las `batch_*`) → `request_upload`, `confirm_upload` y `abort_upload` con `files`; `upload_version` → `import_url` con `versionOf`; `edit_content` → `edit`; `share_links_list` → `files share_links`; `restore_version` va por número de versión. El resto se llama igual en `files_manage`, sin el prefijo `batch_`. |
| `fm_folders` | `list_root` y `get_contents` → `folders list`; `get_tree` → `folders tree`; `get` y `get_breadcrumb` → `folders get`; `get_permissions` → `folders permissions` |
| `fm_folders_manage` | `create` y `batch_create` → `folders_manage create`; `delete_cascade` → `delete` con `cascade`; `unshare` va por persona o departamento. El resto se llama igual. |
| `fm_organization`, `fm_organization_manage` | Las etiquetas → `files tags` y `files_manage tag`, `untag`, `tag_update` y `tag_delete`. Los favoritos → `files favorites` y `files_manage favorite` y `unfavorite`; el orden, en la aplicación. |
| `fm_excel_query` | `files table`, con `mode` `sheets`, `rows` o `stats` |
| `fm_pdf_visual` | `get_info` → `files get`; `render_page` y `render_pages` → `files view` |
| `fm_virtual_folders` | Los árboles y `get_entity_files` → `files search` con `entity`; `link_files` → `files_manage link`; `unlink_file` y `unlink_files` → `files_manage unlink` |

En `utilia-crm` se quedan `crm_files`, `crm_files_management` y `crm_budget_files`, para los archivos de las fichas del CRM. `crm:files:view`, `crm:files:upload` y `crm:files:delete` cubren desde ahora solo esas fichas, y sus rótulos lo dicen: «Ver los archivos de las fichas del CRM», «Subir y vincular archivos a las fichas del CRM» y «Eliminar archivos de las fichas del CRM». El servidor del CRM deja de anunciar `dev:files:*`. Para el Gestor entero, conecta este servidor y autoriza los `files:*` que necesites.

## Siguiente paso

- [Conecta tu IA](https://os.utilia.ai/docs/guides/connect-ai/overview): Cómo conecta cada persona su asistente al Gestor de archivos y a las demás áreas.
- [Subir archivos a una ficha por MCP](https://os.utilia.ai/docs/developers/mcp/file-uploads): file_uploads: el justificante, el adjunto o la imagen que pide otro servidor, sin el Gestor.
