clinica-veterinaria/docs/05-fase-ia/MGN-022-mcp-server/README.md

# MGN-022: MCP Server Veterinario

**Modulo:** MGN-022
**Nombre:** MCP Server para Clinicas Veterinarias
**Fase:** 05 - Inteligencia Artificial
**Estado:** Draft
**Ultima actualizacion:** 2026-01-13

---

## Descripcion

Servidor MCP (Model Context Protocol) especializado para clinicas veterinarias. Expone herramientas de negocio veterinario a los modelos de lenguaje, permitiendo que el asistente IA interactue con expedientes de mascotas, cartillas de vacunacion, citas y hospitalizaciones.

---

## Normativas Aplicables

- **NOM-064-ZOO-2000**: Trazabilidad de medicamentos y vacunas
- **SENASICA**: Registro oficial de vacunacion
- **Bienestar Animal**: Registro de condiciones de pacientes

---

## Herramientas MCP Veterinarias

### Mascotas Tools (4 herramientas)

| Tool | Descripcion | Parametros |
|------|-------------|------------|
| `consultar_historial_mascota` | Expediente clinico completo | mascota_id |
| `buscar_mascota` | Buscar por nombre o propietario | query, propietario_id? |
| `obtener_signos_vitales` | Ultimos signos vitales | mascota_id |
| `listar_mascotas_propietario` | Mascotas de un propietario | propietario_id |

### Vacunacion Tools (4 herramientas)

| Tool | Descripcion | Parametros |
|------|-------------|------------|
| `consultar_cartilla_vacunacion` | Historial de vacunas | mascota_id |
| `registrar_vacuna` | Registrar aplicacion | mascota_id, vacuna_id, lote, veterinario_id |
| `vacunas_pendientes` | Vacunas proximas | mascota_id, dias_anticipacion? |
| `esquema_vacunacion_especie` | Esquema por especie | especie, edad_meses? |

### Desparasitacion Tools (3 herramientas)

| Tool | Descripcion | Parametros |
|------|-------------|------------|
| `verificar_desparasitacion` | Estado actual | mascota_id |
| `registrar_desparasitacion` | Registrar aplicacion | mascota_id, producto_id, dosis |
| `proxima_desparasitacion` | Fecha recomendada | mascota_id |

### Citas Tools (4 herramientas)

| Tool | Descripcion | Parametros |
|------|-------------|------------|
| `agendar_consulta` | Programar cita | mascota_id, fecha, hora, motivo, veterinario_id? |
| `consultar_citas` | Citas del dia/semana | fecha_inicio, fecha_fin?, veterinario_id? |
| `confirmar_cita` | Confirmar asistencia | cita_id |
| `cancelar_cita` | Cancelar cita | cita_id, motivo? |

### Hospitalizacion Tools (4 herramientas)

| Tool | Descripcion | Parametros |
|------|-------------|------------|
| `consultar_hospitalizacion` | Estado de internado | mascota_id |
| `registrar_evolucion` | Agregar nota de evolucion | hospitalizacion_id, notas, signos_vitales? |
| `pacientes_internados` | Lista de hospitalizados | area? |
| `alta_hospitalizacion` | Dar de alta | hospitalizacion_id, instrucciones |

### Laboratorio Tools (3 herramientas)

| Tool | Descripcion | Parametros |
|------|-------------|------------|
| `solicitar_estudio` | Ordenar estudio de lab | mascota_id, tipo_estudio, notas? |
| `resultados_laboratorio` | Consultar resultados | mascota_id, estudio_id? |
| `estudios_pendientes` | Estudios sin resultado | mascota_id? |

---

## Recursos MCP Veterinarios

| URI | Descripcion | Retorna |
|-----|-------------|---------|
| `vet://config/clinica` | Configuracion de la clinica | nombre, direccion, telefono, horarios |
| `vet://catalogo/vacunas` | Catalogo de vacunas | Array de vacunas por especie |
| `vet://catalogo/especies` | Especies soportadas | Array de especies con razas |
| `vet://calendario/vacunacion` | Calendario oficial | Esquemas por especie y edad |
| `vet://hospitalizacion/resumen` | Resumen de internados | total, por_area, alertas |

---

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /api/v1/mcp/tools/call | Ejecutar herramienta |
| GET | /api/v1/mcp/tools | Listar herramientas |
| GET | /api/v1/mcp/tools/:name | Definicion de herramienta |
| GET | /api/v1/mcp/resources | Listar recursos |
| GET | /api/v1/mcp/resources/:uri | Obtener recurso |

---

## Ejemplos de Uso

### Consultar Cartilla de Vacunacion

```json
// Request
{
  "tool": "consultar_cartilla_vacunacion",
  "params": {
    "mascota_id": "pet-123"
  }
}

// Response
{
  "mascota": {
    "nombre": "Max",
    "especie": "canino",
    "raza": "Labrador",
    "edad": "2 anios"
  },
  "vacunas": [
    {
      "vacuna": "Cuadruple",
      "fecha_aplicacion": "2024-03-15",
      "lote": "LOT-2024-001",
      "veterinario": "Dr. Garcia",
      "proxima": "2025-03-15"
    },
    {
      "vacuna": "Rabia",
      "fecha_aplicacion": "2024-06-20",
      "lote": "RAB-2024-050",
      "veterinario": "Dr. Garcia",
      "proxima": "2025-06-20"
    }
  ],
  "pendientes": [
    {
      "vacuna": "Bordetella",
      "recomendada_desde": "2024-09-15",
      "dias_vencida": 120
    }
  ]
}
```

### Agendar Consulta

```json
// Request
{
  "tool": "agendar_consulta",
  "params": {
    "mascota_id": "pet-456",
    "fecha": "2026-01-15",
    "hora": "10:00",
    "motivo": "Vacunacion anual",
    "veterinario_id": "vet-001"
  }
}

// Response
{
  "cita": {
    "id": "cit-789",
    "mascota": "Luna",
    "propietario": "Maria Lopez",
    "fecha": "2026-01-15",
    "hora": "10:00",
    "veterinario": "Dra. Martinez",
    "motivo": "Vacunacion anual",
    "estado": "confirmada"
  },
  "mensaje": "Cita agendada exitosamente. Se enviara recordatorio por WhatsApp."
}
```

### Consultar Hospitalizacion

```json
// Request
{
  "tool": "consultar_hospitalizacion",
  "params": {
    "mascota_id": "pet-789"
  }
}

// Response
{
  "hospitalizacion": {
    "id": "hosp-001",
    "mascota": "Rocky",
    "especie": "canino",
    "ingreso": "2026-01-12T14:00:00Z",
    "motivo": "Cirugia de rodilla",
    "estado": "estable",
    "area": "Post-quirurgico",
    "veterinario_responsable": "Dr. Hernandez"
  },
  "ultima_evolucion": {
    "fecha": "2026-01-13T08:00:00Z",
    "notas": "Paciente alerta, comiendo bien. Herida sin signos de infeccion.",
    "signos_vitales": {
      "temperatura": 38.5,
      "frecuencia_cardiaca": 90,
      "frecuencia_respiratoria": 20
    }
  },
  "dias_internado": 1,
  "alta_estimada": "2026-01-14"
}
```

---

## Arquitectura

```
+-------------------+     +-------------------+     +-------------------+
|   AI Veterinaria  |---->|   MCP Controller  |---->|   Tool Services   |
|   (Claude/GPT)    |     |   (validacion)    |     |   (veterinarios)  |
+-------------------+     +-------------------+     +-------------------+
                                  |                         |
                                  v                         v
                          +-------------+           +---------------+
                          | Tool Logger |           | Backend Vet   |
                          | (auditoria) |           | (services)    |
                          +-------------+           +---------------+
```

---

## Seguridad

- Autenticacion JWT requerida
- Aislamiento por clinica (RLS)
- Logging de todas las llamadas
- Validacion de permisos por herramienta
- Rate limiting por plan
- Datos sensibles de mascotas protegidos

---

## Dependencias

**Este modulo depende de:**
- MGN-001 Auth (autenticacion, tenant_id)
- MGN-017 Plans (rate limiting por plan)
- Modulos veterinarios (mascotas, vacunacion, citas, hospitalizacion)

**Modulos que dependen de este:**
- MGN-020 AI Integration (usa las tools)
- MGN-021 WhatsApp Business (usa las tools)

---

## Indices

- [Requerimientos](./requerimientos/INDICE-RF-MCP.md)
- [Especificaciones](./especificaciones/INDICE-ET-MCP.md)
- [Historias de Usuario](./historias-usuario/INDICE-US-MCP.md)
- [Trazabilidad](./implementacion/TRACEABILITY.yml)

---

*Modulo: MGN-022-mcp-server-vet*
*Propagado desde: erp-core/MGN-022-mcp-server*
*Adaptado para: Dominio veterinario*
*Fecha: 2026-01-13*