SAP SuccessFactors Multi-Agent MCP Prototype

Demostración con datos sintéticos de estilo SuccessFactors. Este es un prototipo educativo de solo lectura, no un sistema SAP SuccessFactors y no está listo para producción.

La aplicación responde a preguntas de RR. HH. autorizadas a través de un límite estrecho de herramientas MCP. El modo mock no requiere credenciales de SAP ni de OpenAI. El modo demo añade orquestación opcional con OpenAI Agents SDK; el modo real está reservado para un tenant de SuccessFactors de no producción explícitamente configurado.

Características

• Once herramientas MCP tipadas y de solo lectura; sin superficie arbitraria de HTTP, OData o escritura.

• Cuatro identidades sintéticas con roles del lado del servidor y ámbitos de población.

• Listas de permitidos explícitas de entidades y campos, además de saneamiento de respuestas con denegación por defecto.

• Diez empleados ficticios, doce puestos, objetos de base, historial con fechas de vigencia, vacantes y problemas intencionados de calidad de datos.

• Registro de auditoría estructurado en SQLite sin cargas útiles completas de RR. HH. ni secretos.

• API de chat/auditoría FastAPI e interfaz Streamlit centrada en la evidencia.

• El chat mock determinista funciona sin clave de API.

Related MCP server: HRIS MCP Connector

Configuración en Windows (ruta principal)

cd .\successfactors-mcp-prototype
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\setup_windows.ps1

Ejecute todos los servicios:

.\scripts\run_all_windows.ps1

O use tres terminales:

.\scripts\run_mcp_windows.ps1
.\scripts\run_backend_windows.ps1
.\scripts\run_ui_windows.ps1

run_ui_windows.ps1 inicia FastAPI en segundo plano automáticamente cuando el backend no está ya en ejecución, por lo que también puede usarse como el lanzador mock de interfaz más sencillo con un solo comando.

• Interfaz: http://127.0.0.1:8501

• API: http://127.0.0.1:8000

• OpenAPI: http://127.0.0.1:8000/docs

• MCP: http://127.0.0.1:8001/mcp

Unix y VS Code

Ejecute bash scripts/setup_unix.sh y, a continuación, bash scripts/run_all_unix.sh. En VS Code seleccione .venv como intérprete de Python y abra tres terminales si lo prefiere.

Configuración y modos

Copie .env.example a .env; los marcadores de posición no contienen secretos.

• APP_MODE=mock: proveedor sintético y chat determinista; sin credenciales externas.

• APP_MODE=demo: proveedor sintético con orquestación en vivo de Agents SDK; requiere OPENAI_API_KEY y MCP_INTERNAL_TOKEN.

• APP_MODE=real: solo tenant de prueba configurado. La falta de ajustes provoca un fallo al iniciar; no hay respaldo mock.

OPENAI_MODEL centraliza la selección del modelo. Los rangos de dependencias apuntan a Python 3.11 y a las versiones principales compatibles actuales, evitando actualizaciones principales no revisadas.

Demo en vivo de Agents SDK

Copie .env.example a .env y, a continuación, establezca estos valores:

APP_MODE=demo
OPENAI_MODEL=gpt-5.4-mini
OPENAI_API_KEY=your-key-from-a-secret-store
MCP_INTERNAL_TOKEN=a-long-random-local-secret

No confirme .env en el repositorio. run_ui_windows.ps1 inicia ahora el servidor MCP y FastAPI cuando es necesario. La aplicación transmite la identidad de usuario, sesión y correlación a MCP a través de cabeceras HTTP protegidas; esos campos no aparecen en los esquemas de herramientas invocables por el modelo. Los especialistas reciben listas de permitidos de herramientas codificadas. El rastro de la interfaz registra únicamente los nombres del ciclo de vida de agentes/herramientas, no las indicaciones, argumentos, resultados ni razonamientos privados.

Los controles de coste se configuran con DEMO_MAX_TURNS, DEMO_MAX_OUTPUT_TOKENS y DEMO_DAILY_TOKEN_BUDGET. Establezca OPENAI_INPUT_COST_PER_1M y OPENAI_OUTPUT_COST_PER_1M a las tarifas actuales del modelo elegido para mostrar una estimación local. El rastreo de OpenAI está desactivado por defecto y, cuando se activa, el contenido sensible del rastro permanece desactivado.

La suite normal nunca llama a OpenAI. Para ejecutar la única prueba de humo de delegación en vivo opcional después de que los tres servicios estén en ejecución en modo demo:

$env:RUN_LIVE_AGENT_TESTS="true"
.\.venv\Scripts\python.exe -m pytest -m live -q

Esta prueba realiza una solicitud real a la API y, por tanto, incurre en uso del modelo.

Verificación

python -m ruff format --check .
python -m ruff check .
python -m mypy src
python -m pytest

Configuración de autenticación real del tenant de prueba

1. Registre un cliente OAuth en SuccessFactors API Center.

2. Cree un usuario de API dedicado.

3. Asigne los permisos de consulta RBP mínimos requeridos.

4. Limite la población objetivo.

5. Conceda acceso de consulta solo a entidades y campos aprobados.

6. Almacene el material OAuth fuera del control de código fuente.

7. Valide el flujo OAuth firmado específico del tenant contra un tenant de no producción.

8. Verifique tanto los escenarios de empleados permitidos como los denegados.

La autenticación básica no es compatible. La interfaz incluida del proveedor de tokens real falla intencionadamente hasta que se implemente y valide el flujo documentado por SAP específico del tenant.

Docker

Después de copiar .env.example a .env, ejecute docker compose up --build. Docker es opcional y el archivo compose es solo para desarrollo, no está endurecido para producción.

Solución de problemas y limitaciones

• Si la interfaz informa de que el backend no está disponible, inicie FastAPI primero.

• Si falla el enlace de puerto, detenga el proceso que usa 8000, 8001 o 8501.

• El selector de usuario del prototipo no es autenticación de producción.

• SQLite no está pensado para almacenamiento de auditoría de producción con escalado horizontal.

• El OAuth real, las peculiaridades de los metadatos del tenant y el comportamiento de RBP requieren validación del tenant.

• El enrutamiento mock admite deliberadamente los patrones de preguntas de demostración proporcionados; no es un motor general de lenguaje natural.

• Las escrituras futuras requieren una arquitectura aprobada por separado y no están presentes, ni siquiera como marcadores de posición.

Para el flujo detallado y los límites de confianza, consulte ARCHITECTURE.md; para controles y riesgos, consulte SECURITY.md. Los registros sintéticos exactos y la guía de escenarios se describen en TEST_DATA.md y se exportan en test_data/.