rckrdmrd/clinica-dental
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
clinica-dental/docs/05-fase-ia/MGN-022-mcp-server/README.md
rckrdmrd 27b4e7bccf [DOCS] feat: Add phase 04-SAAS and 05-IA documentation structure 
- Update docs/_MAP.md with new phase references
- Add docs/04-fase-saas/ phase structure
- Add docs/05-fase-ia/ phase structure

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-16 00:28:18 -06:00

317 lines
10 KiB
Markdown
Raw Permalink Blame History

---
id: MGN-022-mcp-server
title: MCP Server para Clinica Dental
type: Module
status: Draft
priority: P0
phase: 05-fase-ia
version: 1.0.0
created_date: 2026-01-13
updated_date: 2026-01-13
normativas: [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
```json
// 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
```json
// 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](./_MAP.md)
- [Requerimientos](./requerimientos/)
- [Especificaciones](./especificaciones/)
- [Historias de Usuario](./historias-usuario/)
- [Trazabilidad](./implementacion/TRACEABILITY.yml)
---
## Referencias
- **Fuente:** [erp-core/MGN-022-mcp-server](../../../../../erp-core/docs/05-fase-ia/MGN-022-mcp-server/)
- **MCP Spec:** [Model Context Protocol](https://modelcontextprotocol.io/)
- **Anthropic MCP:** [Anthropic MCP Docs](https://docs.anthropic.com/en/docs/mcp)
---
*Modulo MGN-022 - MCP Server | Clinica Dental*
*Propagado desde erp-core via erp-clinicas*
*Actualizado: 2026-01-13*
Reference in New Issue View Git Blame Copy Permalink