mailsocket-mcp 0.2.2__tar.gz → 0.2.3__tar.gz

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket-mcp
-Version: 0.2.2
+Version: 0.2.3
 Summary: MCP server exposing mailsocket inboxes + wait-for-OTP to AI agents.
 Author: mailsocket
 License-Expression: MIT
@@ -39,8 +39,8 @@ no second HTTP client, no re-implemented polling.
 | 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: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from |
-| `wait_for_link(inbox_id, timeout?=60)` | the extracted magic link (returned, *not* followed) |
+| `wait_for_otp(inbox_id, timeout?=60, min_confidence?=0, since?)` | **the headline** — blocks (bounded: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from/id/received_at |
+| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at |
 | `list_inboxes(limit?, cursor?)` | one page of inboxes owned by the key (server default page size 25) + `next_cursor`/`has_more` |
 | `list_messages(inbox_id, has_otp?, subject_contains?, sender?, limit?, cursor?)` | one page of messages, optionally filtered (server default page size 25) + `next_cursor`/`has_more` |
 | `get_latest(inbox_id)` | the newest message, without blocking |
@@ -50,6 +50,18 @@ 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.
 
+### Reusing an inbox
+
+`create_inbox` needs no `since` — a fresh inbox only ever has new messages.
+But if you reuse an existing inbox (e.g. to request a second OTP/link), pass
+`since` to `wait_for_otp`/`wait_for_link`: otherwise the wait can match the
+OLDEST retained message instead of the new one you just triggered. Pass
+either the time right before you triggered the new email (ISO8601 or unix
+seconds), or the `id` of the last message you saw (`msg_...`, meaning "only
+messages after that one") — both tools return `id`/`received_at` on the
+matched message so you can chain `since=<id>` into the next call on that same
+inbox.
+
 ## Requirements
 
 - Python 3.10+
@@ -183,6 +195,7 @@ remote-transport tests talk to a local fake upstream on `127.0.0.1`.
 
 ## Changelog
 
+- **0.2.3** — `wait_for_otp` / `wait_for_link` accept an optional `since` (ISO8601, unix seconds or a message id) so a reused inbox returns the NEW code; results include the message `id` and `received_at`.
 - **0.2.2** — depends on `mailsocket>=0.1.3` (stricter `_seg` id validation in the underlying Python SDK).
 
 <!-- mcp-name: app.mailsocket/mailsocket-mcp -->

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.2.3}/README.md

@@ -12,8 +12,8 @@ no second HTTP client, no re-implemented polling.
 | 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: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from |
-| `wait_for_link(inbox_id, timeout?=60)` | the extracted magic link (returned, *not* followed) |
+| `wait_for_otp(inbox_id, timeout?=60, min_confidence?=0, since?)` | **the headline** — blocks (bounded: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from/id/received_at |
+| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at |
 | `list_inboxes(limit?, cursor?)` | one page of inboxes owned by the key (server default page size 25) + `next_cursor`/`has_more` |
 | `list_messages(inbox_id, has_otp?, subject_contains?, sender?, limit?, cursor?)` | one page of messages, optionally filtered (server default page size 25) + `next_cursor`/`has_more` |
 | `get_latest(inbox_id)` | the newest message, without blocking |
@@ -23,6 +23,18 @@ 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.
 
+### Reusing an inbox
+
+`create_inbox` needs no `since` — a fresh inbox only ever has new messages.
+But if you reuse an existing inbox (e.g. to request a second OTP/link), pass
+`since` to `wait_for_otp`/`wait_for_link`: otherwise the wait can match the
+OLDEST retained message instead of the new one you just triggered. Pass
+either the time right before you triggered the new email (ISO8601 or unix
+seconds), or the `id` of the last message you saw (`msg_...`, meaning "only
+messages after that one") — both tools return `id`/`received_at` on the
+matched message so you can chain `since=<id>` into the next call on that same
+inbox.
+
 ## Requirements
 
 - Python 3.10+
@@ -156,6 +168,7 @@ remote-transport tests talk to a local fake upstream on `127.0.0.1`.
 
 ## Changelog
 
+- **0.2.3** — `wait_for_otp` / `wait_for_link` accept an optional `since` (ISO8601, unix seconds or a message id) so a reused inbox returns the NEW code; results include the message `id` and `received_at`.
 - **0.2.2** — depends on `mailsocket>=0.1.3` (stricter `_seg` id validation in the underlying Python SDK).
 
 <!-- mcp-name: app.mailsocket/mailsocket-mcp -->

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.2.3}/mailsocket_mcp/server.py

@@ -52,7 +52,7 @@ __all__ = [
 # Canonical version, re-exported as ``mailsocket_mcp.__version__`` (see
 # __init__.py). Defined here, not in __init__.py, because __init__.py imports
 # this module at package-load time and a circular self-import would break.
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 # The headline wait is bounded: an agent can request up to the transport's
 # ceiling as the overall deadline (clamped), though transport overhead can push
@@ -461,6 +461,7 @@ def wait_for_otp(
     inbox_id: str,
     timeout: float = DEFAULT_WAIT_TIMEOUT,
     min_confidence: float = 0.0,
+    since: str | int | float | None = None,
 ) -> dict:
     """Block (bounded) until an OTP arrives in ``inbox_id`` and return it.
 
@@ -477,21 +478,35 @@ def wait_for_otp(
     slightly after the ceiling in practice. On a timeout just call it again.
     ``min_confidence`` filters out low-confidence OTP extractions.
 
+    ``since`` (optional) only matches messages that arrived after this point:
+    an ISO8601 timestamp, unix seconds, or a message id (``msg_...``, meaning
+    "only messages after that one"; an unknown id falls back to the oldest
+    message, so prefer a timestamp if unsure). A fresh inbox straight from
+    ``create_inbox`` needs nothing here — the default already matches
+    anything in it. When REUSING an inbox for a second code, pass either the
+    time just before you triggered this email, or the ``id`` of the last
+    message you saw, so you get the NEW code instead of the oldest one still
+    retained in the inbox.
+
     Side effects: none beyond the long-poll HTTP call(s) needed to satisfy the
     wait (``openWorldHint`` — it talks to the live mailsocket API and blocks
     for up to ``timeout`` seconds). Returns the OTP string, a confidence
-    score, and the subject/from of the matching message. Raises a clean tool
-    error (``WaitTimeout``) if nothing matching arrives before the deadline.
+    score, the subject/from of the matching message, and its ``id`` /
+    ``received_at`` (chain ``since=<id>`` into the next call on this inbox).
+    Raises a clean tool error (``WaitTimeout``) if nothing matching arrives
+    before the deadline.
     """
+    kwargs = {} if since is None else {"since": since}
     result = _get_client().wait_for_otp(
         inbox_id,
         timeout=_clamp_timeout(timeout),
         min_confidence=min_confidence,
+        **kwargs,
     )
     return {
         "otp": result.otp,
         "confidence": result.confidence,
-        **_ctx(result, ("subject", "from")),
+        **_ctx(result, ("subject", "from", "id", "received_at")),
     }
 
 
@@ -502,6 +517,7 @@ def wait_for_otp(
 def wait_for_link(
     inbox_id: str,
     timeout: float = DEFAULT_WAIT_TIMEOUT,
+    since: str | int | float | None = None,
 ) -> dict:
     """Block (bounded) until a magic link arrives in ``inbox_id`` and return it.
 
@@ -518,15 +534,28 @@ def wait_for_link(
     return slightly after the ceiling in practice. On a timeout just call it
     again.
 
+    ``since`` (optional) only matches messages that arrived after this point:
+    an ISO8601 timestamp, unix seconds, or a message id (``msg_...``, meaning
+    "only messages after that one"; an unknown id falls back to the oldest
+    message, so prefer a timestamp if unsure). A fresh inbox straight from
+    ``create_inbox`` needs nothing here — the default already matches
+    anything in it. When REUSING an inbox for a second link, pass either the
+    time just before you triggered this email, or the ``id`` of the last
+    message you saw, so you get the NEW link instead of the oldest one still
+    retained in the inbox.
+
     Side effects: none beyond the long-poll HTTP call(s) needed to satisfy the
     wait (``openWorldHint`` — it talks to the live mailsocket API and blocks
-    for up to ``timeout`` seconds). Raises a clean tool error (``WaitTimeout``)
-    if no link arrives before the deadline.
+    for up to ``timeout`` seconds). Returns the magic link, the subject/from
+    of the matching message, and its ``id`` / ``received_at`` (chain
+    ``since=<id>`` into the next call on this inbox). Raises a clean tool
+    error (``WaitTimeout``) if no link arrives before the deadline.
     """
-    result = _get_client().wait_for_link(inbox_id, timeout=_clamp_timeout(timeout))
+    kwargs = {} if since is None else {"since": since}
+    result = _get_client().wait_for_link(inbox_id, timeout=_clamp_timeout(timeout), **kwargs)
     return {
         "magic_link": result.magic_link,
-        **_ctx(result, ("subject", "from")),
+        **_ctx(result, ("subject", "from", "id", "received_at")),
     }
 
 

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.2.3}/mailsocket_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket-mcp
-Version: 0.2.2
+Version: 0.2.3
 Summary: MCP server exposing mailsocket inboxes + wait-for-OTP to AI agents.
 Author: mailsocket
 License-Expression: MIT
@@ -39,8 +39,8 @@ no second HTTP client, no re-implemented polling.
 | 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: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from |
-| `wait_for_link(inbox_id, timeout?=60)` | the extracted magic link (returned, *not* followed) |
+| `wait_for_otp(inbox_id, timeout?=60, min_confidence?=0, since?)` | **the headline** — blocks (bounded: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from/id/received_at |
+| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at |
 | `list_inboxes(limit?, cursor?)` | one page of inboxes owned by the key (server default page size 25) + `next_cursor`/`has_more` |
 | `list_messages(inbox_id, has_otp?, subject_contains?, sender?, limit?, cursor?)` | one page of messages, optionally filtered (server default page size 25) + `next_cursor`/`has_more` |
 | `get_latest(inbox_id)` | the newest message, without blocking |
@@ -50,6 +50,18 @@ 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.
 
+### Reusing an inbox
+
+`create_inbox` needs no `since` — a fresh inbox only ever has new messages.
+But if you reuse an existing inbox (e.g. to request a second OTP/link), pass
+`since` to `wait_for_otp`/`wait_for_link`: otherwise the wait can match the
+OLDEST retained message instead of the new one you just triggered. Pass
+either the time right before you triggered the new email (ISO8601 or unix
+seconds), or the `id` of the last message you saw (`msg_...`, meaning "only
+messages after that one") — both tools return `id`/`received_at` on the
+matched message so you can chain `since=<id>` into the next call on that same
+inbox.
+
 ## Requirements
 
 - Python 3.10+
@@ -183,6 +195,7 @@ remote-transport tests talk to a local fake upstream on `127.0.0.1`.
 
 ## Changelog
 
+- **0.2.3** — `wait_for_otp` / `wait_for_link` accept an optional `since` (ISO8601, unix seconds or a message id) so a reused inbox returns the NEW code; results include the message `id` and `received_at`.
 - **0.2.2** — depends on `mailsocket>=0.1.3` (stricter `_seg` id validation in the underlying Python SDK).
 
 <!-- mcp-name: app.mailsocket/mailsocket-mcp -->

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mailsocket-mcp"
-version = "0.2.2"
+version = "0.2.3"
 description = "MCP server exposing mailsocket inboxes + wait-for-OTP to AI agents."
 readme = "README.md"
 requires-python = ">=3.10"

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.2.3}/tests/test_server.py

@@ -62,13 +62,13 @@ class FakeClient:
         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))
+        self.wait_otp_calls.append((inbox_id, timeout, min_confidence, since))
         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))
+        self.wait_link_calls.append((inbox_id, timeout, since))
         if isinstance(self.wait_link, Exception):
             raise self.wait_link
         return self.wait_link
@@ -233,10 +233,11 @@ def test_wait_for_otp_returns_otp_and_confidence(fake_client):
     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]
+    inbox_id, timeout, min_conf, since = fake_client.wait_otp_calls[0]
     assert inbox_id == "inbox_abc"
     assert timeout == 60
     assert min_conf == 0.0
+    assert since == 0  # absent -> SDK default unchanged
 
 
 def test_wait_for_otp_timeout_is_clamped(fake_client):
@@ -244,14 +245,44 @@ def test_wait_for_otp_timeout_is_clamped(fake_client):
 
     call_tool("wait_for_otp", {"inbox_id": "inbox_abc", "timeout": 9999})
 
-    _, timeout, _ = fake_client.wait_otp_calls[0]
+    _, 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]
+    _, timeout, _, _ = fake_client.wait_otp_calls[1]
     assert timeout == 1.0
 
 
+def test_wait_for_otp_since_passed_through(fake_client):
+    fake_client.wait_otp = FakeWaitResult(otp="123456")
+
+    call_tool("wait_for_otp", {"inbox_id": "inbox_abc", "since": "msg_111"})
+
+    inbox_id, _, _, since = fake_client.wait_otp_calls[0]
+    assert inbox_id == "inbox_abc"
+    assert since == "msg_111"
+
+
+def test_wait_for_otp_result_carries_id_and_received_at(fake_client):
+    fake_client.wait_otp = FakeWaitResult(
+        otp="123456",
+        confidence=0.95,
+        message={
+            "subject": "Your code",
+            "from": "Acme <no-reply@acme.test>",
+            "id": "msg_999",
+            "received_at": "2024-01-01T00:00:00Z",
+        },
+    )
+
+    result = call_tool("wait_for_otp", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is False
+    text = result.content[0].text
+    assert '"msg_999"' in text
+    assert '"2024-01-01T00:00:00Z"' in text
+
+
 def test_wait_for_otp_wait_timeout_is_clean_error(fake_client):
     fake_client.wait_otp = WaitTimeout("No matching message arrived within 60s.")
 
@@ -274,6 +305,38 @@ def test_wait_for_link_returns_magic_link(fake_client):
 
     assert result.is_error is False
     assert "https://example.test/go?token=abc" in result.content[0].text
+    inbox_id, timeout, since = fake_client.wait_link_calls[0]
+    assert inbox_id == "inbox_abc"
+    assert since == 0  # absent -> SDK default unchanged
+
+
+def test_wait_for_link_since_passed_through(fake_client):
+    fake_client.wait_link = FakeWaitResult(magic_link="https://example.test/go?token=abc")
+
+    call_tool("wait_for_link", {"inbox_id": "inbox_abc", "since": "2024-01-01T00:00:00Z"})
+
+    inbox_id, _, since = fake_client.wait_link_calls[0]
+    assert inbox_id == "inbox_abc"
+    assert since == "2024-01-01T00:00:00Z"
+
+
+def test_wait_for_link_result_carries_id_and_received_at(fake_client):
+    fake_client.wait_link = FakeWaitResult(
+        magic_link="https://example.test/go?token=abc",
+        message={
+            "subject": "Sign in",
+            "from": "Acme <no-reply@acme.test>",
+            "id": "msg_777",
+            "received_at": "2024-02-02T00:00:00Z",
+        },
+    )
+
+    result = call_tool("wait_for_link", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is False
+    text = result.content[0].text
+    assert '"msg_777"' in text
+    assert '"2024-02-02T00:00:00Z"' in text
 
 
 # -- create_inbox / list_messages / delete -----------------------------------
@@ -365,13 +428,13 @@ def test_version_exported():
 
 
 def test_metadata_consistency_across_files():
-    """Versions match everywhere: MCP 0.2.2 (pyproject, server.json, __version__)
+    """Versions match everywhere: MCP 0.2.3 (pyproject, server.json, __version__)
     and its Python SDK sibling 0.1.3 (pyproject, __version__, user agent)."""
     import tomllib
     from pathlib import Path
 
     root = Path(__file__).resolve().parents[1]
-    expected = "0.2.2"
+    expected = "0.2.3"
     expected_sdk = "0.1.3"
 
     pyproject = tomllib.loads((root / "pyproject.toml").read_text())