# mcp-email-client

MCP server yang menjembatani LLM (Claude) dengan inbox email kamu — bisa **baca thread, bikin draft, reply, dan kirim email** langsung dari chat. Fokus ke **thread-aware write**, bukan cuma baca inbox.

---

## Fitur

- **Baca & cari email** — `search_messages`, `get_message`, `get_thread`
- **Draft-first safety** — semua write jadi draft dulu, kirim butuh `confirm: true` eksplisit. LLM bisa salah, ini safety net.
- **Thread-aware reply** — reply nempel di thread aslinya (`In-Reply-To` + `References` header), rapi di Gmail/Outlook.
- **Multi-backend** — Gmail API (OAuth) **atau** IMAP/SMTP (App Password), satu interface.
- **Token local-first** — refresh token disimpan di direktori user (`~/.mcp-email/`), bukan server pihak ketiga.

## Cara kerja

```
Claude ──► search_messages("invoice") ──► thread: "194abc"
  ──► get_thread("194abc")        ──► isi thread kronologis
  ──► draft_reply("194abc", ...)  ──► DRAFT (belum terkirim)
  ──► send_reply(...)             ──► VERIFIKASI (confirm) → SENT
```

Detail arsitektur & alur: [`docs/FLOW.md`](docs/FLOW.md).

## Instalasi

```bash
# install via npm
npm install -g mcp-email-client
# lalu daftarkan ke MCP host:
#   command: mcp-email,  args: []
```

## Setup

### Mode A — App Password (recommended, tanpa OAuth)

1. Aktifkan **2-Step Verification**: <https://myaccount.google.com/security>
2. Buat **App Password**: <https://myaccount.google.com/apppasswords>
3. Salin `.env.example` jadi `.env`, isi:

```bash
GMAIL_EMAIL=emailanda@gmail.com
GMAIL_APP_PASSWORD=abcd efgh ijkl mnop
```

### Mode B — OAuth Gmail API

1. Buat Google Cloud Project + OAuth client (tipe "Desktop app"): <https://console.cloud.google.com/apis/credentials>
2. Set `GMAIL_CLIENT_ID` + `GMAIL_CLIENT_SECRET` (hapus `GMAIL_EMAIL`/`GMAIL_APP_PASSWORD`)
3. Login sekali:

```bash
npm install
npm run auth        # buka browser, izinkan gmail.modify
npm run auth:status # cek status
```

### Connect ke Claude (MCP host)

Tambah ke config MCP host (`.mcp.json` / `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "email": {
      "command": "node",
      "args": ["C:/code/mcp-email-client/dist/index.js"]
    }
  }
}
```

## Tools (12)

| Kategori | Tools |
|----------|-------|
| **Read** | `search_messages`, `get_message`, `get_thread`, `list_drafts` |
| **Draft** (aman) | `draft_new`, `draft_reply` |
| **Send** (butuh `confirm`) | `send_email`, `send_draft`, `schedule_send`* |
| **Manipulasi** | `set_thread_state`, `download_attachment` |
| **Health** | `status` |

\* `schedule_send` masih stub.

## Status

✅ **Semua milestone (M0–M4) selesai** — 12 tool MCP, mode OAuth + App Password.

Struktur:

- `src/gmailAuth.ts` — OAuth2 + PKCE, callback loopback, token exchange & refresh
- `src/imapClient.ts` / `src/smtpTransport.ts` — backend App Password (IMAP read, SMTP send)
- `src/tokenStore.ts` — refresh token simpan **local-first** (`~/.mcp-email/`)
- `src/cli.ts` — `login` / `status` / `logout`
- `src/index.ts` — entry point MCP server

Test: `npm test`

## Docs

| File | Isi |
|------|-----|
| [`docs/FLOW.md`](docs/FLOW.md) | Arsitektur, data flow, auth flow |
| [`docs/SCHEMA.md`](docs/SCHEMA.md) | Semua tool + param + tipe return |
| [`docs/PROGRESS.md`](docs/PROGRESS.md) | Status implementasi per milestone |