# RAGfly — Catálogo de operaciones para agentes

> Infraestructura RAG multi-tenant. Entrega a un agente de IA el contexto documental exacto que necesita, filtrado por RBAC, vía MCP, CLI o API REST.

Actualizado: 2026-05-29

## Conexión MCP

- Endpoint SSE: https://seguridad-backend-production-6250.up.railway.app/mcp
- Endpoint HTTP (streamable): https://seguridad-backend-production-6250.up.railway.app/mcp-http
- Autenticación: Authorization: Bearer <JWT | API_KEY>
- Alcance: Todas las operaciones quedan acotadas al grupo y entidad activos del usuario autenticado (RBAC).

También disponible vía la CLI de RAGfly Desktop: `ragfly cloud ...`

## Operaciones (12)

### Sesión

#### estado_sesion

Verifica la sesión y devuelve el contexto del usuario (email, rol, grupo y entidad activos). Úsala antes de cualquier otra operación para confirmar que el JWT o API Key es válido.

- MCP tool: `estado_sesion`
- CLI: `ragfly cloud me`
- REST: `GET /auth/me` (acceso USUARIO)

### Consultar

#### listar_documentos

Lista los documentos del grupo activo con su estado de procesamiento, ubicación, tamaño y número de chunks.

- MCP tool: `listar_documentos`
- CLI: `ragfly cloud documento listar`
- REST: `GET /documentos/paginado` (acceso USUARIO)
- Parámetros:
  - `estado` (string, def: todos) — Filtra por estado: CARGADO, METADATA, ESCANEADO, CHUNKEADO, VECTORIZADO, NO_ESCANEABLE, REVISAR.
  - `limite` (int, def: 20) — Máximo de documentos (máx 100).
  - `pagina` (int, def: 1) — Página de resultados.

#### ver_documento

Detalle completo de un documento: metadatos, estado de procesamiento, chunks, resumen y características extraídas.

- MCP tool: `ver_documento`
- CLI: `ragfly cloud documento ver`
- REST: `GET /documentos/{codigo_documento}` (acceso USUARIO)
- Parámetros:
  - `codigo_documento` (string, def: —) — Código del documento.

#### listar_habilidades

Lista las habilidades LLM disponibles en el catálogo: unidades atómicas de procesamiento LLM sobre documentos.

- MCP tool: `listar_habilidades`
- CLI: `ragfly cloud habilidad listar`
- REST: `GET /habilidades` (acceso USUARIO)

#### ver_habilidad

Detalle de una habilidad: prompt, system prompt, modelo, tipo, salida y variables disponibles.

- MCP tool: `ver_habilidad`
- CLI: `ragfly cloud habilidad ver`
- REST: `GET /habilidades/{codigo_habilidad}` (acceso USUARIO)
- Parámetros:
  - `codigo_habilidad` (string, def: —) — Código de la habilidad.

#### buscar_chunks

Búsqueda semántica RAG sobre los chunks vectorizados del grupo activo. Devuelve los fragmentos más relevantes con su documento de origen, score coseno y rerank — contexto citable sin entrar al chat.

- MCP tool: `buscar_chunks`
- CLI: `ragfly cloud buscar`
- REST: `POST /documentos/buscar-semantico` (acceso USUARIO)
- Parámetros:
  - `consulta` (string, def: —) — Pregunta o frase a buscar en lenguaje natural.
  - `limite` (int, def: 10) — Top-K final.
  - `min_similitud` (float, def: 0.0) — Umbral coseno mínimo.
  - `codigo_entidad` (string, def: todas) — Filtra por entidad específica.

#### preguntar

Pregunta al chat RAG y devuelve la respuesta completa con citas. Crea una conversación nueva o reutiliza una existente.

- MCP tool: `preguntar`
- CLI: `ragfly cloud chat preguntar`
- REST: `POST /chat/conversaciones` (acceso USUARIO)
- Parámetros:
  - `mensaje` (string, def: —) — Pregunta del usuario.
  - `codigo_funcion` (string, def: CHAT-USUARIO) — Función de chat a usar.
  - `id_conversacion` (int, def: 0) — Reutilizar conversación; 0 crea una nueva.
  - `titulo` (string, def: —) — Título al crear una conversación nueva.

### Organizar

#### listar_espacios

Lista los Espacios de Trabajo del grupo activo: colecciones de documentos sobre las que se ejecutan habilidades LLM de forma masiva.

- MCP tool: `listar_espacios`
- CLI: `ragfly cloud espacio listar`
- REST: `GET /espacios-trabajo/paginado` (acceso USUARIO)
- Parámetros:
  - `limite` (int, def: 20) — Máximo de espacios.

#### ver_espacio

Detalle de un Espacio de Trabajo y sus documentos asociados, con el estado de la cola de procesamiento por documento.

- MCP tool: `ver_espacio`
- CLI: `ragfly cloud espacio ver`
- REST: `GET /espacios-trabajo/{id_espacio}/documentos/paginado` (acceso USUARIO)
- Parámetros:
  - `id_espacio` (int, def: —) — ID del Espacio de Trabajo.
  - `limite_docs` (int, def: 20) — Máximo de documentos a devolver.

### Producir

#### ejecutar_habilidad

Ejecuta una habilidad LLM sobre un Espacio de Trabajo o un documento. La tarea se encola y se procesa en background; el resultado se consulta con ver_cola.

- MCP tool: `ejecutar_habilidad`
- CLI: `ragfly cloud habilidad ejecutar`
- REST: `POST /habilidades/{codigo_habilidad}/ejecutar` (acceso USUARIO)
- Parámetros:
  - `codigo_habilidad` (string, def: —) — Código de la habilidad, ej. RESUMIR_DOCUMENTO.
  - `id_espacio` (int, def: 0) — ID del Espacio. Usar 0 si se indica documento.
  - `codigo_documento` (string, def: —) — Código del documento. Vacío si se usa espacio.

### Monitorear

#### ver_cola

Estado actual de la cola del pipeline (ANALIZAR → CHUNKEAR → VECTORIZAR). Útil para monitorear el avance de habilidades o de la ingesta.

- MCP tool: `ver_cola`
- CLI: `ragfly cloud cola ver`
- REST: `GET /cola-estados-docs/paginado` (acceso USUARIO)
- Parámetros:
  - `proceso` (string, def: todos) — Filtra por proceso, ej. VECTORIZAR.
  - `estado` (string, def: todos) — PENDIENTE, EN_PROCESO, COMPLETADO o ERROR.
  - `limite` (int, def: 20) — Máximo de items.

#### ver_ejecuciones

Historial de ejecuciones de habilidades: cuántos documentos procesó cada ejecución, cuántos con éxito y cuántos con error.

- MCP tool: `ver_ejecuciones`
- CLI: `ragfly cloud cola ejecuciones`
- REST: `GET /cola-estados-docs/ejecuciones` (acceso USUARIO)
- Parámetros:
  - `limite` (int, def: 10) — Máximo de ejecuciones.