Guía de uso del MCP: qué puede hacer cada persona¶

La guía de uso es un manual calculado para quien pregunta. Le dice a la persona qué puede pedir en OrpycaMCP con sus permisos de hoy, ordenado por flujo de trabajo, con una frase de ejemplo por acción. A un cliente MCP le da, además, lo necesario para ejecutar cada acción. Los clientes pueden ser el asistente de la aplicación, Hermes, Claude o cualquier otro.

Cómo se pide¶

Vía	Para quién	Qué devuelve
Recurso `orfeo://guia`	el cliente MCP	JSON: flujos, acciones, herramienta, parámetros y confirmación
Prompt `guia_de_uso`	la persona	el mismo contenido en texto, más la instrucción de no intentar lo negado

Las dos salidas salen de la misma función. Lo que lee la persona y lo que usa el cliente para actuar no pueden decir cosas distintas.

Qué trae¶

Capítulos por flujo de trabajo, en el orden del trámite: ventanilla y radicación, trámite y reparto, respuesta y despacho, expediente, archivo físico, transferencias, disposición, preservación y firma, instrumentos archivísticos, correo, consulta, administración y notificaciones. Un flujo en el que la persona no tiene nada que hacer ni nada negado no aparece.
Lo que puede hacer: acciones, procedimientos guiados (varios pasos con una sola confirmación) y consultas. Cada una trae su frase de ejemplo, por ejemplo «Radica este oficio como PQRSD de la ciudadana Ana Pérez de Bogotá».
Lo que no puede, con el motivo y la vía alternativa. El motivo distingue entre no tener el permiso y tenerlo solo para consultar.
Lo que este canal no ofrece por decisión, en un capítulo aparte. Un ejemplo es aprobar una desclasificación. Cada acto trae su motivo y dónde sí se hace.
Precisiones que el sistema no distingue y que el asistente no debe afirmar.

Cómo la usa un cliente para ejecutar¶

Cada acción del JSON trae lo que el cliente necesita para pasar de la frase a la invocación:

{
  "codigo": "F1",
  "nombre": "Ventanilla y radicación",
  "puede": [
    {
      "tipo": "accion",
      "operacion": "Radicar un documento de entrada, salida o interno",
      "ejemplo": "Radica este oficio como PQRSD de la ciudadana Ana Pérez de Bogotá",
      "herramienta": "radicar_documento",
      "parametros": [{"nombre": "doc_type", "etiqueta": "Tipo", "tipo": "string", "obligatorio": true}],
      "confirmacion": {"write": true, "destructive": false}
    }
  ],
  "no_puede": [
    {"operacion": "Anular un radicado", "motivo": "requiere el permiso …", "via_alternativa": "…"}
  ]
}

El cliente reconoce en lo que pide la persona una acción de puede.
Llama a herramienta y pide a la persona los parámetros obligatorio que falten.
Si la acción trae confirmacion, el servidor no ejecuta nada: devuelve una propuesta firmada que la persona aprueba con confirmar_accion. Un acto con acta se aprueba en su sesión, en /aprobar.
Si lo pedido está en no_puede, el cliente responde con el motivo y la vía alternativa sin intentarlo.

El servidor vuelve a comprobar los permisos en cada llamada. La guía orienta, no autoriza.

Para un modelo con poco contexto¶

La guía completa no cabe en el contexto de un modelo. Por eso hay piezas cortas: orfeo://indice da el mapa, guia_flujo una página por flujo, buscar_herramientas y describir_herramienta la acción y sus parámetros, y explicar_limite el motivo de un no. Para conectar un cliente, vea Conectar un cliente MCP.

Guías de tarea (cómo se hace)¶

Además de la guía por flujo hay guías de tarea (ADR-072 D2): «radicar un documento de entrada», «trasladar un radicado», «cerrar y archivar un expediente»… Cada una trae los pasos, la pantalla de cada paso y los campos que se piden (con su etiqueta y si son obligatorios, tomados de la propia herramienta). Se leen con la tool guia_de_tarea (sin argumentos lista las tareas), con el recurso orfeo://guia/{tarea} o por REST en GET /api/v1/mcp/guias[/{tarea}]. Lo que la persona no puede hacer sale aparte, sin pasos, con a quién pedirlo. No usan el modelo ni dependen de la bandera del asistente.

Cuando faltan datos (`preparar_tramite`)¶

Antes de proponer una escritura con datos incompletos, el cliente llama a la tool preparar_tramite(tarea, datos) (tarea es la clave de una guía o el nombre de una herramienta; datos, lo que ya se tiene). Es una lectura del servidor: no guarda nada, no escribe y no despacha. Devuelve listo, resueltos, faltan —cada uno con campo, etiqueta, pregunta (cómo preguntárselo a la persona) y opciones_desde (la lectura del catálogo de donde salen los valores válidos: listar_dependencias, listar_tipos_documentales…)—, invalidos y, si está listo, ejecutaria con la herramienta, los argumentos y el peldaño de confirmación. Cubre los obligatorios condicionales (fecha_documento en una Entrada) y los grupos «exactamente uno de». Regla: se pregunta lo que falte, una pregunta a la vez cuando son varias referencias, y los UUID y códigos nunca se inventan ni se infieren: salen de la lectura. Preparar no es aprobar: ejecutar sigue pasando por la propuesta y su confirmación.

Pendientes de hoy (`mis_pendientes`)¶

La tool mis_pendientes (sin argumentos) y GET /api/v1/mcp/hoy devuelven, por cada rutina que el perfil de la persona alcanza, {clave, titulo, conteo, enlace, guia}: cuántos radicados por tramitar, firmas por dar, borradores en curso, anulaciones por decidir, préstamos vencidos… Las rutinas salen del permiso y el nivel (no del nombre del rol): la que la persona no alcanza no aparece. Cada conteo lo calcula el servicio de dominio con el token de la persona (clearance y privacidad incluidos); si una lectura falla o tarda, el conteo es null y no se explica por qué. No trae contenido de los documentos, solo conteos y el enlace a la pantalla donde se atiende. Responde también con el asistente apagado.

Informes (`preparar_informe`)¶

La tool preparar_informe(informe, dimension, desde, hasta) y GET /api/v1/mcp/informes (catálogo, sin la bandera del asistente) cubren el primer corte de informes: solo conteos de la dependencia activa de la persona por estado, tipo y mes (radicados, trámites vencidos y por vencer), sin nombres de personas. Al modelo llega únicamente el resumen (total, número de grupos y el conteo por valor si son pocos) y el descriptor normalizado; las filas las pide el navegador de la persona con su sesión. El catálogo es cerrado: una clave, dimensión o filtro fuera de él da 422, y el modelo nunca arma la ruta. Clearance y privacidad se aplican en el WHERE del conteo, así que la persona solo cuenta lo que ya puede leer; cada consulta deja el asiento report.consultado.

Acciones masivas de trámite (`*_en_masa`)¶

Primer corte (ADR-072 D6): asignar, trasladar e informar varios radicados, hasta 20 por este canal (la aplicación admite 100). Siempre en dos pasos: primero vista_previa_asignar_en_masa (o _trasladar_, _informar_), una lectura que no escribe nada y dice, por radicado, si procede (aplicable), por qué no (rechazado y su codigo_error) o no_encontrado (inexistente o que la persona no ve: el mismo resultado, sin causa), y devuelve una huella. Después asignar_en_masa (o trasladar_en_masa, informar_en_masa) con los mismos radicados y parámetros, la huella y una clave_idempotencia nueva (un UUID): devuelve la propuesta de peldaño 3 y la tarjeta lista los radicados; se confirma tecleando cuántos son. Si la selección cambió entre la vista previa y la confirmación, el servidor responde 409 seleccion_cambiada y no ejecuta nada. Cada radicado es su propio acto con su asiento; un ítem que falla no deshace los demás, y el resultado es por ítem (consultar_operacion_masiva). Repetir la misma clave devuelve el mismo lote.

Segundo corte (incremento 7): incluir varios radicados en un expediente, con el mismo contrato. vista_previa_incluir_radicados_en_expediente_en_masa (lectura, no escribe, devuelve la huella), después incluir_radicados_en_expediente_en_masa con el expediente_id, los mismos radicados, el motivo, la huella y una clave_idempotencia nueva: peldaño 3 (se confirma tecleando cuántos son), hasta 20, gate USUA_PERM_EXPEDIENTE nivel 2 (el del vínculo unitario). Cada radicado es su propio vínculo con su asiento: un anulado, uno sin tipificar o uno ya vinculado queda rechazado con su codigo_error sin deshacer los demás, y uno inexistente o que la persona no ve es no_encontrado. Hace falta poder leer el expediente (si no, es el mismo 404 que uno inexistente). consultar_inclusion_masiva_en_expediente da el resultado del lote. vincular_radicados_en_lote (todo-o-nada, hasta 500) sigue existiendo.

Por este canal no se ofrecen en masa anular, inactivar, reclasificar, desclasificar, cambiar la privacidad, firmar o dar el visto bueno, aprobar borradores, retipificar, la retención legal, devolver ni finalizar o archivar (NO_OFRECIDAS), ni reprocesar los fallidos de un lote: para esos, uno por uno o desde la aplicación.

De dónde sale¶

La guía no se escribe a mano. Se compone en cada lectura a partir de tres fuentes:

el marco de alcance (mi_alcance), que cruza el catálogo con los permisos, el nivel y el acceso a la información de la persona;
el mapa de flujos del servidor MCP, el mismo que usa el censo de API por flujos;
la frase de ejemplo que declara cada herramienta. En las consultas se deriva de su operación: «Consultar un radicado» se convierte en «Consulta un radicado».

Una herramienta nueva aparece en la guía sin tocar la guía. Un guardián exige que toda escritura y todo procedimiento declaren su frase.