mailerbot-mcp 0.1.0__tar.gz

mailerbot_mcp-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/

mailerbot_mcp-0.1.0/Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.13-slim
+
+WORKDIR /app
+
+# Install uv for fast dependency resolution
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Copy SDK and MCP server source
+COPY sdk/python /app/sdk/python
+COPY mcp /app/mcp
+
+# Install the MCP server (which pulls in the local SDK)
+RUN uv pip install --system /app/sdk/python /app/mcp
+
+EXPOSE 8080
+
+# Default to streamable-http (current MCP standard) for remote deployment
+ENV MAILERBOT_MCP_TRANSPORT=streamable-http
+ENV MAILERBOT_MCP_HOST=0.0.0.0
+ENV MAILERBOT_MCP_PORT=8080
+# In Docker Compose, MAILERBOT_API_URL and MAILERBOT_OAUTH_ISSUER are set
+# via environment or env_file to point at the backend service.
+
+CMD ["mailerbot-mcp"]

mailerbot_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: mailerbot-mcp
+Version: 0.1.0
+Summary: MCP server for the MailerBot direct mail API
+Project-URL: Homepage, https://mailerbot.com
+Project-URL: Documentation, https://mailerbot.com/docs/mcp
+Project-URL: Repository, https://github.com/mailerbot-hq/MailerBot/tree/dev/mcp
+Project-URL: Bug Tracker, https://github.com/mailerbot-hq/MailerBot/issues
+Author-email: MailerBot <dev@mailerbot.com>
+License: MIT
+Keywords: ai,direct-mail,mailerbot,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mailerbot>=0.1.0
+Requires-Dist: mcp[cli]>=1.0
+Description-Content-Type: text/markdown
+
+# MailerBot MCP Server
+
+MCP (Model Context Protocol) server for the MailerBot direct mail API. Enables AI tools like Claude, Cursor, and others to manage contacts, mailings, campaigns, and more.
+
+## Remote server (recommended)
+
+URL: `https://mcp.mailerbot.com/mcp`. OAuth is handled automatically — no API key to manage.
+
+In Claude: **Settings > Connectors > Add custom connector**, then paste the URL above.
+
+## Quick Start (Local / STDIO)
+
+```bash
+# Set your API key
+export MAILERBOT_API_KEY="mb_live_..."
+
+# Run via uvx
+uvx mailerbot-mcp
+
+# Or run from source
+cd mcp
+uv run mailerbot-mcp
+```
+
+### Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "mailerbot": {
+      "command": "uvx",
+      "args": ["mailerbot-mcp"],
+      "env": {
+        "MAILERBOT_API_KEY": "mb_live_..."
+      }
+    }
+  }
+}
+```
+
+## Self-Hosted (SSE)
+
+```bash
+docker build -t mailerbot-mcp -f mcp/Dockerfile .
+docker run -p 8080:8080 \
+  -e MAILERBOT_MCP_TRANSPORT=sse \
+  -e MAILERBOT_BEARER_TOKEN="..." \
+  mailerbot-mcp
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `MAILERBOT_API_KEY` | API key for authentication | — |
+| `MAILERBOT_BEARER_TOKEN` | OAuth bearer token (alternative to API key) | — |
+| `MAILERBOT_API_URL` | API base URL | `https://api.mailerbot.com/api/v1` |
+| `MAILERBOT_MCP_TRANSPORT` | Transport mode: `stdio` or `sse` | `stdio` |
+| `MAILERBOT_MCP_HOST` | Host to bind (SSE mode) | `0.0.0.0` |
+| `MAILERBOT_MCP_PORT` | Port to bind (SSE mode) | `8080` |
+
+## Available Tools
+
+**Contacts** — list, get, create, update, delete, validate addresses
+**Contact Lists** — list, get, create, update, delete, add/remove contacts
+**Documents** — list, get, create, update, delete
+**Postcards** — list templates, list, get, create, delete
+**Mailings** — list, get, create, update, delete, validate addresses, estimate cost, calculate cost, send
+**Campaigns** — list, get, create, update, delete, add/remove mailings
+**Dashboard** — stats, reporting
+**Pricing** — catalog, countries, postage zones, postage rates
+**Coupons** — list, get, create, update, delete, list/import codes, check availability
+**QR Tracking** — list, create, delete links, analytics
+**Merge Tags** — list available tags

mailerbot_mcp-0.1.0/README.md

@@ -0,0 +1,74 @@
+# MailerBot MCP Server
+
+MCP (Model Context Protocol) server for the MailerBot direct mail API. Enables AI tools like Claude, Cursor, and others to manage contacts, mailings, campaigns, and more.
+
+## Remote server (recommended)
+
+URL: `https://mcp.mailerbot.com/mcp`. OAuth is handled automatically — no API key to manage.
+
+In Claude: **Settings > Connectors > Add custom connector**, then paste the URL above.
+
+## Quick Start (Local / STDIO)
+
+```bash
+# Set your API key
+export MAILERBOT_API_KEY="mb_live_..."
+
+# Run via uvx
+uvx mailerbot-mcp
+
+# Or run from source
+cd mcp
+uv run mailerbot-mcp
+```
+
+### Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "mailerbot": {
+      "command": "uvx",
+      "args": ["mailerbot-mcp"],
+      "env": {
+        "MAILERBOT_API_KEY": "mb_live_..."
+      }
+    }
+  }
+}
+```
+
+## Self-Hosted (SSE)
+
+```bash
+docker build -t mailerbot-mcp -f mcp/Dockerfile .
+docker run -p 8080:8080 \
+  -e MAILERBOT_MCP_TRANSPORT=sse \
+  -e MAILERBOT_BEARER_TOKEN="..." \
+  mailerbot-mcp
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `MAILERBOT_API_KEY` | API key for authentication | — |
+| `MAILERBOT_BEARER_TOKEN` | OAuth bearer token (alternative to API key) | — |
+| `MAILERBOT_API_URL` | API base URL | `https://api.mailerbot.com/api/v1` |
+| `MAILERBOT_MCP_TRANSPORT` | Transport mode: `stdio` or `sse` | `stdio` |
+| `MAILERBOT_MCP_HOST` | Host to bind (SSE mode) | `0.0.0.0` |
+| `MAILERBOT_MCP_PORT` | Port to bind (SSE mode) | `8080` |
+
+## Available Tools
+
+**Contacts** — list, get, create, update, delete, validate addresses
+**Contact Lists** — list, get, create, update, delete, add/remove contacts
+**Documents** — list, get, create, update, delete
+**Postcards** — list templates, list, get, create, delete
+**Mailings** — list, get, create, update, delete, validate addresses, estimate cost, calculate cost, send
+**Campaigns** — list, get, create, update, delete, add/remove mailings
+**Dashboard** — stats, reporting
+**Pricing** — catalog, countries, postage zones, postage rates
+**Coupons** — list, get, create, update, delete, list/import codes, check availability
+**QR Tracking** — list, create, delete links, analytics
+**Merge Tags** — list available tags

mailerbot_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mailerbot-mcp"
+version = "0.1.0"
+description = "MCP server for the MailerBot direct mail API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "MailerBot", email = "dev@mailerbot.com" }]
+keywords = ["mailerbot", "mcp", "model-context-protocol", "direct-mail", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "mcp[cli]>=1.0",
+    "mailerbot>=0.1.0",
+]
+
+[project.scripts]
+mailerbot-mcp = "mailerbot_mcp:main"
+
+[project.urls]
+Homepage = "https://mailerbot.com"
+Documentation = "https://mailerbot.com/docs/mcp"
+Repository = "https://github.com/mailerbot-hq/MailerBot/tree/dev/mcp"
+"Bug Tracker" = "https://github.com/mailerbot-hq/MailerBot/issues"
+
+[dependency-groups]
+dev = ["pytest"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mailerbot_mcp"]
+
+# For local development, use the SDK from the monorepo
+[tool.uv.sources]
+mailerbot = { path = "../sdk/python", editable = true }

mailerbot_mcp-0.1.0/src/mailerbot_mcp/__init__.py

@@ -0,0 +1,83 @@
+import os
+
+from .server import mcp
+
+
+def _configure_auth() -> None:
+    """Configure OAuth authentication for remote (SSE/streamable-http) mode.
+
+    Sets up the MCP server as an OAuth Resource Server that:
+    - Points MCP clients to the MailerBot backend's OAuth endpoints
+    - Validates bearer tokens by calling the backend's /auth/me endpoint
+    - Passes valid tokens through to the SDK for API calls
+    """
+    from pydantic import AnyHttpUrl
+    from mcp.server.auth.settings import AuthSettings
+    from .auth import MailerBotTokenVerifier
+
+    api_url = os.environ.get(
+        "MAILERBOT_API_URL", "https://api.mailerbot.com/api/v1"
+    )
+    # The OAuth issuer is the backend root (without /api/v1)
+    issuer_url = os.environ.get(
+        "MAILERBOT_OAUTH_ISSUER",
+        api_url.replace("/api/v1", ""),
+    )
+    # The MCP server's own public URL (for resource server metadata)
+    mcp_url = os.environ.get("MAILERBOT_MCP_URL", "http://localhost:8080")
+
+    mcp.settings.auth = AuthSettings(
+        issuer_url=AnyHttpUrl(issuer_url),
+        resource_server_url=AnyHttpUrl(mcp_url),
+    )
+    mcp._token_verifier = MailerBotTokenVerifier(api_base_url=api_url)
+
+
+def main():
+    transport = os.environ.get("MAILERBOT_MCP_TRANSPORT", "stdio")
+
+    if transport in ("sse", "streamable-http"):
+        import uvicorn
+        from urllib.parse import urlparse
+        from starlette.middleware.cors import CORSMiddleware
+        from mcp.server.transport_security import TransportSecuritySettings
+
+        _configure_auth()
+        host = os.environ.get("MAILERBOT_MCP_HOST", "0.0.0.0")
+        port = int(os.environ.get("MAILERBOT_MCP_PORT", "8080"))
+
+        # Configure transport security to allow the public-facing hostname.
+        # Behind an ALB the Host header is the public domain, not localhost.
+        mcp_url = os.environ.get("MAILERBOT_MCP_URL", "http://localhost:8080")
+        parsed = urlparse(mcp_url)
+        mcp.settings.transport_security = TransportSecuritySettings(
+            enable_dns_rebinding_protection=True,
+            allowed_hosts=[
+                parsed.netloc,          # e.g. "mcp.mailerbot.com" or "localhost:8080"
+                "127.0.0.1:*",
+                "localhost:*",
+            ],
+            allowed_origins=["*"],
+        )
+
+        # Get the ASGI app from FastMCP and wrap with CORS middleware.
+        # This ensures OPTIONS preflight requests are handled before the
+        # auth middleware rejects them with 401.
+        if transport == "streamable-http":
+            app = mcp.streamable_http_app()
+        else:
+            app = mcp.sse_app()
+
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+        uvicorn.run(app, host=host, port=port)
+    else:
+        mcp.run(transport="stdio")
+
+
+__all__ = ["main", "mcp"]

mailerbot_mcp-0.1.0/src/mailerbot_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m mailerbot_mcp` or `uv run mailerbot-mcp`."""
+
+from mailerbot_mcp import main
+
+main()

mailerbot_mcp-0.1.0/src/mailerbot_mcp/auth.py

@@ -0,0 +1,123 @@
+"""Token verification for the MailerBot MCP server.
+
+In SSE/streamable-http mode, MCP clients authenticate via OAuth against the
+MailerBot backend.  The MCP server acts as a Resource Server (RS) — it
+validates incoming bearer tokens by calling the backend's ``/api/v1/auth/me``
+endpoint.  If the backend returns the user profile, the token is valid.
+
+Verified tokens are cached in memory (keyed by token hash) to avoid a
+backend round-trip on every MCP tool invocation.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import os
+import time
+
+import httpx
+
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+
+logger = logging.getLogger(__name__)
+
+# Cache verified tokens for up to 5 minutes to reduce backend round-trips.
+_TOKEN_CACHE_TTL = 300
+_token_cache: dict[str, tuple[AccessToken, float]] = {}
+
+
+class MailerBotTokenVerifier(TokenVerifier):
+    """Verify bearer tokens by calling the MailerBot backend."""
+
+    def __init__(self, api_base_url: str | None = None):
+        self.api_base_url = (api_base_url or os.environ.get(
+            "MAILERBOT_API_URL", "https://api.mailerbot.com/api/v1"
+        )).rstrip("/")
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify a bearer token against the MailerBot backend.
+
+        Checks the local cache first; if not cached, calls GET
+        /api/v1/auth/me with the token.  Valid tokens are cached to avoid
+        repeated round-trips for the same session.
+        """
+        # Check cache first
+        cache_key = hashlib.sha256(token.encode()).hexdigest()[:16]
+        cached = _token_cache.get(cache_key)
+        if cached is not None:
+            access_token, cached_at = cached
+            if time.monotonic() - cached_at < _TOKEN_CACHE_TTL:
+                return access_token
+            else:
+                del _token_cache[cache_key]
+
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(
+                    f"{self.api_base_url}/auth/me",
+                    headers={"Authorization": f"Bearer {token}"},
+                )
+
+                if resp.status_code != 200:
+                    logger.debug("Token verification failed: %s", resp.status_code)
+                    return None
+
+                user_data = resp.json()
+
+                scopes = _extract_scopes_from_jwt(token)
+                expires_at = _extract_exp_from_jwt(token)
+
+                access_token = AccessToken(
+                    token=token,
+                    client_id=user_data.get("id", "unknown"),
+                    scopes=scopes,
+                    expires_at=expires_at,
+                )
+
+                # Cache the verified token
+                _token_cache[cache_key] = (access_token, time.monotonic())
+
+                return access_token
+
+        except httpx.HTTPError as exc:
+            logger.error("Token verification HTTP error: %s", exc)
+            return None
+        except Exception as exc:
+            logger.error("Token verification error: %s", exc)
+            return None
+
+
+def _decode_jwt_payload(token: str) -> dict | None:
+    """Decode JWT payload without signature verification.
+
+    The backend already validated the token — we just need the claims.
+    """
+    try:
+        payload_b64 = token.split(".")[1]
+        # Add padding
+        padding = 4 - len(payload_b64) % 4
+        if padding != 4:
+            payload_b64 += "=" * padding
+        return json.loads(base64.urlsafe_b64decode(payload_b64))
+    except Exception:
+        return None
+
+
+def _extract_scopes_from_jwt(token: str) -> list[str]:
+    """Extract scopes from a JWT."""
+    payload = _decode_jwt_payload(token)
+    return payload.get("scopes", []) if payload else []
+
+
+def _extract_exp_from_jwt(token: str) -> int | None:
+    """Extract expiration from a JWT."""
+    payload = _decode_jwt_payload(token)
+    if not payload:
+        return None
+    exp = payload.get("exp")
+    if exp is None:
+        logger.warning("JWT has no exp claim — token refresh may not work correctly")
+    return exp