Work Assistant

El correo se convierte en un archivo local utilizable por una persona o por un agente inteligente.

Independiente del proveedor · Varias casillas · CLI · MCP · Revisión humana

Empieza por la demo · Conecta un agente · Comprende la seguridad · Estado del proyecto

Qué es Work Assistant

Work Assistant es un sistema local para organizar y usar el correo electrónico con herramientas inteligentes.

El sistema obtiene mensajes de una o varias casillas, los normaliza y los conserva en un archivo SQLite local. A partir de ese archivo reconstruye una vista de contactos e interacciones. Una persona puede usar el sistema desde la línea de comandos. Un agente, como Codex o Claude, puede usarlo mediante el protocolo MCP.

Work Assistant no es un cliente de correo tradicional ni una simple skill:

• el core gestiona cuentas, archivo, verificaciones y contenidos propuestos;

• la CLI permite a una persona usar el core sin un modelo;

• el servidor MCP expone herramientas estructuradas a los agentes;

• la skill enseña al agente a usar estas herramientas dentro de los límites permitidos;

• un adaptador conecta un servicio de correo específico al core.

El core público no envía correos. Las respuestas preparadas continúan siendo candidatos locales hasta una posible acción separada y autorizada.

Related MCP server: Mailing Manager MCP

Por qué existe

Una casilla contiene más que mensajes individuales. Contiene conversaciones, personas, archivos adjuntos, decisiones y actividades pendientes. Los clientes habituales muestran bien el correo actual, pero dificultan la reutilización de ese historial como conocimiento operativo.

Work Assistant separa tres niveles:

1. Archivo local: mete lo que se ha adquirido y verifica su integridad.

2. Vista de conocimiento: reconstruye contactos e interacciones a partir del archivo. Es derivada y puede regenerarse.

3. Superficie para agentes: permite a un modelo buscar, leer y preparar contenidos mediante operaciones controladas.

La vista de conocimiento no es la fuente original y no constituye, por sí misma, una copia de seguridad verificada. Una copia de seguridad real requiere también copia, conservación, control y prueba de restauración.

Cómo funciona

Es el código

flowchart LR
  Persona[Persona] --> Agente[Agente intelligente]
  Agente -->|strumenti MCP| Gateway[Gateway MCP]
  Gateway -->|IPC locale autenticato| Broker[Broker locale]
  Broker --> Archivio[(Archivio locale)]
  Broker --> Vista[Vista di conoscenza]
  Broker --> Candidati[Candidati di risposta]
  Adapter[Adapter del provider] --> Broker

  classDef paper fill:#f7f2e7,stroke:#294b37,color:#172019;
  classDef sage fill:#dce8d8,stroke:#294b37,color:#172019;
  classDef accent fill:#aa593e,stroke:#aa593e,color:#f7f2e7;
  class Persona,Archivio,Vista,Candidati paper;
  class Gateway,Broker,Adapter sage;
  class Agente accent;

El broker es el confín de confianza. Fíe los datos en claro, aplica la regla de seudonimización y devuelve solo al gateway un esquema declarado. Los identificadores del proveedor se convierten en referencias opacas. Los metadatos no reconocidos no cruzan la frontera.

Prueba la demo

La demo usa solo identidades y mensajes sintéticos. No requiere credenciales ni una casilla real.

Requisitos

• Python 3.11 o posterior;

• Git;

• macOS, Linux o Windows.

1. Instala el step

git clone https://github.com/Wulfgardr/work-assistant.git
cd work-assistant
python3 -m venv .venv

Activa el entorno en macOS o Linux:

source .venv/bin/activate

En Windows PowerShell:

.venv\Scripts\Activate.ps1

Instala Work Assistant:

python -m pip install .

2. Crea la configuración

work-assistant --config work-assistant.toml init

El comando crea una carpeta de datos específica del sistema operativo. El cierre de sesión, las claves y el registro de identidades no se generan en el repositorio.

3. Carga las casillas sintéticas

work-assistant --config work-assistant.toml sync --account personal
work-assistant --config work-assistant.toml sync --account team
work-assistant --config work-assistant.toml list
work-assistant --config work-assistant.toml knowledge
work-assistant --config work-assistant.toml verify

El comando verify comprueba la integridad de SQLite y los hash de los mensajes. No demuestra que una copia de seguridad pueda restaurarse.

Cómo usar Work Assistant con un agente

Codex, Claude y otros clientes MCP usan la misma superficie. El modelo no está integrado en la CLI.

Instala el soporte MCP:

python -m pip install '.[mcp]'

1. Inicia el broker local

Abre una terminal local segura y ejecuta:

work-assistant --config work-assistant.toml broker

El broker debe permanecer activo. Si no está disponible, el gateway MCP se detiene sin leer directamente el archivo.

En una segunda terminal, recupera las dos rutas necesarias:

work-assistant --config work-assistant.toml broker-info

2. Registra el servidor en Codex

Sustituye los dos marcadores de posición por los valores de broker-info:

codex mcp add work-assistant -- \
  "$PWD/.venv/bin/work-assistant" \
  mcp \
  --broker-address '<BROKER_ADDRESS>' \
  --broker-auth-file '<BROKER_AUTH_FILE>'

En Windows usa .venv\Scripts\work-assistant.exe.

Ejemplo de solicitud:

Usa Work Assistant. Comprueba la modalidad de privacidad, verifica la casilla personal, muéstrame los últimos mensajes y prepara un candidato de respuesta. No envíes nada.

La skill opcional está en skills/work-assistant. La skill añade reglas operativas, pero no sustituye al servidor MCP.

3. Registra el servidor en Claude Code

claude mcp add work-assistant -- \
  "$PWD/.venv/bin/work-assistant" \
  mcp \
  --broker-address '<BROKER_ADDRESS>' \
  --broker-auth-file '<BROKER_AUTH_FILE>'

Para Claude Desktop, configura un servidor stdio equivalente:

{
  "mcpServers": {
    "work-assistant": {
      "command": "/percorso/assoluto/work-assistant/.venv/bin/work-assistant",
      "args": [
        "mcp",
        "--broker-address",
        "<BROKER_ADDRESS>",
        "--broker-auth-file",
        "<BROKER_AUTH_FILE>"
      ]
    }
  }
}

Usa la CLI sin un agente

La CLI es determinista: no contiene un modelo y no interpreta solicitudes en lenguaje natural.

work-assistant --config work-assistant.toml list --account personal --limit 10
work-assistant --config work-assistant.toml show --account personal --id p-001

Para guardar un candidato de respuesta local:

printf 'Grazie. Verifico il documento entro venerdì.\n' > risposta.txt
work-assistant --config work-assistant.toml draft-candidate \
  --account personal \
  --to sam@example.test \
  --subject 'Re: Revisione del progetto' \
  --in-reply-to p-001 \
  --body-file risposta.txt

La respuesta incluye sent: false. No se escribe ningún contenido en el proveedor.

Un agente con acceso a un terminal debe usar MCP. No debe leer directamente SQLite ni la salida en claro de la CLI.

Configura varias casillas

Cada tabla en [accounts] describe una clave independiente:

schema_version = 1
data_dir = "/percorso/esterno/al/repository"

[privacy]
mode = "all"
default_action = "pseudonymize"

[accounts.personal]
provider = "demo"
source = "./examples/demo-mailbox.jsonl"
address = "alex@example.test"

[accounts.team]
provider = "demo"
source = "./examples/team-mailbox.jsonl"
address = "team@example.test"

El repositorio incluye solo el adaptador de demostración. Los adaptadores reales deben implementar el contrato descrito en docs/PROVIDER_ADAPTERS.md.

Zimbra y Carbonio

La versión pública incluye una preparación local para preparar una sesión de Zimbra o Carbonio desde un archivo HAR. El adaptador operativo de Zimbra no está incluido.

sequenceDiagram
  participant A as Agente
  participant P as Persona
  participant B as Browser
  participant C as CLI locale
  A->>P: Spiega i passaggi e controlla lo stato
  P->>B: Esegue login e autenticazione a due fattori
  P->>C: Importa localmente il file HAR
  C-->>P: Conferma solo nomi dei cookie e stato
  Note over A,C: Password, OTP, HAR e valori dei cookie non entrano nel modello

El comando local es:

work-assistant --config work-assistant.toml import-zimbra-har \
  --account work \
  --har /percorso/locale/session.har

El comando no elimina el archivo HAR. Después de la verificación, mueve o elimina la exportación con una procedimiento adecuada al contenido sensible.

Cómo protege los datos

Work Assistant ofrece tres modos:

Ejemplos de reglas selectivas:

[privacy]
mode = "selective"
default_action = "pseudonymize"

[[privacy.sender_rules]]
pattern = "newsletter@example.test"
action = "allow_raw"

[[privacy.sender_rules]]
pattern = "*@sensitive.example"
action = "pseudonymize"

La respuesta del agente contiene solo un identificador opaco de la regla, no su valor literal.

El registro opcional de identidades se encuentra, por defecto, en <data_dir>/privacy/entities.json. En sistemas POSIX debe pertenecer al usuario y tener permisos 0600.

La seudonimización es reversible y no garantiza el anonimato. Hechos graves hechos, contexto, estilo de escritura o términos no reconocidos pueden identificar a una persona.

Para que el broker sea una frontera real, la carpeta de datos debe quedar fuera de cualquier área de trabajo accesible por el agente. El software, al sistema, está en la colección, salvo una excepción explícita e insegura para demostraciones controladas.

Lee SECURITY.md antes de usar mensajes reales.

Revisión de seguridad Daybreak

El 24 de agosto de 2026 una revisión Daybreak analizó el broker, la seudonimización, la IPC y la superficie MCP. La revisión detectó siete problemas: uno de gravedad media y seis de gravedad baja.

La versión 0.3.0 aplica estas correcciones:

• datos y claves fuera del repositorio por defecto;

• rechazo del broker cuando con un espacio protegido dentro del workspace del agente;

• registro de identidades externo y con control de permisos;

• esquema MCP de lista cerrada, referencias opacas y metadatos del proveedor excluidos;

• identificadores opacos para reglas selectivas;

• número fijo de worker y caducidad para conexiones inactivas;

• timeout global en connection, autenticación, solicitud y respuesta.

El informe, las pruebas y las limitaciones restantes están en docs/security/DAYBREAK-REVIEW.md.

Copia de seguridad y restauración

Work Assistant conserva mensajes normalizados y sus hash. Esto hace que el archivo sea comprobable, pero no lo convierte automáticamente en una copia de seguridad útil.

Para declarar una backup verificada es necesario definir y comprobar:

• qué mensajes y adjuntos se incluyen;

• cifrado y gestión de claves;

• frecuencia, conservación y versiones;

• verificación de los hash;

• procedimiento de restauración en un entorno aislado;

• comparación entre el contenido esperado y el contenido restaurado.

La función verify comprueba el archivo actual. No realiza una restauración.

Estado del proyecto

main (en desarrollo)

Work Assistant es un proyecto alpha.

Disponible:

• core independiente del proveedor;

• configuración de varias casillas;

• adaptador de demostración sintético;

• archivo SQLite con hash;

• interacciones y contactos en vista local;

• CLI;

• gateway MCP y broker local;

• seudónimos reversibles;

• skills para agentes;

• preparación de Zimbra y Carbonio.

No disponible:

• adaptador de producción para proveedores reales;

• envío de correos;

• prueba completa de backup y restauración;

• seudonimización del contenido binario de los archivos adjuntos;

• garantía de anonimato.

Desarrollo y contribuciones

python -m pip install '.[dev,mcp]'
pytest
python scripts/privacy_check.py
work-assistant benchmark-privacy --iterations 50

Usa solo datos sintéticos en código, pruebas, capturas de pantalla, issues y pull requests. Lee CONTRIBUTING.md para conocer las reglas del proyecto.

Licencia

Work Assistant se distribuye bajo la licencia MIT.