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

[![Security Grade](https://img.shields.io/badge/security-enterprise%20grade-brightgreen)](https://github.com/jdlar1/siigo-mcp)

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

```bash
cd mcpsiigo
npm install
cp .env.example .env
```

### 2. Configurar credenciales

Editar `.env` con tus credenciales de Siigo:

```bash
SIIGO_USERNAME=tu_email@siigo.com
SIIGO_ACCESS_KEY=tu_api_key_aqui
SIIGO_ROLE=viewer  # Empezar con viewer (solo lectura)
```

### 3. Build y test

```bash
npm run build
npm test
```

### 4. Iniciar servidor

```bash
npm start
```

## 🔐 Configuración de Seguridad

### Roles y Permisos

```typescript
// 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

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

### Auditoría

```bash
# Habilitar logging de todas las operaciones
ENABLE_AUDIT_LOG=true

# Enmascarar datos sensibles
MASK_SENSITIVE_DATA=true
```

## 📚 Documentación de Tools

### Productos

```typescript
// 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

```typescript
// 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: "john@example.com"
  }
})
```

### Facturas

```typescript
// 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: "customer@example.com"
})
```

### Reportes

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

// Cuentas por pagar
siigo_get_accounts_payable()
```

### Sistema

```typescript
// 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:

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

## 🧪 Testing

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

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

```bash
# ✅ Usar variable de entorno para credenciales
SIIGO_USERNAME=user@siigo.com

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

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

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

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

```bash
curl http://localhost:3000/health
```

### Estadísticas de servidor

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

## 🔄 Desarrollo

### Modo watch

```bash
npm run dev
```

### Linting

```bash
npm run lint
npm run lint:fix
```

### Formateo

```bash
npm run format
```

## 📦 Compilación para Producción

```bash
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 security@example.com
3. Dar tiempo para patch antes de divulgar

## 📞 Soporte

- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📧 Email: support@example.com

## 🎯 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](https://siigoapi.docs.apiary.io/)
- [MCP Specification](https://modelcontextprotocol.io/)
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [Node.js Security Best Practices](https://nodejs.org/en/docs/guides/security/)

---

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