mirror of https://github.com/beilunyang/moemail.git synced 2026-06-23 00:14:51 +08:00

Files

ty b99b872791 feat(cli,mcp): extract @moemail/core and add MCP server; release 1.0.0

Extract the HTTP client and config into a new @moemail/core package shared
by the CLI and a new @moemail/mcp server, so both frontends talk to the same
MoeMail API through one code path.

- core: api client (now throws typed ConfigError/AuthError/PermissionError/
  QuotaError instead of process.exit), config, msToIso, and a transport-
  agnostic pollForNewMessage helper.
- cli: consume @moemail/core; route command errors through a shared fail()
  that preserves exit codes (config/auth = 2, else = 1). Bump to 1.0.0.
- mcp: new stdio MCP server exposing 8 tools (create/list/read/wait/send/
  delete); wait_for_email is bounded and returns a timeout status to retry.
  Configured via MOEMAIL_API_KEY / MOEMAIL_API_URL env. Release 1.0.0.

Docs:
- Fix packages/cli/README.md (config set, send --content not --body, full
  flag table).
- Add MCP section to both root READMEs; complete the CLI command list
  (send, list, message-level delete).
- SKILL.md: --json works before or after the subcommand.
- Ignore bun.lock in package gitignores.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-15 23:52:35 +08:00

3.4 KiB

Raw Blame History

MoeMail CLI

Agent-first CLI for MoeMail temporary email service

Install

npm i -g @moemail/cli

Quick Start

1. Configure endpoint and API key

moemail config set api-url https://moemail.app
moemail config set api-key YOUR_API_KEY

Config is read from ~/.moemail/config.json, or overridden by the MOEMAIL_API_URL / MOEMAIL_API_KEY environment variables.

2. Create a temporary email

moemail create --expiry 1h

3. Wait for messages

moemail wait --email-id <email_id> --timeout 120

Command Reference

Command	Description	Key Flags
`config set`	Set `api-url` or `api-key`	`config set <api-url\|api-key> <value>`
`config list`	Show current configuration	—
`create`	Create a temporary email address	`--name <prefix>`, `--domain <domain>`, `--expiry <1h\|24h\|3d\|permanent>`, `--json`
`list`	List mailboxes, or messages in a mailbox	`--email-id <id>`, `--cursor <cursor>`, `--json`
`wait`	Wait for incoming messages	`--email-id <id>`, `--timeout <seconds>`, `--interval <seconds>`, `--json`
`read`	Read email message content	`--email-id <id>`, `--message-id <id>`, `--format <text\|html>`, `--json`
`send`	Send email from temporary address	`--email-id <id>`, `--to <address>`, `--subject <text>`, `--content <text>`, `--json`
`delete`	Delete a mailbox, or a single message	`--email-id <id>`, `--message-id <id>`
`skill install`	Install AI agent skill	`--platform <claude\|codex\|all>`

Agent Workflow Example

The CLI is designed to support agent-first automation. Here's a typical workflow:

# Create temporary email and extract details
EMAIL=$(moemail create --domain moemail.app --expiry 1h --json)
EMAIL_ID=$(echo $EMAIL | jq -r '.id')
ADDRESS=$(echo $EMAIL | jq -r '.address')

# Use ADDRESS for signup or service registration...

# Wait for verification email
MSG=$(moemail wait --email-id $EMAIL_ID --timeout 120 --json)
MSG_ID=$(echo $MSG | jq -r '.messageId')

# Read message content
CONTENT=$(moemail read --email-id $EMAIL_ID --message-id $MSG_ID --json)

# Extract verification code from CONTENT...

# Cleanup
moemail delete --email-id $EMAIL_ID

AI Agent Skill

The CLI ships with a built-in skill file that teaches AI agents how to use MoeMail. Install it to your agent platform:

# Auto-detect installed platforms (Claude Code, Codex)
moemail skill install

# Install to a specific platform
moemail skill install --platform claude
moemail skill install --platform codex

# Install to all supported platforms (skip detection)
moemail skill install --platform all

After installation, AI agents will automatically know how to create temporary emails, wait for messages, and read content using the MoeMail CLI.

JSON Output

All commands support --json flag for structured output, making them ideal for agent automation:

Success: Command output in JSON format to stdout
Errors: Error messages written to stderr
Exit Codes:
- 0: Command succeeded
- 1: Runtime error (invalid input, service error)
- 2: Configuration or authentication error (missing api-url/api-key, invalid credentials)

Project Links

Main Project: https://github.com/beilunyang/moemail
Issues & Feedback: https://github.com/beilunyang/moemail/issues

License

MIT

3.4 KiB Raw Blame History