# inbox-tap-mcp — satu MCP untuk semua OTP temporer 📩📱

MCP server **standalone** yang memberi AI agent (opencode, Claude Code/Desktop, Cursor, Cline, dsb) inbox temporer gabungan **email + SMS** untuk verifikasi OTP/link saat registrasi akun di target:

- 📩 **Email temporer** — buat akun, cek inbox, baca pesan, tunggu email + ekstrak OTP/link (via mail.tm API)
- 📱 **SMS temporer** — list negara/nomor, cek inbox, tunggu SMS + ekstrak OTP/link (via freephonenum scrape)
- ⚡ **Unified OTP** — `mcp_inbox_wait_otp(channel=email|sms)` satu pintu untuk kedua channel
- 🛡️ **Aman by default** — token mail.tm ter-redact di `audit.jsonl`; OTP/links tetap tampil di result (dibutuhkan agent)
- 📦 **Zero-deployment hell** — 1 repo, **stdlib only** (tanpa `pip install`), backend di-vendor (`vendor_inbox.py`), tanpa dependensi `mailtap`/`smstap`

> 11 tools. 1 perintah install. `mailtap` + `smstap` tetap untuk manusia via CLI — MCP ini jalan sendiri walau keduanya dihapus.

---

## Demo 30 detik

```bash
git clone https://github.com/eye-fox/inbox-tap-mcp.git
cd inbox-tap-mcp
./install.sh
# restart opencode / AI client Anda, lalu suruh agent:
# "list akun email, buat akun attacker bila belum ada, tunggu OTP"
python3 examples/quickstart.py   # tanpa LLM: bukti end-to-end lewat stdio
```

## Cara kerja

```mermaid
flowchart LR
    Agent["AI agent"] -- "MCP stdio<br/>JSON-RPC" --> Server["server.py"]
    Server -- "import" --> Vendor["vendor_inbox.py<br/>stdlib only"]
    Vendor -- "REST" --> MailTM["mail.tm API<br/>email temporer"]
    Vendor -- "scrape" --> FPN["freephonenum.com<br/>SMS publik"]
    Server --- Audit["audit.jsonl<br/>token redacted"]
```

Akun email disimpan di `~/.tempmail/accounts.json` (format kompatibel `mailtap`, kode baca/tulis mandiri). SMS stateless (tidak ada penyimpanan).

## Syarat

| Kebutuhan | Versi | Cek |
|---|---|---|
| Python | ≥ 3.9 | `python3 --version` |
| Koneksi internet | — | `curl -sI https://api.mail.tm` |
| mailtap/smstap | tidak butuh | sengaja independen |

## Install

```bash
./install.sh
```

Script melakukan: cek python → `chmod +x` → init `audit.jsonl` → **auto-register ke `~/.config/opencode/opencode.json`** → smoke test `tools/list` (harus 11 tools).

Opsi:

```bash
./uninstall.sh   # hapus entri MCP, repo + ~/.tempmail tidak dihapus
```

## Config manual (non-opencode)

**Claude Desktop / Cursor / Cline (`mcp.json` / `claude_desktop_config.json`):**

```json
{
  "mcpServers": {
    "inbox-tap-mcp": {
      "command": "python3",
      "args": ["/ABSOLUTE/PATH/inbox-tap-mcp/server.py"]
    }
  }
}
```

Template siap copy: [`mcp.json.example`](mcp.json.example). Untuk opencode mentah: [`opencode.json.snippet`](opencode.json.snippet).

## Struktur repo

```text
inbox-tap-mcp/
├── install.sh              # setup full: cek python + register opencode + smoke test
├── uninstall.sh            # cabut entri MCP
├── server.py               # MCP stdio server (11 tools, audit+redact)
├── vendor_inbox.py         # backend email mail.tm + SMS freephonenum (stdlib only) — di-vendor
├── requirements.txt        # kosong (stdlib only, dokumentasi saja)
├── SKILL.md                # instruksi agent (copy ke skill-dir bila perlu)
├── opencode.json.snippet   # referensi config opencode
├── mcp.json.example        # referensi config generik MCP
├── examples/quickstart.py  # e2e tanpa LLM: email_list + sms_countries
├── scripts/smoke_test.py   # initialize + tools/list, exit 0 bila 11 tools
├── LICENSE (MIT)
└── .gitignore (melindungi audit.jsonl runtime)
```

> `audit.jsonl` adalah **runtime** — tidak ikut ke git (lihat `.gitignore`). `~/.tempmail/accounts.json` milik user, juga tidak ikut ke git.

## Pakai di agent (pola baku)

1. `mcp_inbox_email_list {}` → pastikan alias ada; belum ada? `mcp_inbox_email_create {"name":"attacker"}`
2. Isi form registrasi di target (via `browser-mcp` bila web) dengan email/nomor itu
3. `mcp_inbox_wait_otp {"channel":"email","target":"attacker","timeout":120}` → dapat OTP (+links bila ada)
4. Isi OTP → submit
5. Varian SMS: `mcp_inbox_sms_numbers {"country":"us"}` → pilih nomor → `mcp_inbox_wait_otp {"channel":"sms","target":"318-545-6266"}`
6. Eksplorasi manual: `mcp_inbox_email_inbox/read`, `mcp_inbox_sms_inbox/read`

Aturan detail + 11 tools: lihat [`SKILL.md`](SKILL.md).

### Batasan yang perlu tahu

- SMS bersifat **publik/shared** — semua orang dengan nomor sama bisa lihat pesan. Jangan untuk akun sensitif (bank, password reset).
- Akun mail.tm valid **~7 hari**, setelah itu hangus.
- Provider SMS gratis sering berubah layout/rate-limit — bila `sms_*` gagal massal, cek manual `freephonenum.com` dulu sebelum menyalahkan MCP.

## Keamanan

- `audit.jsonl`: key sensitif (`password/token/secret`) di-redact. Jangan commit file runtime.
- Jangan taruh kredensial asli di contoh manapun.
- Hanya pakai terhadap target yang Anda punya izin uji; nomor SMS publik bukan untuk akun sungguhan.

## Publish ke GitHub (checklist)

```bash
cd inbox-tap-mcp
# pastikan tidak ada secret bocor:
grep -ri "password\|token\|api.key\|bearer" --include="*.py" --include="*.md" --include="*.json" --include="*.sh" . | grep -v REDACT | grep -v CHANGEME | grep -v Testing123 || echo "bersih"
git init && git add . && git commit -m "inbox-tap-mcp standalone v1.0.0" && git branch -M main
gh repo create inbox-tap-mcp --public --source=. --push
```

## Troubleshooting

| Gejala | Obat |
|---|---|
| MCP tidak muncul di client | restart client; pastikan path `server.py` absolut; `python3 scripts/smoke_test.py` harus PASS |
| `email_wait` timeout terus | cek `email_inbox` manual — mungkin email memang belum masuk / akun >7 hari hangus → `email_create` baru |
| `sms_*` gagal / kosong | `freephonenum.com` mungkin berubah layout atau rate-limit — buka manual di browser, coba nomor/negara lain |
| `Timeout ... tidak ada SMS baru` | nomor publik lambat — naikkan `timeout`, atau ganti nomor via `sms_numbers` |

## Lisensi

MIT — lihat [LICENSE](LICENSE).