Motor Semantic MCP

Aplicación maestra para capturar evaluaciones motoras pediátricas, conservar su contexto metodológico y exponer consultas semánticas y carga clínica controlada mediante Model Context Protocol (MCP).

Este repositorio es el artefacto principal del proyecto final “Modelado semántico y exposición de contexto mediante MCP para la automatización analítica en sistemas de evaluación motora pediátrica”. El servicio Python tests-calculator es un componente subordinado y determinista: calcula KTK, pero no gestiona participantes, sesiones, permisos ni MCP.

Propósito del proyecto

El proyecto estudia si un agente de IA puede utilizar con mayor corrección los datos de un único sistema de evaluaciones motoras cuando, además de recibir campos y tipos, dispone de un modelo semántico canónico con unidades, versiones de protocolo, temporalidad, restricciones y procedencia. La interoperabilidad se produce entre dos sistemas independientes: esta plataforma y el cliente o agente MCP. No requiere integrar múltiples sistemas clínicos para constituir un caso válido de interoperabilidad.

MCP aporta descubrimiento e invocación estandarizada de recursos y herramientas; no crea por sí mismo el significado del dominio. La semántica pertenece al modelo canónico y se expone mediante MCP. La evaluación principal comparará una exposición MCP estructural básica con otra semánticamente enriquecida, manteniendo constantes el agente, los datos y las tareas.

Related MCP server: fhir-synthetic-mcp

Arquitectura

Interfaz Laravel
  └─ registra la evaluación
       ├─ tests-calculator (cálculo KTK)
       └─ persistencia transaccional del contexto semántico
            ├─ Participant seudonimizado
            ├─ AssessmentSession
            ├─ ProtocolVersion inmutable
            ├─ Trial
            └─ Measurement con unidad y procedencia

Cliente de IA
  └─ MCP HTTP + Sanctum + capacidades de lectura o carga clínica
       └─ casos de uso de aplicación
            ├─ consultas semánticas seudonimizadas
            └─ borradores clínicos cifrados con confirmación

La tabla histórica test_applications se mantiene por compatibilidad con la interfaz. Cada KTK nuevo se guarda, dentro de la misma transacción, en el modelo normalizado. La API Python nunca recibe acceso a la base de datos ni credenciales MCP.

Capacidades actuales

• gestión web de pacientes, profesionales, especialidades y equipos;

• captura KTK y cálculo mediante la API Python externa;

• captura TUG con tres intentos por lado en segundos;

• captura de prensión manual con tres intentos por mano, dominancia, configuración y unidad del dinamómetro;

• anamnesis clínica en el sistema transaccional;

• persistencia normalizada y versionada de KTK;

• servidor MCP autenticado con tokens revocables y rate limiting;

• herramientas get-protocol-context y get-participant-timeline;

• consultas MCP sin nombre, documento, fecha de nacimiento ni identificador clínico del paciente, y escritura clínica separada mediante borradores cifrados, permisos y confirmación;

• paquete experimental versionado con dataset sintético, corpus, rúbricas y telemetría MCP correlacionada;

• traducciones es_AR y pt_BR y pruebas de arquitectura.

Los protocolos institucionales TUG y prensión se publican como borradores gpec-form-2026.1 y no generan clasificación clínica automática. Consentimiento Research, snapshots analíticos y ejecución reproducible de Python/R siguen siendo incrementos posteriores.

Puesta en marcha

composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan serve

Configurar el calculador con TESTS_CALCULATOR_URL y el contexto semántico con SEMANTIC_CONTEXT_CODE. Para validar:

php artisan test

Documentación

• Persistencia semántica

• Servidor MCP y contrato seguro

• Paquete experimental estructural frente a semántico

• Internacionalización

• Documentación metodológica del proyecto final

• Guía para revisar el anteproyecto y ejecutar el experimento

Datos sensibles

La implementación es un prototipo académico. El módulo operativo de Research no integra el alcance actual. Antes de usar datos reales se requieren aprobación institucional, base legal o consentimiento aplicable, HTTPS, gestión de identidades y roles, backups, retención, respuesta a incidentes y revisión de seguridad independiente.

Para configurar TOKEN mcp utilizar el siguiente comando:

read -s MOTOR_TOKEN
launchctl setenv MOTOR_MCP_TOKEN "$MOTOR_TOKEN"
unset MOTOR_TOKEN

y pegar el TOKEN generado. Luego aceptar con Enter.

motor-semantic-mcp

motor-semantic-mcp