siimaster

# SIIMaster Asistente contable tributario chileno con IA. Servidor **MCP** (Model Context Protocol) que expone 123 tools sobre el SII (Servicio de Impuestos Internos) y un módulo de contabilidad PyME. Pensado para ser consumido por Claude Desktop / Claude Code como "agente contador" — no es un form-filler, es un asesor real que lee el archivo de la entidad, propone acciones con justificación, y ejecuta tras aprobación humana. Cliente original: ACME SpA (RUT 76.543.210-K). Arquitectura multi-empresa. ## Qué hace - **Lee SII en vivo**: F29 propuesta, RCV (compras/ventas), DJ Renta, perfil tributario, giros, situación tributaria, DTEs emitidos/recibidos, BHE. - **Escribe en SII** (con aprobación humana): anular BHE, desistir SISPA, anular DJ, importar CSV de DJ, emitir DTE 33/34/39/41/52/56/61. - **Contabilidad PyME**: plan de cuentas, asientos automáticos desde DTEs/BHE/F29, libros (Diario/Mayor/Compras/Ventas/Balance), Estado de Resultado, Balance General, RLI Art. 33 LIR, simulador de escenarios y comparador de regímenes 14D N°3 vs N°8, cierre anual, generación F22. - **Detección de anomalías**: BHE fraudulentas, DJs observadas, vencimientos próximos, alertas folios CAF. - **Emisión DTE**: módulo `app/services/dte/` con Protocol pluggable (Mock para tests / emisor propio `sii_native/` con XMLDSIG, CAF parser, cert storage Fernet). ## Arquitectura ``` backend/ ├─ app/ │ ├─ mcp_server.py ← 123 tools MCP (Claude Desktop / Code) │ ├─ services/ │ │ ├─ agente_contador.py ← orquestador de tools (lectura + escritura SII + contabilidad) │ │ ├─ archivo_entidad.py ← almacenamiento por entidad: data/entidades/{empresas|personas}/{RUT}_{slug}/ │ │ ├─ empresas.py ← registry multi-empresa (data/empresas.json) │ │ ├─ sii_api.py ← clientes HTTP de APIs internas SII (lectura) │ │ ├─ sii/ │ │ │ ├─ nodriver_client.py ← browser CDP que esquiva el WAF │ │ │ ├─ dj/dj_1879.py ← spec CSV importador SII (cp850, ;) │ │ │ ├─ dj_rechazos.py ← parser observaciones formales R+ │ │ │ ├─ diagnostico_fe.py ← multi-source: régimen + actividades + MiPyme + DAS │ │ │ ├─ rcv_scraper.py ← scraper UI consdcvinternetui │ │ │ └─ rcv_sync.py ← diff cantidad/monto por tipo doc, snapshots persistidos │ │ ├─ contabilidad/ ← plan de cuentas, asientos, libros, EERR, BG, RLI, F22 │ │ └─ dte/ │ │ ├─ emisor.py ← Protocol EmisorDTE (intercambiable) │ │ ├─ mock_emisor.py ← para tests │ │ ├─ sii_native/ ← emisor propio: XMLDSIG, CAF, RSA-SHA1, cert Fernet │ │ └─ models.py ← Documento, DatosGuiaDespacho, etc. │ ├─ api/v1/ ← REST: /accounts, /billing, /jobs, /dte, /contabilidad, /dashboard │ └─ core/ ← config, db, celery, auth (JWT con account_id+rol) ├─ data/ │ ├─ empresas.json ← registry de entidades │ └─ entidades/ ← archivo por entidad (snapshots, SISPAs, DTEs, F29, ...) ├─ docs/ │ ├─ mcp_setup.md ← cómo conectar Claude Desktop / Code al MCP │ └─ sii/ ← 376 endpoints SII catalogados └─ tests/ ← 980 tests verdes (~5s, sin Chrome) frontend/ ← React + Vite + Tailwind (UI complementaria) docker-compose.yml ← Postgres + Redis (opcional para Celery) ``` **Lectura SII** → `sii_api.py` (HTTP directo, segundos). **Escritura SII** → `nodriver_client.py` (browser real, human-in-the-loop, preview → aprobación). **Agente** → vive en Claude Desktop/Code vía MCP. Sin API key Anthropic propia: usa el plan Max del usuario. ## Pre-requisitos | Software | Para qué | Notas | |---|---|---| | Chrome real | nodriver lo controla via CDP | NO Chromium — nodriver detecta Chrome instalado en su path estándar | | `uv` | Gestor de Python | <https://docs.astral.sh/uv/> | | Docker Desktop | Postgres + Redis (opcional) | Solo si usas Celery / endpoints REST | | Claude Desktop o Code | Cliente MCP | <https://claude.com/claude-code> | | Node 20+ | Solo si tocas el frontend | | ## Arranque ```bash # 1. Variables de entorno (raíz del repo) cp .env.example .env # Editar .env con credenciales SII y SECRET_KEY # 2. Backend cd backend uv sync --extra dev # Python 3.12 uv run alembic upgrade head # opcional, solo si usas Postgres # 3. Registrar empresa(s) uv run python scripts/registrar_empresa.py # o manualmente: editar data/empresas.json # 4. Tests (sanidad) uv run pytest tests/ # 980 tests, ~5s, sin Chrome ni red ``` ### Uso vía MCP (modo principal) Configurar el MCP server en Claude Desktop / Code — ver [`backend/docs/mcp_setup.md`](backend/docs/mcp_setup.md). Una vez conectado, Claude tiene acceso a las 123 tools y opera como tu agente contador. ### Uso vía REST (modo complementario) ```bash # Backend FastAPI uv run uvicorn app.main:app --reload --port 8000 # → http://localhost:8000/docs # Worker Celery (Windows: --pool=solo OBLIGATORIO) uv run celery -A app.core.celery_app worker -Q sii --pool=solo --loglevel=info ``` Endpoints principales: `/api/v1/accounts`, `/api/v1/billing` (Stripe), `/api/v1/jobs`, `/api/v1/dte`, `/api/v1/contabilidad`, `/api/v1/dashboard`, `/api/v1/perfil`, `/api/v1/fase1`, `/ws/agent` (WebSocket gateway al agente local). ## Variables de entorno (.env) ```dotenv DB_PASSWORD=siimaster_dev SECRET_KEY=siimaster_dev_key_cambiar_en_prod FERNET_KEY=... # para credenciales SII cifradas en disco # Claude API (opcional — solo workflow_planner.py legacy; el agente real usa MCP) ANTHROPIC_API_KEY=sk-ant-... # nodriver SII_HEADLESS=false # true no probado en Windows # Stripe (opcional — mock por defecto) STRIPE_SECRET_KEY=sk_test_... ``` Las credenciales SII por entidad **NO viven en .env** — se guardan cifradas con Fernet en `data/empresas.json` vía `scripts/registrar_empresa.py`. ## Tests ```bash cd backend uv run pytest tests/ # 980 tests, ~5s ``` Cubre: clientes HTTP del SII (mocked), helpers nodriver, parsers DJ/RCV/F29, modelo de archivo por entidad, contabilidad completa (asientos, libros, EERR, BG, RLI, F22), DTE (emisor mock + sii_native: CAF, XMLDSIG, RSA), MCP tools, multi-tenancy, JWT, billing, jobs, invitaciones, monetización MCP HTTP remoto. ## Estado actual (2026-05-04) ### ✅ Completado - **MCP server con 123 tools** distribuidas en 10 categorías (lectura archivo, contabilidad, cierre/simulación, live SII perfil/F29, anulación BHE/SISPA, DJ Renta, RCV/Giros/FE, workflow planner, DTE emisión, vencimientos). - **Contabilidad PyME completa** (Fases 1–5): plan de cuentas, asientos auto, libros, EERR, BG, RLI, simuladores, comparador 14D N°3 vs N°8, cierre anual, F22, detección de anomalías. - **Emisión DTE**: módulo clean-room con Protocol intercambiable (Mock para tests / emisor propio sii_native con XMLDSIG y CAF). Frontend `/dte/emitir` y `/dte/historial`. - **SaaS multi-tenant**: Account con planes (trial/solo/estudio/enterprise), Stripe billing, JWT con account_id+rol, invitaciones por email firmadas. - **MCP HTTP remoto monetizado**: API keys con scope+quota, Streamable HTTP en `/mcp/v1`, `.well-known/mcp.json`. - **980 tests verdes**. ### Hitos operativos resueltos para ACME - 3 BHE fraudulentas (folios 69/70/71 = $94.2M) anuladas. - DJ 1879 AT 2026 anulada (rechazo R08/R467 por inconsistencia con F29 cód. 151). - 2 SISPAs borrador desistidas, 1 DAS aprobada. - F29 nov-2025 verificado: el saldo a pagar es solo multas+intereses por declaración fuera de plazo, no requiere rectificar. ### 🚧 Pendientes conocidos - Auto-handler de modales informativos post-acción del SII. - Toggle COMPRA/VENTA en `rcv_sync` (ui-router específico no sniffeado todavía). - Foto-OCR de facturas → libro de compras (Vision API). - Modelos DJ adicionales: 1948, 1887, 3325, 3500. - Esperando respuesta SII a Verificación de Actividad de ACME. ## Filosofía > **Asesor contable real, no form-filler.** Cada tool justifica su decisión, opera sobre el archivo persistente de la entidad, y respeta el principio de preview → aprobación humana antes de cualquier escritura en el SII. El agente vive en Claude (plan Max del usuario) — SIIMaster es el sistema de archivos + las manos. Ver [`feedback_filosofia_asesor.md`](memory/) en la memoria del proyecto para el detalle. ## Troubleshooting **Chrome muere silencioso al arrancar (Windows)** — nodriver requiere `--user-data-dir` absoluto. `_profile_dir()` lo resuelve con `.resolve()`. **WAF rechaza el login (`Transacción Rechazada CT`)** — el flujo es click-through: `homer.sii.cl` → "Ingresar a Mi Sii" → form. NO ir directo a `zeusr.sii.cl`. **Worker Celery: `NotRegistered`** — worker zombie de un arranque previo. `taskkill /F /IM python.exe` y arrancar fresh. **Worker en Windows arranca pero no procesa** — falta `--pool=solo` (el default prefork no funciona en Windows). **HTTP 401 en endpoints www2 de djconsulta** — falta el OAuth bridge: navegar primero a www4 djconsultarentaui dispara el handshake. **RCV API "Usuario o Empresa nulo"** — generar GWT-ID local de 13 chars y usarlo como `conversationId` en todas las calls de la sesión. ## Documentación - [`backend/docs/mcp_setup.md`](backend/docs/mcp_setup.md) — setup del MCP en Claude Desktop / Code, listado completo de tools. - [`backend/docs/sii/`](backend/docs/sii/) — 376 endpoints SII catalogados con metadata. - Memoria del proyecto en `C:\Users\vicen\.claude\projects\D--dev-siimaster\memory\` (índice: `MEMORY.md`).