en es it ja ko ru zh

work-assistant

Name: work-assistant
Author: Wulfgardr

by Wulfgardr

Overview Schema Source Related Servers Discussions Admin

Python

Local

Work Assistant

邮件会变成一个人或一个智能代理都能使用的本地存档。

与提供商无关 · 多邮箱 · CLI · MCP · 人工审核

从演示开始 · 连接智能代理 · 了解安全 · 项目状态

图示意：从邮箱到本地归档，再到 broker 和代理

什么是 Work Assistant

Work Assistant 是一个本地系统，用于借助智能工具整理和使用电子邮件。

系统从一个或多个邮箱获取消息，将其规范化后保存在本地 SQLite 归档中。系统再从这些归档中重建联系人和交互视图，一个人可以从命令行、一个像 Codex 这样可以通过 MCP 协议就能正常使用。

Work Assistant 不是传统邮件客户端，也不是一个简单的技能：

核心负责管理账户、归档、删除数据以及推荐内容；
CLI 允许用户在不用动大语言模型的情况下使用核心；
MCP 服务器为代理提供结构化工具；
skill 教授如何在授权限制内使用这些工具；
adapter 把某项具体邮件服务接入核心。

公开的核心不会发电子邮件。 Prepared replies remain local candidates until a separate, authorized action occurs.

三个维度：本地记忆、代理表面、人类控制

能力	说明
本地记忆	规范化消息保留在本机，并保留完整性哈希。
代理表面	MCP 暴露带类型的命令，而不会把归档的直接访问权交给网关。
人工控制	公开核心只准备工作内容，但不暴露发送命令提供任何确认。

Related MCP server: mail-index

为什么存在

一枚邮箱里不只是邮件，还有对话、人、附件、决策和待办事项。普通客户端能很好地展示当前邮件，但是很难把这段历史重新用于实际知识中。

Work Assistant 将三层分开：

本地归档：保存已获得的内容并校验其完整性。
知识视图：从归档重新构建联系人和交互。它是一个派生数据，可再次生成。
代理表面：让模型可以通过受控操作搜索、阅读和准备内容。

知识视图不是原始来源，不是被单独视为已验证的备份。真正的备份还需要有副本、保留期、校验以及恢复演练。

工作方式

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;

Broker 是信任边界。它读取明文数据，应用假名化规则，且只向网关返回一套已定义 schema。所有 Provider 标识都被转为不透明的引用。未被识别的元数据无法穿越这条边界。

尝试 Demo

Demo 只使用合成身份和合成消息，不需要真实的凭证和邮箱。

系统要求

Python 3.11 或更高版本；
Git；
macOS、Linux 或 Windows。

1. 安装项目

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

在 macOS 或 Linux 上激活：

source .venv/bin/activate

在 Windows PowerShell 上：

.venv\Scripts\Activate.ps1

安装 Work Assistant:

python -m pip install .

2. 创建配置

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

该命令自动创建一个随操作系统用户而确定的数据目录。它不会把归档和密钥放到当前项目的仓库里。

3. 载入合成的邮箱

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

verify 命令会检查 SQLite 过程和并级对象哈希完整性。这里的验证不代表完成了备份的恢复演练。

与代理配合使用

Codex、Claude 和其他 MCP 客户端使用同一套表面，模型不在 CLI 内之外。

安装 MCP 支持：

python -m pip install '.[mcp]'

1. 启动本地 broker

打开一个可信的本地终端，然后运行：

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

broker 必须保持运行中。如果 broker 不可用，MCP 网关就会停止，不会直接读取整个归档。

在第二个终端中，记下两个必要路径：

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

2. 在 Codex 中注册服务器

用 broker-info 的输出来替换 Codex 端需要的运行信息：

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

在 Windows 上用 .venv\Scripts\work-assistant.exe。

比如下面的提示：

Use Django. Check privacy mode, sync the personal mailbox, show the latest email and prepare a reply draft. Don't send anything.

可选 skill 放在 skills/work-assistant。它补充了操作规则，但并不改变 MCP 服务器中不存在。

3. 在 Claude Code 中注册服务器

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

对于 Claude Desktop，请配置一个等价的 stdio 服务器：

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

使用 CLI （no agent）

CLI 是不用模型的：它只运行，不解析自然语言。

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

若要将一个回复候选写到本地：

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

返回结果会包含 sent: false，即不会写回到 Provider。一个代理如果只有一个终端本身，应该用 MCP，避免直接读 SQLite 或 CLI 的最原始 output。

设置多个邮箱

[accounts] 下的每个 table 都指向一个独立邮箱：

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"

本仓库只包含一个 demo adapter。真实 adapter 需遵循文档 docs/PROVIDER_ADAPTERS.md 中定义的。生产环境中还有待验证的协议。

Zimbra 和 Carbonio

公开版包含一个本地 pre-boarding，用于从 HAR 文件准备 Zimbra 或 Carbonio 会话。生成生产级 Zimbra 连接的 adapter 并不在此。

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

下面的命令是本地化的：

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

命令不会去删除这个 HAR 文件。完成校验之后，请用与保护敏感文件安全一致的方式移动到所在目录。

它如何保护数据

Work Assistant 有三种模式：

模式	行为
`off`	不做任何转化。模型可见内容可能进入模型提供方大数据范围。
`all`	对结构化的标识符以及可识别文本进行假名化。这是 sample配置本身的值。
`selective`	按发件人匹配一组有序规则，第一条命中的规则直接生效。

一个带写写伪 IMPORT 的示例：

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

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

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

回复中只包含规则的一个不透明 ID，不包含匹配文本的字面。

可选的身份登记表，默认是 <data_dir>/privacy/entities.json。在 POSIX 系统上，必须由当前用户所有，且权限为 0600。

化名只可解密，不代表匿名。极端识别信息、上下文、书写习惯、和未被识别到的词汇可能不爱。

如果 Broker 要成为有效的信任边界，数据目录必须不能出现在任何可被代理读取的 workspace 目录里。除非有显式标记的不安全标志，否则 broker 会拒绝这样的配置，仅保证为隔离的演示。

因此在收到真实邮件之前，请阅读 SECURITY.md。

Daybreak 安全评估

在 2026 年 8 月 24 日，Daybreak 对 Broker、pseudonymization、IPC 和 MCP 层进行了一次代码审计。这个审查发现了 7 个问题：一个中等风险，其余六低。

版本 0.3.0 包含了以下修复：

数据和设计完全不在仓库中，是默认；
broker 会拒绝在 protected directory 落入 agent 的 workspace 中运行；
身份注册表被放在外部，并加入权限检查；
MCP 改为 closed schema，外部、只使用 opaque 引用，排除 Provider 元数据；
选择性规则一律使用 opaque 的标识而不是字面；
固定 worker 数量保留默认值并加上了空闲连接 fail-- 超时；
通过设置超时覆盖连接、认证、逻辑请求和响应。

在以下两个文件中你会找到评估报告、测试证据和图例残差：docs/security/DAYBREAK-REVIEW.md。

备份与恢复

Work Assistant 保留规范化消息和其哈希。这使归档可校验，但并未使之自动成为一个恢复能力强的备份。

要声明一个可验证的备份，还必须定义和证明：

包括哪些回邮件和附件；
加密方式和密钥管理；
备份频率、保留策略和版本；
哈希验证；
隔离环境中的恢复步骤；
预期内容和恢复后内容的对拍。

verify 函数只验证当前归档，并不会执行恢复动作。

项目当前状态

Work Assistant 处于 alpha 版本阶段。

已提供：

与 Provider 无关的核心；
多邮箱配置；
demo 合成 adapter；
带哈希的 SQLite 存储；
本地联系人和交互视图；
CLI；
MCP 网关和本地的 broker；
可反向的别名机制；
适配代理的 skill；
Zimbra 和 Carbonio HAR 的辅助 onboarding。

暂缺：

真实生产 Provider 的生产级 adapter；
发送邮件的功能；
完整的备份恢复演练；
对二进制附件内容的化名；
真正的匿名化承诺。

开发与参与贡献

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

在代码、测试、截图、issue 和 pull request 中只允许使用合成数据。请阅读 CONTRIBUTING.md 中参与项目的规范。

许可证

Work Assistant 采用 MIT 许可证发布。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

Mailera
app.mailera
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Email Communication
1
https://mailera.app/api/public/v1/mcp
OleaDesk Mail
com.oleadesk
Your own AI reads, searches and drafts in your mailbox, on your Windows computer.
Email App Automation Workplace & Productivity
1
https://app.oleadesk.com/api/mcp
Lettio MCP
eu.lettio
Private, EU-hosted email for AI agents over JMAP: read, search, reply, draft, organize, send.
Email App Automation
1
https://mcp.lettio.eu/mcp
Lockally Email
com.lockally
Stateful email for AI agents — read inboxes, reply in-thread, draft with approval.
Email Communication
1
https://mcp.lockally.com/

Related MCP Servers

Mailing Manager MCP
Email Communication App Automation
Tatine13
A
license
Not graded
quality
D
maintenance
Enables AI assistants to manage multiple email accounts with secure credentials, local full-text search, thread-aware replies, and automation.
Updated 6 months ago (2026-05-15 06:39 UTC)
4 npm
MIT
mail-index
Email Search Text Summarization
unsoldgroup
A
license
Not graded
quality
A
maintenance
Enables AI agents to query and recall your entire Gmail inbox locally, providing fast summarization and semantic search without relying on Gmail's search API.
Updated 8 days ago (2026-10-27 22:01 UTC)
68 npm
4
MIT
mbox-mcp
Email Search File Systems
koleharv
A
license
A
quality
C
maintenance
Reads and searches local email archives (.mbox or .eml) with full MIME parsing, enabling queries about senders, subjects, dates, and bodies while keeping all data on your machine.
Updated 17 days ago (2026-10-18 13:42 UTC)
3
162 npm
MIT
email-archive
Email Search
Noerdsteil
A
license
Not graded
quality
B
maintenance
Enables AI assistants to search a local email archive using hybrid keyword and semantic search, and retrieve individual emails with thread context.
Updated 2 months ago (2026-09-15 07:46 UTC)
1
MIT