Metadata-Version: 2.4
Name: mailsocket-mcp
Version: 0.1.0
Summary: MCP server exposing mailsocket inboxes + wait-for-OTP to AI agents.
Author: mailsocket
License-Expression: MIT
Keywords: mailsocket,mcp,email,otp,inbox,magic-link
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mailsocket
Requires-Dist: mcp<3.0,>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# mailsocket — MCP server

An [MCP](https://modelcontextprotocol.io) server that exposes
[mailsocket](https://mailsocket.app) to AI coding agents as native tools, so an
agent can create a throwaway inbox and **block on the OTP or magic link**
without writing any polling code. It wraps the
[Python SDK](../python/) — no second HTTP client, no re-implemented polling.

## What it does

| Tool | What the agent gets |
| --- | --- |
| `create_inbox(label?)` | a fresh inbox `id` + `address` |
| `wait_for_otp(inbox_id, timeout?=60, min_confidence?=0)` | **the headline** — blocks (bounded, clamped to 120s) and returns the OTP string + confidence + subject/from |
| `wait_for_link(inbox_id, timeout?=60)` | the extracted magic link (returned, *not* followed) |
| `list_inboxes()` | every inbox owned by the key |
| `list_messages(inbox_id, has_otp?, subject_contains?, from?)` | messages, optionally filtered |
| `get_latest(inbox_id)` | the newest message, without blocking |
| `delete_inbox(inbox_id)` | remove an inbox when done |

Errors from the SDK (`AuthError` / `NotFound` / `RateLimited` / `WaitTimeout`)
are turned into clean MCP tool errors — no stack traces, and the API key is
never echoed back.

## Install

```bash
# from this directory, with the repo's backend venv (or your own):
/Users/tuki/MailBridge/backend/.venv/bin/python -m pip install mcp          # official MCP SDK
/Users/tuki/MailBridge/backend/.venv/bin/python -m pip install -e ../python # local mailsocket SDK
/Users/tuki/MailBridge/backend/.venv/bin/python -m pip install -e .         # this server (mailsocket-mcp)
```

## Run

```bash
export MAILSOCKET_API_KEY="ms_live_..."
# optional: export MAILSOCKET_BASE_URL="https://dash.mailsocket.app/api/v1"
mailsocket-mcp
```

It reads `MAILSOCKET_API_KEY` (and optional `MAILSOCKET_BASE_URL`) from the
environment. If the key is missing it exits with a clear message and status 2;
the key is never logged.

## Register with an MCP client

The server is a plain stdio MCP server, so it works with any MCP-compatible
client. Point your client's `mcpServers` config at the `mailsocket-mcp`
executable and pass the key through the environment:

```json
{
  "mcpServers": {
    "mailsocket": {
      "command": "mailsocket-mcp",
      "args": [],
      "env": {
        "MAILSOCKET_API_KEY": "ms_live_...",
        "MAILSOCKET_BASE_URL": "https://dash.mailsocket.app/api/v1"
      }
    }
  }
}
```

If `mailsocket-mcp` is not on the client's `PATH`, use the venv's full path for
`command`, e.g. `/Users/tuki/MailBridge/backend/.venv/bin/mailsocket-mcp`.

## Develop

```bash
cd sdks/mcp
/Users/tuki/MailBridge/backend/.venv/bin/python -m pytest -q
```

Tests are fully offline — the SDK client is faked, so nothing touches the live
API.
