zerocommerce-mcp 0.1.0__py3-none-any.whl

zerocommerce_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""ZeroCommerce MCP Server — natural language commerce management."""
+
+__version__ = "0.1.0"

zerocommerce_mcp/auth.py

@@ -0,0 +1,93 @@
+"""API key validation for store-scoped MCP authentication (Refs #382).
+
+Phase 1 (legacy): single admin API key from environment variable.
+Phase 2 (current): per-store scoped keys (``zc_live_*``) verified via
+the internal ``/api/v1/internal/store-api-keys/verify`` endpoint.
+Falls back to the admin key if the presented key is not a store key.
+
+When a store-scoped key is used, the ``store_slug`` is automatically
+derived from the key and passed to all tool calls so the merchant does
+not need to provide it manually.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+import httpx
+
+
+# Key prefix that identifies store-scoped keys
+_STORE_KEY_PREFIX = "zc_live_"
+
+
+@dataclass(frozen=True)
+class StoreContext:
+    """Resolved store identity from a verified store-scoped API key."""
+    store_id: str
+    store_slug: str
+    scopes: list[str]
+
+
+def get_api_key() -> str:
+    """Return the configured ZeroCommerce API key.
+
+    Raises ValueError if the key is not set so server startup fails
+    fast with a clear message.
+    """
+    key = os.environ.get("ZEROCOMMERCE_API_KEY", "")
+    if not key:
+        raise ValueError(
+            "ZEROCOMMERCE_API_KEY environment variable is required. "
+            "Set it to a valid ZeroCommerce admin or store API key."
+        )
+    return key
+
+
+def is_store_key(key: str) -> bool:
+    """Return True if the key looks like a store-scoped key (``zc_live_*``)."""
+    return key.startswith(_STORE_KEY_PREFIX)
+
+
+async def verify_store_key(
+    raw_key: str,
+    base_url: Optional[str] = None,
+) -> Optional[StoreContext]:
+    """Verify a store-scoped API key via the internal verification endpoint.
+
+    Returns a ``StoreContext`` on success, ``None`` on any failure.
+    """
+    url = (
+        base_url
+        or os.environ.get("ZEROCOMMERCE_API_URL", "")
+    ).rstrip("/")
+
+    if not url:
+        return None
+
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            resp = await client.post(
+                f"{url}/api/v1/internal/store-api-keys/verify",
+                json={"raw_key": raw_key},
+            )
+            if resp.status_code != 200:
+                return None
+            data = resp.json()
+            return StoreContext(
+                store_id=data["store_id"],
+                store_slug=data["store_slug"],
+                scopes=data.get("scopes", []),
+            )
+    except (httpx.HTTPError, KeyError, ValueError):
+        return None
+
+
+def validate_store_slug(slug: str) -> str:
+    """Basic validation for store slug format."""
+    slug = slug.strip().lower()
+    if not slug or len(slug) < 3 or len(slug) > 64:
+        raise ValueError(f"Invalid store slug: '{slug}'. Must be 3-64 characters.")
+    return slug

zerocommerce_mcp/client.py

@@ -0,0 +1,116 @@
+"""Async HTTP client wrapper for the ZeroCommerce REST API.
+
+All MCP tools delegate to this client rather than implementing business
+logic themselves.  Errors are caught and returned as human-readable
+strings so the LLM always gets a usable response.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import httpx
+
+
+class ZeroCommerceClient:
+    """Thin async wrapper around the ZeroCommerce API."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = (
+            base_url
+            or os.environ.get("ZEROCOMMERCE_API_URL", "")
+        ).rstrip("/")
+        self.api_key = api_key or os.environ.get("ZEROCOMMERCE_API_KEY", "")
+        self.timeout = timeout
+        self._client: Optional[httpx.AsyncClient] = None
+
+    async def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers={
+                    "X-API-Key": self.api_key,
+                    "Content-Type": "application/json",
+                },
+                timeout=self.timeout,
+            )
+        return self._client
+
+    async def close(self) -> None:
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()
+
+    # ----- HTTP helpers -----
+
+    async def _handle_response(self, resp: httpx.Response) -> Any:
+        """Parse response or raise a human-readable error string."""
+        if resp.status_code in (401, 403):
+            raise ApiError("Authentication failed. Check your API key.")
+        if resp.status_code == 404:
+            raise ApiError(f"Not found: {resp.url.path}")
+        if resp.status_code == 422:
+            detail = resp.json().get("detail", resp.text)
+            raise ApiError(f"Validation error: {detail}")
+        if resp.status_code >= 400:
+            raise ApiError(f"API error {resp.status_code}: {resp.text[:300]}")
+        if resp.status_code == 204:
+            return {"ok": True}
+        return resp.json()
+
+    async def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        client = await self._ensure_client()
+        try:
+            resp = await client.get(path, params=_clean_params(params))
+            return await self._handle_response(resp)
+        except httpx.HTTPError as exc:
+            raise ApiError(f"Service unavailable. Try again. ({exc})")
+
+    async def post(self, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        client = await self._ensure_client()
+        try:
+            resp = await client.post(path, json=body or {})
+            return await self._handle_response(resp)
+        except httpx.HTTPError as exc:
+            raise ApiError(f"Service unavailable. Try again. ({exc})")
+
+    async def put(self, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        client = await self._ensure_client()
+        try:
+            resp = await client.put(path, json=body or {})
+            return await self._handle_response(resp)
+        except httpx.HTTPError as exc:
+            raise ApiError(f"Service unavailable. Try again. ({exc})")
+
+    async def patch(self, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        client = await self._ensure_client()
+        try:
+            resp = await client.patch(path, json=body or {})
+            return await self._handle_response(resp)
+        except httpx.HTTPError as exc:
+            raise ApiError(f"Service unavailable. Try again. ({exc})")
+
+    async def delete(self, path: str) -> Any:
+        client = await self._ensure_client()
+        try:
+            resp = await client.delete(path)
+            return await self._handle_response(resp)
+        except httpx.HTTPError as exc:
+            raise ApiError(f"Service unavailable. Try again. ({exc})")
+
+
+class ApiError(Exception):
+    """Human-readable API error surfaced to the LLM."""
+    pass
+
+
+def _clean_params(params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Strip None values so httpx doesn't send `?key=None`."""
+    if params is None:
+        return None
+    return {k: v for k, v in params.items() if v is not None}