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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket-mcp
-Version: 0.2.3
+Version: 0.4.0
 Summary: MCP server exposing mailsocket inboxes + wait-for-OTP to AI agents.
 Author: mailsocket
 License-Expression: MIT
@@ -19,7 +19,7 @@ Classifier: Topic :: Communications :: Email
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mailsocket>=0.1.3
+Requires-Dist: mailsocket>=0.3.0
 Requires-Dist: mcp<3.0,>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
@@ -39,11 +39,12 @@ 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, 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 |
+| `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. Default `since` omitted: only messages arriving after this call are matched. |
+| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at. Default `since` omitted: only messages arriving after this call are matched. |
 | `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 |
+| `send_test_code(inbox_id)` | puts one sample OTP email straight into the inbox (no mail server) and returns its `message_id` + `sent_at`, so you can check the wait loop without real email. 5 per inbox / 20 per account per hour. |
 | `delete_inbox(inbox_id)` | remove an inbox when done |
 
 Errors from the SDK (`AuthError` / `NotFound` / `RateLimited` / `WaitTimeout`)
@@ -53,14 +54,26 @@ 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.
+By default, `wait_for_otp`/`wait_for_link` omit `since` entirely, so the
+server matches only messages arriving AFTER the call (the request start
+time). But if you reuse an existing inbox (e.g. to request a second
+OTP/link), pass `since` explicitly: otherwise a call with no `since` will
+correctly ignore anything already sitting in the inbox, which is right for
+most reuse, but if you actually WANT to catch a code that already arrived
+before you called the tool, 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.
+
+### Trying the loop without real email
+
+`send_test_code` does not go through the mail server, so the code is
+already in the inbox when the tool returns. Take a cutoff first: the `id`
+from `get_latest` (or `since=0` if the inbox is empty), or the current time.
+Then call `send_test_code(inbox_id)`, then
+`wait_for_otp(inbox_id, since=<that cutoff>)`. Without `since` the wait only
+sees mail that arrives during the wait, so it would miss the test code.
 
 ## Requirements
 
@@ -195,6 +208,20 @@ remote-transport tests talk to a local fake upstream on `127.0.0.1`.
 
 ## Changelog
 
+- **0.4.0** — new `send_test_code(inbox_id)` tool (stdio and the hosted
+  remote server, under the same per-key caps as the other non-wait tools):
+  puts one sample OTP email into your own inbox without going through the
+  mail server. Requires `mailsocket>=0.3.0` (`Client.send_test_code`).
+- **0.3.0** — BEHAVIOUR CHANGE (via `mailsocket>=0.2.0`): `wait_for_otp` /
+  `wait_for_link` now omit `since` by default instead of forwarding `0`
+  ("any message already in the inbox"). The old default could return a
+  STALE OTP/link already sitting in a reused inbox; the new default matches
+  only messages arriving after the call. Pass `since=0` explicitly to keep
+  the old behaviour.
+  Hosted server (mcp.mailsocket.app, deployed from the repo, no new PyPI
+  release): per-key concurrent waits raised 3 → 10 (= the Pro plan cap; the
+  API still enforces each plan's own cap) and the shared wait pool 16 → 32,
+  following the backend's raised wait capacity (global 64).
 - **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).
 

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

@@ -12,11 +12,12 @@ 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, 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 |
+| `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. Default `since` omitted: only messages arriving after this call are matched. |
+| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at. Default `since` omitted: only messages arriving after this call are matched. |
 | `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 |
+| `send_test_code(inbox_id)` | puts one sample OTP email straight into the inbox (no mail server) and returns its `message_id` + `sent_at`, so you can check the wait loop without real email. 5 per inbox / 20 per account per hour. |
 | `delete_inbox(inbox_id)` | remove an inbox when done |
 
 Errors from the SDK (`AuthError` / `NotFound` / `RateLimited` / `WaitTimeout`)
@@ -26,14 +27,26 @@ 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.
+By default, `wait_for_otp`/`wait_for_link` omit `since` entirely, so the
+server matches only messages arriving AFTER the call (the request start
+time). But if you reuse an existing inbox (e.g. to request a second
+OTP/link), pass `since` explicitly: otherwise a call with no `since` will
+correctly ignore anything already sitting in the inbox, which is right for
+most reuse, but if you actually WANT to catch a code that already arrived
+before you called the tool, 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.
+
+### Trying the loop without real email
+
+`send_test_code` does not go through the mail server, so the code is
+already in the inbox when the tool returns. Take a cutoff first: the `id`
+from `get_latest` (or `since=0` if the inbox is empty), or the current time.
+Then call `send_test_code(inbox_id)`, then
+`wait_for_otp(inbox_id, since=<that cutoff>)`. Without `since` the wait only
+sees mail that arrives during the wait, so it would miss the test code.
 
 ## Requirements
 
@@ -168,6 +181,20 @@ remote-transport tests talk to a local fake upstream on `127.0.0.1`.
 
 ## Changelog
 
+- **0.4.0** — new `send_test_code(inbox_id)` tool (stdio and the hosted
+  remote server, under the same per-key caps as the other non-wait tools):
+  puts one sample OTP email into your own inbox without going through the
+  mail server. Requires `mailsocket>=0.3.0` (`Client.send_test_code`).
+- **0.3.0** — BEHAVIOUR CHANGE (via `mailsocket>=0.2.0`): `wait_for_otp` /
+  `wait_for_link` now omit `since` by default instead of forwarding `0`
+  ("any message already in the inbox"). The old default could return a
+  STALE OTP/link already sitting in a reused inbox; the new default matches
+  only messages arriving after the call. Pass `since=0` explicitly to keep
+  the old behaviour.
+  Hosted server (mcp.mailsocket.app, deployed from the repo, no new PyPI
+  release): per-key concurrent waits raised 3 → 10 (= the Pro plan cap; the
+  API still enforces each plan's own cap) and the shared wait pool 16 → 32,
+  following the backend's raised wait capacity (global 64).
 - **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).
 

{mailsocket_mcp-0.2.3 → mailsocket_mcp-0.4.0}/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.3"
+__version__ = "0.4.0"
 
 # 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
@@ -66,16 +66,23 @@ MIN_WAIT_TIMEOUT = 1.0
 
 # Bounded worker-thread concurrency for the (sync, urllib) SDK calls. Waits and
 # everything else get SEPARATE pools so long waits can never starve
-# list/create calls. WAIT matches the backend's global WaitCapacity (16). A
+# list/create calls. WAIT is half the backend's global WaitCapacity (64): the
+# hosted MCP is ONE client of that pool, so it must stay below it and can
+# never fill the backend's wait slots on its own (direct API callers keep the
+# other half). WAIT + OTHER (48) must stay <= uvicorn --limit-concurrency (64)
+# in docker-compose.yml / deploy/mcp/Dockerfile — pinned by test_remote. A
 # caller that cannot get a slot within LIMITER_QUEUE_TIMEOUT gets a clean
 # "busy, retry" tool error instead of queueing unboundedly.
-WAIT_CONCURRENCY = 16
+WAIT_CONCURRENCY = 32
 OTHER_CONCURRENCY = 16
 LIMITER_QUEUE_TIMEOUT = 10.0
 # Per-key fairness (remote mode only): one key may hold at most this many
 # in-flight calls of each kind, so it can never monopolise the shared pools
-# above. Over the cap → an immediate clean tool error (no queueing).
-PER_KEY_WAIT_CONCURRENCY = 3
+# above. Over the cap → an immediate clean tool error (no queueing). The wait
+# cap equals the Pro plan's backend cap (10) so the hosted MCP never limits a
+# paying key below its plan; the backend still enforces each plan's own cap
+# (Free 2, Pro 10, ...) and answers 429 too_many_wait_requests above it.
+PER_KEY_WAIT_CONCURRENCY = 10
 PER_KEY_OTHER_CONCURRENCY = 8
 
 MISSING_KEY_MESSAGE = (
@@ -277,7 +284,7 @@ def _error_result(exc: BaseException) -> types.CallToolResult:
         msg = f"Not found (HTTP 404): {_safe(str(exc), key)}"
     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), key)}.{retry}"
+        msg = f"Rate limited (HTTP 429): {_safe(str(exc), key).rstrip('.')}.{retry}"
     elif isinstance(exc, _Busy):
         msg = str(exc)
     elif isinstance(exc, MailsocketError):
@@ -481,12 +488,13 @@ def wait_for_otp(
     ``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.
+    message, so prefer a timestamp if unsure). Omitted (the default), the
+    server matches only messages that arrive during this call — the right
+    choice for a fresh inbox from ``create_inbox``. When REUSING an inbox for
+    a second code and you want to catch one that already arrived before this
+    call, 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
+    missing it.
 
     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
@@ -537,12 +545,13 @@ def wait_for_link(
     ``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.
+    message, so prefer a timestamp if unsure). Omitted (the default), the
+    server matches only messages that arrive during this call — the right
+    choice for a fresh inbox from ``create_inbox``. When REUSING an inbox for
+    a second link and you want to catch one that already arrived before this
+    call, 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
+    missing it.
 
     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
@@ -652,6 +661,46 @@ def get_latest(inbox_id: str) -> dict:
     return _get_client().get_latest(inbox_id)
 
 
+@server.tool(
+    annotations=types.ToolAnnotations(
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
+@_guarded()
+def send_test_code(inbox_id: str) -> dict:
+    """Put one sample OTP email (a random 6-digit code) into ``inbox_id``.
+
+    Use this to check the wait loop end to end when you have no real email
+    to trigger. It does NOT go through the mail server: the message is
+    stored and parsed exactly like real inbound mail, so ``wait_for_otp``
+    returns it.
+
+    How to pair it with the wait (one call at a time, no concurrency):
+    BEFORE calling this tool, take a cutoff, either the ``id`` of the newest
+    message (``get_latest``; use ``since=0`` if the inbox is empty) or the
+    current time (ISO8601 or unix seconds). Then call ``send_test_code``,
+    then ``wait_for_otp(inbox_id, since=<that cutoff>)``. Without ``since``,
+    the wait only matches mail arriving during the wait itself and would
+    miss this code. Do not pass the returned ``message_id`` as ``since``:
+    that means "after this message" and skips it.
+
+    Limits: 5 per inbox and 20 per account per hour (shared with the
+    dashboard "Send a test code" button); over that, a clean rate-limit
+    error says when to retry. A disabled inbox, or an unknown/deleted/
+    foreign inbox id, returns a clean tool error and nothing is charged.
+
+    Side effects: creates one message in the inbox (counts toward monthly
+    message usage and fires the inbox's webhook, like real mail). Makes one
+    network call to the mailsocket API (``openWorldHint``). Returns
+    ``message_id`` and ``sent_at`` of the new message.
+    """
+    data = _get_client().send_test_code(inbox_id)
+    return {"message_id": data.get("message_id"), "sent_at": data.get("sent_at")}
+
+
 @server.tool(
     annotations=types.ToolAnnotations(destructiveHint=True, openWorldHint=True),
 )

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket-mcp
-Version: 0.2.3
+Version: 0.4.0
 Summary: MCP server exposing mailsocket inboxes + wait-for-OTP to AI agents.
 Author: mailsocket
 License-Expression: MIT
@@ -19,7 +19,7 @@ Classifier: Topic :: Communications :: Email
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mailsocket>=0.1.3
+Requires-Dist: mailsocket>=0.3.0
 Requires-Dist: mcp<3.0,>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
@@ -39,11 +39,12 @@ 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, 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 |
+| `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. Default `since` omitted: only messages arriving after this call are matched. |
+| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at. Default `since` omitted: only messages arriving after this call are matched. |
 | `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 |
+| `send_test_code(inbox_id)` | puts one sample OTP email straight into the inbox (no mail server) and returns its `message_id` + `sent_at`, so you can check the wait loop without real email. 5 per inbox / 20 per account per hour. |
 | `delete_inbox(inbox_id)` | remove an inbox when done |
 
 Errors from the SDK (`AuthError` / `NotFound` / `RateLimited` / `WaitTimeout`)
@@ -53,14 +54,26 @@ 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.
+By default, `wait_for_otp`/`wait_for_link` omit `since` entirely, so the
+server matches only messages arriving AFTER the call (the request start
+time). But if you reuse an existing inbox (e.g. to request a second
+OTP/link), pass `since` explicitly: otherwise a call with no `since` will
+correctly ignore anything already sitting in the inbox, which is right for
+most reuse, but if you actually WANT to catch a code that already arrived
+before you called the tool, 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.
+
+### Trying the loop without real email
+
+`send_test_code` does not go through the mail server, so the code is
+already in the inbox when the tool returns. Take a cutoff first: the `id`
+from `get_latest` (or `since=0` if the inbox is empty), or the current time.
+Then call `send_test_code(inbox_id)`, then
+`wait_for_otp(inbox_id, since=<that cutoff>)`. Without `since` the wait only
+sees mail that arrives during the wait, so it would miss the test code.
 
 ## Requirements
 
@@ -195,6 +208,20 @@ remote-transport tests talk to a local fake upstream on `127.0.0.1`.
 
 ## Changelog
 
+- **0.4.0** — new `send_test_code(inbox_id)` tool (stdio and the hosted
+  remote server, under the same per-key caps as the other non-wait tools):
+  puts one sample OTP email into your own inbox without going through the
+  mail server. Requires `mailsocket>=0.3.0` (`Client.send_test_code`).
+- **0.3.0** — BEHAVIOUR CHANGE (via `mailsocket>=0.2.0`): `wait_for_otp` /
+  `wait_for_link` now omit `since` by default instead of forwarding `0`
+  ("any message already in the inbox"). The old default could return a
+  STALE OTP/link already sitting in a reused inbox; the new default matches
+  only messages arriving after the call. Pass `since=0` explicitly to keep
+  the old behaviour.
+  Hosted server (mcp.mailsocket.app, deployed from the repo, no new PyPI
+  release): per-key concurrent waits raised 3 → 10 (= the Pro plan cap; the
+  API still enforces each plan's own cap) and the shared wait pool 16 → 32,
+  following the backend's raised wait capacity (global 64).
 - **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).
 

{mailsocket_mcp-0.2.3 → mailsocket_mcp-0.4.0}/mailsocket_mcp.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mailsocket>=0.1.3
+mailsocket>=0.3.0
 mcp<3.0,>=2.0
 
 [dev]

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mailsocket-mcp"
-version = "0.2.3"
+version = "0.4.0"
 description = "MCP server exposing mailsocket inboxes + wait-for-OTP to AI agents."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,7 +22,7 @@ classifiers = [
     "Topic :: Communications :: Email",
 ]
 dependencies = [
-    "mailsocket>=0.1.3",  # published on PyPI as `mailsocket` (0.1.3 adds strict _seg validation)
+    "mailsocket>=0.3.0",  # published on PyPI as `mailsocket` (0.3.0: Client.send_test_code; 0.2.0: since defaults to omitted — see CHANGELOG)
     "mcp>=2.0,<3.0",
 ]
 

{mailsocket_mcp-0.2.3 → mailsocket_mcp-0.4.0}/tests/test_remote.py

@@ -81,6 +81,8 @@ class Upstream:
                     )
                 if self.command == "DELETE":
                     return self._send(204, None)
+                if path.endswith("/test-code") and self.command == "POST":
+                    return self._send(201, {"data": {"message_id": f"msg_{tenant}", "sent_at": "2026-10-08T12:00:00Z"}})
                 if path.endswith("/messages/latest"):
                     return self._send(200, {"data": {"id": "msg_1", "subject": f"hello {tenant} {path}"}})
                 if path.endswith("/messages/wait"):
@@ -391,6 +393,7 @@ ALL_TOOL_CALLS = [
     ("list_messages", {"inbox_id": "i"}),
     ("get_latest", {"inbox_id": "i"}),
     ("delete_inbox", {"inbox_id": "i"}),
+    ("send_test_code", {"inbox_id": "i"}),
 ]
 
 
@@ -757,7 +760,7 @@ def test_stateless_no_session_id_needed(upstream):
 
     r1, r2 = run(go)
     assert r1.status_code == 200 and "mcp-session-id" not in r1.headers
-    assert len(r1.json()["result"]["tools"]) == 7
+    assert len(r1.json()["result"]["tools"]) == 8
     assert r2.status_code == 200 and r2.json()["result"]["isError"] is False
     assert "tenant-B" in r2.json()["result"]["content"][0]["text"]
 
@@ -828,6 +831,12 @@ class FakeClient:
 
         return R()
 
+    def send_test_code(self, inbox_id):
+        self.calls.append(("send_test_code", inbox_id))
+        if FakeClient.block_keys is not None and self.key in FakeClient.block_keys:
+            self._block()
+        return {"message_id": "msg_t", "sent_at": "2026-10-08T12:00:00Z"}
+
     def list_inboxes(self, limit=None, cursor=None):
         if FakeClient.block_keys is not None and self.key in FakeClient.block_keys:
             self._block()
@@ -874,9 +883,14 @@ def test_wait_capacity_429_is_clean_error_with_retry_hint(upstream, fake_client_
     assert "Traceback" not in text
 
 
-def test_limiter_caps_waits_at_16_and_other_tools_still_served(upstream, fake_client_cls, monkeypatch):
-    """20 concurrent waits: at most 16 in flight, the rest get a clean busy
-    error after the queue timeout, and list_inboxes is served meanwhile."""
+def test_limiter_caps_waits_at_wait_concurrency_and_other_tools_still_served(
+    upstream, fake_client_cls, monkeypatch
+):
+    """WAIT_CONCURRENCY + 4 concurrent waits: at most WAIT_CONCURRENCY in
+    flight, the 4 extra get a clean busy error after the queue timeout, and
+    list_inboxes is served meanwhile."""
+    cap = srv.WAIT_CONCURRENCY
+    excess = 4
     monkeypatch.setattr(srv, "LIMITER_QUEUE_TIMEOUT", 0.5)
     fake_client_cls.gate = threading.Event()
     app = make_app(upstream)
@@ -896,42 +910,58 @@ def test_limiter_caps_waits_at_16_and_other_tools_still_served(upstream, fake_cl
                 waits.append(r.json()["result"])
 
             async with anyio.create_task_group() as tg:
-                for i in range(20):
+                for i in range(cap + excess):
                     tg.start_soon(wait_one, i)
                 # Let the waits saturate their pool, then prove "other" is free.
                 with anyio.fail_after(5):
-                    while FakeClient.inflight < 16:
+                    while FakeClient.inflight < cap:
                         await anyio.sleep(0.01)
                 other = await client.post(
                     "/mcp", headers=bearer(KEY_A), json=tool_call("list_inboxes", {}, id_=99)
                 )
                 other_inflight = FakeClient.inflight
-                # Wait until the 4 excess callers have been refused, then release.
+                # Wait until the excess callers have been refused, then release.
                 with anyio.fail_after(5):
-                    while len(waits) < 4:
+                    while len(waits) < excess:
                         await anyio.sleep(0.01)
                 FakeClient.gate.set()
         return waits, other, other_inflight
 
     waits, other, other_inflight = run(go)
-    assert FakeClient.max_inflight == 16
+    assert FakeClient.max_inflight == cap
     assert other.json()["result"]["isError"] is False
-    assert other_inflight == 16  # served while all 16 wait slots were busy
+    assert other_inflight == cap  # served while every wait slot was busy
     busy = [w for w in waits if w["isError"]]
     ok = [w for w in waits if not w["isError"]]
-    assert len(busy) == 4 and len(ok) == 16
+    assert len(busy) == excess and len(ok) == cap
     assert all("Retry in a few seconds" in w["content"][0]["text"] for w in busy)
 
 
+@pytest.mark.parametrize("path", ["docker-compose.yml", "deploy/mcp/Dockerfile"])
+def test_uvicorn_limit_concurrency_covers_both_pools(path):
+    """uvicorn answers 503 above --limit-concurrency before our limiters ever
+    see the request, so it must admit every wait + other slot (and the wait
+    pool must stay below the backend's global 64 so MCP alone cannot fill it)."""
+    import re
+    from pathlib import Path
+
+    text = (Path(__file__).resolve().parents[3] / path).read_text()
+    m = re.search(r'"--limit-concurrency",\s*"(\d+)"', text)
+    assert m, path
+    assert int(m.group(1)) >= srv.WAIT_CONCURRENCY + srv.OTHER_CONCURRENCY
+    assert srv.WAIT_CONCURRENCY < 64
+
+
 # -- per-key fairness (opus P2-1) --------------------------------------------
 
 
 def test_p2_one_key_cannot_starve_another_real_upstream_429(upstream, monkeypatch):
-    """opus's exact scenario on the REAL SDK + wire: 16 concurrent waits from key
-    A against an upstream answering 429 too_many_wait_requests (Retry-After 1).
+    """opus's exact scenario on the REAL SDK + wire: PER_KEY_WAIT_CONCURRENCY + 6
+    concurrent waits from key A against an upstream answering 429 too_many_wait_requests (Retry-After 1).
     Key B's wait must still be served (and reach the upstream) promptly; A's
     calls come back as clean tool errors without sleeping/retrying in a slot."""
     monkeypatch.setattr(srv, "LIMITER_QUEUE_TIMEOUT", 1.5)
+    n_attack = srv.PER_KEY_WAIT_CONCURRENCY + 6
     upstream.wait_429_keys = {KEY_A}
     app = make_app(upstream)
 
@@ -948,7 +978,7 @@ def test_p2_one_key_cannot_starve_another_real_upstream_429(upstream, monkeypatc
                 a_results.append(r.json()["result"])
 
             async with anyio.create_task_group() as tg:
-                for i in range(16):
+                for i in range(n_attack):
                     tg.start_soon(attacker, i)
                 await anyio.sleep(0.05)  # let A's calls grab whatever they can
                 started = time.monotonic()
@@ -970,11 +1000,11 @@ def test_p2_one_key_cannot_starve_another_real_upstream_429(upstream, monkeypatc
     assert len(b_calls) == 1
     # A: every call is a clean, immediate error — either the per-key cap or
     # the upstream 429 surfaced as-is. No Retry-After sleeping inside a slot.
-    assert len(a_results) == 16 and all(r["isError"] for r in a_results)
+    assert len(a_results) == n_attack and all(r["isError"] for r in a_results)
     texts = [r["content"][0]["text"] for r in a_results]
     capped = [t for t in texts if "Too many concurrent wait calls for this API key" in t]
     limited = [t for t in texts if t.startswith("Rate limited (HTTP 429)")]
-    assert len(capped) + len(limited) == 16
+    assert len(capped) + len(limited) == n_attack
     assert len(limited) <= srv.PER_KEY_WAIT_CONCURRENCY
     a_calls = [c for c in upstream.calls if c["headers"]["authorization"] == f"Bearer {KEY_A}"]
     assert len(a_calls) == len(limited)  # exactly one upstream hit each, no retries
@@ -982,9 +1012,11 @@ def test_p2_one_key_cannot_starve_another_real_upstream_429(upstream, monkeypatc
     assert srv._PerKeyInflight.counts == {}  # entries removed at 0
 
 
-def test_p2_per_key_wait_cap_is_3_and_other_key_still_served(upstream, fake_client_cls):
-    """Per-key cap alone: A's 16 waits → only 3 in flight, 13 immediate clean
-    errors; B's wait is served while A's 3 are still held."""
+def test_p2_per_key_wait_cap_and_other_key_still_served(upstream, fake_client_cls):
+    """Per-key cap alone: A's cap + 6 waits → only PER_KEY_WAIT_CONCURRENCY in
+    flight, 6 immediate clean errors; B's wait is served while A's are held."""
+    cap = srv.PER_KEY_WAIT_CONCURRENCY
+    n = cap + 6
     fake_client_cls.gate = threading.Event()
     fake_client_cls.block_keys = {KEY_A}
     app = make_app(upstream)
@@ -1001,10 +1033,10 @@ def test_p2_per_key_wait_cap_is_3_and_other_key_still_served(upstream, fake_clie
                 results.append(r.json()["result"])
 
             async with anyio.create_task_group() as tg:
-                for i in range(16):
+                for i in range(n):
                     tg.start_soon(a, i)
                 with anyio.fail_after(5):
-                    while len(results) < 13 or FakeClient.inflight < 3:
+                    while len(results) < n - cap or FakeClient.inflight < cap:
                         await anyio.sleep(0.01)
                 held = FakeClient.inflight
                 counts_while_held = dict(srv._PerKeyInflight.counts)
@@ -1016,10 +1048,10 @@ def test_p2_per_key_wait_cap_is_3_and_other_key_still_served(upstream, fake_clie
         return results, b.json()["result"], held, counts_while_held
 
     results, b, held, counts = run(go)
-    assert held == 3 and FakeClient.max_inflight == 3
+    assert held == cap and FakeClient.max_inflight == cap
     busy = [r for r in results if r["isError"]]
-    assert len(busy) == 13 and len(results) == 16
-    assert all("max 3 in flight" in r["content"][0]["text"] for r in busy)
+    assert len(busy) == n - cap and len(results) == n
+    assert all(f"max {cap} in flight" in r["content"][0]["text"] for r in busy)
     assert b["isError"] is False
     # keyed by sha256 digest, never by the key itself
     assert all(KEY_A not in k[0] and len(k[0]) == 64 for k in counts)
@@ -1060,6 +1092,59 @@ def test_p2_per_key_other_cap_is_8(upstream, fake_client_cls):
     assert srv._PerKeyInflight.counts == {}
 
 
+def test_send_test_code_reaches_upstream_as_tenant_post(upstream):
+    """Remote: the tool POSTs /inboxes/{id}/test-code upstream with the
+    CALLER's key and returns that tenant's result."""
+    app = make_app(upstream)
+    r = _post(app, json=tool_call("send_test_code", {"inbox_id": "inbox_x"}))
+    result = r.json()["result"]
+    assert result["isError"] is False
+    assert json.loads(result["content"][0]["text"]) == {
+        "message_id": "msg_tenant-A",
+        "sent_at": "2026-10-08T12:00:00Z",
+    }
+    assert [(c["method"], c["path"]) for c in upstream.calls] == [("POST", "/api/v1/inboxes/inbox_x/test-code")]
+    assert upstream.calls[0]["headers"]["authorization"] == f"Bearer {KEY_A}"
+
+
+def test_send_test_code_shares_the_per_key_non_wait_cap(upstream, fake_client_cls):
+    """send_test_code is a non-wait tool: the per-key cap of 8 in-flight
+    non-wait calls applies to it, and another key is still served."""
+    fake_client_cls.gate = threading.Event()
+    fake_client_cls.block_keys = {KEY_A}
+    app = make_app(upstream)
+
+    async def go():
+        results = []
+        async with serving(app) as client:
+
+            async def a(i):
+                r = await client.post(
+                    "/mcp", headers=bearer(KEY_A), json=tool_call("send_test_code", {"inbox_id": "i"}, id_=i)
+                )
+                results.append(r.json()["result"])
+
+            async with anyio.create_task_group() as tg:
+                for i in range(12):
+                    tg.start_soon(a, i)
+                with anyio.fail_after(5):
+                    while len(results) < 4 or FakeClient.inflight < srv.PER_KEY_OTHER_CONCURRENCY:
+                        await anyio.sleep(0.01)
+                b = await client.post(
+                    "/mcp", headers=bearer(KEY_B), json=tool_call("send_test_code", {"inbox_id": "i"})
+                )
+                FakeClient.gate.set()
+        return results, b.json()["result"]
+
+    results, b = run(go)
+    assert FakeClient.max_inflight == srv.PER_KEY_OTHER_CONCURRENCY
+    busy = [r for r in results if r["isError"]]
+    assert len(busy) == 12 - srv.PER_KEY_OTHER_CONCURRENCY
+    assert all("non-wait calls for this API key (max 8" in r["content"][0]["text"] for r in busy)
+    assert b["isError"] is False
+    assert srv._PerKeyInflight.counts == {}
+
+
 def test_p2_remote_wait_429_returns_immediately_no_sleep(upstream, monkeypatch):
     """Remote mode: an upstream 429 on a wait is surfaced at once (one upstream
     hit), never slept on inside the slot."""
@@ -1085,7 +1170,7 @@ def test_p2_per_key_counter_released_on_error(upstream, fake_client_cls):
     async def go():
         texts = []
         async with serving(app) as client:
-            for i in range(5):  # would hit the cap of 3 if slots leaked
+            for i in range(srv.PER_KEY_WAIT_CONCURRENCY + 2):  # would hit the cap if slots leaked
                 r = await client.post(
                     "/mcp", headers=bearer(KEY_A),
                     json=tool_call("wait_for_otp", {"inbox_id": "i"}, id_=i),
@@ -1094,7 +1179,7 @@ def test_p2_per_key_counter_released_on_error(upstream, fake_client_cls):
         return texts
 
     texts = run(go)
-    assert len(texts) == 5
+    assert len(texts) == srv.PER_KEY_WAIT_CONCURRENCY + 2
     assert all("Too many concurrent" not in t for t in texts)
     assert all(t == "boom" for t in texts)
     assert srv._PerKeyInflight.counts == {}
@@ -1113,6 +1198,8 @@ def test_stdio_binding_has_no_per_key_cap_and_sdk_still_retries():
         inflight = 0
         peak = 0
 
+    n = srv.PER_KEY_WAIT_CONCURRENCY + 3
+
     async def go():
         ev = anyio.Event()
 
@@ -1126,12 +1213,13 @@ def test_stdio_binding_has_no_per_key_cap_and_sdk_still_retries():
 
         with srv.bind_client(object(), KEY_A):
             async with anyio.create_task_group() as tg:
-                for _ in range(6):
+                for _ in range(n):
                     tg.start_soon(body)
                 with anyio.fail_after(5):
-                    while Gate.inflight < 6:
+                    while Gate.inflight < n:
                         await anyio.sleep(0.01)
                 ev.set()
 
     run(go)
-    assert Gate.peak == 6  # > per-key cap of 3: stdio is single-tenant, uncapped
+    # > the remote per-key wait cap: stdio is single-tenant, uncapped
+    assert Gate.peak == n > srv.PER_KEY_WAIT_CONCURRENCY

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

@@ -56,18 +56,20 @@ class FakeClient:
         self.deleted = []
         self.wait_otp = None  # (result | exception) scripted per-test
         self.wait_link = None
+        self.test_code_calls = []
+        self.test_code = {"message_id": "msg_test1", "sent_at": "2026-10-08T12:00:00Z"}
 
     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):
+    def wait_for_otp(self, inbox_id, *, timeout=60.0, min_confidence=0.0, since=None):
         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):
+    def wait_for_link(self, inbox_id, *, timeout=60.0, since=None):
         self.wait_link_calls.append((inbox_id, timeout, since))
         if isinstance(self.wait_link, Exception):
             raise self.wait_link
@@ -96,6 +98,12 @@ class FakeClient:
         self.deleted.append(inbox_id)
         return None
 
+    def send_test_code(self, inbox_id):
+        self.test_code_calls.append(inbox_id)
+        if isinstance(self.test_code, Exception):
+            raise self.test_code
+        return self.test_code
+
 
 class SimplePage:
     def __init__(self, data):
@@ -132,6 +140,7 @@ def test_tools_list_returns_all_tools_with_valid_schemas():
         "list_messages",
         "get_latest",
         "delete_inbox",
+        "send_test_code",
     }
     by_name = {t.name: t for t in tools}
     for name, tool in by_name.items():
@@ -213,6 +222,12 @@ def test_tools_list_annotation_values():
             "idempotentHint": None,
             "openWorldHint": True,
         },
+        "send_test_code": {
+            "readOnlyHint": False,
+            "destructiveHint": False,
+            "idempotentHint": False,
+            "openWorldHint": True,
+        },
     }
 
     assert set(expected) == set(by_name)
@@ -237,7 +252,7 @@ def test_wait_for_otp_returns_otp_and_confidence(fake_client):
     assert inbox_id == "inbox_abc"
     assert timeout == 60
     assert min_conf == 0.0
-    assert since == 0  # absent -> SDK default unchanged
+    assert since is None  # absent -> SDK omits since (server uses request start time)
 
 
 def test_wait_for_otp_timeout_is_clamped(fake_client):
@@ -263,6 +278,17 @@ def test_wait_for_otp_since_passed_through(fake_client):
     assert since == "msg_111"
 
 
+def test_wait_for_otp_explicit_since_zero_passed_through(fake_client):
+    """since=0 (include messages already in the inbox) must reach the SDK as 0,
+    not be dropped as falsy and turned into the new request-start default."""
+    fake_client.wait_otp = FakeWaitResult(otp="123456")
+
+    call_tool("wait_for_otp", {"inbox_id": "inbox_abc", "since": 0})
+
+    _, _, _, since = fake_client.wait_otp_calls[0]
+    assert since == 0
+
+
 def test_wait_for_otp_result_carries_id_and_received_at(fake_client):
     fake_client.wait_otp = FakeWaitResult(
         otp="123456",
@@ -307,7 +333,7 @@ def test_wait_for_link_returns_magic_link(fake_client):
     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
+    assert since is None  # absent -> SDK omits since (server uses request start time)
 
 
 def test_wait_for_link_since_passed_through(fake_client):
@@ -375,6 +401,68 @@ def test_get_latest_and_delete_inbox(fake_client):
     assert fake_client.deleted == ["inbox_abc"]
 
 
+# -- send_test_code ----------------------------------------------------------
+
+
+def test_send_test_code_returns_message_id_and_sent_at(fake_client):
+    result = call_tool("send_test_code", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is False
+    payload = json.loads(result.content[0].text)
+    assert payload == {"message_id": "msg_test1", "sent_at": "2026-10-08T12:00:00Z"}
+    assert fake_client.test_code_calls == ["inbox_abc"]
+
+
+def test_send_test_code_description_explains_pairing_with_wait():
+    tools = {t.name: t for t in asyncio.run(server.list_tools())}
+    desc = tools["send_test_code"].description
+    assert "does NOT go through the mail server" in desc
+    assert "since" in desc and "wait_for_otp" in desc
+    assert "BEFORE calling this tool" in desc
+    schema = tools["send_test_code"].input_schema
+    assert set(schema["properties"]) == {"inbox_id"}
+    assert schema.get("required") == ["inbox_id"]
+
+
+@pytest.mark.parametrize(
+    "exc, expected_substring",
+    [
+        (NotFound("Resource not found.", code="not_found", status=404), "Not found (HTTP 404)"),
+        (
+            RateLimited("Too many test codes. Try again at 13:00 UTC.", code="rate_limited", retry_after=1800.0),
+            "Retry after 1800s",
+        ),
+        (
+            MailsocketError(
+                "This inbox is disabled. Enable it to receive a test code.", code="inbox_disabled", status=409
+            ),
+            "This inbox is disabled",
+        ),
+        (AuthError("Authentication required.", code="authentication_required"), "Authentication failed"),
+    ],
+)
+def test_send_test_code_errors_are_clean_tool_errors(fake_client, exc, expected_substring):
+    fake_client.test_code = exc
+
+    result = call_tool("send_test_code", {"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
+
+
+def test_send_test_code_error_never_leaks_the_key(fake_client):
+    fake_client.test_code = MailsocketError(f"boom for {API_KEY} and ms_live_otherkey123")
+
+    result = call_tool("send_test_code", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is True
+    text = result.content[0].text
+    assert API_KEY not in text and "ms_live_" not in text
+    assert "***" in text
+
+
 # -- error mapping -----------------------------------------------------------
 
 
@@ -428,14 +516,14 @@ def test_version_exported():
 
 
 def test_metadata_consistency_across_files():
-    """Versions match everywhere: MCP 0.2.3 (pyproject, server.json, __version__)
-    and its Python SDK sibling 0.1.3 (pyproject, __version__, user agent)."""
+    """Versions match everywhere: MCP 0.4.0 (pyproject, server.json, __version__)
+    and its Python SDK sibling 0.3.0 (pyproject, __version__, user agent)."""
     import tomllib
     from pathlib import Path
 
     root = Path(__file__).resolve().parents[1]
-    expected = "0.2.3"
-    expected_sdk = "0.1.3"
+    expected = "0.4.0"
+    expected_sdk = "0.3.0"
 
     pyproject = tomllib.loads((root / "pyproject.toml").read_text())
     assert pyproject["project"]["version"] == expected