@libro-de-raya/mcp

Servidor oficial de Model Context Protocol (MCP) para Libro de Raya. Digitalización de tickets, facturación CFDI 4.0 y organización de comprobantes fiscales en México para cualquier entorno o cliente compatible con MCP (Claude Desktop, Cursor, Windsurf, Claude Code, Goose, etc.).

🚀 Instalación y Configuración Rápida

El servidor funciona mediante el transporte estándar stdio a través de npx:

npx -y @libro-de-raya/mcp

1. Claude Desktop

Agrega la configuración en tu archivo claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "libro-de-raya": {
      "command": "npx",
      "args": ["-y", "@libro-de-raya/mcp"]
    }
  }
}

2. Cursor

En Cursor, ve a Settings → Features → MCP → Add New MCP Server o añade en .cursor/mcp.json:

{
  "mcpServers": {
    "libro-de-raya": {
      "command": "npx",
      "args": ["-y", "@libro-de-raya/mcp"]
    }
  }
}

3. Windsurf

Agrega en tu archivo ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "libro-de-raya": {
      "command": "npx",
      "args": ["-y", "@libro-de-raya/mcp"]
    }
  }
}

4. Claude Code (CLI)

Ejecuta directamente en tu terminal:

claude mcp add libro-de-raya -- npx -y @libro-de-raya/mcp

⚡ Onboarding Conversacional (Zero-Browser)

No necesitas ingresar a ningún portal web ni generar llaves de API manualmente para comenzar a operar:

1. Inicia la conversación con tu cliente MCP:

   "Quiero registrarme en Libro de Raya con mi correo [email protected]"

2. Flujo guiado interactivo:

   • Tu asistente ejecutará automáticamente la herramienta solicitar_registro_mcp(email).
   • Recibirás un código de verificación de 6 dígitos en tu bandeja de entrada.
   • Pásale el código a tu asistente y este ejecutará confirmar_registro_mcp(email, code).
   • ¡Listo! Recibirás 5 créditos de bienvenida para procesar tickets o emitir facturas, tu API Key se guardará de forma segura en ~/.libro-de-raya/credentials.json (0600) y el cliente se activará en caliente sin requerir reinicio.

⚙️ Variables de Entorno (Opcional)

Si prefieres usar una API Key ya existente o configurar el entorno de forma estática:

| Variable | Descripción | Valor por Defecto | | :--- | :--- | :--- | | LIBRO_DE_RAYA_API_KEY | Llave de API con prefijo ldr_live_ | Lee automáticamente de ~/.libro-de-raya/credentials.json | | LIBRO_DE_RAYA_API_URL | Endpoint base de la API backend | https://app.libroderaya.mx/api (o http://localhost:8080) | | CSD_CER_PATH | Ruta absoluta al certificado CSD (.cer) para sellado local | Sellado remoto seguro en la nube | | CSD_KEY_PATH | Ruta absoluta a la llave privada CSD (.key) | Sellado remoto seguro en la nube | | CSD_PASSWORD | Contraseña del CSD | Sellado remoto seguro en la nube |

Ejemplo con variables de entorno en tu cliente MCP:

{
  "mcpServers": {
    "libro-de-raya": {
      "command": "npx",
      "args": ["-y", "@libro-de-raya/mcp"],
      "env": {
        "LIBRO_DE_RAYA_API_KEY": "ldr_live_tu_api_key_aqui"
      }
    }
  }
}

🛠️ Catálogo de Herramientas de Producción (12 Herramientas Oficiales)

1. Diagnóstico y Onboarding Conversacional (Zero-Browser)

• consultar_estado_mcp: Consulta el estado de la sesión, usuario conectado, balance de créditos y ruta local de credenciales.
• solicitar_registro_mcp: Inicia el registro de una cuenta o vinculación y solicita el código OTP por correo electrónico (soporta detección de 2FA).
• confirmar_registro_mcp: Valida el código OTP (y código 2FA TOTP / código de respaldo si aplica), activa la cuenta con 5 créditos de bienvenida y almacena la API Key en ~/.libro-de-raya/credentials.json con permisos 0600.

2. Facturación Electrónica (CFDI 4.0 — Doña Factura)

• simular_factura_cfdi: Simula el desglose de impuestos (IVA, ISR retenido, IVA retenido) y la estructura del CFDI 4.0 (soporta cálculo matemático local gratuito con 0 créditos).
• emitir_factura_cfdi: Emite, sella y timbra facturas CFDI 4.0 ante el SAT. Soporta sellado en la nube (cloud_vault) o sellado local soberano en memoria RAM con sellos CSD (sovereign_local).
• cancelar_factura_cfdi: Cancela una factura ante el SAT con los motivos oficiales (01 a 04) y UUID de sustitución.
• consultar_facturas: Obtiene el listado de facturas emitidas por el usuario, con filtros opcionales de estado (valid, cancelled) o búsqueda por cliente/RFC.
• descargar_factura_xml: Descarga el archivo XML oficial con timbre fiscal digital del SAT.

3. Digitalización de Comprobantes (Don Ticket)

• escanear_ticket_gasto: Registra un ticket o comprobante de gasto deduciendo automáticamente para tu declaración fiscal (proveedor, montos, IVA, RFC y categoría).
• consultar_gastos_tickets: Consulta la lista de comprobantes de gastos registrados y clasificados.

4. Monedero y Recargas Desacopladas (Ledger)

• consultar_saldo_creditos: Consulta el saldo disponible de créditos en tu monedero de Libro de Raya.
• generar_link_pago_creditos: Genera un link seguro de Mercado Pago para recargar créditos sin necesidad de iniciar sesión en el navegador.

🛡️ Seguridad y Buenas Prácticas

• Cero e.Firma (FIEL): El servidor MCP rechaza explícitamente cualquier certificado o llave correspondiente a la e.Firma. Para timbrado de facturas únicamente se admiten Certificados de Sello Digital (CSD), protegiendo la identidad legal del contribuyente.
• Permisos POSIX Estrictos: Las credenciales generadas localmente se resguardan en ~/.libro-de-raya/credentials.json con permisos de lectura exclusivos para el usuario del sistema operativo (0600).
• Autenticación Dinámica en Memoria (Hot-Reload): Las herramientas actualizan en caliente el token de sesión sin requerir detener o reiniciar el servidor de transporte.

🧪 Desarrollo Local y Pruebas

Si deseas compilar o contribuir al desarrollo del servidor:

# Instalar dependencias
pnpm install

# Compilar TypeScript
pnpm build

# Ejecutar suite de pruebas unitarias y E2E
pnpm test

📄 Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.

Copyright (c) 2026 Gary Pixel Tech.