Siigo MCP Server - Versión Segura 2.0

Servidor Model Context Protocol (MCP) para la API de Siigo con seguridad empresarial de grado de producción.

🔒 Características de Seguridad

Implementadas ✅

• RBAC (Role-Based Access Control): Viewer, Editor, Admin con permisos granulares
• Rate Limiting: Protección contra abuso local + límites de Siigo
• Validación de Entrada: Schema validation con Zod en todos los inputs
• Sanitización de Datos: Prevención de inyección de prompts y XSS
• Auditoría Completa: Logging estructurado de todas las operaciones
• Certificados HTTPS: Validación TLS 1.2+ con rechazo de certificados inválidos
• Enmascaramiento de Credenciales: No se exponen keys en logs
• Validación de Respuestas: Schema validation de respuestas de API
• Manejo de Errores Seguro: Errores sin información sensible

📋 Requisitos

• Node.js >= 18.0.0
• npm >= 9.0.0
• Cuenta de Siigo con acceso a API
• Credenciales de API (username y access_key)

🚀 Instalación Rápida

1. Clonar y configurar

cd mcpsiigo
npm install
cp .env.example .env

2. Configurar credenciales

Editar .env con tus credenciales de Siigo:

[email protected]
SIIGO_ACCESS_KEY=tu_api_key_aqui
SIIGO_ROLE=viewer  # Empezar con viewer (solo lectura)

3. Build y test

npm run build
npm test

4. Iniciar servidor

npm start

🔐 Configuración de Seguridad

Roles y Permisos

// Viewer: Solo lectura (default, recomendado)
SIIGO_ROLE=viewer

// Editor: Lectura + Crear/Actualizar
SIIGO_ROLE=editor

// Admin: Acceso completo (requiere confirmación)
SIIGO_ROLE=admin

Rate Limiting

# 50 requests/minuto por tool (default)
RATE_LIMIT_REQUESTS=50
RATE_LIMIT_WINDOW_MS=60000

Auditoría

# Habilitar logging de todas las operaciones
ENABLE_AUDIT_LOG=true

# Enmascarar datos sensibles
MASK_SENSITIVE_DATA=true

📚 Documentación de Tools

Productos

// Listar productos
siigo_get_products({ limit?: 100, offset?: 0 })

// Obtener producto específico
siigo_get_product({ id: 123 })

// Crear producto (requiere editor/admin)
siigo_create_product({
  product: {
    code: "PROD001",
    name: "Mi Producto",
    account_group: 1253,
    type: "Product"
  }
})

// Actualizar producto (requiere editor/admin)
siigo_update_product({
  id: 123,
  product: { name: "Nuevo Nombre" }
})

// Eliminar producto (requiere admin)
siigo_delete_product({ id: 123 })

Clientes

// Listar clientes
siigo_get_customers({ limit?: 100 })

// Crear cliente (requiere editor/admin)
siigo_create_customer({
  customer: {
    person_type: "Person",
    id_type: "13",
    identification: "123456789",
    name: "John Doe",
    email: "[email protected]"
  }
})

Facturas

// Listar facturas
siigo_get_invoices()

// Crear factura (requiere editor/admin)
siigo_create_invoice({
  invoice: {
    customer_id: 1,
    invoice_number: "INV001",
    date: "2026-03-14",
    due_date: "2026-04-14",
    total: 100000
  }
})

// Enviar factura por email
siigo_send_invoice_email({
  id: 1,
  email: "[email protected]"
})

Reportes

// Balance de prueba
siigo_get_trial_balance({ year?: 2026, month?: 3 })

// Cuentas por pagar
siigo_get_accounts_payable()

Sistema

// Ver herramientas disponibles
siigo_get_available_tools()

// Estado del servidor
siigo_get_server_status()

🔍 Auditoría y Logs

Los logs se almacenan en logs/:

logs/
├── error.log        # Errores del servidor
├── combined.log     # Todos los logs
└── audit.log        # Operaciones auditadas

Ver logs en tiempo real:

tail -f logs/audit.log | grep -E "Invoice|Purchase|Delete"

🧪 Testing

# Todos los tests
npm test

# Tests de seguridad
npm test:security

# Watch mode
npm test:watch

# Con cobertura
npm test -- --coverage

📊 Configuración de Claude Desktop

Agregar a ~/.claude/profiles.json:

{
  "mcpServers": {
    "siigo": {
      "command": "node",
      "args": ["path/to/dist/index.js"],
      "env": {
        "SIIGO_USERNAME": "${SIIGO_USERNAME}",
        "SIIGO_ACCESS_KEY": "${SIIGO_ACCESS_KEY}",
        "SIIGO_ROLE": "viewer",
        "NODE_ENV": "production"
      }
    }
  }
}

🛡️ Buenas Prácticas

✅ DO - Hacer

# ✅ Usar variable de entorno para credenciales
[email protected]

# ✅ Empezar con viewer role
SIIGO_ROLE=viewer

# ✅ Habilitar auditoría
ENABLE_AUDIT_LOG=true

# ✅ Usar sandbox para testing
SIIGO_BASE_URL=https://sandbox.siigo.com

# ✅ Monitorear logs de auditoría
tail -f logs/audit.log

❌ DON'T - No Hacer

# ❌ NO hardcodear credenciales
const apiKey = "xxx_api_key_xxx"

# ❌ NO usar role=admin en producción
SIIGO_ROLE=admin

# ❌ NO deshabilitar validación
rejectUnauthorized: false

# ❌ NO permitir acceso sin autenticación
AUTH_REQUIRED=false

# ❌ NO committed .env con valores reales
git commit .env

🚨 Manejo de Incidentes

Credenciales comprometidas

# 1. Rotar API key en Siigo
# 2. Actualizar .env
# 3. Reiniciar servidor
npm start

# 4. Revisar logs de auditoría para acceso no autorizado
grep "denied\|failure" logs/audit.log

Rate limit excedido

# Los límites se resetan automáticamente
# Pero se puede resetear manualmente:
npm run reset-limiters

# O reducir el límite
RATE_LIMIT_REQUESTS=20

📈 Monitoreo

Health check

curl http://localhost:3000/health

Estadísticas de servidor

siigo_get_server_status()
// Retorna: uptime, role, audit stats, rate limit stats

🔄 Desarrollo

Modo watch

npm run dev

Linting

npm run lint
npm run lint:fix

Formateo

npm run format

📦 Compilación para Producción

npm run build
npm run type-check
npm test
npm start

🐛 Troubleshooting

Error: "Missing credentials"

Solución: Configurar SIIGO_USERNAME y SIIGO_ACCESS_KEY en .env

Error: "Rate limit exceeded"

Solución: Esperar o aumentar RATE_LIMIT_REQUESTS

Error: "Access denied to tool"

Solución: Cambiar SIIGO_ROLE a un nivel superior (viewer -> editor -> admin)

Error de certificado SSL

Solución: Usar SIIGO_BASE_URL=https://sandbox.siigo.com para testing

📝 Licencia

MIT

🤝 Contribuir

Las contribuciones de seguridad son bienvenidas. Por favor:

1. No abrir issues públicos sobre vulnerabilidades
2. Reportar a través de [email protected]
3. Dar tiempo para patch antes de divulgar

📞 Soporte

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]

🎯 Roadmap

• [ ] Integración con Vault para secretos
• [ ] Métricas Prometheus
• [ ] Dashboard de auditoría
• [ ] Webhooks para eventos
• [ ] Sincronización de datos en tiempo real
• [ ] Cache inteligente de API

📚 Referencias

• Siigo API Documentation
• MCP Specification
• OWASP Top 10
• Node.js Security Best Practices

Versión: 2.0.0
Estado: Producción Ready
Última actualización: Marzo 2026