@bencibro/tempmail-mcp 0.0.1

package/GUIDE.md

@@ -0,0 +1,286 @@
+# AI Guide: How to Use TempMail MCP
+
+> This document is written for **AI agents** (Claude, GPT, etc.) that have access to the TempMail MCP server. It explains every available tool, when to use which, and provides copy-paste-ready decision trees for common tasks.
+
+---
+
+## Quick Start: The 3-Step Pattern
+
+Almost every task with this MCP follows the same 3-step pattern:
+
+```
+1. create_mailbox  →  get a temporary email address
+2. [do something that sends email to that address]
+3. wait_for_email / get_verification_code  →  retrieve the result
+```
+
+That's it. Everything else is optimization (choosing the right provider, filtering, cleanup).
+
+---
+
+## Tool Reference (Quick)
+
+| Tool | Purpose | Key Parameters |
+|------|---------|---------------|
+| `list_providers` | See which providers are available | — |
+| `get_domains` | Get available email domains | `provider` |
+| `create_mailbox` | Create a temp email inbox | `provider`, `username`, `domain` |
+| `get_messages` | List current emails | `address` |
+| `get_message` | Read full email content | `address`, `messageId` |
+| `wait_for_email` | Block until email arrives | `address`, `subjectContains`, `fromContains`, `timeoutMs` |
+| `get_verification_code` | Wait + extract OTP/code | `address`, `subjectContains`, `fromContains`, `timeoutMs` |
+| `list_mailboxes` | Show all created mailboxes | — |
+| `delete_mailbox` | Clean up | `address` |
+| `auto_register` | Auto-obtain API key | `provider` (`"maildrop"` or `"mail.cx"`) |
+
+---
+
+## Choosing a Provider
+
+### Default: `mail.tm`
+
+Use `mail.tm` unless you have a specific reason not to. It's free, no API key needed, reliable, and supports account-based mailboxes.
+
+### When to use other providers
+
+| If you need... | Use |
+|---|---|
+| No setup, fastest path | `mail.tm` (default) |
+| A specific username | `guerrillamail` (supports custom usernames, 60-min expiry) |
+| The simplest API | `1secmail` (implicit mailbox, no account) |
+| Custom domains | `catchmail` (MX-based) or `mail.cx` |
+| Long-polling (faster email arrival) | `mail.cx` (25s server-side hold) |
+| High volume (300/day) | `maildrop` (requires API key — use `auto_register`) |
+| High volume (500/day) | `mail.cx` (requires API token — use `auto_register`) |
+
+### When to call `auto_register`
+
+Call `auto_register` when:
+- The user needs `maildrop` or `mail.cx` but no API key is configured.
+- You see `"maildrop"` or `"mail.cx"` missing from `list_providers` results.
+- The user explicitly asks to "register" or "get an API key".
+
+```json
+// Call auto_register — it takes ~2s for maildrop, ~15-30s for mail.cx
+{ "provider": "maildrop" }
+{ "provider": "mail.cx", "tokenName": "my-project" }
+```
+
+After `auto_register`, the provider is **immediately available** in the current session — no need to restart or reconfigure.
+
+---
+
+## Common Workflows
+
+### Workflow 1: Website Registration with Email Verification
+
+This is the most common task: register on a website that requires email verification.
+
+```
+Step 1: create_mailbox
+   → Returns: { address: "abc123@somedomain.com", ... }
+
+Step 2: [User or you register on the website using this email address]
+
+Step 3: get_verification_code
+   → Waits for a verification email
+   → Automatically extracts the code
+   → Returns: { code: "829451", from: "noreply@example.com", ... }
+
+Step 4: [Enter the code on the website to complete registration]
+
+Step 5: delete_mailbox (optional cleanup)
+```
+
+**Tip:** Use `subjectContains` to filter for the right email:
+- `"verification"` — most common
+- `"confirm"` — alternative
+- `"code"` — another common one
+- `"activate"` — account activation emails
+
+### Workflow 2: Waiting for a Specific Email
+
+If you need a specific email (not just any verification code):
+
+```
+Step 1: create_mailbox
+Step 2: [Trigger the email — fill form, request password reset, etc.]
+Step 3: wait_for_email
+   - Set subjectContains to filter by subject
+   - Set fromContains to filter by sender
+   - Set timeoutMs to 60000 (60s) or higher if needed
+Step 4: get_message (if you need full body, attachments, etc.)
+Step 5: delete_mailbox (cleanup)
+```
+
+### Workflow 3: Manual Email Checking
+
+If you just want to see what's in the inbox:
+
+```
+Step 1: create_mailbox
+Step 2: get_messages → See all emails (summary only)
+Step 3: get_message → Read a specific email in full
+```
+
+### Workflow 4: Setting Up All Providers
+
+If the user wants maximum capacity:
+
+```
+Step 1: auto_register (provider: "maildrop")     → ~2 seconds
+Step 2: auto_register (provider: "mail.cx")      → ~15-30 seconds
+Step 3: list_providers → Now shows all 6 providers
+```
+
+---
+
+## Important Details
+
+### Mailbox State
+
+- Mailboxes are tracked **in-memory per session**. If the MCP server restarts, all mailbox references are lost.
+- Always use `create_mailbox` before `get_messages`, `wait_for_email`, or `get_verification_code`.
+- If you get "No mailbox found for address", call `create_mailbox` first.
+
+### Timeouts
+
+- Default timeout for `wait_for_email` and `get_verification_code` is **60 seconds**.
+- If the email might take longer (slow sender, network issues), increase `timeoutMs` to `120000` (2 min).
+- For `mail.cx`, the server uses 25-second long-polling, so emails arrive faster.
+
+### Verification Code Extraction
+
+`get_verification_code` uses pattern matching to extract codes:
+- Looks for keywords: `code`, `verification`, `verify`, `otp`, `pin`, `passcode`
+- Extracts 4-8 digit numbers or alphanumeric codes near those keywords
+- Falls back to any standalone 4-8 digit number
+
+If extraction fails (returns `code: null`), call `get_message` and read the email body manually.
+
+### Error Handling
+
+- `isError: true` in the response means the tool call failed. Read the `text` field for details.
+- Common errors: mailbox not found, timeout waiting for email, provider not available.
+- For provider not available: use `auto_register` or check `list_providers`.
+
+### Provider Quotas
+
+| Provider | Limit | Behavior when exceeded |
+|---|---|---|
+| Mail.tm | 8 QPS | Rate limited (429) |
+| Guerrilla Mail | Unlimited | — |
+| 1secmail | Unlimited | — |
+| Catchmail | 1 req/s | Rate limited |
+| MailDrop | 300/day | 429 error |
+| Mail.cx | 500/day | 429 error |
+
+If you hit a quota, switch to another provider or use `auto_register` to get a new key.
+
+---
+
+## Response Formats
+
+### `create_mailbox` response
+
+```json
+{
+  "success": true,
+  "address": "abc123@somedomain.com",
+  "provider": "mail.tm",
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "message": "Mailbox created. Use 'get_messages' to check for incoming emails..."
+}
+```
+
+### `get_verification_code` response
+
+```json
+{
+  "success": true,
+  "code": "829451",
+  "messageId": "msg_abc123",
+  "from": "noreply@example.com",
+  "subject": "Your verification code",
+  "date": "2026-01-01T00:00:00.000Z",
+  "bodyPreview": "Your verification code is 829451..."
+}
+```
+
+If no code could be extracted:
+
+```json
+{
+  "success": true,
+  "code": null,
+  "messageId": "msg_abc123",
+  ...
+}
+```
+
+### `auto_register` response
+
+```json
+{
+  "success": true,
+  "provider": "maildrop",
+  "apiKey": "md_abc123...",
+  "email": "tmp_xxx@maildrop.cc",
+  "registeredAt": "2026-01-01T00:00:00.000Z",
+  "instructions": "API key is now active for this session. To make it permanent, set:\n  MAILDROP_API_KEY=md_abc123..."
+}
+```
+
+---
+
+## Anti-Patterns: What NOT to Do
+
+1. **Don't call `get_messages` in a tight loop.** Use `wait_for_email` or `get_verification_code` instead — they handle polling internally and are more efficient.
+
+2. **Don't hardcode provider names unless necessary.** Call `list_providers` first to see what's available.
+
+3. **Don't forget to pass the `address`.** All email-reading tools require the exact address returned by `create_mailbox`.
+
+4. **Don't ignore `isError` responses.** If a tool returns `isError: true`, read the message and adjust your approach.
+
+5. **Don't create multiple mailboxes for one task.** One mailbox per registration flow is enough.
+
+6. **Don't call `auto_register` repeatedly.** It creates real accounts. Call it once per provider, save the key, and reuse it.
+
+---
+
+## Decision Tree: Which Tool to Call
+
+```
+What does the user want?
+│
+├── "I need a temp email"
+│   └── create_mailbox (provider: "mail.tm" by default)
+│
+├── "I'm waiting for a verification code"
+│   └── get_verification_code (address, subjectContains: "verification")
+│
+├── "I'm waiting for a specific email"
+│   └── wait_for_email (address, subjectContains / fromContains)
+│
+├── "Show me what's in the inbox"
+│   └── get_messages (address)
+│
+├── "Read a specific email"
+│   └── get_message (address, messageId)
+│
+├── "I need MailDrop / mail.cx but have no API key"
+│   └── auto_register (provider: "maildrop" or "mail.cx")
+│
+├── "What providers are available?"
+│   └── list_providers
+│
+├── "What domains can I use?"
+│   └── get_domains (provider)
+│
+├── "Show me all my temp mailboxes"
+│   └── list_mailboxes
+│
+└── "Delete / clean up a mailbox"
+    └── delete_mailbox (address)
+```

package/GUIDE.zh-CN.md

@@ -0,0 +1,287 @@
+# AI 使用指南：如何使用 TempMail MCP
+
+> 本文档面向已接入 TempMail MCP 服务器的 **AI 代理**（Claude、GPT 等），解释每个可用工具的使用时机，并提供常见任务的决策树，可直接参考执行。
+
+---
+
+## 快速上手：三步模式
+
+几乎所有任务都遵循同一个三步模式：
+
+```
+1. create_mailbox  →  获取一个临时邮箱地址
+2. [用该地址触发某个会发送邮件的操作]
+3. wait_for_email / get_verification_code  →  获取结果
+```
+
+其余工具用于优化体验（选择合适的服务商、过滤、清理）。
+
+---
+
+## 工具速查表
+
+| 工具 | 用途 | 关键参数 |
+|------|---------|---------------|
+| `list_providers` | 查看可用服务商 | — |
+| `get_domains` | 获取可用域名 | `provider` |
+| `create_mailbox` | 创建临时邮箱 | `provider`, `username`, `domain` |
+| `get_messages` | 列出当前邮件 | `address` |
+| `get_message` | 读取邮件完整内容 | `address`, `messageId` |
+| `wait_for_email` | 阻塞等待邮件到达 | `address`, `subjectContains`, `fromContains`, `timeoutMs` |
+| `get_verification_code` | 等待并自动提取验证码 | `address`, `subjectContains`, `fromContains`, `timeoutMs` |
+| `list_mailboxes` | 列出所有已创建的邮箱 | — |
+| `delete_mailbox` | 清理邮箱 | `address` |
+| `auto_register` | 自动获取 API Key | `provider`（`"maildrop"` 或 `"mail.cx"`） |
+
+---
+
+## 服务商选择指南
+
+### 默认选择：`mail.tm`
+
+除非有特殊需求，默认使用 `mail.tm`。免费、无需 API Key、稳定可靠。
+
+### 何时使用其他服务商
+
+| 需求 | 推荐服务商 |
+|---|---|
+| 无需配置，最快路径 | `mail.tm`（默认） |
+| 需要指定用户名 | `guerrillamail`（支持自定义用户名，60 分钟过期） |
+| 最简 API | `1secmail`（隐式邮箱，无需创建账号） |
+| 自定义域名 | `catchmail`（基于 MX 记录）或 `mail.cx` |
+| 长轮询（更快收到邮件） | `mail.cx`（服务端 25 秒长轮询） |
+| 高频使用（300 次/天） | `maildrop`（需 API Key — 用 `auto_register` 获取） |
+| 高频使用（500 次/天） | `mail.cx`（需 API Token — 用 `auto_register` 获取） |
+
+### 何时调用 `auto_register`
+
+以下情况调用 `auto_register`：
+- 用户需要 `maildrop` 或 `mail.cx`，但未配置 API Key。
+- `list_providers` 结果中缺少 `"maildrop"` 或 `"mail.cx"`。
+- 用户明确要求"注册"或"获取 API Key"。
+
+```json
+// 调用 auto_register — maildrop 约 2 秒，mail.cx 约 15-30 秒
+{ "provider": "maildrop" }
+{ "provider": "mail.cx", "tokenName": "my-project" }
+```
+
+`auto_register` 后，该服务商在**当前会话中立即可用** — 无需重启或重新配置。
+
+---
+
+## 常见工作流
+
+### 工作流 1：网站注册 + 邮箱验证
+
+最常见的任务：在需要邮箱验证的网站上注册。
+
+```
+步骤 1：create_mailbox
+   → 返回：{ address: "abc123@somedomain.com", ... }
+
+步骤 2：[用户或你在网站上使用该邮箱地址注册]
+
+步骤 3：get_verification_code
+   → 等待验证邮件
+   → 自动提取验证码
+   → 返回：{ code: "829451", from: "noreply@example.com", ... }
+
+步骤 4：[在网站上输入验证码完成注册]
+
+步骤 5：delete_mailbox（可选清理）
+```
+
+**提示：** 使用 `subjectContains` 过滤正确邮件：
+- `"verification"` — 最常见
+- `"confirm"` — 备选
+- `"code"` — 另一种常见
+- `"activate"` — 账号激活邮件
+- `"验证"` — 中文邮件
+
+### 工作流 2：等待特定邮件
+
+如果需要特定的邮件（不仅仅是验证码）：
+
+```
+步骤 1：create_mailbox
+步骤 2：[触发邮件 — 填写表单、请求密码重置等]
+步骤 3：wait_for_email
+   - 设置 subjectContains 按主题过滤
+   - 设置 fromContains 按发件人过滤
+   - 设置 timeoutMs 为 60000（60 秒）或更长
+步骤 4：get_message（如需完整正文、附件等）
+步骤 5：delete_mailbox（清理）
+```
+
+### 工作流 3：手动查看邮件
+
+如果只想查看邮箱内容：
+
+```
+步骤 1：create_mailbox
+步骤 2：get_messages → 查看所有邮件（仅摘要）
+步骤 3：get_message → 读取特定邮件的完整内容
+```
+
+### 工作流 4：启用所有服务商
+
+如果用户需要最大容量：
+
+```
+步骤 1：auto_register (provider: "maildrop")     → 约 2 秒
+步骤 2：auto_register (provider: "mail.cx")      → 约 15-30 秒
+步骤 3：list_providers → 现在显示全部 6 个服务商
+```
+
+---
+
+## 重要细节
+
+### 邮箱状态
+
+- 邮箱在**当前会话内存中跟踪**。MCP 服务器重启后，所有邮箱引用将丢失。
+- 在调用 `get_messages`、`wait_for_email` 或 `get_verification_code` 之前，务必先调用 `create_mailbox`。
+- 如果收到 "No mailbox found for address" 错误，请先调用 `create_mailbox`。
+
+### 超时
+
+- `wait_for_email` 和 `get_verification_code` 的默认超时为 **60 秒**。
+- 如果邮件可能延迟（发送方慢、网络问题），将 `timeoutMs` 增加到 `120000`（2 分钟）。
+- 对于 `mail.cx`，服务端使用 25 秒长轮询，邮件到达更快。
+
+### 验证码提取
+
+`get_verification_code` 使用模式匹配提取验证码：
+- 查找关键词：`code`、`verification`、`verify`、`otp`、`pin`、`passcode`、`验证`、`認証`
+- 提取这些关键词附近的 4-8 位数字或字母数字代码
+- 回退到任何独立的 4-8 位数字
+
+如果提取失败（返回 `code: null`），调用 `get_message` 手动阅读邮件正文。
+
+### 错误处理
+
+- 响应中 `isError: true` 表示工具调用失败。阅读 `text` 字段了解详情。
+- 常见错误：邮箱未找到、等待邮件超时、服务商不可用。
+- 服务商不可用时：使用 `auto_register` 或检查 `list_providers`。
+
+### 服务商配额
+
+| 服务商 | 限制 | 超限行为 |
+|---|---|---|
+| Mail.tm | 8 QPS | 限流（429） |
+| Guerrilla Mail | 无限制 | — |
+| 1secmail | 无限制 | — |
+| Catchmail | 1 req/s | 限流 |
+| MailDrop | 300 次/天 | 429 错误 |
+| Mail.cx | 500 次/天 | 429 错误 |
+
+如果达到配额限制，切换到其他服务商或使用 `auto_register` 获取新 Key。
+
+---
+
+## 响应格式
+
+### `create_mailbox` 响应
+
+```json
+{
+  "success": true,
+  "address": "abc123@somedomain.com",
+  "provider": "mail.tm",
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "message": "Mailbox created. Use 'get_messages' to check for incoming emails..."
+}
+```
+
+### `get_verification_code` 响应
+
+```json
+{
+  "success": true,
+  "code": "829451",
+  "messageId": "msg_abc123",
+  "from": "noreply@example.com",
+  "subject": "Your verification code",
+  "date": "2026-01-01T00:00:00.000Z",
+  "bodyPreview": "Your verification code is 829451..."
+}
+```
+
+无法提取验证码时：
+
+```json
+{
+  "success": true,
+  "code": null,
+  "messageId": "msg_abc123",
+  ...
+}
+```
+
+### `auto_register` 响应
+
+```json
+{
+  "success": true,
+  "provider": "maildrop",
+  "apiKey": "md_abc123...",
+  "email": "tmp_xxx@maildrop.cc",
+  "registeredAt": "2026-01-01T00:00:00.000Z",
+  "instructions": "API key is now active for this session. To make it permanent, set:\n  MAILDROP_API_KEY=md_abc123..."
+}
+```
+
+---
+
+## 反模式：不应该做的事
+
+1. **不要在紧密循环中调用 `get_messages`。** 改用 `wait_for_email` 或 `get_verification_code` — 它们内部处理轮询，效率更高。
+
+2. **不要硬编码服务商名称。** 先调用 `list_providers` 查看可用服务商。
+
+3. **不要忘记传递 `address`。** 所有邮件读取工具都要求传递 `create_mailbox` 返回的确切地址。
+
+4. **不要忽略 `isError` 响应。** 如果工具返回 `isError: true`，阅读消息并调整策略。
+
+5. **不要为一个任务创建多个邮箱。** 一次注册流程一个邮箱就够了。
+
+6. **不要反复调用 `auto_register`。** 每次调用都会创建真实账号。每个服务商调用一次，保存 Key，然后复用。
+
+---
+
+## 决策树：该调用哪个工具
+
+```
+用户想要什么？
+│
+├── "我需要一个临时邮箱"
+│   └── create_mailbox（默认 provider: "mail.tm"）
+│
+├── "我在等验证码"
+│   └── get_verification_code（address, subjectContains: "verification"）
+│
+├── "我在等一封特定邮件"
+│   └── wait_for_email（address, subjectContains / fromContains）
+│
+├── "查看邮箱里有什么"
+│   └── get_messages（address）
+│
+├── "读取某封邮件"
+│   └── get_message（address, messageId）
+│
+├── "需要 MailDrop / mail.cx 但没有 API Key"
+│   └── auto_register（provider: "maildrop" 或 "mail.cx"）
+│
+├── "有哪些可用服务商？"
+│   └── list_providers
+│
+├── "可以用哪些域名？"
+│   └── get_domains（provider）
+│
+├── "查看我创建的所有邮箱"
+│   └── list_mailboxes
+│
+└── "删除 / 清理邮箱"
+    └── delete_mailbox（address）
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bencibr
+
+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.