# Documentación Exhaustiva para Modelos de Lenguaje y Entornos de Desarrollo: Libro de Raya

Este documento contiene el contexto integral, especificaciones de arquitectura, reglas de negocio, modelo de precios, comandos de WhatsApp, directrices fiscales para México y especificaciones operativas del ecosistema **Libro de Raya**, sus módulos especializados y su servidor oficial de **Model Context Protocol** (@libro-de-raya/mcp).

---

## 1. Misión y Propósito
Libro de Raya es una plataforma mexicana de automatización contable y gestión tributaria desarrollada por **Gary Pixel Tech**. Su misión es transformar el desorden de los tickets de papel y comprobantes fiscales en paz mental y certidumbre financiera para profesionistas independientes, freelancers, comercios y pequeñas empresas (PyMEs) en México.

### El Problema en México
- Millones de tickets impresos en papel térmico se desvanecen con el calor o la fricción en pocos días, perdiendo deducciones fiscales valiosas.
- Los contribuyentes pierden miles de pesos de IVA acreditable y deducciones autorizadas por falta de tiempo o desorden en sus comprobantes.
- Confusión recurrente sobre qué gastos son deducibles según las disposiciones fiscales públicas (ej. pago de combustible en efectivo, compras mayores a $2,000 MXN en efectivo).
- Los contadores y despachos externos gastan horas transcribiendo números de recibos arrugados o fotos borrosas.

### La Solución Multicanal de Libro de Raya
- **Centro de Control Web (`app.libroderaya.mx`):** Plataforma activa y operativa hoy para carga individual y masiva en lote (hasta 30 comprobantes simultáneos con drag-and-drop), visor interactivo de tickets térmicos con pan/zoom/rotación, asistente de autofactura con copiado en 1 clic, semáforo fiscal preventivo SAT y exportación de Paquete Contable Excel (.xlsx / CSV UTF-8).
- **Canal Oficial WhatsApp (`+52 1 55 4560 3107` / `https://wa.me/5215545603107`):** Asistente conversacional activo en producción con 8 comandos nativos deterministas a costo $0, detección automática de tickets repetidos a $0 MXN y entrega directa de Paquete Contable Excel.
- **Servidor Oficial Model Context Protocol (`@libro-de-raya/mcp`):** Diseñado para que agentes de Inteligencia Artificial (Claude Desktop, Cursor, Windsurf, Claude Code, Goose, n8n) registren tickets, timbren facturas CFDI 4.0 y administren saldos de forma autónoma con Onboarding Conversacional Zero-Browser.
- **Transparencia Comercial ($1.00 MXN = 1 Crédito):** 5 créditos de cortesía automáticos al registrarte sin tarjeta de crédito, y recargas prepago desde $30 MXN sin suscripciones ni plazos forzosos.
- **Privacidad y Protección (Zero e.firma):** Jamás se solicita la firma electrónica (e.firma), contraseñas CIEC del SAT ni claves bancarias. La emisión de facturas solo requiere Certificados de Sello Digital (CSD).

---

## 2. Modelo Comercial, Precios y Reglas de Cobro Justo ($1.00 MXN = 1 Crédito)

Libro de Raya opera bajo una regla transparente de prepago sin rentas mensuales forzosas:
- **Equivalencia Oficial:** `$1.00 Peso Mexicano = 1 Crédito`.
- **Bienvenida sin Costo:** **+5 Créditos de cortesía ($0 MXN)** al registrarse en la WebApp, activar cuenta en WhatsApp (`/activar`) o completar el registro conversacional en MCP (`confirmar_registro_mcp`).
- **Consumo por Operación:**
  - *Don Ticket (Digitalización y Validación SAT):* **1 Crédito por comprobante nuevo y válido procesado**.
  - *Doña Factura / MCP (Timbrado Oficial CFDI 4.0):* **1 Crédito por factura timbrada exitosamente ante el SAT**.
  - *Detección de Duplicados:* **0 Créditos ($0 MXN)** si el comprobante ya fue procesado anteriormente.
  - *Comandos Conversacionales en WhatsApp y Consultas de Catálogo SAT en MCP:* **0 Créditos ($0 MXN)**.
  - *Política de 3 Strikes de Cortesía:* Los primeros 2 envíos consecutivos de imágenes borrosas o no válidas no descuentan créditos; el 3er intento inválido consecutivo descuenta 1 crédito para proteger el servicio.

### Catálogo Oficial de Paquetes de Recarga (Mercado Pago Checkout Seguro)
1. **Paquetes Esenciales (IVA incluido — Personas Físicas, Freelancers y RESICO):**
   - **Paquete 30 créditos:** `$30.00 MXN` (IVA incluido).
   - **Paquete 50 créditos:** `$50.00 MXN` (IVA incluido).
   - **Paquete 100 créditos (Recomendado ⭐):** `$100.00 MXN` (IVA incluido).
2. **Bolsas de Alto Volumen con Bonificación (Comercios, PyMEs y Despachos Contables):**
   - **Bolsa Negocio (210 créditos: 200 base + 10 bono):** `$200.00 MXN + IVA` (`$232.00 MXN`).
   - **Bolsa PyME (550 créditos: 500 base + 50 bono):** `$500.00 MXN + IVA` (`$580.00 MXN`).
   - **Bolsa Corporativa (1,150 créditos: 1,000 base + 150 bono):** `$1,000.00 MXN + IVA` (`$1,160.00 MXN`).

---

## 3. Canal Oficial de WhatsApp y Paquete Contable Excel

### 3.1 Catálogo de 8 Comandos Nativos de Meta (Ejecución Determinista a $0 Créditos)
- `ayuda` (alias `/help`, `/info`, `/comandos`): Consulta guía de uso y comandos disponibles en español.
- `resumen`: Genera el corte y resumen fiscal de los tickets registrados en el mes.
- `creditos` (alias `/saldo`): Consulta el saldo actual de créditos disponibles.
- `paquetes` (alias `/precios`): Presenta los paquetes de recarga (30, 50 y 100) con enlace dinámico de Mercado Pago.
- `activar`: Activa la cuenta acreditando 5 créditos de bienvenida sin costo.
- `reactivar` (alias `/recuperar`): Reactiva una cuenta inactiva conservando intacto su saldo de créditos.
- `desactivar` (alias `/baja`): Pausa la cuenta resguardando su saldo e historial.
- `exportar`: Genera y descarga el **Paquete Contable Excel** del mes con enlace seguro de descarga y contingencia en WebApp (`/reports/download`).

### 3.2 Estructura del Paquete Contable Excel (`LIBRO DE RAYA - PAQUETE CONTABLE`)
- Codificación UTF-8 para apertura inmediata en Microsoft Excel con acentos y caracteres especiales intactos.
- **Bloque Ejecutivo de Resumen Fiscal:** Total de comprobantes del periodo, Subtotal acumulado ($ MXN), IVA 16% Acreditable Recuperable ($ MXN), IEPS acumulado, Total bruto gastado ($ MXN), desglose de comprobantes deducibles vs. con observaciones SAT, y gastos pagados en efectivo vs. medios electrónicos (tarjeta/SPEI).
- **Tabla Detallada Conciliada:** Fecha en zona horaria CDMX (filtrado dual por fecha de emisión o registro), Comercio, RFC emisor normalizado (`XAXX010101000` si carece de RFC), concepto, impuestos desglosados y estatus del semáforo fiscal.

---

## 4. Servidor Oficial Model Context Protocol (@libro-de-raya/mcp / LDR_MCP)

Libro de Raya expone una interfaz estándar mediante el Model Context Protocol para habilitar la interoperabilidad con clientes de escritorio como Claude Desktop, editores como Cursor y agentes locales autónomos.

### 4.1 Instalación y Ejecución
El paquete se distribuye a través del registro oficial de npm:
```bash
npx -y @libro-de-raya/mcp
```

### 4.2 Configuración JSON Canónica
En el archivo de configuración del cliente (por ejemplo, `claude_desktop_config.json` o configuración de Cursor):
```json
{
  "mcpServers": {
    "libro-de-raya": {
      "command": "npx",
      "args": ["-y", "@libro-de-raya/mcp"],
      "env": {
        "LDR_API_KEY": "tu_api_key_personal"
      }
    }
  }
}
```

Las API Keys se generan directamente en la WebApp oficial en la sección de Perfil:
`https://app.libroderaya.mx/app/perfil?tab=api-keys`

### 4.3 Catálogo Exhaustivo de Herramientas (Tools)

#### 1. Módulo de Tickets y Gastos
- **`escanear_ticket_gasto`**:
  - *Descripción:* Registra un gasto o comprobante de compra en Don Ticket. Admite texto del ticket, monto total en MXN, IVA desglosado, RFC del comercio emisor, fecha y categoría contable.
  - *Parámetros:* `vendorName` (string), `total` (number), `taxAmount` (number?), `vendorRfc` (string?), `category` (string?), `ticketDate` (string?), `notes` (string?).
- **`consultar_gastos_tickets`**:
  - *Descripción:* Obtiene el listado de tickets y comprobantes registrados con desglose impositivo y metadatos fiscales.
  - *Parámetros:* `limit` (number, default: 20).

#### 2. Módulo de Facturación CFDI 4.0
- **`simular_factura_cfdi`**:
  - *Descripción:* Simula el cálculo de impuestos (IVA trasladado, retenciones de ISR e IVA) y la estructura del CFDI 4.0 antes del timbrado. Soporta modo de cálculo local gratuito (0 créditos) o simulación remota.
  - *Parámetros:* `customer` (objeto con `rfc`, `legalName`, `taxSystem`, `zipCode`), `items` (array con `description`, `productKey`, `unitKey`, `quantity`, `unitPrice`, `taxRate`), `paymentMethod`, `paymentForm`, `use`, `localOnly`.
- **`emitir_factura_cfdi`**:
  - *Descripción:* Emite y timbra formalmente un comprobante fiscal CFDI 4.0 ante el SAT a través de PAC certificado. Consume 1 crédito por factura timbrada exitosamente. Principio de Cero e.firma.
  - *Parámetros:* `customer`, `items`, `paymentMethod`, `paymentForm`, `use`, `serie`, `folio`, `signingMode`.
- **`cancelar_factura_cfdi`**:
  - *Descripción:* Gestiona la solicitud de cancelación oficial ante el SAT indicando motivo (01 a 04) y UUID de sustitución.
  - *Parámetros:* `invoiceId` (string), `reason` ('01' | '02' | '03' | '04'), `substitutionUuid` (string?).
- **`consultar_facturas`**:
  - *Descripción:* Consulta el catálogo de facturas emitidas por el contribuyente con filtros de estatus (`valid`, `cancelled`) y búsqueda por cliente o UUID.
  - *Parámetros:* `status` (string?), `query` (string?).
- **`descargar_factura_xml`**:
  - *Descripción:* Descarga la cadena y archivo XML timbrado oficial con sello del SAT.
  - *Parámetros:* `invoiceId` (string).

#### 3. Módulo de Monedero y Créditos (Ledger)
- **`consultar_saldo_creditos`**:
  - *Descripción:* Consulta el balance disponible en tiempo real de créditos fiscales en la cuenta del usuario.
- **`generar_link_pago_creditos`**:
  - *Descripción:* Genera una URL de pago segura de Mercado Pago para recargar créditos.
  - *Parámetros:* `packageId` (string?), `credits` (number?), `amount` (number?).

#### 4. Módulo de Onboarding y Sesión
- **`solicitar_registro_mcp`**:
  - *Descripción:* Inicia el registro conversacional o vinculación de cuenta mediante código de verificación de 6 dígitos enviado por correo.
  - *Parámetros:* `email` (string), `name` (string?), `phone` (string?), `force` (boolean?).
- **`confirmar_registro_mcp`**:
  - *Descripción:* Verifica el código de activación, deposita 5 créditos de bienvenida en cuentas nuevas y activa la API Key inmediatamente.
  - *Parámetros:* `email` (string), `code` (string, 6 dígitos), `agentName` (string?), `twoFactorCode` (string?).
- **`consultar_estado_mcp`**:
  - *Descripción:* Reporta el estado de configuración, sesión activa y conectividad del servidor MCP.

---

## 5. Ecosistema de Especialistas Modulares y Políticas de Retención

1. **Don Ticket (ACTIVO EN PRODUCCIÓN WEB Y WHATSAPP):**
   - Recepción y análisis de fotos o PDFs de comprobantes comerciales (OXXO, Walmart, gasolineras, papelerías, restaurantes, servicios) de forma individual o en lotes de hasta 30 archivos.
   - Extracción de RFC del emisor, fecha, subtotal, desglose de impuestos (IVA 16%, IVA 8% frontera, IEPS) y total en MXN.
   - Semáforo fiscal preventivo según normativas públicas del SAT y asistente de autofactura en 1 clic.
   - **Retención de Imágenes a 90 Días:** Cumple el principio de minimización de datos de la LFPDPPP 2025 eliminando automáticamente las fotografías a los 90 días tras el cierre trimestral.
2. **Doña Factura (TIMBRADO CFDI 4.0 CERTIFICADO):**
   - Arquitectura certificada con PAC autorizado y opción de sellado local con Certificados de Sello Digital (CSD) sin exponer llaves privadas.
   - **Resguardo Legal a 5 Años:** Conservación de archivos XML timbrados durante 5 años en cumplimiento del Artículo 30 del Código Fiscal de la Federación (CFF).

---

## 6. Normativa Fiscal Mexicana Atendida
- **Artículo 27 Fracción III de la Ley del Impuesto Sobre la Renta (LISR):**
  - Para que los consumos de combustible (gasolina, diésel) sean deducibles para ISR, el pago debe realizarse estrictamente mediante medios electrónicos autorizados (tarjeta de crédito, débito, servicios, monedero autorizado o cheque nominativo), independientemente del monto. La plataforma alerta de forma preventiva si detecta combustible pagado en efectivo.
- **Límite General de Efectivo de $2,000 MXN:**
  - Los gastos mayores a $2,000.00 MXN deben liquidarse con medios bancarios para ser deducibles.
- **Régimen Simplificado de Confianza (RESICO):**
  - Aunque el ISR en RESICO se calcula sobre ingresos brutos, el IVA trasladado en compras e inversiones es acreditable contra el IVA cobrado si el gasto es indispensable. La plataforma calcula y consolida el IVA acreditable del periodo.

---

## 7. Preguntas Frecuentes y Respuestas Canónicas
- **¿Es seguro usar Libro de Raya?** Sí. Los datos se resguardan bajo medidas de seguridad administrativas, técnicas y físicas con cifrado en tránsito y en reposo. Jamás se solicita la e.firma ni contraseñas del SAT.
- **¿Cuánto tiempo guardan mis documentos?** La foto del ticket se guarda 90 días (minimización de datos LFPDPPP 2025). Las facturas XML se resguardan 5 años por mandato del Art. 30 del CFF.
- **¿Por qué canales se puede utilizar hoy?** En el Centro de Control Web oficial (https://app.libroderaya.mx), directamente en WhatsApp (+52 1 55 4560 3107 / https://wa.me/5215545603107) y conectando el servidor oficial Model Context Protocol (`@libro-de-raya/mcp`).
- **¿Cómo se prueba el servicio y cuánto cuesta después?** Al registrarte o activar tu cuenta en WhatsApp recibes 5 créditos de cortesía sin tarjeta de crédito ($0 MXN). Después, cada crédito cuesta $1.00 MXN (en paquetes prepago de 30, 50 y 100 créditos o bolsas con bono para negocios), sin rentas mensuales y con tickets duplicados a $0 MXN.
- **¿Qué formatos admite la plataforma?** Fotografías en JPG, PNG, WebP y documentos PDF de tickets y notas de compra.