sii (TypeScript)

Núcleo TypeScript + CLI + servidor MCP para automatizar interacciones rutinarias
con el SII de Chile, para un usuario sobre su propio RUT y las empresas que está
autorizado a representar. Pensado para usarse tanto en Claude Code como en
Claude Desktop.

Reescritura desde cero en TypeScript del sii-cli (Python) ya probado: el
conocimiento del SII y los guardrails se portan; el código se escribe nuevo.

⚠️ Herramienta no oficial. Este proyecto no está afiliado al SII ni
respaldado por él. Se entrega "tal cual" (ver LICENSE), sin garantía
de ningún tipo. Cada usuaria/o es responsable de cumplir los términos de servicio
del SII y la legislación chilena. Automatiza el portal de un ente público: úsalo
con criterio (la cuenta se bloquea tras intentos fallidos; nunca reintentar tras
un bloqueo).

Estado

Superficies de lectura operativas y validadas en vivo: autenticación
(auth), representación (operate), RCV, F22 (status / formulario /
observaciones / historial), F29 (Fase 1), BTE/BHE, DTE autorizados
(consulta pública), whoami y peticiones administrativas (SISPAD). Primera
superficie de escritura: bte emit (emisión de Boletas de Honorarios
Electrónicas). Ver el detalle en
docs/CURRENT_STATUS.md y el checklist completo en
docs/ROADMAP.md.

Estructura

packages/
  core/   @albertomarturelo/sii-core   Núcleo de dominio (librería Node). Las superficies llaman solo a sus tasks.
  cli/    @albertomarturelo/sii-cli     CLI humana (terminal). También lo que Claude Code corre vía Bash.
  mcp/    @albertomarturelo/sii-mcp     Servidor MCP (stdio). El punto de integración para Claude Code y Claude Desktop.
docs/                  Capa de contexto CFD (ARCHITECTURE, CONVENTIONS, ADRs…).

Un solo núcleo (@albertomarturelo/sii-core) respalda ambas superficies, así que todos los
guardrails legales y operativos (throttling, auditoría, manejo de credenciales,
el modelo de identidad operate-céntrico) aplican sin importar la superficie.
Las dependencias externas (driver del portal, secretos, sesión, auditoría,
reloj) viven detrás de seams inyectables para que los tests no toquen el SII
real. Ver docs/ARCHITECTURE.md.

Cómo se usa con Claude

• Claude Desktop — conecta el servidor MCP (sii-mcp, stdio) vía
  claude_desktop_config.json.
• Claude Code — conecta el mismo MCP (.mcp.json / claude mcp add), y/o
  deja que Claude Code use la CLI directamente por Bash.

El Clave Tributaria nunca llega al LLM ni a disco en texto plano: login por
navegador (cookies-only) — ningún tool de MCP recibe contraseña. Ver
ADR-006.

Instalación y uso

Para usarlo (sin clonar el repo). Requiere Node ≥ 20. Para desarrollar,
ver Desarrollo.

# 1) Instala la CLI y el servidor MCP
npm i -g @albertomarturelo/sii-cli @albertomarturelo/sii-mcp

# 2) Instala el navegador que usa el login (una sola vez, ~100–150 MB)
npx playwright install chromium

# 3) Inicia sesión — abre tu navegador en la página REAL del SII;
#    tecleas tu RUT + Clave ahí. La Clave nunca llega al modelo ni a disco.
sii auth login

# 4) Úsalo desde la terminal
sii peticiones list            # ¿tengo trámites detenidos ("en espera de Antecedentes")?
sii rcv summary 2026-05        # resumen del RCV de compras
sii f29 overview 2026          # posición de IVA mes a mes

Conectar el MCP a Claude

El servidor es stdio (no requiere hosting): Claude lo lanza como un proceso.

Claude Desktop — añade a claude_desktop_config.json y reinicia la app
(macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "sii": { "command": "sii-mcp" }
  }
}

Claude Code — un comando:

claude mcp add sii -- sii-mcp

Luego pídele en lenguaje natural (p. ej. «¿cuál es el estado de mi sesión?» o
«muéstrame el RCV de compras de 2026-05»). Si aún no iniciaste sesión, corre
sii auth login primero (o pídele a Claude la herramienta auth_login, que abre
tu navegador). Los tools de lectura no cambian nada; emitir una BHE exige
confirmación explícita.

Playwright es la única dependencia con peso: sii lo usa para el login por
navegador (cookies-only, ADR-006). Por eso el paso 2 (npx playwright install chromium) es obligatorio la primera vez; el paquete npm no descarga navegadores
automáticamente.

Capacidades

Ambas superficies exponen las mismas operaciones sobre el SII (un solo núcleo):
el MCP las ofrece como tools a Claude; la CLI, como comandos sii ….

Vía MCP (Claude Desktop / Claude Code)

Claude ve las operaciones como herramientas con permiso configurable por
herramienta (lectura vs escritura). Las de escritura —iniciar/cerrar sesión,
operar como, y emitir una BHE— quedan controladas: bte_emit es la única
destructive y exige confirmación explícita.

Ejemplos de prompts (lenguaje natural; Claude elige la herramienta):

• «¿Cuál es el estado de mi sesión y a nombre de qué RUT estoy operando?» → auth_status
• «Muéstrame el resumen del RCV de compras del período 2026-05.» → rcv_summary
• «Lista el detalle de ventas del RCV de 2026-05.» → rcv_list
• «Dame todos los documentos del RCV de compras de 2026-05 en una sola tabla.» → rcv_all
• «¿Cómo quedó mi declaración de renta (F22) del año tributario 2025?» → f22_status / f22_formulario
• «¿Tengo observaciones en el F22 de 2025?» → f22_observaciones
• «¿Cuál es mi posición de IVA mes a mes en el F29 durante 2026?» → f29_overview
• «Dame la propuesta del F29 de mayo 2026, agrupada por línea.» → f29_formulario
• «¿Qué documentos tributarios está autorizado a emitir el RUT 77.777.777-7?» → dte_authorized (público, sin login)
• «Lista las boletas de honorarios que recibí en junio 2026.» → bte_list
• «¿Tengo peticiones administrativas detenidas ante el SII (en espera de antecedentes)?» → peticiones_list
• «¿A nombre de quién estoy registrado — razón social y correo?» → whoami
• «Simula una boleta de honorarios de $500.000 a un cliente (sin emitir).» → bte_emit_preview
• «Cambia a operar como la empresa que represento.» → operate

Emitir una BHE de verdad (bte_emit) no ocurre por un prompt suelto: es una
herramienta destructive que pide confirmación explícita + el monto en eco
(ADR-017). El login abre tu navegador en la página real del SII — la Clave nunca
llega al modelo.

Vía CLI (sii)

Salida JSON por defecto (pipeable a jq); --human para lectura. El header
operando como … va a STDERR.

Las superficies session-keyed (f22, f29, bte) leen siempre el principal
de la sesión (sin --rut); la body-RUT (rcv) acepta --rut / operate
para llegar a una empresa representada (ADR-005).

Modelo de identidad

Una sola cuenta activa a la vez (cambiar de cuenta = logout → login). Dentro
de la sesión, una cuenta persona usa el puntero operate para elegir a
nombre de qué RUT actúa (sí misma por defecto, o una empresa que representa). Las
cuentas empresa no representan a nadie. Ver
ADR-005.

Desarrollo

pnpm install         # instalar dependencias
pnpm build           # tsc -b (typecheck + build de todos los paquetes)
pnpm test            # vitest
pnpm lint            # eslint
pnpm format          # prettier

Requiere Node >=20 y el pnpm fijado en packageManager (package.json).

Metodología

El repo corre bajo Context-First Development (CFD): decisiones-antes-de-código
(ADRs), una capa de contexto que cada sesión lee primero, y slash commands en
.claude/commands/ (/session:start, /session:close, /decision:new,
/issue:new, /issue:start, /review-pr, /context:validate). Ver
ADR-001.

Seguridad

Nunca subas secretos ni PII real (RUT, Clave, cookies, nombres, montos). Para
reportar una vulnerabilidad y ver la postura de seguridad, lee
SECURITY.md.

Contribuir

Las contribuciones son bienvenidas — parte por CONTRIBUTING.md
y la capa de contexto en docs/.

Licencia

MIT © 2026 Alberto Marturelo Lorenzo. Ver
ADR-018.