tossinbox 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Khairy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,271 @@
+# TossInbox — Disposable Email CLI & MCP Server for AI Agents
+
+<p align="center">
+  <img src="docs/logo.png" width="140" alt="TossInbox logo: an envelope tossed into a trash bin">
+</p>
+
+**Disposable email inboxes for humans and AI agents. Spawn a temporary inbox, wait for the OTP verification code, toss it.**
+
+[![CI](https://github.com/mohamed-khairy-5i/tossinbox/actions/workflows/ci.yml/badge.svg)](https://github.com/mohamed-khairy-5i/tossinbox/actions/workflows/ci.yml)
+![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)
+![Node](https://img.shields.io/badge/node-18%2B-34d399.svg)
+![MCP](https://img.shields.io/badge/MCP-server-222a39.svg)
+
+> **Built by [Mohamed Khairy](https://github.com/mohamed-khairy-5i).**
+> If TossInbox saved you a signup form, consider starring the repo — it helps more people find it.
+
+TossInbox is a temp-mail CLI and MCP server: it creates a brand-new throwaway
+email address in one command, waits for the email verification to land, extracts
+the OTP code, and deletes the inbox when you are done — server-side and locally.
+Use it for signups, QA email flows, and test automation — or let your **AI
+agent** do all of it through the built-in **MCP server**. No sign-up, no ads,
+no browser, no API keys. Humans read the output; agents parse the `--json`.
+
+<a href="https://tossinbox.pages.dev/"><strong>Website & docs → tossinbox.pages.dev</strong></a>
+
+## Demo
+
+```text
+$ tossinbox spawn
+✔ Inbox ready : qwd6996p1lbc@uberip.com
+  provider    : mailtm
+
+$ tossinbox wait --code --from noreply@github.com --timeout 120
+✔ Verify your device
+  from : GitHub <noreply@github.com>
+  code : 9378412
+
+$ tossinbox toss
+✔ tossed qwd6996p1lbc@uberip.com
+```
+
+## Why TossInbox
+
+- **For humans** — stop exposing your real address to every signup form.
+- **For agents** — built agent-first from day one:
+  - `--json` output on every command
+  - documented exit codes, no interactive prompts
+  - an [MCP server](https://modelcontextprotocol.io) so Claude, Cursor, and any
+    MCP client can create inboxes and read verification codes as native tools
+  - an `llms.txt` at the repository root for LLM-friendly onboarding
+
+|                        | TossInbox               | temp-mail websites  | tmpmail-era CLIs            |
+|------------------------|-------------------------|---------------------|-----------------------------|
+| JSON on every command  | `--json`                | no                  | rarely                      |
+| Documented exit codes  | 0–4                     | none                | no                          |
+| MCP server for agents  | yes, built in           | no                  | no                          |
+| Runs headless / in CI  | yes                     | no                  | partial                     |
+| Upstream alive         | mail.tm + GuerrillaMail | varies              | many wrap the dead 1secmail |
+| Ads, trackers, popups  | none                    | the business model  | none                        |
+
+Checked September 2026. If a cell is wrong, open an issue and win the argument.
+
+## Install
+
+Requires Node.js 18+.
+
+```bash
+# Homebrew (macOS, Linux)
+brew install mohamed-khairy-5i/tap/tossinbox
+
+# npm from GitHub (npm registry publish coming soon)
+npm install -g github:mohamed-khairy-5i/tossinbox
+
+# Or run without installing
+npx github:mohamed-khairy-5i/tossinbox spawn
+```
+
+From source:
+
+```bash
+git clone https://github.com/mohamed-khairy-5i/tossinbox.git
+cd tossinbox
+npm install
+npm run build
+node dist/cli.js --help
+```
+
+## Quickstart
+
+Four commands from zero to a tossed inbox:
+
+```bash
+tossinbox providers             # sanity check: install + network work
+tossinbox spawn                 # create an inbox (saved locally)
+tossinbox wait --code           # block until a message arrives, print its OTP
+tossinbox toss                  # delete the inbox server-side + wipe local state
+```
+
+Every command also accepts `--json` for machine-readable output:
+
+```bash
+tossinbox spawn --json
+tossinbox wait --code --json
+```
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `spawn` | Create a new disposable inbox (`-p provider`, `-l label`) |
+| `list` | List messages (`-a address`) |
+| `read <id>` | Read a full message, including any detected code |
+| `wait` | Poll until a message arrives (`-f sender`, `-s subject`, `-c` extract code, `-t timeout` max 600s) |
+| `inboxes` | List locally saved inboxes |
+| `toss` | Delete an inbox server-side and remove it from local state (`--all` for every inbox) |
+| `clear` | Remove all inboxes from local state only |
+| `providers` | List available email providers |
+| `mcp` | Run the MCP server over stdio |
+
+### Exit codes
+
+A stable contract: agents script against these, not against stdout.
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | Error (provider / network / unexpected) |
+| `2` | Timeout (`wait` expired without a matching message) |
+| `3` | Not found (no saved inbox, unknown address, or message missing) |
+| `4` | Usage error (bad flags, unknown command, or unknown provider) |
+
+## GitHub Action (email verification in CI)
+
+Use TossInbox directly in your workflows to test real signup / verification
+email flows:
+
+```yaml
+- uses: mohamed-khairy-5i/tossinbox@v1
+  id: mail
+  with:
+    args: "wait --code --json"
+    timeout: "180"
+
+- run: echo "Verification code: ${{ steps.mail.outputs.code }}"
+```
+
+Outputs: `address` (the disposable inbox) and `code` (the extracted OTP).
+
+## MCP Server (for AI agents)
+
+TossInbox ships with an MCP server exposing four tools:
+
+| Tool | Description |
+|---|---|
+| `create_inbox` | Create a disposable inbox and return its address |
+| `list_messages` | List messages in an inbox |
+| `read_message` | Read a full message, including any detected code |
+| `wait_for_code` | Poll until a message arrives and return its verification code |
+
+### Claude Desktop / Cursor / any MCP client
+
+```json
+{
+  "mcpServers": {
+    "tossinbox": {
+      "command": "npx",
+      "args": ["-y", "github:mohamed-khairy-5i/tossinbox", "mcp"]
+    }
+  }
+}
+```
+
+Or after a global install, simply use `tossinbox-mcp` as the command.
+
+### Works with any AI agent
+
+TossInbox is deliberately agent-agnostic — no lock-in to one vendor:
+
+- **Any MCP client**: Claude Desktop, Claude Code, Cursor, Windsurf, Cline,
+  Codex CLI, Gemini CLI, and every other MCP-compatible client
+- **Any shell-capable agent**: the CLI itself is the interface — `--json` on
+  every command, exit codes `0–4` documented, zero interactive prompts
+- **CI/CD**: the GitHub Action above needs no agent at all
+
+## Using TossInbox with an agent (copy-paste flow)
+
+```text
+1. "Create a disposable inbox"            -> tool: create_inbox
+2. "Sign up at example.com with this address"
+3. "Wait for the verification code from example.com"
+                                           -> tool: wait_for_code
+4. "Use code 482913 to finish the signup"
+5. "Toss the inbox when done"              -> CLI: tossinbox toss
+```
+
+## Agent discovery surfaces
+
+If you are an AI agent or LLM reading this: everything below is
+machine-readable and kept up to date.
+
+- [llms.txt](./llms.txt) at the repository root — full onboarding in one file
+- [llms.txt on the website](https://tossinbox.pages.dev/llms.txt)
+- [MCP Server Card](https://tossinbox.pages.dev/.well-known/mcp/server-card.json)
+- [Agent skill (SKILL.md)](https://tossinbox.pages.dev/.well-known/agent-skills/tossinbox/SKILL.md)
+  · [skills index](https://tossinbox.pages.dev/.well-known/agent-skills/index.json)
+- [API catalog (RFC 9727)](https://tossinbox.pages.dev/.well-known/api-catalog)
+- [ARD manifest](https://tossinbox.pages.dev/.well-known/ard.json)
+- Markdown mirrors of every docs page: send `Accept: text/markdown` to
+  [tossinbox.pages.dev](https://tossinbox.pages.dev/) or fetch `/index.md`,
+  `/quickstart.md`, `/cli.md`, `/agents.md`, `/faq.md`
+
+## Providers
+
+| Provider | API key | Notes |
+|---|---|---|
+| `mailtm` (default) | not required | mail.tm — reliable, fast |
+| `guerrillamail` | not required | GuerrillaMail — classic fallback |
+
+Adding a provider means implementing a small interface (`createInbox`,
+`listMessages`, `readMessage`, optional `destroyInbox`) — PRs welcome.
+
+## FAQ
+
+**Is it really free?**
+Yes. MIT-licensed, and both upstream providers are free with no API keys.
+
+**Can it send email?**
+No — receive-only by design. TossInbox exists for privacy and testing and
+ships no bulk-send or bulk-signup mode.
+
+**Does it work on Windows?**
+Yes, anywhere Node.js 18+ runs. `npx github:mohamed-khairy-5i/tossinbox spawn`
+works in PowerShell exactly the same.
+
+**A site blocked my disposable address. What now?**
+Some sites blocklist known disposable domains. Try the other provider:
+`tossinbox spawn -p guerrillamail`. If both are blocked, the site wins that
+round.
+
+## Privacy and safety
+
+- The local state file (`~/.tossinbox/state.json`, override with
+  `TOSSINBOX_STATE`) contains provider tokens and is written with `0600`
+  permissions.
+- `toss` deletes the account on the provider when supported, then wipes local
+  state.
+- Disposable email is for privacy and testing — not for abuse. Please respect
+  each provider's terms of service.
+
+## Roadmap
+
+- [x] GitHub Action: `mohamed-khairy-5i/tossinbox@v1`
+- [x] Homebrew tap: `brew install mohamed-khairy-5i/tap/tossinbox`
+- [x] Project website at [tossinbox.pages.dev](https://tossinbox.pages.dev/)
+- [ ] Publish `tossinbox` + `tossinbox-mcp` to the npm registry
+- [ ] `mail.gw` provider (mail.tm-compatible API — small lift)
+- [ ] `tempmail.lol` provider (free API)
+- [ ] Provider failover: auto-switch when a provider is down
+- [ ] Homebrew core formula (after community adoption)
+
+## Documentation
+
+- [Quickstart](https://tossinbox.pages.dev/quickstart) — first inbox in four commands
+- [CLI reference](https://tossinbox.pages.dev/cli) — every command, flag, and exit code
+- [Agents & MCP](https://tossinbox.pages.dev/agents) — setup for every MCP client
+- [FAQ](https://tossinbox.pages.dev/faq) — privacy, providers, troubleshooting
+- [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md) · [Security](./SECURITY.md)
+
+## License
+
+[MIT](./LICENSE) © Mohamed Khairy

package/dist/cli.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+import { Command, CommanderError } from "commander";
+import { DEFAULT_PROVIDER, getProvider, listProviders, listSavedInboxes, removeInbox, clearInboxes, resolveInbox, saveInbox, statePath, waitForMessage, htmlToText, ProviderError, } from "./core/index.js";
+import { VERSION } from "./version.js";
+/* Documented exit codes:
+ * 0  success
+ * 1  error (provider / network / unexpected)
+ * 2  timeout (wait expired without a matching message)
+ * 3  not found (no saved inbox, unknown address, or message missing)
+ * 4  usage error (bad flags / unknown command / unknown provider)
+ */
+const EXIT_OK = 0;
+const EXIT_ERROR = 1;
+const EXIT_TIMEOUT = 2;
+const EXIT_NOT_FOUND = 3;
+const EXIT_USAGE = 4;
+const program = new Command();
+program
+    .name("tossinbox")
+    .description("Disposable email inboxes for humans and AI agents. Spawn an inbox, wait for the OTP, toss it.")
+    .version(VERSION)
+    .option("--json", "machine-readable JSON output (agent-friendly)");
+function jsonMode() {
+    return Boolean(program.opts().json);
+}
+function out(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+/** Resolve a provider by name; an unknown provider is a usage error (exit 4). */
+function providerOrExit(name) {
+    try {
+        return getProvider(name);
+    }
+    catch (err) {
+        fail(err, EXIT_USAGE);
+    }
+}
+function fail(err, exitCode = EXIT_ERROR) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (jsonMode()) {
+        out({ ok: false, error: message });
+    }
+    else {
+        console.error(`✖ ${message}`);
+    }
+    process.exit(exitCode);
+}
+function exitWith(code) {
+    process.exit(code);
+}
+function jsonMessage(message, includeHtml = false) {
+    return {
+        id: message.id,
+        from: message.from,
+        fromName: message.fromName,
+        subject: message.subject,
+        createdAt: message.createdAt,
+        code: message.code,
+        text: message.text ?? (message.html ? htmlToText(message.html) : undefined),
+        html: includeHtml ? message.html : undefined,
+    };
+}
+function printMessageHuman(message, withBody) {
+    console.log(`✔ ${message.subject}`);
+    console.log(`  from : ${message.fromName ? `${message.fromName} <${message.from}>` : message.from}`);
+    if (message.createdAt)
+        console.log(`  date : ${message.createdAt}`);
+    if (message.code)
+        console.log(`  code : ${message.code}`);
+    if (withBody) {
+        const body = message.text ?? (message.html ? htmlToText(message.html) : "");
+        if (body)
+            console.log(`\n${body}\n`);
+    }
+}
+/* ------------------------------------------------------------------ */
+/* commands                                                            */
+/* ------------------------------------------------------------------ */
+program
+    .command("spawn")
+    .description("Create a new disposable inbox")
+    .option("-p, --provider <name>", "email provider (see: providers)", DEFAULT_PROVIDER)
+    .option("-l, --label <label>", "optional label to identify this inbox")
+    .action(async (opts) => {
+    try {
+        const provider = providerOrExit(opts.provider);
+        const inbox = await provider.createInbox({ label: opts.label });
+        await saveInbox(inbox);
+        if (jsonMode()) {
+            out({ ok: true, inbox });
+            return;
+        }
+        console.log(`✔ Inbox ready : ${inbox.address}`);
+        console.log(`  provider    : ${inbox.provider}`);
+        if (inbox.label)
+            console.log(`  label       : ${inbox.label}`);
+        console.log(`  state file  : ${statePath()}`);
+    }
+    catch (err) {
+        if (err instanceof ProviderError && err.status && err.status >= 400 && err.status < 500 && err.status !== 429) {
+            fail(err, EXIT_ERROR);
+        }
+        fail(err);
+    }
+});
+program
+    .command("list")
+    .description("List messages in an inbox")
+    .option("-a, --address <address>", "inbox address (defaults to the most recent inbox)")
+    .action(async (opts) => {
+    try {
+        const inbox = await resolveInbox(opts.address);
+        if (!inbox)
+            fail(new Error("No saved inbox found. Run: tossinbox spawn"), EXIT_NOT_FOUND);
+        const provider = providerOrExit(inbox.provider);
+        const messages = await provider.listMessages(inbox);
+        if (jsonMode()) {
+            out({ ok: true, inbox: inbox.address, provider: inbox.provider, count: messages.length, messages });
+            return;
+        }
+        console.log(`✔ ${messages.length} message(s) in ${inbox.address}`);
+        messages.forEach((m, i) => {
+            console.log(`  ${i + 1}) [${m.id}] ${m.subject}`);
+            console.log(`     from: ${m.fromName ? `${m.fromName} <${m.from}>` : m.from}`);
+            if (m.intro)
+                console.log(`     ${m.intro.slice(0, 100)}`);
+        });
+    }
+    catch (err) {
+        fail(err);
+    }
+});
+program
+    .command("read <id>")
+    .description("Read a full message by id")
+    .option("-a, --address <address>", "inbox address (defaults to the most recent inbox)")
+    .action(async (id, opts) => {
+    try {
+        const inbox = await resolveInbox(opts.address);
+        if (!inbox)
+            fail(new Error("No saved inbox found. Run: tossinbox spawn"), EXIT_NOT_FOUND);
+        const provider = providerOrExit(inbox.provider);
+        const message = await provider.readMessage(inbox, id);
+        if (jsonMode()) {
+            out({ ok: true, inbox: inbox.address, message: jsonMessage(message, true) });
+            return;
+        }
+        printMessageHuman(message, true);
+    }
+    catch (err) {
+        fail(err, err instanceof ProviderError && err.status === 404 ? EXIT_NOT_FOUND : EXIT_ERROR);
+    }
+});
+program
+    .command("wait")
+    .description("Wait for a message to arrive (optionally extract the OTP code)")
+    .option("-a, --address <address>", "inbox address (defaults to the most recent inbox)")
+    .option("-f, --from <sender>", "only match messages from this sender (substring)")
+    .option("-s, --subject <text>", "only match messages whose subject contains this text")
+    .option("-c, --code", "extract the verification code / OTP from the message")
+    .option("-t, --timeout <seconds>", "give up after this many seconds (max 600)", "120")
+    .option("-i, --interval <seconds>", "poll interval in seconds", "5")
+    .action(async (opts) => {
+    try {
+        const timeoutSeconds = Number(opts.timeout);
+        const intervalSeconds = Number(opts.interval);
+        if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 0) {
+            fail(new Error(`Invalid --timeout "${opts.timeout}" (expected a number of seconds)`), EXIT_USAGE);
+        }
+        if (!Number.isFinite(intervalSeconds) || intervalSeconds < 0) {
+            fail(new Error(`Invalid --interval "${opts.interval}" (expected a number of seconds)`), EXIT_USAGE);
+        }
+        const inbox = await resolveInbox(opts.address);
+        if (!inbox)
+            fail(new Error("No saved inbox found. Run: tossinbox spawn"), EXIT_NOT_FOUND);
+        const provider = providerOrExit(inbox.provider);
+        const { timedOut, message } = await waitForMessage(provider, inbox, {
+            timeoutSeconds,
+            intervalSeconds,
+            from: opts.from,
+            subject: opts.subject,
+        });
+        if (timedOut || !message) {
+            const detail = `No matching message within ${opts.timeout}s`;
+            if (jsonMode())
+                out({ ok: false, error: "timeout", detail, inbox: inbox.address });
+            else
+                console.error(`✖ ${detail}`);
+            exitWith(EXIT_TIMEOUT);
+        }
+        if (jsonMode()) {
+            if (opts.code) {
+                if (message.code)
+                    out({ ok: true, code: message.code, inbox: inbox.address, message: jsonMessage(message) });
+                else
+                    out({ ok: false, error: "message arrived but no code was detected", message: jsonMessage(message) });
+            }
+            else {
+                out({ ok: true, inbox: inbox.address, message: jsonMessage(message) });
+            }
+        }
+        else {
+            printMessageHuman(message, false);
+            if (opts.code && !message.code) {
+                console.error("✖ Message arrived but no verification code was detected");
+                exitWith(EXIT_ERROR);
+            }
+        }
+        exitWith(opts.code && !message.code ? EXIT_ERROR : EXIT_OK);
+    }
+    catch (err) {
+        fail(err);
+    }
+});
+program
+    .command("inboxes")
+    .description("List locally saved inboxes")
+    .action(async () => {
+    const inboxes = await listSavedInboxes();
+    if (jsonMode()) {
+        out({ ok: true, count: inboxes.length, inboxes });
+        return;
+    }
+    console.log(`✔ ${inboxes.length} saved inbox(es)`);
+    inboxes.forEach((i) => {
+        console.log(`  - ${i.address} (${i.provider}${i.label ? `, ${i.label}` : ""})`);
+    });
+});
+program
+    .command("toss")
+    .description("Delete an inbox (server-side when supported) and remove it from local state")
+    .option("-a, --address <address>", "inbox address (defaults to the most recent inbox)")
+    .option("--all", "toss every saved inbox")
+    .action(async (opts) => {
+    try {
+        const targets = [];
+        if (opts.all) {
+            targets.push(...(await listSavedInboxes()));
+        }
+        else {
+            const inbox = await resolveInbox(opts.address);
+            if (inbox)
+                targets.push(inbox);
+        }
+        if (targets.length === 0) {
+            fail(new Error("Nothing to toss"), EXIT_NOT_FOUND);
+        }
+        for (const inbox of targets) {
+            const provider = providerOrExit(inbox.provider);
+            if (provider.destroyInbox) {
+                await provider.destroyInbox(inbox);
+            }
+            await removeInbox(inbox.address);
+        }
+        if (jsonMode()) {
+            out({ ok: true, tossed: targets.map((t) => t.address) });
+            return;
+        }
+        targets.forEach((t) => console.log(`✔ tossed ${t.address}`));
+        exitWith(EXIT_OK);
+    }
+    catch (err) {
+        fail(err);
+    }
+});
+program
+    .command("clear")
+    .description("Remove all inboxes from local state (no server-side deletion)")
+    .action(async () => {
+    const count = await clearInboxes();
+    if (jsonMode())
+        out({ ok: true, removed: count });
+    else
+        console.log(`✔ removed ${count} inbox(es) from local state`);
+    exitWith(EXIT_OK);
+});
+program
+    .command("providers")
+    .description("List available email providers")
+    .action(async () => {
+    const all = listProviders();
+    if (jsonMode()) {
+        out({ ok: true, default: DEFAULT_PROVIDER, providers: all.map((p) => ({ name: p.name, description: p.description })) });
+        return;
+    }
+    console.log(`✔ available providers (default: ${DEFAULT_PROVIDER})`);
+    all.forEach((p) => console.log(`  - ${p.name.padEnd(14)} ${p.description}`));
+    exitWith(EXIT_OK);
+});
+program
+    .command("mcp")
+    .description("Run the TossInbox MCP server over stdio (for Claude, Cursor, and other MCP clients)")
+    .action(async () => {
+    const { startMcpServer } = await import("./mcp.js");
+    await startMcpServer();
+});
+program.exitOverride();
+// exitOverride is per-command: apply it to every subcommand too, so bad flags
+// surface as CommanderError (-> exit 4) instead of commander's default exit 1.
+for (const cmd of program.commands)
+    cmd.exitOverride();
+program.parseAsync(process.argv).catch((err) => {
+    if (err instanceof CommanderError) {
+        // --help / --version exit cleanly even under exitOverride
+        if (err.code === "commander.helpDisplayed" || err.code === "commander.help" || err.code === "commander.version") {
+            exitWith(EXIT_OK);
+        }
+        fail(err, EXIT_USAGE); // bad flags / unknown command = usage error
+    }
+    fail(err);
+});

package/dist/core/index.js

@@ -0,0 +1,25 @@
+import { mailTm } from "./providers/mailtm.js";
+import { guerrillaMail } from "./providers/guerrillamail.js";
+export * from "./types.js";
+export { extractCode, htmlToText } from "./otp.js";
+export * from "./state.js";
+export { waitForMessage } from "./wait.js";
+export const providers = {
+    [mailTm.name]: mailTm,
+    [guerrillaMail.name]: guerrillaMail,
+};
+export const DEFAULT_PROVIDER = mailTm.name;
+export function getProvider(name) {
+    const key = (name || DEFAULT_PROVIDER).toLowerCase();
+    const provider = providers[key];
+    if (!provider) {
+        const known = Object.values(providers)
+            .map((p) => p.name)
+            .join(", ");
+        throw new Error(`Unknown provider "${name}". Available providers: ${known}`);
+    }
+    return provider;
+}
+export function listProviders() {
+    return Object.values(providers);
+}

package/dist/core/otp.js

@@ -0,0 +1,56 @@
+/**
+ * Extract OTP / verification codes from message text or HTML.
+ *
+ * Strategy (in order):
+ *  1. On a line containing a code keyword, prefer a standalone token that
+ *     looks like a code (4-8 digits, or 5-8 uppercase alphanumeric chars
+ *     containing both letters and digits).
+ *  2. Fall back to the first standalone 4-8 digit number in the text.
+ */
+const CODE_KEYWORDS = /\b(?:code|otp|passcode|pin|password.?code|verification|verify|confirm|activation|active.?code|one.?time)\b|رمز|كود|تفعيل|تحقق|الرمز/i;
+export function htmlToText(html) {
+    return html
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<br\s*\/?>/gi, "\n")
+        .replace(/<\/(p|div|tr|h[1-6]|li)>/gi, "\n")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&quot;/gi, '"')
+        .replace(/&#0?39;/g, "'")
+        .replace(/[ \t]+/g, " ")
+        .trim();
+}
+export function extractCode(input) {
+    if (!input)
+        return undefined;
+    const text = /<[a-z!][\s\S]*>/i.test(input) ? htmlToText(input) : input;
+    if (!text)
+        return undefined;
+    const lines = text.split(/\r?\n/);
+    // 1) Keyword line -> prefer a code-shaped token on that line
+    for (const line of lines) {
+        if (!CODE_KEYWORDS.test(line))
+            continue;
+        // Case-insensitive on purpose: many services send lowercase codes (f4x9k2).
+        const tokens = line.match(/(?<![\w-])[A-Za-z0-9]{4,10}(?![\w-])/g);
+        if (!tokens)
+            continue;
+        for (const token of tokens) {
+            if (/^\d{4,8}$/.test(token))
+                return token;
+            const upper = token.toUpperCase();
+            if (/^[A-Z0-9]{5,8}$/.test(upper) && /\d/.test(upper) && /[A-Z]/.test(upper)) {
+                return upper;
+            }
+        }
+    }
+    // 2) Fallback: first standalone 4-8 digit number anywhere
+    const numeric = text.match(/(?<![\w-])(\d{4,8})(?![\w-])/);
+    if (numeric)
+        return numeric[1];
+    return undefined;
+}

package/dist/core/providers/guerrillamail.js

@@ -0,0 +1,82 @@
+import { ProviderError } from "../types.js";
+import { extractCode } from "../otp.js";
+import { VERSION } from "../../version.js";
+const BASE = "https://api.guerrillamail.com/ajax.php";
+const REQUEST_TIMEOUT_MS = 20_000;
+function timestampToIso(ts) {
+    if (!ts)
+        return undefined;
+    // guerrillamail timestamps are in seconds
+    return new Date(ts * 1000).toISOString();
+}
+async function call(params) {
+    const url = new URL(BASE);
+    for (const [k, v] of Object.entries(params))
+        url.searchParams.set(k, v);
+    // Hard timeout on every request — an agent must never hang forever.
+    const res = await fetch(url, {
+        headers: { Accept: "application/json", "User-Agent": `tossinbox/${VERSION}` },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok)
+        throw new ProviderError("guerrillamail", `HTTP ${res.status}`, res.status);
+    return (await res.json());
+}
+export const guerrillaMail = {
+    name: "guerrillamail",
+    description: "GuerrillaMail — classic disposable email, no API key required",
+    async createInbox(options) {
+        const data = await call({ f: "get_email_address", lang: "en" });
+        const addr = data;
+        if (!addr.email_addr || !addr.sid_token) {
+            throw new ProviderError(this.name, "Unexpected response while creating inbox");
+        }
+        const inbox = {
+            provider: this.name,
+            address: addr.email_addr,
+            label: options?.label,
+            session: addr.sid_token,
+            createdAt: new Date().toISOString(),
+        };
+        return inbox;
+    },
+    async listMessages(inbox) {
+        if (!inbox.session)
+            throw new ProviderError(this.name, "Inbox is missing its session token");
+        const data = await call({ f: "get_email_list", offset: "0", sid_token: inbox.session });
+        const list = data.list?.list ?? [];
+        return list.map((m) => ({
+            id: String(m.mail_id),
+            from: m.mail_from ?? "unknown",
+            subject: m.mail_subject ?? "(no subject)",
+            intro: m.mail_excerpt,
+            createdAt: timestampToIso(m.mail_timestamp),
+        }));
+    },
+    async readMessage(inbox, id) {
+        if (!inbox.session)
+            throw new ProviderError(this.name, "Inbox is missing its session token");
+        const data = await call({ f: "fetch_email", sid_token: inbox.session, email_id: id });
+        const m = data;
+        const message = {
+            id: String(m.mail_id ?? id),
+            from: m.mail_from ?? "unknown",
+            subject: m.mail_subject ?? "(no subject)",
+            intro: m.mail_excerpt,
+            createdAt: timestampToIso(m.mail_timestamp),
+            html: m.mail_body,
+        };
+        message.code = extractCode(message.html);
+        return message;
+    },
+    async destroyInbox(inbox) {
+        if (!inbox.session)
+            return;
+        try {
+            await call({ f: "forget_me", email_addr: inbox.address, sid_token: inbox.session });
+        }
+        catch {
+            // best effort
+        }
+    },
+};

package/dist/core/providers/mailtm.js

@@ -0,0 +1,150 @@
+import { randomBytes } from "node:crypto";
+import { ProviderError } from "../types.js";
+import { extractCode } from "../otp.js";
+import { VERSION } from "../../version.js";
+const BASE = "https://api.mail.tm";
+const REQUEST_TIMEOUT_MS = 20_000;
+function randomString(length, alphabet) {
+    const bytes = randomBytes(length);
+    let out = "";
+    for (let i = 0; i < length; i++) {
+        out += alphabet[bytes[i] % alphabet.length];
+    }
+    return out;
+}
+function randomUser(length = 12) {
+    return randomString(length, "abcdefghijklmnopqrstuvwxyz0123456789");
+}
+function randomPassword(length = 16) {
+    return randomString(length, "abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789");
+}
+function headers(token) {
+    const h = {
+        Accept: "application/json",
+        "User-Agent": `tossinbox/${VERSION}`,
+    };
+    if (token)
+        h.Authorization = `Bearer ${token}`;
+    return h;
+}
+/** Hard timeout on every request — an agent must never hang forever. */
+function fetchJson(url, init) {
+    return fetch(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+}
+/** mail.tm allows ~8 requests per second; retry once on 429. */
+async function request(method, url, options = {}) {
+    const init = {
+        method,
+        headers: { ...headers(options.token), ...(options.body ? { "Content-Type": "application/json" } : {}) },
+        body: options.body ? JSON.stringify(options.body) : undefined,
+    };
+    let res = await fetchJson(url, init);
+    if (res.status === 429) {
+        await new Promise((r) => setTimeout(r, 1200));
+        res = await fetchJson(url, init);
+    }
+    return res;
+}
+async function parseJson(res, provider) {
+    if (!res.ok) {
+        let detail = "";
+        try {
+            const body = (await res.json());
+            const msg = body["hydra:description"] ?? body.message ?? body.detail;
+            if (typeof msg === "string")
+                detail = `: ${msg}`;
+        }
+        catch {
+            // ignore body parse errors
+        }
+        throw new ProviderError(provider, `HTTP ${res.status}${detail}`, res.status);
+    }
+    return (await res.json());
+}
+/** mail.tm returns a plain array with Accept: application/json and a hydra
+ *  collection with Accept: application/ld+json — normalize both. */
+async function parseCollection(res, provider) {
+    const data = await parseJson(res, provider);
+    if (Array.isArray(data))
+        return data;
+    if (data && typeof data === "object") {
+        const obj = data;
+        const member = obj["hydra:member"] ?? obj.member;
+        if (Array.isArray(member))
+            return member;
+    }
+    throw new ProviderError(provider, "Unexpected collection response shape");
+}
+export const mailTm = {
+    name: "mailtm",
+    description: "mail.tm — free disposable email, no API key required",
+    async createInbox(options) {
+        const domainsRes = await request("GET", `${BASE}/domains?page=1`);
+        const domains = await parseCollection(domainsRes, this.name);
+        const domain = domains.find((d) => d.isActive && !d.isPrivate)?.domain;
+        if (!domain) {
+            throw new ProviderError(this.name, "No active public domain available on mail.tm");
+        }
+        const address = `${randomUser()}@${domain}`;
+        const password = randomPassword();
+        const accountRes = await request("POST", `${BASE}/accounts`, { body: { address, password } });
+        const account = await parseJson(accountRes, this.name);
+        const tokenRes = await request("POST", `${BASE}/token`, { body: { address, password } });
+        const auth = await parseJson(tokenRes, this.name);
+        const inbox = {
+            provider: this.name,
+            address: account.address || address,
+            label: options?.label,
+            token: auth.token,
+            password,
+            accountId: account.id || auth.id,
+            createdAt: new Date().toISOString(),
+        };
+        return inbox;
+    },
+    async listMessages(inbox) {
+        if (!inbox.token)
+            throw new ProviderError(this.name, "Inbox is missing its API token");
+        const res = await request("GET", `${BASE}/messages?page=1`, { token: inbox.token });
+        const data = await parseCollection(res, this.name);
+        return data.map((m) => ({
+            id: m.id,
+            from: m.from?.address ?? "unknown",
+            fromName: m.from?.name,
+            subject: m.subject ?? "(no subject)",
+            intro: m.intro,
+            createdAt: m.createdAt,
+        }));
+    },
+    async readMessage(inbox, id) {
+        if (!inbox.token)
+            throw new ProviderError(this.name, "Inbox is missing its API token");
+        const res = await request("GET", `${BASE}/messages/${encodeURIComponent(id)}`, { token: inbox.token });
+        const m = await parseJson(res, this.name);
+        const html = m.html && m.html.length > 0 ? m.html.join("\n") : undefined;
+        const message = {
+            id: m.id,
+            from: m.from?.address ?? "unknown",
+            fromName: m.from?.name,
+            subject: m.subject ?? "(no subject)",
+            intro: m.intro,
+            createdAt: m.createdAt,
+            text: m.text,
+            html,
+        };
+        message.code = extractCode(message.text) ?? extractCode(message.html);
+        return message;
+    },
+    async destroyInbox(inbox) {
+        if (!inbox.token || !inbox.accountId)
+            return;
+        try {
+            await request("DELETE", `${BASE}/accounts/${encodeURIComponent(inbox.accountId)}`, {
+                token: inbox.token,
+            });
+        }
+        catch {
+            // best effort: local removal always happens regardless
+        }
+    },
+};

package/dist/core/state.js

@@ -0,0 +1,69 @@
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export function statePath() {
+    return process.env.TOSSINBOX_STATE || path.join(os.homedir(), ".tossinbox", "state.json");
+}
+export async function loadState() {
+    let raw;
+    try {
+        raw = await fs.readFile(statePath(), "utf8");
+    }
+    catch (err) {
+        // Only a missing file means "no state yet" — anything else must be loud,
+        // otherwise the next write would silently destroy saved inboxes.
+        const code = err.code;
+        if (code === "ENOENT")
+            return { inboxes: [] };
+        throw new Error(`Cannot read state file ${statePath()} (${err.message}). ` +
+            "Fix its permissions or point TOSSINBOX_STATE at a writable path.");
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return { inboxes: Array.isArray(parsed.inboxes) ? parsed.inboxes : [] };
+    }
+    catch {
+        throw new Error(`State file ${statePath()} is not valid JSON. ` +
+            "Refusing to overwrite it — fix or delete the file manually (it may contain inboxes you still need).");
+    }
+}
+export async function saveInbox(inbox) {
+    const state = await loadState();
+    const filtered = state.inboxes.filter((i) => i.address !== inbox.address);
+    filtered.push(inbox);
+    await writeState({ inboxes: filtered });
+}
+export async function removeInbox(address) {
+    const state = await loadState();
+    const before = state.inboxes.length;
+    const filtered = state.inboxes.filter((i) => i.address !== address);
+    await writeState({ inboxes: filtered });
+    return filtered.length < before;
+}
+export async function clearInboxes() {
+    const state = await loadState();
+    const count = state.inboxes.length;
+    await writeState({ inboxes: [] });
+    return count;
+}
+export async function listSavedInboxes() {
+    const state = await loadState();
+    return [...state.inboxes].sort((a, b) => (a.createdAt < b.createdAt ? -1 : 1));
+}
+/** Resolve the inbox to operate on: an explicit address, or the most recent one. */
+export async function resolveInbox(address) {
+    const inboxes = await listSavedInboxes();
+    if (address) {
+        const needle = address.trim().toLowerCase();
+        return inboxes.find((i) => i.address.toLowerCase() === needle);
+    }
+    return inboxes.length > 0 ? inboxes[inboxes.length - 1] : undefined;
+}
+async function writeState(state) {
+    const file = statePath();
+    // The state file contains provider tokens — keep it private.
+    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    await fs.writeFile(file, JSON.stringify(state, null, 2) + "\n", "utf8");
+    // writeFile's mode option only applies at creation — enforce on every write.
+    await fs.chmod(file, 0o600);
+}

package/dist/core/types.js

@@ -0,0 +1,10 @@
+export class ProviderError extends Error {
+    status;
+    provider;
+    constructor(provider, message, status) {
+        super(message);
+        this.name = "ProviderError";
+        this.provider = provider;
+        this.status = status;
+    }
+}

package/dist/core/wait.js

@@ -0,0 +1,51 @@
+/**
+ * Poll the inbox until a matching message arrives or the timeout expires.
+ * Transient provider errors are swallowed and retried until the deadline.
+ */
+export async function waitForMessage(provider, inbox, options = {}) {
+    const timeoutSeconds = Math.max(1, Math.min(options.timeoutSeconds ?? 120, 600));
+    const intervalSeconds = Math.max(1, Math.min(options.intervalSeconds ?? 5, 60));
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    while (Date.now() < deadline) {
+        let summaries;
+        try {
+            summaries = await provider.listMessages(inbox);
+        }
+        catch {
+            await sleep(Math.min(intervalSeconds * 1000, deadline - Date.now()));
+            continue;
+        }
+        const matched = summaries.find((m) => {
+            if (options.from) {
+                const hay = `${m.from} ${m.fromName ?? ""}`.toLowerCase();
+                if (!hay.includes(options.from.toLowerCase()))
+                    return false;
+            }
+            if (options.subject && !m.subject.toLowerCase().includes(options.subject.toLowerCase())) {
+                return false;
+            }
+            return true;
+        });
+        if (matched) {
+            // One retry after a short delay — a transient read error should not
+            // throw away a wait that may have taken minutes.
+            try {
+                const message = await provider.readMessage(inbox, matched.id);
+                return { timedOut: false, message };
+            }
+            catch {
+                await sleep(1500);
+                const message = await provider.readMessage(inbox, matched.id);
+                return { timedOut: false, message };
+            }
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        await sleep(Math.min(intervalSeconds * 1000, remaining));
+    }
+    return { timedOut: true };
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}

package/dist/mcp.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { DEFAULT_PROVIDER, getProvider, resolveInbox, saveInbox, waitForMessage, htmlToText, } from "./core/index.js";
+import { VERSION } from "./version.js";
+function text(result, isError = false) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+function messageJson(message, includeHtml = false) {
+    return {
+        id: message.id,
+        from: message.from,
+        fromName: message.fromName,
+        subject: message.subject,
+        createdAt: message.createdAt,
+        code: message.code,
+        text: message.text ?? (message.html ? htmlToText(message.html) : undefined),
+        html: includeHtml ? message.html : undefined,
+    };
+}
+async function requireInbox(address) {
+    const inbox = await resolveInbox(address);
+    if (inbox)
+        return inbox;
+    return null;
+}
+export async function startMcpServer() {
+    const server = new McpServer({
+        name: "tossinbox",
+        version: VERSION,
+    });
+    server.registerTool("create_inbox", {
+        title: "Create a disposable inbox",
+        description: "Create a brand new disposable email inbox. The inbox is saved locally so the other tools can use it. Returns the full email address to use in sign-up forms.",
+        inputSchema: {
+            provider: z.string().optional().describe(`Provider name (default: "${DEFAULT_PROVIDER}", see the providers list)`),
+            label: z.string().optional().describe("Optional label to identify this inbox"),
+        },
+    }, async ({ provider, label }) => {
+        try {
+            const p = getProvider(provider);
+            const inbox = await p.createInbox({ label });
+            await saveInbox(inbox);
+            return text({
+                ok: true,
+                inbox: { address: inbox.address, provider: inbox.provider, label: inbox.label },
+                hint: `Use address "${inbox.address}" in the sign-up form, then call wait_for_code after submitting it.`,
+            });
+        }
+        catch (err) {
+            return text({ ok: false, error: err instanceof Error ? err.message : String(err) }, true);
+        }
+    });
+    server.registerTool("list_messages", {
+        title: "List inbox messages",
+        description: "List the messages currently in a disposable inbox (defaults to the most recently created inbox).",
+        inputSchema: {
+            address: z.string().optional().describe("Inbox address; defaults to the most recent inbox"),
+        },
+    }, async ({ address }) => {
+        try {
+            const inbox = await requireInbox(address);
+            if (!inbox)
+                return text({ ok: false, error: "No saved inbox found. Call create_inbox first." }, true);
+            const p = getProvider(inbox.provider);
+            const messages = await p.listMessages(inbox);
+            return text({ ok: true, inbox: inbox.address, count: messages.length, messages });
+        }
+        catch (err) {
+            return text({ ok: false, error: err instanceof Error ? err.message : String(err) }, true);
+        }
+    });
+    server.registerTool("read_message", {
+        title: "Read a message",
+        description: "Read the full body of a message by id, including any verification code detected in it.",
+        inputSchema: {
+            id: z.string().describe("Message id (from list_messages)"),
+            address: z.string().optional().describe("Inbox address; defaults to the most recent inbox"),
+        },
+    }, async ({ id, address }) => {
+        try {
+            const inbox = await requireInbox(address);
+            if (!inbox)
+                return text({ ok: false, error: "No saved inbox found. Call create_inbox first." }, true);
+            const p = getProvider(inbox.provider);
+            const message = await p.readMessage(inbox, id);
+            return text({ ok: true, message: messageJson(message, false) });
+        }
+        catch (err) {
+            return text({ ok: false, error: err instanceof Error ? err.message : String(err) }, true);
+        }
+    });
+    server.registerTool("wait_for_code", {
+        title: "Wait for a verification code",
+        description: "Poll a disposable inbox until a message arrives, then return the verification code (OTP) found in it. Ideal right after submitting a sign-up form. Times out gracefully.",
+        inputSchema: {
+            address: z.string().optional().describe("Inbox address; defaults to the most recent inbox"),
+            timeout_seconds: z.number().int().min(5).max(600).optional().describe("Max seconds to wait (default 120)"),
+            from: z.string().optional().describe("Only match messages from this sender (substring)"),
+            subject: z.string().optional().describe("Only match messages whose subject contains this text"),
+        },
+    }, async ({ address, timeout_seconds, from, subject }) => {
+        try {
+            const inbox = await requireInbox(address);
+            if (!inbox)
+                return text({ ok: false, error: "No saved inbox found. Call create_inbox first." }, true);
+            const p = getProvider(inbox.provider);
+            const { timedOut, message } = await waitForMessage(p, inbox, {
+                timeoutSeconds: timeout_seconds,
+                from,
+                subject,
+            });
+            if (timedOut || !message) {
+                return text({
+                    ok: false,
+                    error: "timeout",
+                    detail: `No matching message within ${timeout_seconds ?? 120}s`,
+                    inbox: inbox.address,
+                }, true);
+            }
+            if (!message.code) {
+                return text({
+                    ok: false,
+                    error: "message arrived but no code was detected",
+                    message: messageJson(message, false),
+                }, true);
+            }
+            return text({ ok: true, code: message.code, inbox: inbox.address, message: messageJson(message, false) });
+        }
+        catch (err) {
+            return text({ ok: false, error: err instanceof Error ? err.message : String(err) }, true);
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is reserved for the MCP protocol; status goes to stderr.
+    console.error("tossinbox MCP server running on stdio");
+}
+/* When executed directly, start the server. This must also work when the file
+ * is launched through an npm/Homebrew bin symlink — resolve both paths before
+ * comparing, and fall back to the script name for exotic shim wrappers. */
+function isDirectRun() {
+    if (!process.argv[1])
+        return false;
+    try {
+        const arg = fs.realpathSync(process.argv[1]);
+        const self = fs.realpathSync(fileURLToPath(import.meta.url));
+        if (arg === self)
+            return true;
+        return path.basename(arg) === "mcp.js";
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectRun()) {
+    startMcpServer().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/dist/version.js

@@ -0,0 +1,3 @@
+/** Single source of truth for the runtime version string.
+ *  Keep in sync with package.json — bump both on release. */
+export const VERSION = "0.1.1";

package/llms.txt

@@ -0,0 +1,52 @@
+# TossInbox
+
+> Disposable email inboxes for humans and AI agents. Spawn an inbox, wait for the OTP, toss it.
+
+TossInbox creates disposable email addresses from the command line or through
+an MCP server, collects verification codes (OTP) from them, and deletes the
+inboxes when done. It is designed agent-first: every CLI command supports
+`--json`, exit codes are documented, and there are no interactive prompts.
+
+## CLI (binary: `tossinbox`)
+
+- `tossinbox spawn` — create a new disposable inbox (flags: `-p provider`, `-l label`)
+- `tossinbox list` — list messages in an inbox (flag: `-a address`)
+- `tossinbox read <id>` — read a full message by id
+- `tossinbox wait --code` — poll until a message arrives and print its verification code
+  (flags: `-f sender`, `-s subject`, `-t timeout`, `-i interval`)
+- `tossinbox inboxes` — list locally saved inboxes
+- `tossinbox toss` — delete an inbox server-side and wipe local state (`--all` for all)
+- `tossinbox providers` — list providers (default: `mailtm`, also `guerrillamail`)
+
+All commands accept `--json`. Exit codes: 0 success, 1 error, 2 timeout,
+3 not found, 4 usage error (bad flags / unknown provider).
+
+## MCP server (binary: `tossinbox-mcp`, or `tossinbox mcp`)
+
+Stdio MCP server exposing four tools:
+
+- `create_inbox` — create a disposable inbox, returns its email address
+- `list_messages` — list messages in an inbox
+- `read_message` — read a full message including any detected code
+- `wait_for_code` — poll until a message arrives and return its verification code
+
+Typical agent flow: `create_inbox` -> use the address in a signup form ->
+`wait_for_code` -> submit the code -> delete the inbox from the CLI with
+`tossinbox toss`.
+
+## Installation
+
+```bash
+npm install -g github:mohamed-khairy-5i/tossinbox
+# or run without installing:
+npx github:mohamed-khairy-5i/tossinbox spawn
+```
+
+## Notes
+
+- Providers: `mailtm` (default) and `guerrillamail`; no API keys required.
+- Local state is stored in `~/.tossinbox/state.json` (override with the
+  `TOSSINBOX_STATE` environment variable) with 0600 permissions.
+- TossInbox intentionally has no bulk mode; use it for privacy and testing and
+  respect the providers' terms of service.
+- License: MIT. Repository: https://github.com/mohamed-khairy-5i/tossinbox

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "tossinbox",
+  "version": "0.1.1",
+  "description": "Disposable email inboxes for humans and AI agents. Spawn an inbox, wait for the OTP, toss it.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mohamed Khairy <mohamed-khairy-5i@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohamed-khairy-5i/tossinbox.git"
+  },
+  "homepage": "https://github.com/mohamed-khairy-5i/tossinbox#readme",
+  "bugs": "https://github.com/mohamed-khairy-5i/tossinbox/issues",
+  "keywords": [
+    "disposable-email",
+    "temporary-email",
+    "temp-mail",
+    "temp-email",
+    "throwaway-email",
+    "disposable-inbox",
+    "otp",
+    "otp-verification",
+    "verification-code",
+    "email-verification",
+    "email-automation",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "ai-agents",
+    "cli",
+    "cli-tool",
+    "developer-tools",
+    "privacy",
+    "testing"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "tossinbox": "dist/cli.js",
+    "tossinbox-mcp": "dist/mcp.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "llms.txt"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "commander": "^12.1.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.4"
+  }
+}