mailsocket-mcp 0.1.0__tar.gz

mailsocket_mcp-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,78 @@
+# 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/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-0.1.0/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/mailsocket_mcp.egg-info/PKG-INFO

@@ -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/mailsocket_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+mailsocket_mcp/__init__.py
+mailsocket_mcp/server.py
+mailsocket_mcp.egg-info/PKG-INFO
+mailsocket_mcp.egg-info/SOURCES.txt
+mailsocket_mcp.egg-info/dependency_links.txt
+mailsocket_mcp.egg-info/entry_points.txt
+mailsocket_mcp.egg-info/requires.txt
+mailsocket_mcp.egg-info/top_level.txt
+tests/test_server.py

mailsocket_mcp-0.1.0/mailsocket_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mailsocket_mcp-0.1.0/mailsocket_mcp.egg-info/entry_points.txt

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

mailsocket_mcp-0.1.0/mailsocket_mcp.egg-info/requires.txt

@@ -0,0 +1,5 @@
+mailsocket
+mcp<3.0,>=2.0
+
+[dev]
+pytest>=7

mailsocket_mcp-0.1.0/mailsocket_mcp.egg-info/top_level.txt

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

mailsocket_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mailsocket-mcp"
+version = "0.1.0"
+description = "MCP server exposing mailsocket inboxes + wait-for-OTP to AI agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "mailsocket" }]
+keywords = ["mailsocket", "mcp", "email", "otp", "inbox", "magic-link"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Email",
+]
+dependencies = [
+    "mailsocket",       # local sibling SDK — `pip install -e ../python` first
+    "mcp>=2.0,<3.0",
+]
+
+[project.scripts]
+mailsocket-mcp = "mailsocket_mcp.server:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.setuptools]
+packages = ["mailsocket_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "../python"]

mailsocket_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mailsocket_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,327 @@
+"""Offline unit tests for the mailsocket MCP server (fake SDK client, no network)."""
+
+import asyncio
+
+import pytest
+
+import mailsocket_mcp
+from mailsocket import AuthError, MailsocketError, NotFound, RateLimited, WaitTimeout
+from mailsocket_mcp.server import (
+    MAX_WAIT_TIMEOUT,
+    MISSING_KEY_MESSAGE,
+    _State,
+    _build_client_from_env,
+    server,
+)
+
+API_KEY = "ms_live_test1234567890"
+
+OTP_MESSAGE = {
+    "id": "msg_123",
+    "inbox_id": "inbox_abc",
+    "from": "Acme <no-reply@acme.test>",
+    "subject": "Your code",
+    "otp": "123456",
+    "otp_confidence": 0.95,
+    "magic_link": None,
+}
+
+LINK_MESSAGE = {
+    **OTP_MESSAGE,
+    "id": "msg_456",
+    "otp": None,
+    "otp_confidence": None,
+    "magic_link": "https://example.test/go?token=abc",
+}
+
+
+class FakeWaitResult:
+    def __init__(self, otp=None, confidence=None, magic_link=None, message=None):
+        self.otp = otp
+        self.confidence = confidence
+        self.magic_link = magic_link
+        self.message = message or {}
+
+
+class FakeClient:
+    """Scripted stand-in for the SDK Client, recording every call."""
+
+    def __init__(self):
+        self.created = []
+        self.wait_otp_calls = []
+        self.wait_link_calls = []
+        self.list_messages_calls = []
+        self.latest_calls = []
+        self.deleted = []
+        self.wait_otp = None  # (result | exception) scripted per-test
+        self.wait_link = None
+
+    def create_inbox(self, label=None):
+        self.created.append(label)
+        return {"id": "inbox_1", "address": "x@in.inboxpipe.net"}
+
+    def wait_for_otp(self, inbox_id, *, timeout=60.0, min_confidence=0.0, since=0):
+        self.wait_otp_calls.append((inbox_id, timeout, min_confidence))
+        if isinstance(self.wait_otp, Exception):
+            raise self.wait_otp
+        return self.wait_otp
+
+    def wait_for_link(self, inbox_id, *, timeout=60.0, since=0):
+        self.wait_link_calls.append((inbox_id, timeout))
+        if isinstance(self.wait_link, Exception):
+            raise self.wait_link
+        return self.wait_link
+
+    def list_inboxes(self, limit=None, cursor=None):
+        return SimplePage([{"id": "inbox_1", "address": "x@in.inboxpipe.net"}])
+
+    def list_messages(
+        self,
+        inbox_id,
+        has_otp=None,
+        subject_contains=None,
+        sender=None,
+        limit=None,
+        cursor=None,
+    ):
+        self.list_messages_calls.append((inbox_id, has_otp, subject_contains, sender))
+        return SimplePage([OTP_MESSAGE])
+
+    def get_latest(self, inbox_id):
+        self.latest_calls.append(inbox_id)
+        return OTP_MESSAGE
+
+    def delete_inbox(self, inbox_id):
+        self.deleted.append(inbox_id)
+        return None
+
+
+class SimplePage:
+    def __init__(self, data):
+        self.data = data
+
+
+@pytest.fixture
+def fake_client(monkeypatch):
+    """Wire a FakeClient into the server and ensure a key is present."""
+    monkeypatch.setenv("MAILSOCKET_API_KEY", API_KEY)
+    monkeypatch.delenv("MAILSOCKET_BASE_URL", raising=False)
+    _State.client = None
+    fake = FakeClient()
+    _State.client = fake
+    yield fake
+    _State.client = None
+
+
+def call_tool(name, arguments):
+    return asyncio.run(server.call_tool(name, arguments))
+
+
+# -- tools/list --------------------------------------------------------------
+
+
+def test_tools_list_returns_all_tools_with_valid_schemas():
+    tools = asyncio.run(server.list_tools())
+    names = {t.name for t in tools}
+    assert names == {
+        "create_inbox",
+        "wait_for_otp",
+        "wait_for_link",
+        "list_inboxes",
+        "list_messages",
+        "get_latest",
+        "delete_inbox",
+    }
+    by_name = {t.name: t for t in tools}
+    for name, tool in by_name.items():
+        assert tool.description, f"{name} missing a description"
+        schema = tool.input_schema
+        assert schema.get("type") == "object", f"{name} schema is not an object"
+        assert isinstance(schema.get("properties"), dict), f"{name} schema has no properties"
+
+    otp_schema = by_name["wait_for_otp"].input_schema
+    assert set(otp_schema["properties"]) >= {"inbox_id", "timeout", "min_confidence"}
+    assert "inbox_id" in otp_schema.get("required", [])
+    # min_confidence defaults to 0, timeout defaults to 60
+    assert otp_schema["properties"]["timeout"].get("default") == 60
+
+    create_schema = by_name["create_inbox"].input_schema
+    assert "label" in create_schema["properties"]
+
+
+# -- wait_for_otp ------------------------------------------------------------
+
+
+def test_wait_for_otp_returns_otp_and_confidence(fake_client):
+    fake_client.wait_otp = FakeWaitResult(
+        otp="123456", confidence=0.95, message={"subject": "Your code", "from": "Acme <no-reply@acme.test>"}
+    )
+
+    result = call_tool("wait_for_otp", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is False
+    text = result.content[0].text
+    assert '"123456"' in text
+    inbox_id, timeout, min_conf = fake_client.wait_otp_calls[0]
+    assert inbox_id == "inbox_abc"
+    assert timeout == 60
+    assert min_conf == 0.0
+
+
+def test_wait_for_otp_timeout_is_clamped(fake_client):
+    fake_client.wait_otp = FakeWaitResult(otp="123456")
+
+    call_tool("wait_for_otp", {"inbox_id": "inbox_abc", "timeout": 9999})
+
+    _, timeout, _ = fake_client.wait_otp_calls[0]
+    assert timeout == MAX_WAIT_TIMEOUT
+
+    call_tool("wait_for_otp", {"inbox_id": "inbox_abc", "timeout": 0})
+    _, timeout, _ = fake_client.wait_otp_calls[1]
+    assert timeout == 1.0
+
+
+def test_wait_for_otp_wait_timeout_is_clean_error(fake_client):
+    fake_client.wait_otp = WaitTimeout("No matching message arrived within 60s.")
+
+    result = call_tool("wait_for_otp", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is True
+    text = result.content[0].text
+    assert "Traceback" not in text
+    assert API_KEY not in text
+    assert "timed out" in text.lower() or "No matching message" in text
+
+
+# -- wait_for_link -----------------------------------------------------------
+
+
+def test_wait_for_link_returns_magic_link(fake_client):
+    fake_client.wait_link = FakeWaitResult(magic_link="https://example.test/go?token=abc")
+
+    result = call_tool("wait_for_link", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is False
+    assert "https://example.test/go?token=abc" in result.content[0].text
+
+
+# -- create_inbox / list_messages / delete -----------------------------------
+
+
+def test_create_inbox_returns_address_and_id(fake_client):
+    result = call_tool("create_inbox", {"label": "signup"})
+
+    assert result.is_error is False
+    text = result.content[0].text
+    assert '"inbox_1"' in text
+    assert "x@in.inboxpipe.net" in text
+    assert fake_client.created == ["signup"]
+
+
+def test_list_messages_passes_filters_through(fake_client):
+    result = call_tool(
+        "list_messages",
+        {"inbox_id": "inbox_abc", "has_otp": True, "subject_contains": "code", "sender": "acme.test"},
+    )
+
+    assert result.is_error is False
+    inbox_id, has_otp, subject, sender = fake_client.list_messages_calls[0]
+    assert inbox_id == "inbox_abc"
+    assert has_otp is True
+    assert subject == "code"
+    assert sender == "acme.test"
+
+
+def test_get_latest_and_delete_inbox(fake_client):
+    call_tool("get_latest", {"inbox_id": "inbox_abc"})
+    assert fake_client.latest_calls == ["inbox_abc"]
+
+    result = call_tool("delete_inbox", {"inbox_id": "inbox_abc"})
+    assert result.is_error is False
+    assert fake_client.deleted == ["inbox_abc"]
+
+
+# -- error mapping -----------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "exc, expected_substring",
+    [
+        (AuthError("Authentication required.", code="authentication_required"), "Authentication failed"),
+        (NotFound("Resource not found.", code="not_found"), "Not found"),
+        (RateLimited("Rate limit exceeded.", retry_after=7.0), "Rate limited"),
+    ],
+)
+def test_sdk_errors_map_to_clean_tool_errors(fake_client, exc, expected_substring):
+    fake_client.wait_otp = exc
+
+    result = call_tool("wait_for_otp", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is True
+    text = result.content[0].text
+    assert expected_substring in text
+    assert "Traceback" not in text
+    assert API_KEY not in text
+
+
+def test_api_key_never_appears_in_any_error(fake_client):
+    # The SDK error message itself embeds the key — the server must redact it.
+    fake_client.wait_otp = WaitTimeout(f"failed with key {API_KEY} on inbox")
+
+    result = call_tool("wait_for_otp", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is True
+    text = result.content[0].text
+    assert API_KEY not in text
+    assert "***" in text
+
+
+# -- startup / missing key ---------------------------------------------------
+
+
+def test_missing_api_key_raises_clear_startup_error(monkeypatch):
+    monkeypatch.delenv("MAILSOCKET_API_KEY", raising=False)
+    _State.client = None
+
+    with pytest.raises(RuntimeError) as exc_info:
+        _build_client_from_env()
+
+    assert MISSING_KEY_MESSAGE in str(exc_info.value)
+    assert "MAILSOCKET_API_KEY" in str(exc_info.value)
+
+
+def test_version_exported():
+    assert hasattr(mailsocket_mcp, "__version__")
+
+
+# -- ocr-found HIGH: reformatted-key redaction + broadened exception scrub ----
+
+
+def test_safe_redacts_url_encoded_and_prefixed_keys(fake_client):
+    from urllib.parse import quote
+
+    from mailsocket_mcp.server import _safe
+
+    # literal
+    assert API_KEY not in _safe(f"boom {API_KEY} boom")
+    # url-encoded form (e.g. key appearing inside a URL in an error)
+    enc = quote(API_KEY, safe="")
+    assert API_KEY not in _safe(f"GET /x?k={enc} failed")
+    assert enc not in _safe(f"GET /x?k={enc} failed")
+    # a DIFFERENT but ms_live_-shaped token is still scrubbed (defense in depth)
+    other = "ms_live_SOMEOTHERSECRET99"
+    assert other not in _safe(f"leaked {other} here")
+    assert "***" in _safe(f"leaked {other} here")
+
+
+def test_unexpected_exception_is_scrubbed_not_raw_traceback(fake_client):
+    # An unexpected error type (not a MailsocketError/RuntimeError) that embeds
+    # the key must still become a clean, key-free tool error — never a raw raise.
+    fake_client.wait_otp = KeyError(f"weird {API_KEY} boom")
+
+    result = call_tool("wait_for_otp", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is True
+    text = result.content[0].text
+    assert API_KEY not in text
+    assert "Traceback" not in text