# mail-archive

Per-project Outlook PST / live-folder mail archive with incremental sync.
Designed to be driven either from a plain CLI or from any AI assistant
(Claude, Gemini, ChatGPT, local LLMs) via an MCP server or by piping JSON
output.

**Status: pre-alpha.** APIs and config schema will change.

## What it does

Given one or more Outlook folders (or PST files) already split by project,
`mail-archive` incrementally ingests new mail into a per-project local
archive stored as JSON. Downstream tools (an AI, a script, a MCP client) can
then answer questions about that history without re-parsing Outlook every
time.

## Requirements

- Windows + Outlook desktop (for the live-folder / COM source)
- Python 3.11+
- `pip install mail-archive[outlook]` for the pywin32 dependency

Only `pywin32` is required for basic use; `[mcp]` adds AI-client support.

## Quick start

```powershell
# 1. Install
pip install "mail-archive[outlook]"

# 2. Create a config file (edit projects afterwards)
mail-archive init

# 3. Ingest the first batch (Outlook must be running)
mail-archive ingest --project "ProjectA"

# 4. Later, sync everything incrementally
mail-archive update-all
```

## Config

`~/.mail-archive/config.toml`:

```toml
storage_dir = "~/.mail-archive/storage"

[[project]]
name = "ProjectA"
source = "outlook-folder"
folder = "Inbox/ProjectA"
auto_update = true

[[project]]
name = "ProjectB"
source = "outlook-folder"
folder = "Inbox/ProjectB"
```

## Using it from an AI assistant (MCP)

`mail-archive` ships a Model Context Protocol server so any MCP-capable client
— Claude Desktop, Cursor, Cline, Zed, Continue, and others — can query the
archive directly.

```powershell
pip install "mail-archive[outlook,mcp]"
```

Then point your client at the `mail-archive-mcp` command. Example config for
**Claude Desktop** (`%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "mail-archive": {
      "command": "mail-archive-mcp",
      "args": ["--config", "C:/Users/you/.mail-archive/config.toml"]
    }
  }
}
```

**Cursor / Cline / Zed** use the same shape — look for their `mcpServers`
JSON block and drop in the same `command` + `args`.

The server exposes four tools: `list_projects`, `query_emails`,
`update_project`, and `update_all`. Once loaded, you can ask the AI things
like "show me the three most recent emails about topic X in ProjectA" and
it will pick the right tool and arguments on its own.

## Design

- Storage layout is stable: `<storage_dir>/_index.json` +
  `<storage_dir>/<project>/emails.jsonl`.
- Every CLI subcommand is pure Python and prints JSON on stdout (except
  `update-all`, which is quiet by default).
- The MCP server is a thin wrapper over the same library functions — no
  subprocesses, no duplicated logic.
- Sources are pluggable: implement one function in `mail_archive.sources`
  and dispatch to it from `fetch_for_project`.