mailsocket-mcp 0.1.0__py3-none-any.whl

mailsocket_mcp/__init__.py

@@ -0,0 +1,12 @@
+"""mailsocket MCP server — expose inboxes + the OTP wait to AI agents.
+
+The actual server lives in :mod:`mailsocket_mcp.server` (imported as a
+submodule, not re-exported under its own name, so ``mailsocket_mcp.server``
+always resolves to the module for ``mailsocket_mcp.server:main``).
+"""
+
+from .server import MAX_WAIT_TIMEOUT, MISSING_KEY_MESSAGE
+
+__version__ = "0.1.0"
+
+__all__ = ["MAX_WAIT_TIMEOUT", "MISSING_KEY_MESSAGE"]

mailsocket_mcp/server.py

@@ -0,0 +1,267 @@
+"""mailsocket MCP server.
+
+Wraps the official :mod:`mailsocket` Python SDK (sprint B1) as MCP tools so an
+AI coding agent can create a throwaway inbox and *block* on the OTP / magic
+link without writing any polling code.
+
+The server speaks MCP over stdio (JSON-RPC). It reads ``MAILSOCKET_API_KEY``
+(and optional ``MAILSOCKET_BASE_URL``) from the environment; the key is never
+logged and never echoed back in a tool error.
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+import re
+from typing import Any, Callable
+from urllib.parse import quote
+
+import mcp.types as types
+from mcp.server.mcpserver import MCPServer
+
+from mailsocket import AuthError, Client, MailsocketError, NotFound, RateLimited, WaitTimeout
+
+__all__ = ["server", "main", "MAX_WAIT_TIMEOUT", "MISSING_KEY_MESSAGE"]
+
+# The headline wait is bounded: an agent can ask for up to 120s, never more.
+DEFAULT_WAIT_TIMEOUT = 60.0
+MAX_WAIT_TIMEOUT = 120.0
+MIN_WAIT_TIMEOUT = 1.0
+
+MISSING_KEY_MESSAGE = (
+    "MAILSOCKET_API_KEY is not set. Export it before starting the server, e.g. "
+    "`MAILSOCKET_API_KEY=ms_live_... mailsocket-mcp`."
+)
+
+server = MCPServer(
+    name="mailsocket",
+    title="mailsocket MCP server",
+    description=(
+        "Ephemeral email inboxes for AI agents: create an inbox, hand the "
+        "address to any signup form, then block on the OTP or magic link."
+    ),
+    version="0.1.0",
+)
+
+
+# -- client construction -----------------------------------------------------
+
+
+class _State:
+    client: Client | None = None
+
+
+def _build_client_from_env() -> Client:
+    """Build an SDK client from the environment, failing clearly without a key."""
+    api_key = os.environ.get("MAILSOCKET_API_KEY", "")
+    if not api_key:
+        raise RuntimeError(MISSING_KEY_MESSAGE)
+    base_url = os.environ.get("MAILSOCKET_BASE_URL") or None
+    if base_url:
+        return Client(api_key, base_url=base_url)
+    return Client(api_key)
+
+
+def _get_client() -> Client:
+    if _State.client is None:
+        _State.client = _build_client_from_env()
+    return _State.client
+
+
+# -- error handling ----------------------------------------------------------
+
+
+def _safe(text: str) -> str:
+    """Redact the API key from any text so it can never leak into a tool error.
+
+    Defense in depth against reformatted keys: redact the literal key, its
+    URL-encoded form, AND any token sharing the ``ms_live_`` credential prefix,
+    so an SDK/network error that url-encodes, wraps, or splits the key around
+    still cannot surface a usable secret to the agent.
+    """
+    key = os.environ.get("MAILSOCKET_API_KEY", "")
+    if key:
+        text = text.replace(key, "***")
+        encoded = quote(key, safe="")
+        if encoded != key:
+            text = text.replace(encoded, "***")
+    # Belt and braces: scrub anything that looks like a live key, even if the
+    # env value was reformatted beyond a literal/url-encoded match.
+    text = re.sub(r"ms_live_[A-Za-z0-9_\-]{4,}", "***", text)
+    return text.strip()
+
+
+def _error_result(exc: BaseException) -> types.CallToolResult:
+    """Turn an SDK exception into a clean MCP tool error (no traceback, no key)."""
+    if isinstance(exc, AuthError):
+        msg = "Authentication failed (HTTP 401): the API key was rejected. Check MAILSOCKET_API_KEY."
+    elif isinstance(exc, WaitTimeout):
+        msg = f"Timed out waiting for a matching message: {_safe(str(exc))}"
+    elif isinstance(exc, NotFound):
+        msg = f"Not found (HTTP 404): {_safe(str(exc))}"
+    elif isinstance(exc, RateLimited):
+        retry = f" Retry after {exc.retry_after:g}s." if exc.retry_after else ""
+        msg = f"Rate limited (HTTP 429): {_safe(str(exc))}.{retry}"
+    elif isinstance(exc, MailsocketError):
+        msg = _safe(str(exc)) or exc.__class__.__name__
+    else:
+        msg = _safe(str(exc)) or exc.__class__.__name__
+    return types.CallToolResult(
+        is_error=True,
+        content=[types.TextContent(type="text", text=msg)],
+    )
+
+
+def _guarded(fn: Callable) -> Callable:
+    """Wrap a tool so SDK errors become clean MCP tool errors."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except Exception as exc:  # noqa: BLE001 — any tool error must be scrubbed
+            # Route EVERY exception (incl. unexpected KeyError/TypeError/ValueError)
+            # through _error_result so the key is scrubbed and no raw traceback
+            # ever reaches the agent. _error_result handles known SDK types
+            # specially and falls back to a class-name-only message otherwise.
+            return _error_result(exc)
+
+    return wrapper
+
+
+def _clamp_timeout(timeout: float) -> float:
+    return max(MIN_WAIT_TIMEOUT, min(float(timeout), MAX_WAIT_TIMEOUT))
+
+
+def _ctx(result, include: tuple[str, ...]) -> dict:
+    """Pick subject/from context off a ``WaitResult`` message."""
+    message = getattr(result, "message", None) or {}
+    ctx: dict = {}
+    for field in include:
+        ctx[field] = message.get(field)
+    return ctx
+
+
+# -- tools -------------------------------------------------------------------
+
+
+@server.tool()
+@_guarded
+def create_inbox(label: str | None = None) -> dict:
+    """Create a new throwaway inbox and return its id and email address.
+
+    Hand the returned ``address`` to whatever signup form sends the code, then
+    call ``wait_for_otp`` (or ``wait_for_link``) with the returned ``id``.
+    """
+    inbox = _get_client().create_inbox(label=label)
+    return {"id": inbox.get("id"), "address": inbox.get("address")}
+
+
+@server.tool()
+@_guarded
+def wait_for_otp(
+    inbox_id: str,
+    timeout: float = DEFAULT_WAIT_TIMEOUT,
+    min_confidence: float = 0.0,
+) -> dict:
+    """Block (bounded) until an OTP arrives in ``inbox_id`` and return it.
+
+    This is the headline tool: no polling loop, no email parsing. ``timeout`` is
+    clamped to [1, 120] seconds. Returns the OTP string, a confidence score and
+    the subject/from of the message it came from. Raises a clean error if no
+    matching message arrives in time.
+    """
+    result = _get_client().wait_for_otp(
+        inbox_id,
+        timeout=_clamp_timeout(timeout),
+        min_confidence=min_confidence,
+    )
+    return {
+        "otp": result.otp,
+        "confidence": result.confidence,
+        **_ctx(result, ("subject", "from")),
+    }
+
+
+@server.tool()
+@_guarded
+def wait_for_link(
+    inbox_id: str,
+    timeout: float = DEFAULT_WAIT_TIMEOUT,
+) -> dict:
+    """Block (bounded) until a magic link arrives in ``inbox_id`` and return it.
+
+    The link is returned, NOT followed — use it (e.g. in a headless browser or
+    ``curl``) however you like. ``timeout`` is clamped to [1, 120] seconds.
+    """
+    result = _get_client().wait_for_link(inbox_id, timeout=_clamp_timeout(timeout))
+    return {
+        "magic_link": result.magic_link,
+        **_ctx(result, ("subject", "from")),
+    }
+
+
+@server.tool()
+@_guarded
+def list_inboxes() -> dict:
+    """List all inboxes owned by the API key."""
+    page = _get_client().list_inboxes()
+    return {"inboxes": list(page.data)}
+
+
+@server.tool()
+@_guarded
+def list_messages(
+    inbox_id: str,
+    has_otp: bool | None = None,
+    subject_contains: str | None = None,
+    sender: str | None = None,
+) -> dict:
+    """List messages in ``inbox_id``, optionally filtered.
+
+    ``has_otp`` keeps only messages with a detected OTP, ``subject_contains``
+    does a case-insensitive substring match on the subject, and ``sender``
+    matches the ``from`` address (maps to the API's ``from`` filter).
+    """
+    page = _get_client().list_messages(
+        inbox_id,
+        has_otp=has_otp,
+        subject_contains=subject_contains,
+        sender=sender,
+    )
+    return {"messages": list(page.data)}
+
+
+@server.tool()
+@_guarded
+def get_latest(inbox_id: str) -> dict:
+    """Return the newest message in ``inbox_id`` (without blocking)."""
+    return _get_client().get_latest(inbox_id)
+
+
+@server.tool()
+@_guarded
+def delete_inbox(inbox_id: str) -> dict:
+    """Delete ``inbox_id`` and everything in it. Use when you are done with it."""
+    _get_client().delete_inbox(inbox_id)
+    return {"deleted": inbox_id}
+
+
+# -- entrypoint --------------------------------------------------------------
+
+
+def main() -> None:
+    """Console entry point: fail fast on a missing key, then serve MCP over stdio."""
+    import sys
+
+    try:
+        _get_client()
+    except RuntimeError as exc:  # missing MAILSOCKET_API_KEY
+        print(_safe(str(exc)), file=sys.stderr)
+        raise SystemExit(2)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

mailsocket_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+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.

mailsocket_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mailsocket_mcp/__init__.py,sha256=NoCQmyrJZC4ESoXpZ65uzonNv6SXLSNJYPSHzbu5k-w,429
+mailsocket_mcp/server.py,sha256=wZim3PwUbwl9mtw2q9GRrz71puTZyX9iXvAXalOPYbc,8616
+mailsocket_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=Eyot-wc-_WRgJlHzEP7XSrVlFqlwaDvM9BYqHpDJVY0,1067
+mailsocket_mcp-0.1.0.dist-info/METADATA,sha256=FUQ3x8rekaiPZTl6JfVTuv18I1-51rGebPbgYe2sH8U,3561
+mailsocket_mcp-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mailsocket_mcp-0.1.0.dist-info/entry_points.txt,sha256=2Jv4dW-IGegpnKX_PJqaSPbncebu3yoSV89-SGQZR2I,62
+mailsocket_mcp-0.1.0.dist-info/top_level.txt,sha256=wzXAJ1o-ulXKdF7Xi3GLmhXKtu5SwTaqfqjA0tBEaCM,15
+mailsocket_mcp-0.1.0.dist-info/RECORD,,

mailsocket_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mailsocket_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mailsocket-mcp = mailsocket_mcp.server:main

mailsocket_mcp-0.1.0.dist-info/licenses/LICENSE

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

mailsocket_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mailsocket_mcp