# 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.

## Arquitectura

```text
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

```bash
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:

```bash
php artisan test
```

## Documentación

- [Persistencia semántica](docs/semantic-assessments.md)
- [Servidor MCP y contrato seguro](docs/mcp.md)
- [Paquete experimental estructural frente a semántico](experiment/README.md)
- [Internacionalización](docs/internationalization.md)
- [Documentación metodológica del proyecto final](docs/project-final/00-vision-y-alcance.md)
- [Guía para revisar el anteproyecto y ejecutar el experimento](material/tesis.md)

## 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:
``` bash
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