mcp-simplr 0.1.0__tar.gz

mcp_simplr-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: mcp-simplr
+Version: 0.1.0
+Summary: Simplr client library for MCP services
+Author-email: contact@mcp-simplr.au
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+
+# mcp-simplr
+
+Python client library for [MCP Simplr](https://mcp-simplr.au) — payments, emailing, and auth for MCP services.
+
+## Installation
+
+```bash
+pip install mcp-simplr
+```
+
+## Payments
+
+Customers register once on the platform and receive a `customer_token`. MCP owners accept this token from their users and pass it to `charge()` — no customer registration code needed on your end.
+
+### Token billing — charge per output token
+
+Best for AI tools where cost scales with usage.
+
+```python
+from mcp_simplr import MCPPayments, PaymentConfig, PaymentModel
+
+payments = MCPPayments(PaymentConfig(
+    api_key="simplr_owner_...",
+    payment_model=PaymentModel.TOKEN,
+    price_per_token=0.000_5,   # AUD per output token
+    currency="aud",
+    environment="production",
+))
+
+# Charge explicitly
+await payments.charge(customer_token, tokens=500)
+
+# Or use the decorator — counts tokens and charges automatically
+@payments.track_usage(customer_id="<customer-token>")
+async def my_tool(query: str) -> str:
+    return await run_model(query)
+
+# Dynamic customer token from request payload
+@payments.track_usage(customer_id_key="customer_token")
+async def my_tool(query: str, customer_token: str) -> str:
+    return await run_model(query)
+```
+
+### Fixed billing — charge a set amount per call
+
+Best for tools with a predictable cost per request.
+
+```python
+from mcp_simplr import MCPPayments, PaymentConfig, PaymentModel
+
+payments = MCPPayments(PaymentConfig(
+    api_key="simplr_owner_...",
+    payment_model=PaymentModel.FIXED,
+    currency="aud",
+    environment="production",
+))
+
+await payments.charge(
+    customer_token,
+    amount_cents=500,           # AUD $5.00
+    description="Property report",
+)
+```
+
+### Recurring billing — subscription plans
+
+Best for services with ongoing access (monthly/yearly).
+
+```python
+from mcp_simplr import MCPPayments, PaymentConfig, PaymentModel, PlanConfig, BillingInterval
+
+payments = MCPPayments(PaymentConfig(
+    api_key="simplr_owner_...",
+    payment_model=PaymentModel.RECURRING,
+    currency="aud",
+    environment="production",
+    plans=[
+        PlanConfig(id="basic", name="Basic", amount=999, interval=BillingInterval.MONTH),
+        PlanConfig(id="pro",   name="Pro",   amount=2999, interval=BillingInterval.MONTH),
+    ],
+))
+
+# Subscribe a customer to a plan
+await payments.charge(customer_token, plan_id="pro")
+
+# Cancel a subscription
+payments.cancel_subscription(customer_token, plan_id="pro")
+
+# List available plans
+plans = payments.list_plans()
+```
+
+### Charge history
+
+```python
+history = await payments.get_charges(customer_token)
+history = await payments.get_charges(customer_token, from_date="2026-06-01", to_date="2026-06-30")
+```
+
+### Testing
+
+Use `MCPPayments.TEST_CUSTOMER_TOKEN` in sandbox mode to test the full charge flow without a real customer:
+
+```python
+await payments.charge(MCPPayments.TEST_CUSTOMER_TOKEN, tokens=500)
+```
+
+---
+
+## Emailing
+
+Send emails to your users from your branded `slug@mcp-simplr.au` address. Subscribe to the email service on the platform website first, then use this client to send.
+
+This is a **no-reply, unidirectional** service — emails are sent from your address but replies from users are not forwarded back to you. It is intended for outbound notifications, reports, and updates only.
+
+```python
+from mcp_simplr import MCPEmail, EmailServiceConfig
+
+email = MCPEmail(EmailServiceConfig(
+    api_key="simplr_owner_...",
+    service_slug="property-ai",   # → property-ai@mcp-simplr.au
+    environment="production",
+))
+
+await email.send(
+    to="customer@example.com",
+    subject="Your property report is ready",
+    body="Hi Sarah, your report for 123 Main St is attached.",
+)
+```
+
+---
+
+## Auth
+
+Verify that a customer token is valid before your MCP tool runs.
+
+```python
+from mcp_simplr import MCPAuth, AuthConfig
+
+auth = MCPAuth(AuthConfig(
+    api_key="simplr_owner_...",
+    service_slug="property-ai",
+    environment="production",
+))
+
+# Decorator — verifies token before the function runs
+@auth.require(customer_token_key="customer_token")
+async def search_properties(query: str, customer_token: str) -> str:
+    return await do_search(query)
+
+# Or verify explicitly — raises AuthenticationError on failure
+customer = await auth.verify(customer_token)
+# {"customer_id": "...", "email": "...", "name": "..."}
+```
+
+---
+
+## Support
+
+Contact us at [contact@mcp-simplr.au](mailto:contact@mcp-simplr.au)

mcp_simplr-0.1.0/README.md

@@ -0,0 +1,161 @@
+# mcp-simplr
+
+Python client library for [MCP Simplr](https://mcp-simplr.au) — payments, emailing, and auth for MCP services.
+
+## Installation
+
+```bash
+pip install mcp-simplr
+```
+
+## Payments
+
+Customers register once on the platform and receive a `customer_token`. MCP owners accept this token from their users and pass it to `charge()` — no customer registration code needed on your end.
+
+### Token billing — charge per output token
+
+Best for AI tools where cost scales with usage.
+
+```python
+from mcp_simplr import MCPPayments, PaymentConfig, PaymentModel
+
+payments = MCPPayments(PaymentConfig(
+    api_key="simplr_owner_...",
+    payment_model=PaymentModel.TOKEN,
+    price_per_token=0.000_5,   # AUD per output token
+    currency="aud",
+    environment="production",
+))
+
+# Charge explicitly
+await payments.charge(customer_token, tokens=500)
+
+# Or use the decorator — counts tokens and charges automatically
+@payments.track_usage(customer_id="<customer-token>")
+async def my_tool(query: str) -> str:
+    return await run_model(query)
+
+# Dynamic customer token from request payload
+@payments.track_usage(customer_id_key="customer_token")
+async def my_tool(query: str, customer_token: str) -> str:
+    return await run_model(query)
+```
+
+### Fixed billing — charge a set amount per call
+
+Best for tools with a predictable cost per request.
+
+```python
+from mcp_simplr import MCPPayments, PaymentConfig, PaymentModel
+
+payments = MCPPayments(PaymentConfig(
+    api_key="simplr_owner_...",
+    payment_model=PaymentModel.FIXED,
+    currency="aud",
+    environment="production",
+))
+
+await payments.charge(
+    customer_token,
+    amount_cents=500,           # AUD $5.00
+    description="Property report",
+)
+```
+
+### Recurring billing — subscription plans
+
+Best for services with ongoing access (monthly/yearly).
+
+```python
+from mcp_simplr import MCPPayments, PaymentConfig, PaymentModel, PlanConfig, BillingInterval
+
+payments = MCPPayments(PaymentConfig(
+    api_key="simplr_owner_...",
+    payment_model=PaymentModel.RECURRING,
+    currency="aud",
+    environment="production",
+    plans=[
+        PlanConfig(id="basic", name="Basic", amount=999, interval=BillingInterval.MONTH),
+        PlanConfig(id="pro",   name="Pro",   amount=2999, interval=BillingInterval.MONTH),
+    ],
+))
+
+# Subscribe a customer to a plan
+await payments.charge(customer_token, plan_id="pro")
+
+# Cancel a subscription
+payments.cancel_subscription(customer_token, plan_id="pro")
+
+# List available plans
+plans = payments.list_plans()
+```
+
+### Charge history
+
+```python
+history = await payments.get_charges(customer_token)
+history = await payments.get_charges(customer_token, from_date="2026-06-01", to_date="2026-06-30")
+```
+
+### Testing
+
+Use `MCPPayments.TEST_CUSTOMER_TOKEN` in sandbox mode to test the full charge flow without a real customer:
+
+```python
+await payments.charge(MCPPayments.TEST_CUSTOMER_TOKEN, tokens=500)
+```
+
+---
+
+## Emailing
+
+Send emails to your users from your branded `slug@mcp-simplr.au` address. Subscribe to the email service on the platform website first, then use this client to send.
+
+This is a **no-reply, unidirectional** service — emails are sent from your address but replies from users are not forwarded back to you. It is intended for outbound notifications, reports, and updates only.
+
+```python
+from mcp_simplr import MCPEmail, EmailServiceConfig
+
+email = MCPEmail(EmailServiceConfig(
+    api_key="simplr_owner_...",
+    service_slug="property-ai",   # → property-ai@mcp-simplr.au
+    environment="production",
+))
+
+await email.send(
+    to="customer@example.com",
+    subject="Your property report is ready",
+    body="Hi Sarah, your report for 123 Main St is attached.",
+)
+```
+
+---
+
+## Auth
+
+Verify that a customer token is valid before your MCP tool runs.
+
+```python
+from mcp_simplr import MCPAuth, AuthConfig
+
+auth = MCPAuth(AuthConfig(
+    api_key="simplr_owner_...",
+    service_slug="property-ai",
+    environment="production",
+))
+
+# Decorator — verifies token before the function runs
+@auth.require(customer_token_key="customer_token")
+async def search_properties(query: str, customer_token: str) -> str:
+    return await do_search(query)
+
+# Or verify explicitly — raises AuthenticationError on failure
+customer = await auth.verify(customer_token)
+# {"customer_id": "...", "email": "...", "name": "..."}
+```
+
+---
+
+## Support
+
+Contact us at [contact@mcp-simplr.au](mailto:contact@mcp-simplr.au)

mcp_simplr-0.1.0/mcp_simplr/__init__.py

@@ -0,0 +1,50 @@
+from mcp_simplr.payments.client import MCPPayments
+from mcp_simplr.email.client import MCPEmail
+from mcp_simplr.auth.client import MCPAuth
+from mcp_simplr.config import (
+    PaymentConfig,
+    PlanConfig,
+    EmailServiceConfig,
+    AuthConfig,
+    PaymentModel,
+    Environment,
+    Currency,
+    BillingInterval,
+)
+from mcp_simplr.exceptions import (
+    MCPPaymentError,
+    ConfigurationError,
+    CustomerNotFoundError,
+    PaymentFailedError,
+    InsufficientPaymentMethodError,
+    PlanNotFoundError,
+    MCPAuthError,
+    AuthenticationError,
+)
+
+__all__ = [
+    # Payments
+    "MCPPayments",
+    "PaymentConfig",
+    "PlanConfig",
+    # Enums
+    "PaymentModel",
+    "Environment",
+    "Currency",
+    "BillingInterval",
+    # Email service
+    "MCPEmail",
+    "EmailServiceConfig",
+    # Auth + rate limit
+    "MCPAuth",
+    "AuthConfig",
+    # Exceptions
+    "MCPPaymentError",
+    "ConfigurationError",
+    "CustomerNotFoundError",
+    "PaymentFailedError",
+    "InsufficientPaymentMethodError",
+    "PlanNotFoundError",
+    "MCPAuthError",
+    "AuthenticationError",
+]

mcp_simplr-0.1.0/mcp_simplr/api/client.py

@@ -0,0 +1,55 @@
+import httpx
+
+from mcp_simplr.exceptions import MCPPaymentError, PaymentFailedError
+
+
+class APIClient:
+    """
+    HTTP client that talks to the mcp-payments backend.
+    Uses sync httpx for setup calls (register_customer, subscribe)
+    and async httpx for per-request charges so the event loop is never blocked.
+    """
+
+    def __init__(self, api_key: str, base_url: str, environment: str = "sandbox"):
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "X-Stripe-Environment": environment,
+        }
+        self._base_url = base_url.rstrip("/")
+
+    # ------------------------------------------------------------------
+    # Sync — used at server startup (register_customer, subscribe, cancel)
+    # ------------------------------------------------------------------
+
+    def post(self, path: str, body: dict) -> dict:
+        with httpx.Client(headers=self._headers, timeout=30) as client:
+            return self._handle(client.post(f"{self._base_url}{path}", json=body))
+
+    def delete(self, path: str) -> dict:
+        with httpx.Client(headers=self._headers, timeout=30) as client:
+            return self._handle(client.delete(f"{self._base_url}{path}"))
+
+    # ------------------------------------------------------------------
+    # Async — used on every MCP request (charge)
+    # ------------------------------------------------------------------
+
+    async def apost(self, path: str, body: dict) -> dict:
+        async with httpx.AsyncClient(headers=self._headers, timeout=30) as client:
+            return self._handle(await client.post(f"{self._base_url}{path}", json=body))
+
+    async def aget(self, path: str, params: dict | None = None) -> dict:
+        async with httpx.AsyncClient(headers=self._headers, timeout=30) as client:
+            return self._handle(await client.get(f"{self._base_url}{path}", params=params))
+
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _handle(response: httpx.Response) -> dict:
+        try:
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as e:
+            detail = e.response.json().get("detail", str(e)) if e.response.content else str(e)
+            raise PaymentFailedError(detail)
+        except httpx.RequestError as e:
+            raise MCPPaymentError(f"Could not reach mcp-payments backend: {e}")

mcp_simplr-0.1.0/mcp_simplr/auth/__init__.py

@@ -0,0 +1,4 @@
+from mcp_simplr.auth.client import MCPAuth
+from mcp_simplr.config import AuthConfig
+
+__all__ = ["MCPAuth", "AuthConfig"]

mcp_simplr-0.1.0/mcp_simplr/auth/client.py

@@ -0,0 +1,84 @@
+import functools
+
+import httpx
+
+from mcp_simplr.config import AuthConfig
+from mcp_simplr.exceptions import AuthenticationError
+
+
+class MCPAuth:
+    """
+    Authentication client for MCP owners.
+
+    Verifies that a customer_token is valid before your MCP tool runs.
+
+    Subscription is managed via the platform website — not through this library.
+    Once subscribed, use verify() or the @require decorator in every tool.
+
+    Usage:
+        from mcp_simplr import MCPAuth, AuthConfig
+
+        auth = MCPAuth(AuthConfig(
+            api_key="simplr_owner_xxx",
+            service_slug="property-ai",
+        ))
+
+        # Decorator — auto-verifies before the function runs
+        @auth.require(customer_token_key="customer_token")
+        async def my_tool(query: str, customer_token: str) -> str:
+            return await do_work(query)
+
+        # Or explicit — raises AuthenticationError on failure
+        customer = await auth.verify(customer_token)
+        # customer = {"customer_id": "...", "email": "...", "name": "..."}
+    """
+
+    def __init__(self, config: AuthConfig) -> None:
+        self._config = config
+        self._headers = {
+            "Authorization": f"Bearer {config.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    async def verify(self, customer_token: str) -> dict:
+        """
+        Verify a customer token.
+
+        Returns {"customer_id": str, "email": str, "name": str | None} on success.
+        Raises AuthenticationError if the token is invalid.
+        """
+        async with httpx.AsyncClient(timeout=10) as client:
+            res = await client.post(
+                f"{self._config.api_base}/v1/auth-service/verify",
+                headers=self._headers,
+                json={
+                    "service_slug": self._config.service_slug,
+                    "customer_token": customer_token,
+                },
+            )
+
+        if res.status_code == 401:
+            raise AuthenticationError(res.json().get("detail", "Invalid customer token"))
+        res.raise_for_status()
+        return res.json()
+
+    def require(self, customer_token_key: str = "customer_token"):
+        """
+        Decorator that verifies the customer token before the function runs.
+
+        The decorated function must accept the token as a keyword argument
+        matching customer_token_key (default: "customer_token").
+        """
+        def decorator(fn):
+            @functools.wraps(fn)
+            async def wrapper(*args, **kwargs):
+                token = kwargs.get(customer_token_key)
+                if not token:
+                    raise AuthenticationError(
+                        f"Missing '{customer_token_key}' argument — "
+                        "pass the customer's simplr_ token to this tool."
+                    )
+                await self.verify(token)
+                return await fn(*args, **kwargs)
+            return wrapper
+        return decorator

mcp_simplr-0.1.0/mcp_simplr/billing/fixed.py

@@ -0,0 +1,32 @@
+_STRIPE_MIN_CENTS = 50
+
+
+class FixedBilling:
+    """
+    One-time fixed-price billing. The MCP owner calculates the cost and calls
+    charge() explicitly. customer_id is the platform UUID from /v1/customers/register.
+    """
+
+    def __init__(self, config, api_client):
+        self.config = config
+        self._api = api_client
+
+    async def charge(self, customer_id: str, amount_cents: int, description: str = "") -> dict | None:
+        """
+        Charge the customer a fixed amount calculated by the MCP owner.
+        Returns the charge result dict, or None if below Stripe's minimum.
+        """
+        if amount_cents < _STRIPE_MIN_CENTS:
+            return None
+
+        return await self._api.apost(
+            "/v1/charge",
+            {
+                "customer_token": customer_id,
+                "amount_cents": amount_cents,
+                "currency": self.config.currency,
+                "description": description,
+                "service_name": self.config.service_name,
+                "service_description": self.config.service_description,
+            },
+        )

mcp_simplr-0.1.0/mcp_simplr/billing/recurring.py

@@ -0,0 +1,70 @@
+from mcp_simplr.exceptions import PlanNotFoundError
+
+
+class RecurringBilling:
+    """
+    Recurring subscription billing. The MCP owner defines plans and Stripe handles
+    automatic charges on each billing cycle. customer_id is the platform UUID
+    from /v1/customers/register.
+    """
+
+    def __init__(self, config, api_client):
+        self.config = config
+        self._api = api_client
+        # customer_id -> {plan_id, stripe_sub_id} — tracked in memory for cancel()
+        self._subscriptions: dict[str, dict] = {}
+
+    async def subscribe(self, customer_id: str, plan_id: str) -> str:
+        """
+        Subscribe a customer to a recurring plan via the backend.
+        Returns the Stripe Subscription ID.
+        """
+        plan = self._resolve_plan(plan_id)
+        result = await self._api.apost(
+            "/v1/subscriptions",
+            {
+                "customer_token": customer_id,
+                "plan": {
+                    "id": plan.id,
+                    "name": plan.name,
+                    "amount": plan.amount,
+                    "currency": self.config.currency,
+                    "interval": plan.interval,
+                    "description": plan.description,
+                },
+            },
+        )
+        self._subscriptions[customer_id] = {
+            "plan_id": plan_id,
+            "stripe_sub_id": result["stripe_subscription_id"],
+        }
+        return result["stripe_subscription_id"]
+
+    def cancel(self, customer_id: str, plan_id: str) -> None:
+        sub = self._subscriptions.get(customer_id)
+        if not sub or sub["plan_id"] != plan_id:
+            raise KeyError(
+                f"No active subscription found for customer '{customer_id}' on plan '{plan_id}'. "
+                "subscribe() must be called in the same process before cancel()."
+            )
+        self._api.delete(f"/v1/subscriptions/{sub['stripe_sub_id']}")
+        del self._subscriptions[customer_id]
+
+    def list_plans(self) -> list[dict]:
+        return [
+            {
+                "id": p.id,
+                "name": p.name,
+                "amount": p.amount,
+                "currency": self.config.currency.upper(),
+                "interval": p.interval,
+                "description": p.description,
+            }
+            for p in self.config.plans
+        ]
+
+    def _resolve_plan(self, plan_id: str):
+        for plan in self.config.plans:
+            if plan.id == plan_id:
+                return plan
+        raise PlanNotFoundError(f"Plan '{plan_id}' not found in config")

mcp_simplr-0.1.0/mcp_simplr/billing/token.py

@@ -0,0 +1,34 @@
+_STRIPE_MIN_CENTS = 50
+
+
+class TokenBilling:
+    """
+    Per-request billing charged by output tokens. Every tracked MCP call immediately
+    fires a charge through the platform backend using the customer's platform UUID.
+    """
+
+    def __init__(self, config, api_client):
+        self.config = config
+        self._api = api_client
+
+    async def charge_for_request(self, customer_id: str, tokens: int) -> dict | None:
+        """
+        Calculate cost and immediately charge the customer via the backend.
+        customer_id is the platform UUID from /v1/customers/register.
+        Returns the charge result dict, or None if below Stripe's minimum.
+        """
+        amount_cents = int(tokens * self.config.price_per_token * 100)
+        if amount_cents < _STRIPE_MIN_CENTS:
+            return None
+
+        return await self._api.apost(
+            "/v1/charge",
+            {
+                "customer_token": customer_id,
+                "amount_cents": amount_cents,
+                "currency": self.config.currency,
+                "description": f"MCP request — {tokens:,} output tokens",
+                "service_name": self.config.service_name,
+                "service_description": self.config.service_description,
+            },
+        )