sendmux-mcp 1.0.0__tar.gz

sendmux_mcp-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules/
+dist/
+.tmp/
+coverage/
+.DS_Store
+*.log
+*.codegen.json
+.codegen/
+.codegraph/
+*.tsbuildinfo
+packages/ts/cli/oclif.manifest.json
+packages/ts/cli/tmp/
+.phpunit.result.cache
+__pycache__/
+*.py[cod]
+vendor/
+.bundle/

sendmux_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: sendmux-mcp
+Version: 1.0.0
+Summary: Curated MCP servers for the Sendmux API surfaces.
+Project-URL: Repository, https://github.com/Sendmux/sendmux-sdk
+Requires-Python: >=3.10
+Requires-Dist: fastmcp==3.3.1
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: sendmux-core<2.0.0,>=1.0.0
+Description-Content-Type: text/markdown
+
+# Sendmux MCP
+
+Curated Model Context Protocol servers for the Sendmux mailbox, management, and sending API surfaces.
+
+## Install
+
+```bash
+pip install sendmux-mcp
+```
+
+For local development from this repository:
+
+```bash
+OPENAPI_INPUT_DIR=/path/to/sendmux-docs pnpm build:mcp
+```
+
+## Run
+
+Each surface is a separate server so credentials and tools stay isolated.
+
+```bash
+SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox
+SENDMUX_API_KEY=smx_root_... sendmux-mcp-management
+SENDMUX_API_KEY=smx_root_... sendmux-mcp-sending
+```
+
+Use HTTP transport for hosted or remote clients. HTTP requires a separate MCP bearer token unless you explicitly opt out.
+
+```bash
+SENDMUX_API_KEY=smx_mbx_... \
+SENDMUX_MCP_HTTP_BEARER_TOKEN=local-mcp-token \
+sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765
+```
+
+The MCP endpoint defaults to `/mcp`; `/health` returns a small JSON health response.
+
+## Configuration
+
+| Setting | Environment | Default |
+| --- | --- | --- |
+| API key | `SENDMUX_API_KEY` | required |
+| App API base URL | `SENDMUX_APP_BASE_URL` | `https://app.sendmux.ai/api/v1` |
+| Sending API base URL | `SENDMUX_SENDING_BASE_URL` | `https://smtp.sendmux.ai/api/v1` |
+| Transport | `SENDMUX_MCP_TRANSPORT` | `stdio` |
+| HTTP host | `SENDMUX_MCP_HOST` | `127.0.0.1` |
+| HTTP port | `SENDMUX_MCP_PORT` | `8765` |
+| HTTP path | `SENDMUX_MCP_PATH` | `/mcp` |
+| HTTP bearer token | `SENDMUX_MCP_HTTP_BEARER_TOKEN` | required for HTTP |
+| Allowed browser origins | `SENDMUX_MCP_ALLOWED_ORIGINS` | no browser origins |
+| Snapshot directory override | `SENDMUX_MCP_OPENAPI_INPUT_DIR` or `OPENAPI_INPUT_DIR` | packaged snapshots |
+| App snapshot override | `SENDMUX_MCP_APP_OPENAPI` | packaged app snapshot |
+| Sending snapshot override | `SENDMUX_MCP_SENDING_OPENAPI` | packaged sending snapshot |
+
+Packaged OpenAPI snapshots are the default so released tool names, schemas, and descriptions do not drift. Path, directory, and URL overrides are available for development, canary, and debugging runs.
+
+## Tool Surfaces
+
+- Mailbox: message read/send, threads, folders, identity, and mailbox state tools. Requires an `smx_mbx_` key.
+- Management: domains, mailboxes, logs, metrics, and webhook tools. Requires an `smx_root_` key.
+- Sending: send and batch send tools. Requires an `smx_root_` key.
+
+The server rejects keys with the wrong prefix before starting.

sendmux_mcp-1.0.0/README.md

@@ -0,0 +1,62 @@
+# Sendmux MCP
+
+Curated Model Context Protocol servers for the Sendmux mailbox, management, and sending API surfaces.
+
+## Install
+
+```bash
+pip install sendmux-mcp
+```
+
+For local development from this repository:
+
+```bash
+OPENAPI_INPUT_DIR=/path/to/sendmux-docs pnpm build:mcp
+```
+
+## Run
+
+Each surface is a separate server so credentials and tools stay isolated.
+
+```bash
+SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox
+SENDMUX_API_KEY=smx_root_... sendmux-mcp-management
+SENDMUX_API_KEY=smx_root_... sendmux-mcp-sending
+```
+
+Use HTTP transport for hosted or remote clients. HTTP requires a separate MCP bearer token unless you explicitly opt out.
+
+```bash
+SENDMUX_API_KEY=smx_mbx_... \
+SENDMUX_MCP_HTTP_BEARER_TOKEN=local-mcp-token \
+sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765
+```
+
+The MCP endpoint defaults to `/mcp`; `/health` returns a small JSON health response.
+
+## Configuration
+
+| Setting | Environment | Default |
+| --- | --- | --- |
+| API key | `SENDMUX_API_KEY` | required |
+| App API base URL | `SENDMUX_APP_BASE_URL` | `https://app.sendmux.ai/api/v1` |
+| Sending API base URL | `SENDMUX_SENDING_BASE_URL` | `https://smtp.sendmux.ai/api/v1` |
+| Transport | `SENDMUX_MCP_TRANSPORT` | `stdio` |
+| HTTP host | `SENDMUX_MCP_HOST` | `127.0.0.1` |
+| HTTP port | `SENDMUX_MCP_PORT` | `8765` |
+| HTTP path | `SENDMUX_MCP_PATH` | `/mcp` |
+| HTTP bearer token | `SENDMUX_MCP_HTTP_BEARER_TOKEN` | required for HTTP |
+| Allowed browser origins | `SENDMUX_MCP_ALLOWED_ORIGINS` | no browser origins |
+| Snapshot directory override | `SENDMUX_MCP_OPENAPI_INPUT_DIR` or `OPENAPI_INPUT_DIR` | packaged snapshots |
+| App snapshot override | `SENDMUX_MCP_APP_OPENAPI` | packaged app snapshot |
+| Sending snapshot override | `SENDMUX_MCP_SENDING_OPENAPI` | packaged sending snapshot |
+
+Packaged OpenAPI snapshots are the default so released tool names, schemas, and descriptions do not drift. Path, directory, and URL overrides are available for development, canary, and debugging runs.
+
+## Tool Surfaces
+
+- Mailbox: message read/send, threads, folders, identity, and mailbox state tools. Requires an `smx_mbx_` key.
+- Management: domains, mailboxes, logs, metrics, and webhook tools. Requires an `smx_root_` key.
+- Sending: send and batch send tools. Requires an `smx_root_` key.
+
+The server rejects keys with the wrong prefix before starting.

sendmux_mcp-1.0.0/evals.xml

@@ -0,0 +1,42 @@
+<evals>
+  <eval id="1">
+    <question>Send a short message from the authenticated mailbox to a supplied recipient, then list recent mailbox messages to confirm the mailbox can still be read.</question>
+    <expected>Call mailbox_send_message with an idempotency key, then mailbox_list_messages with a small limit.</expected>
+  </eval>
+  <eval id="2">
+    <question>Find the latest message matching a subject fragment and read its body.</question>
+    <expected>Call mailbox_search_message_snippets, choose a message_id, then call mailbox_list_body or mailbox_list_content.</expected>
+  </eval>
+  <eval id="3">
+    <question>Show unread message volume and list the first page of messages without fetching full bodies.</question>
+    <expected>Call mailbox_count_messages, then mailbox_list_messages with a small limit.</expected>
+  </eval>
+  <eval id="4">
+    <question>Archive or mark a set of mailbox messages after the user supplies message IDs.</question>
+    <expected>Call mailbox_batch_update_messages with the supplied IDs and desired flag or folder changes.</expected>
+  </eval>
+  <eval id="5">
+    <question>Summarise the current mailbox identity and the folders available for filing messages.</question>
+    <expected>Call mailbox_get_identity and mailbox_list_folders.</expected>
+  </eval>
+  <eval id="6">
+    <question>Prepare a domain for sending and return the DNS records the user should configure.</question>
+    <expected>Call management_create_domain if needed, then management_get_domain_zone_file.</expected>
+  </eval>
+  <eval id="7">
+    <question>Create a mailbox and produce a mailbox API key for an agent that should only access that mailbox.</question>
+    <expected>Call management_create_mailbox, then management_create_mailbox_key for the new mailbox.</expected>
+  </eval>
+  <eval id="8">
+    <question>Investigate a delivery issue for a known email log ID.</question>
+    <expected>Call management_get_email_log and use the structured result to explain the delivery status.</expected>
+  </eval>
+  <eval id="9">
+    <question>Send one transactional email through the sending surface and include an idempotency key.</question>
+    <expected>Call sending_send_email with a complete message body and Idempotency-Key.</expected>
+  </eval>
+  <eval id="10">
+    <question>Explain why a mailbox-key MCP server cannot manage domains or create mailbox keys.</question>
+    <expected>List mailbox tools only; management tools are absent and management startup rejects smx_mbx_ credentials.</expected>
+  </eval>
+</evals>

sendmux_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sendmux-mcp"
+version = "1.0.0"
+description = "Curated MCP servers for the Sendmux API surfaces."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "fastmcp==3.3.1",
+  "httpx>=0.28.1,<1",
+  "sendmux-core>=1.0.0,<2.0.0",
+]
+
+[project.scripts]
+sendmux-mcp = "sendmux_mcp.cli:main"
+sendmux-mcp-mailbox = "sendmux_mcp.cli:main_mailbox"
+sendmux-mcp-management = "sendmux_mcp.cli:main_management"
+sendmux-mcp-sending = "sendmux_mcp.cli:main_sending"
+
+[project.urls]
+Repository = "https://github.com/Sendmux/sendmux-sdk"
+
+[tool.hatch.build.targets.sdist]
+core-metadata-version = "2.4"
+include = [
+  "README.md",
+  "evals.xml",
+  "sendmux_mcp",
+]
+
+[tool.hatch.build.targets.wheel]
+core-metadata-version = "2.4"
+packages = ["sendmux_mcp"]
+artifacts = ["sendmux_mcp/openapi/*.json"]

sendmux_mcp-1.0.0/sendmux_mcp/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from sendmux_mcp.config import ServerConfig, Surface
+from sendmux_mcp.server import create_server
+
+__all__ = ["ServerConfig", "Surface", "create_server"]

sendmux_mcp-1.0.0/sendmux_mcp/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from sendmux_mcp.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sendmux_mcp-1.0.0/sendmux_mcp/cli.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import argparse
+
+from sendmux_mcp.config import RetryConfig, ServerConfig, Surface, config_from_env, normalise_transport, parse_csv
+from sendmux_mcp.server import run
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser(prog="sendmux-mcp").parse_args(argv)
+    surface = args.surface
+    if surface is None:
+        raise SystemExit("--surface is required when using sendmux-mcp")
+    run(config_from_args(surface, args))
+    return 0
+
+
+def main_mailbox(argv: list[str] | None = None) -> int:
+    args = parser(default_surface="mailbox", prog="sendmux-mcp-mailbox").parse_args(argv)
+    run(config_from_args("mailbox", args))
+    return 0
+
+
+def main_management(argv: list[str] | None = None) -> int:
+    args = parser(default_surface="management", prog="sendmux-mcp-management").parse_args(argv)
+    run(config_from_args("management", args))
+    return 0
+
+
+def main_sending(argv: list[str] | None = None) -> int:
+    args = parser(default_surface="sending", prog="sendmux-mcp-sending").parse_args(argv)
+    run(config_from_args("sending", args))
+    return 0
+
+
+def parser(*, default_surface: Surface | None = None, prog: str) -> argparse.ArgumentParser:
+    command = argparse.ArgumentParser(prog=prog)
+    if default_surface is None:
+        command.add_argument("--surface", choices=["mailbox", "management", "sending"])
+    command.add_argument("--api-key")
+    command.add_argument("--transport", choices=["stdio", "http", "streamable-http"])
+    command.add_argument("--host")
+    command.add_argument("--port", type=int)
+    command.add_argument("--path")
+    command.add_argument("--app-base-url")
+    command.add_argument("--sending-base-url")
+    command.add_argument("--openapi-input-dir")
+    command.add_argument("--app-openapi")
+    command.add_argument("--sending-openapi")
+    command.add_argument("--allowed-origin", action="append", default=[])
+    command.add_argument("--http-bearer-token")
+    command.add_argument("--allow-unauthenticated-http", action="store_true")
+    command.add_argument("--timeout-seconds", type=float)
+    command.add_argument("--retry-max-attempts", type=int)
+    command.add_argument("--retry-base-delay-seconds", type=float)
+    command.add_argument("--retry-max-delay-seconds", type=float)
+    command.set_defaults(surface=default_surface)
+    return command
+
+
+def config_from_args(surface: Surface, args: argparse.Namespace) -> ServerConfig:
+    base = config_from_env(surface, api_key=args.api_key)
+    allowed_origins = tuple(args.allowed_origin) or parse_csv(None)
+    transport = normalise_transport(args.transport) if args.transport else base.transport
+    return ServerConfig(
+        surface=surface,
+        api_key=base.api_key,
+        app_base_url=args.app_base_url or base.app_base_url,
+        sending_base_url=args.sending_base_url or base.sending_base_url,
+        transport=transport,
+        host=args.host or base.host,
+        port=args.port or base.port,
+        path=args.path or base.path,
+        openapi_input_dir=args.openapi_input_dir or base.openapi_input_dir,
+        app_openapi=args.app_openapi or base.app_openapi,
+        sending_openapi=args.sending_openapi or base.sending_openapi,
+        allowed_origins=allowed_origins or base.allowed_origins,
+        http_bearer_token=args.http_bearer_token or base.http_bearer_token,
+        allow_unauthenticated_http=args.allow_unauthenticated_http or base.allow_unauthenticated_http,
+        timeout_seconds=args.timeout_seconds or base.timeout_seconds,
+        stateless_http=base.stateless_http,
+        retry=RetryConfig(
+            max_attempts=args.retry_max_attempts or base.retry.max_attempts,
+            base_delay_seconds=args.retry_base_delay_seconds or base.retry.base_delay_seconds,
+            max_delay_seconds=args.retry_max_delay_seconds or base.retry.max_delay_seconds,
+        ),
+    )

sendmux_mcp-1.0.0/sendmux_mcp/config.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+from sendmux_core import validate_api_key
+
+Surface = Literal["mailbox", "management", "sending"]
+Transport = Literal["stdio", "http", "streamable-http"]
+
+DEFAULT_APP_BASE_URL = "https://app.sendmux.ai/api/v1"
+DEFAULT_SENDING_BASE_URL = "https://smtp.sendmux.ai/api/v1"
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    max_attempts: int = 3
+    base_delay_seconds: float = 0.25
+    max_delay_seconds: float = 8.0
+
+
+@dataclass(frozen=True)
+class ServerConfig:
+    surface: Surface
+    api_key: str
+    app_base_url: str = DEFAULT_APP_BASE_URL
+    sending_base_url: str = DEFAULT_SENDING_BASE_URL
+    transport: Transport = "stdio"
+    host: str = "127.0.0.1"
+    port: int = 8765
+    path: str = "/mcp"
+    openapi_input_dir: str | None = None
+    app_openapi: str | None = None
+    sending_openapi: str | None = None
+    allowed_origins: tuple[str, ...] = ()
+    http_bearer_token: str | None = None
+    allow_unauthenticated_http: bool = False
+    timeout_seconds: float = 30.0
+    stateless_http: bool = True
+    retry: RetryConfig = RetryConfig()
+
+    @property
+    def required_key_surface(self) -> Literal["root", "mailbox"]:
+        return "mailbox" if self.surface == "mailbox" else "root"
+
+    @property
+    def api_base_url(self) -> str:
+        return self.sending_base_url if self.surface == "sending" else self.app_base_url
+
+    def validate(self) -> None:
+        validate_api_key(self.api_key, surface=self.required_key_surface)
+        if self.transport in {"http", "streamable-http"} and not self.allow_unauthenticated_http:
+            if not self.http_bearer_token:
+                raise ValueError(
+                    "HTTP transport requires SENDMUX_MCP_HTTP_BEARER_TOKEN or --allow-unauthenticated-http."
+                )
+
+
+def config_from_env(surface: Surface, *, api_key: str | None = None) -> ServerConfig:
+    transport = normalise_transport(os.environ.get("SENDMUX_MCP_TRANSPORT", "stdio"))
+    return ServerConfig(
+        surface=surface,
+        api_key=api_key or require_env("SENDMUX_API_KEY"),
+        app_base_url=os.environ.get("SENDMUX_APP_BASE_URL", DEFAULT_APP_BASE_URL),
+        sending_base_url=os.environ.get("SENDMUX_SENDING_BASE_URL", DEFAULT_SENDING_BASE_URL),
+        transport=transport,
+        host=os.environ.get("SENDMUX_MCP_HOST", "127.0.0.1"),
+        port=int(os.environ.get("SENDMUX_MCP_PORT", "8765")),
+        path=os.environ.get("SENDMUX_MCP_PATH", "/mcp"),
+        openapi_input_dir=os.environ.get("SENDMUX_MCP_OPENAPI_INPUT_DIR") or os.environ.get("OPENAPI_INPUT_DIR"),
+        app_openapi=os.environ.get("SENDMUX_MCP_APP_OPENAPI"),
+        sending_openapi=os.environ.get("SENDMUX_MCP_SENDING_OPENAPI"),
+        allowed_origins=parse_csv(os.environ.get("SENDMUX_MCP_ALLOWED_ORIGINS")),
+        http_bearer_token=os.environ.get("SENDMUX_MCP_HTTP_BEARER_TOKEN"),
+        allow_unauthenticated_http=parse_bool(os.environ.get("SENDMUX_MCP_ALLOW_UNAUTHENTICATED_HTTP")),
+        timeout_seconds=float(os.environ.get("SENDMUX_MCP_TIMEOUT_SECONDS", "30")),
+        stateless_http=parse_bool(os.environ.get("SENDMUX_MCP_STATELESS_HTTP"), default=True),
+        retry=RetryConfig(
+            max_attempts=int(os.environ.get("SENDMUX_MCP_RETRY_MAX_ATTEMPTS", "3")),
+            base_delay_seconds=float(os.environ.get("SENDMUX_MCP_RETRY_BASE_DELAY_SECONDS", "0.25")),
+            max_delay_seconds=float(os.environ.get("SENDMUX_MCP_RETRY_MAX_DELAY_SECONDS", "8")),
+        ),
+    )
+
+
+def normalise_transport(value: str) -> Transport:
+    if value == "streamable-http":
+        return "streamable-http"
+    if value in {"stdio", "http"}:
+        return value  # type: ignore[return-value]
+    raise ValueError("transport must be one of: stdio, http, streamable-http")
+
+
+def parse_csv(value: str | None) -> tuple[str, ...]:
+    if not value:
+        return ()
+    return tuple(item.strip() for item in value.split(",") if item.strip())
+
+
+def parse_bool(value: str | None, *, default: bool = False) -> bool:
+    if value is None:
+        return default
+    return value.lower() in {"1", "true", "yes", "on"}
+
+
+def require_env(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        raise ValueError(f"Missing required environment variable {name}")
+    return value