MCP para Primavera Unifier

Servidor MCP por stdio y aplicación web agentic para Oracle Primavera Unifier. Autentica un usuario de integración contra el endpoint V2 de token y reutiliza el access_token como Bearer para las llamadas REST V1/V2.

Proyecto comunitario de demostración. No es un producto oficial de Oracle, no está afiliado, patrocinado, respaldado ni mantenido por Oracle. Oracle, OCI, Primavera y Unifier son marcas comerciales de Oracle Corporation y/o sus afiliadas.

Sin soporte ni garantías. El código se proporciona «tal cual», exclusivamente para evaluación y demostración. Los autores y mantenedores no asumen ninguna obligación de soporte, mantenimiento, actualización, corrección de errores o parches de seguridad. Cada usuario debe validar la solución, permisos, endpoints, costes y controles de seguridad en su propio entorno antes de utilizarla.

Este repositorio no incluye credenciales, documentos de cliente ni datos extraídos. Utiliza secretos de entorno y documentos sintéticos para las pruebas. Consulta SUPPORT.md, SECURITY.md y LICENSE antes de utilizar el proyecto.

Herramientas disponibles

• unifier_connection_test: comprueba autenticación y acceso de lectura.

• unifier_list_shells: lista proyectos y shells (GET /ws/rest/service/v1/admin/projectshell).

• unifier_read_shell_360: workflow de dos lecturas encadenadas: valida el shell en V1 y obtiene sus metadatos activos en V2. Devuelve únicamente campos operativos seleccionados.

• unifier_list_bp_records: consulta registros de un BP de un shell (POST /ws/rest/service/v1/bp/records/{project_number}). Este POST es una consulta y se mantiene habilitado en modo de solo lectura.

• unifier_rest_request: acceso a cualquier endpoint REST V1/V2 documentado. Solo permite GET y HEAD de inicio; las mutaciones requieren una habilitación explícita.

Workflows Enterprise AI de solo lectura

• unifier_inspect_bp, unifier_find_bp_record y unifier_approval_control: inspección de BPs, búsqueda acotada por destinos y control de pendientes.

• unifier_project_health y unifier_cost_sheet_budget: visión de proyecto, Cost Sheet, snapshots, paquetes de trabajo y BPs financieros configurados.

• unifier_project_autopilot_snapshot: snapshot compacto y comparable de coste, planificación, BPs y aprobaciones; no devuelve registros completos ni escribe en Unifier.

• unifier_risk_center: centro de riesgos con evidencia de shell, Cost Sheet, planificación y BPs seleccionados; clasifica señales y prepara borradores de acción, sin escribir en Unifier.

• unifier_schedule_health: Schedule Sheets y, con source_project_id, actividades del System Activity Sheet.

• unifier_search_documents: metadatos y documentos de una ruta de Document Manager, sin descargas.

• unifier_audit_inactive_shells y unifier_compare_projects: auditoría de inactivos y comparación de varios shells.

• unifier_bp_permissions: permisos de visualización, edición y administración de registros de un BP.

Los nombres técnicos de BPs, la ruta de Document Manager y el source_project_id dependen de cada configuración de Unifier. Los workflows los solicitan solo cuando son necesarios.

Related MCP server: oracle-mcp

Configuración

Instala las dependencias y compila:

npm install
npm run build

Configura las variables como secretos de tu cliente MCP (no uses un .env versionado):

{
  "mcpServers": {
    "primavera-unifier": {
      "command": "node",
      "args": ["/RUTA/ABSOLUTA/mcp_primavera/dist/index.js"],
      "env": {
        "UNIFIER_BASE_URL": "https://your-unifier-host.example.com/companycode/unifier",
        "UNIFIER_USERNAME": "<usuario-integracion>",
        "UNIFIER_PASSWORD": "<secreto>"
      }
    }
  }
}

Para desarrollo local, guarda los valores en un archivo .env (que ya está ignorado por Git) y arranca con node --env-file=.env dist/index.js. No uses .env.example para secretos: debe quedar como plantilla sin valores reales.

Para permitir altas, actualizaciones o borrados por unifier_rest_request, añade UNIFIER_ALLOW_WRITE=true. Déjalo desactivado durante el descubrimiento.

Si ya dispones de un token de Unifier, puedes configurar UNIFIER_ACCESS_TOKEN como secreto de entorno. Tiene prioridad sobre usuario y contraseña; úsalo solo hasta su vencimiento. Usa UNIFIER_TOKEN_AUTH_SCHEME=Bearer para un token V2/OAuth o UNIFIER_TOKEN_AUTH_SCHEME=Basic para un token de sesión V1.

Límites y seguridad

Con UNIFIER_AUTH_MODE=credentials, el servidor obtiene el token V2 con el usuario y contraseña del entorno, lo mantiene en memoria y lo renueva; en este modo ignora cualquier UNIFIER_ACCESS_TOKEN antiguo. UNIFIER_BASE_URL puede ser la URL de la interfaz o terminar en /ws/rest/service: el cliente normaliza ambos formatos y evita duplicar ese tramo.

La URL de la interfaz puede terminar en /unifier; el cliente elimina ese sufijo para llamar a la raíz REST https://<host>/<companycode>/ws/rest/service/..., según la configuración de conexiones de Oracle. La conexión solo se considera validada con un listado JSON y status: 200. Un HTTP 200 que contenga una página HTML de login es un error, no una conexión correcta. Las llamadas REST no siguen redirecciones al SSO.

El servidor no almacena ni devuelve contraseñas o tokens. Solo acepta rutas bajo /ws/rest/service/v1/ o /ws/rest/service/v2/, y renueva el token tras un 401.

Las capacidades reales dependen de los permisos del usuario de integración y de los módulos publicados en la instancia Unifier.

Si el endpoint V2 redirige a Oracle Identity/SSO en lugar de responder JSON, el usuario no está listo para Basic Authentication. Un administrador debe confirmar que sea un Integration User activo con tipo de autenticación Basic, o proporcionar los parámetros del flujo OAuth habilitado para la instancia.

Interfaz conversacional local

El proyecto incluye una interfaz de chat en http://127.0.0.1:3000. El navegador conserva el historial visual y el backend conserva el contexto lógico de la conversación mediante previous_response_id. En cada turno, el modelo decide qué herramienta del MCP necesita ejecutar.

Primer workflow Enterprise AI: Ficha 360

La interfaz usa OCI Responses API con funciones MCP, por lo que el modelo ejecuta el workflow cuando se pide una ficha, detalle o visión 360 de un shell. unifier_read_shell_360 valida primero el project_number en GET /ws/rest/service/v1/admin/projectshell y encadena GET /ws/rest/service/v2/admin/shell para recuperar metadatos activos. Es una operación estrictamente de lectura.

Ejemplo: Dame la ficha 360 del shell P-0001.

Además de las variables de Unifier, configura en tu .env el proveedor de modelo. OCI GenAI usa la Responses API compatible con OpenAI y es la opción preferida:

# OCI Generative AI (API key de Generative AI, no la clave privada de tu perfil OCI)
OCI_GENAI_API_KEY=<api-key-de-generative-ai>
OCI_GENAI_REGION=<region-oci, por-ejemplo-us-chicago-1>
OCI_GENAI_PROJECT_OCID=<ocid-del-generative-ai-project>
OCI_GENAI_MODEL=<id-de-modelo-soportado-en-tu-region>

# Opcional: habilita RAG con documentos cargados en un Vector Store de OCI.
OCI_VECTOR_STORE_ID=<id-del-vector-store>

# Opcional: auditoría periódica de shells inactivos; 0 o vacío la desactiva.
AGENT_MONITOR_INTERVAL_MINUTES=0

# Para el token V1 que se envía como Authorization: Basic <token>
UNIFIER_ACCESS_TOKEN=<token-unifier>
UNIFIER_TOKEN_AUTH_SCHEME=Basic

Como alternativa a OCI_GENAI_API_KEY, puedes usar el perfil IAM local que indicaste. La aplicación usa oci raw-request para firmar cada llamada mediante el perfil; necesita que la CLI de OCI esté instalada y que el perfil contenga región y una clave válida:

OCI_GENAI_PROFILE=DEFAULT
OCI_GENAI_PROJECT_OCID=<ocid-del-generative-ai-project>
OCI_GENAI_MODEL=<id-de-modelo-soportado-en-tu-region>
# OCI_GENAI_REGION es opcional si ya está configurada en el perfil indicado.

Como última alternativa, admite OPENAI_API_KEY y OPENAI_MODEL. Si existen varias configuraciones, la prioridad es API key de OCI, IAM de OCI y, finalmente, OpenAI.

Después, inicia la interfaz con:

npm run build
node --env-file=.env dist/web.js

La interfaz exige autenticación antes de acceder a cualquier ruta /api. Configura el usuario, la contraseña y la duración de la sesión en .env:

APP_AUTH_USERNAME=admin
APP_AUTH_PASSWORD=change-this-before-running
APP_AUTH_SESSION_HOURS=8

La sesión se mantiene en memoria mediante una cookie HttpOnly y SameSite=Strict; por tanto, se cierra al reiniciar el servidor o al pulsar Salir. Cambia la contraseña de demostración antes de exponer la aplicación fuera de un equipo de desarrollo.

El proceso escucha únicamente en 127.0.0.1. Si necesitas acceso remoto, colócalo detrás de un proxy HTTPS, cambia la contraseña de demostración, activa APP_AUTH_SECURE_COOKIE=true y aplica controles de red adecuados. Para reiniciar el contexto, pulsa Nueva conversación.

Portlet de Unifier

La ruta /unifier-portlet está diseñada para mostrarse en un Portlet Block de Unifier sin relajar la protección anti-iframe de la ruta principal. La plantilla deploy/nginx-primavera-agentica.conf.template necesita dos valores antes de instalarse:

export PUBLIC_HOST=demo.example.com
export UNIFIER_PARENT_ORIGIN=https://your-unifier-host.example.com

La ruta principal conserva X-Frame-Options: DENY y frame-ancestors 'none'. La ruta del portlet usa una cookie de sesión independiente con Secure, SameSite=None y Partitioned. Para un uso real, emplea un certificado emitido por una CA de confianza.

Historial de decisiones de contratos

El panel colapsable «Historial de decisiones» muestra los eventos de la sesión actual para el shell activo y permite buscar por campo, contrato, responsable o motivo. Antes de confirmar un bloqueo, indica el responsable y el motivo/fuente en el agente de contratos. Las correcciones se registran al salir del campo; cambiar un dato confirmado vuelve a abrir su bloqueo.

Se conservan propuestas de extracción y revalidación, valores anteriores/nuevos, evidencia textual, nombres y hashes SHA-256 de los PDF analizados, confirmaciones, excepciones y eventos de publicación. Cada expediente tiene un identificador incluido en el JSON revisado. La revalidación conserva la historia anterior y registra nuevas propuestas; no restaura automáticamente correcciones manuales.

El destino persistente es Unifier, no el disco local. Al pulsar «Publicar contrato e historial» y confirmar, el backend genera en memoria historial-decisiones-<expediente>.pdf y .json. Ambos se adjuntan al mismo registro BP y en la misma llamada REST que los contratos y anexos. No requieren nuevos campos de uDesigner. Se mantienen los requisitos existentes del BP, permisos para adjuntos, configuración de Auto Creation y mapeo de campos.

El PDF permite leer la secuencia de decisiones, valores finales, campos técnicos, responsables, motivos, evidencias y hashes. El JSON conserva los valores y texto Unicode completos. Ambos son una foto previa al envío: no certifican la creación ni incluyen la respuesta de esa misma publicación. Los eventos de respuesta se muestran solo en la pestaña; consulta el estado real y los adjuntos del registro en Unifier. El estado inicial del BP depende de su configuración, no del nombre «borrador» usado en la UI.

Hasta publicar, las decisiones y archivos solo permanecen en memoria de la pestaña. Recargar o cerrar pierde la revisión pendiente; el navegador avisa si hay decisiones sin publicar. Si falla el envío, conserva la pestaña y comprueba primero en Unifier si se creó el registro para evitar duplicados. Se bloquea la publicación si el shell no coincide con el análisis o si los hashes de los documentos han cambiado: revalida en ese caso. Máximo: 6 PDF de origen + 2 informes, 25 MB en conjunto; historial de hasta 1000 eventos / 2 MB.

Los historiales publicados se consultan en los adjuntos del contrato en Unifier; el panel no los descarga automáticamente. El backend ya no lee ni escribe data/decisions.jsonl y /api/decisions responde 410 a clientes antiguos. Un archivo local de una versión anterior no se migra ni elimina automáticamente.

Esta demo registra identidad y fechas declaradas por el navegador, sin autenticarlas. Los informes no son una auditoría inalterable ni reemplazan el Audit Log nativo de Unifier. Las decisiones anteriores a esta funcionalidad no se reconstruyen.

Pruebas: npm test valida generación, empaquetado y controles del historial. RUN_INTEGRATION_TESTS=1 npm test añade el recorrido web → MCP → servidor Unifier simulado en loopback, sin cargar .env ni usar credenciales reales. Para comprobar visualmente el informe con datos sintéticos: npm run build && node scripts/preview-decision-report.mjs; el PDF de QA se genera en tmp/pdfs/ (excluido de Git).

Autopilot de proyecto

El panel «Autopilot de proyecto» de Mission Control permite activar la vigilancia del shell seleccionado. Configura nombres técnicos de BPs separados por comas, los BPs que representan aprobaciones y, opcionalmente, el source_project_id para contar actividades vencidas. Si se omite, intenta descubrirlo desde los metadatos Gateway/Primavera Cloud del shell. Al activar, hace una lectura real y crea una línea base sin alerta.

Mientras dist/web.js siga ejecutándose, cada mañana compara una nueva lectura de Cost Sheet, paquetes, Schedule Sheets, actividades, estados e importes de BPs y carga de aprobaciones. Solo abre una alerta en Mission Control si cambia una métrica material, el estado del shell o la disponibilidad de una fuente. Los cambios financieros inferiores a PROJECT_AUTOPILOT_AMOUNT_DELTA (1000 por defecto) se ignoran. Errores idénticos consecutivos no duplican alertas.

La hora se configura con PROJECT_AUTOPILOT_HOUR, PROJECT_AUTOPILOT_MINUTE y PROJECT_AUTOPILOT_TIMEZONE (por defecto 08:00 Europe/Madrid). Si el proceso arranca después de esa hora y aún no ha ejecutado ese día, realiza la revisión pendiente. «Ejecutar ahora» permite demostrar el flujo sin esperar. Para garantizar la ejecución diaria en producción, mantén el proceso bajo systemd, Docker, Kubernetes o un servicio equivalente.

El Autopilot es de solo lectura en Unifier. Su línea base, configuración y alertas de Mission Control se guardan en data/project-autopilot.json, con métricas agregadas y sin credenciales ni registros completos. «Marcar revisada» solo reconoce la alerta en la aplicación; no crea ni modifica un BP de Unifier.

Referencias

• Autenticación REST V2 de Unifier

• Listado de proyectos y shells

• Metadatos de un shell V2

• OCI Enterprise AI Agents y Responses API

• Guía de integración REST de Unifier