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

id	title	type	status	priority	phase	version	created_date	updated_date	normativas
MGN-022-mcp-server	MCP Server para Clinica Dental	Module	Draft	P0	05-fase-ia	1.0.0	2026-01-13	2026-01-13	NOM-013-SSA2-2015 NOM-004-SSA3-2012 COFEPRIS

MGN-022: MCP Server para Clinica Dental

Modulo: MGN-022 Nombre: MCP Server (Model Context Protocol) Dental Fase: 05 - Inteligencia Artificial Story Points: 55 SP Estado: En Diseno Ultima actualizacion: 2026-01-13

---

Descripcion

Modulo que implementa un servidor MCP (Model Context Protocol) siguiendo el estandar de Anthropic, especializado en odontologia. Expone herramientas (tools) de negocio dental a los modelos de lenguaje de manera estandarizada, permitiendo que agentes IA interactuen con el sistema para consultar odontogramas, gestionar citas, registrar tratamientos y administrar presupuestos dentales.

---

Funcionalidades Principales

1. Odontograma Tools - Consulta y actualizacion de odontogramas usando nomenclatura FDI
2. Tratamientos Tools - Registro y consulta de tratamientos dentales
3. Citas Tools - Gestion completa de citas dentales
4. Pacientes Tools - Busqueda y consulta de pacientes
5. Presupuestos Tools - Generacion y consulta de presupuestos
6. Historial Tools - Consulta de historial clinico dental
7. MCP Resources - Recursos expuestos (catalogo tratamientos, precios)
8. Tool Call Logging - Registro de llamadas para auditoria (NOM-004)

---

Herramientas MCP Odontologicas

Odontograma Tools (4 herramientas)

Tool	Descripcion	Parametros
consultar_odontograma	Ver estado completo de piezas dentales	paciente_id
consultar_pieza_dental	Detalle de una pieza especifica	paciente_id, pieza (ej: "16")
registrar_estado_pieza	Actualizar estado de pieza	paciente_id, pieza, estado, cara?, notas?
historial_pieza	Tratamientos previos en pieza	paciente_id, pieza

Estados de Pieza Soportados:

• sano - Sin patologia
• caries - Caries activa
• obturacion_resina - Obturacion con resina
• obturacion_amalgama - Obturacion con amalgama
• endodoncia - Tratamiento de conducto
• corona - Protesis fija
• puente_pilar - Pilar de puente
• puente_pontico - Pontico de puente
• implante - Implante dental
• ausente - Pieza ausente
• extraccion_indicada - Extraccion planificada

Caras Dentales (parametro cara):

• M - Mesial
• D - Distal
• O - Oclusal (molares/premolares)
• I - Incisal (incisivos/caninos)
• V - Vestibular
• L - Lingual
• P - Palatino

Tratamientos Tools (4 herramientas)

Tool	Descripcion	Parametros
registrar_tratamiento	Documentar tratamiento realizado	paciente_id, tipo, piezas[], doctor_id, notas?
consultar_tratamiento	Detalle de un tratamiento	tratamiento_id
listar_tratamientos_paciente	Historial de tratamientos	paciente_id, desde?, hasta?
catalogo_tratamientos	Lista de tratamientos disponibles	categoria?

Categorias de Tratamiento:

• preventivo - Limpiezas, selladores, fluor
• restaurador - Resinas, amalgamas, incrustaciones
• endodoncia - Tratamientos de conducto
• periodoncia - Raspados, cirugia periodontal
• cirugia - Extracciones, implantes
• ortodoncia - Brackets, alineadores
• protesis - Coronas, puentes, dentaduras
• estetica - Blanqueamiento, carillas

Citas Tools (5 herramientas)

Tool	Descripcion	Parametros
agendar_cita_dental	Crear nueva cita	paciente_id, fecha, hora, tratamiento_tipo, doctor_id?, sillon?
consultar_cita	Detalle de cita	cita_id
consultar_citas_paciente	Citas de un paciente	paciente_id, estado?
verificar_disponibilidad_sillon	Horarios libres	fecha, sillon?, doctor_id?
cancelar_reprogramar_cita	Modificar cita	cita_id, accion, nueva_fecha?, nueva_hora?

Pacientes Tools (3 herramientas)

Tool	Descripcion	Parametros
buscar_paciente	Buscar por nombre/telefono	query, limit?
consultar_paciente	Datos completos del paciente	paciente_id
consultar_historial_dental	Historial clinico completo	paciente_id

Presupuestos Tools (3 herramientas)

Tool	Descripcion	Parametros
generar_presupuesto_dental	Crear presupuesto	paciente_id, tratamientos[], descuento?
consultar_presupuesto	Detalle de presupuesto	presupuesto_id
aprobar_rechazar_presupuesto	Cambiar estado	presupuesto_id, decision, notas?

---

Recursos MCP Dentales

URI	Descripcion	Retorna
dental://catalogo/tratamientos	Catalogo de tratamientos con precios	Array de tratamientos
dental://catalogo/materiales	Materiales dentales disponibles	Array de materiales
dental://config/clinica	Configuracion de la clinica	Nombre, horarios, sillones
dental://config/doctores	Lista de doctores	Array de doctores y especialidades
dental://nomenclatura/fdi	Referencia nomenclatura FDI	Cuadrantes y piezas

---

Endpoints API

Metodo	Endpoint	Descripcion
POST	/api/v1/mcp/tools/call	Ejecutar una herramienta MCP
GET	/api/v1/mcp/tools	Listar herramientas disponibles
GET	/api/v1/mcp/tools/:name	Obtener definicion de herramienta
GET	/api/v1/mcp/resources	Listar recursos disponibles
GET	/api/v1/mcp/resources/:uri	Obtener recurso
GET	/api/v1/mcp/tool-calls	Historial de llamadas (auditoria)
GET	/api/v1/mcp/tool-calls/:id	Detalle de una llamada

---

Ejemplos de Uso

Consultar Odontograma

// Request
{
  "tool": "consultar_odontograma",
  "parameters": {
    "paciente_id": "pac_123"
  }
}

// Response
{
  "paciente": "Maria Garcia",
  "fecha_actualizacion": "2026-01-13",
  "piezas": [
    { "numero": "11", "estado": "sano" },
    { "numero": "16", "estado": "obturacion_resina", "caras": ["O", "M"], "fecha": "2025-06-15" },
    { "numero": "36", "estado": "endodoncia", "fecha": "2024-03-20" },
    { "numero": "46", "estado": "caries", "caras": ["O"], "notas": "Caries oclusal, indicada resina" }
  ],
  "piezas_ausentes": ["18", "28", "38", "48"],
  "tratamientos_pendientes": [
    { "pieza": "46", "tratamiento": "Resina compuesta" }
  ]
}

Agendar Cita Dental

// Request
{
  "tool": "agendar_cita_dental",
  "parameters": {
    "paciente_id": "pac_123",
    "fecha": "2026-01-20",
    "hora": "10:00",
    "tratamiento_tipo": "resina",
    "doctor_id": "doc_456",
    "sillon": 2
  }
}

// Response
{
  "cita_id": "cita_789",
  "confirmada": true,
  "fecha": "2026-01-20",
  "hora": "10:00",
  "duracion_minutos": 45,
  "doctor": "Dra. Rodriguez",
  "sillon": 2,
  "tratamiento": "Resina compuesta",
  "recordatorio_programado": true
}

---

Dependencias

Este modulo depende de:

• MGN-001 Auth (autenticacion, clinica_id)
• MGN-004 Tenants (multi-tenant, aislamiento por clinica)
• DENTAL-001 Odontograma (consulta/actualizacion)
• DENTAL-002 Tratamientos (registro/consulta)
• Citas (agendamiento)
• Pacientes (busqueda/consulta)

Modulos que dependen de este:

• MGN-021 WhatsApp Business (chatbots con herramientas MCP)
• MGN-020 AI Integration (agentes IA)

---

Arquitectura

                    +-------------------+
                    | Clientes MCP      |
                    +-------------------+
                    |  AI Agents        |
                    |  WhatsApp Service |
                    |  API Externa      |
                    +---------+---------+
                              |
                              v
                    +-------------------+
                    |   MCP Server      |
                    +-------------------+
                    | MCP Controller    |
                    | Tool Registry     |
                    | Tool Executor     |
                    | Audit Logger      |
                    +---------+---------+
                              |
        +---------------------+---------------------+
        |           |           |           |       |
        v           v           v           v       v
+------------+ +--------+ +--------+ +----------+ +--------+
| Odontograma| | Citas  | | Tratam.| | Pacientes| | Presup.|
| Tools      | | Tools  | | Tools  | | Tools    | | Tools  |
+------------+ +--------+ +--------+ +----------+ +--------+
        |           |           |           |       |
        v           v           v           v       v
+------------+ +--------+ +--------+ +----------+ +--------+
| Odontograma| | Citas  | | Tratam.| | Pacientes| | Presup.|
| Service    | | Service| | Service| | Service  | | Service|
+------------+ +--------+ +--------+ +----------+ +--------+

---

Seguridad y Normativas

Seguridad General

• Todas las herramientas requieren autenticacion JWT
• Aislamiento por clinica (RLS)
• Rate limiting por clinica
• Sanitizacion de inputs
• Validacion de permisos por herramienta

NOM-004-SSA3-2012 (Expediente Clinico)

• Registro completo de todas las llamadas a herramientas
• Trazabilidad de consultas y modificaciones
• Almacenamiento seguro de logs

NOM-013-SSA2-2015 (Salud Bucal)

• Uso correcto de nomenclatura FDI
• Registro adecuado de tratamientos
• Protocolos de atencion

COFEPRIS

• Registro de materiales utilizados
• Trazabilidad de insumos
• Bitacora de procedimientos

---

Documentacion

• Mapa del Modulo
• Requerimientos
• Especificaciones
• Historias de Usuario
• Trazabilidad

---

Referencias

• Fuente: erp-core/MGN-022-mcp-server
• MCP Spec: Model Context Protocol
• Anthropic MCP: Anthropic MCP Docs

---

Modulo MGN-022 - MCP Server | Clinica Dental Propagado desde erp-core via erp-clinicas Actualizado: 2026-01-13