pocketsmith-mcp 1.0.0__py3-none-any.whl

pocketsmith_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""PocketSmith MCP Server - Production-ready MCP server for PocketSmith API."""
+
+__version__ = "1.0.0"
+__author__ = "PocketSmith MCP"
+
+from pocketsmith_mcp.server import create_server
+
+__all__ = ["create_server", "__version__"]

pocketsmith_mcp/__main__.py

@@ -0,0 +1,19 @@
+"""Entry point for pocketsmith-mcp server.
+
+This module allows running the server as:
+    python -m pocketsmith_mcp
+    uvx pocketsmith-mcp
+    uv run pocketsmith-mcp
+"""
+
+from pocketsmith_mcp.server import get_server
+
+
+def main() -> None:
+    """Run the PocketSmith MCP server."""
+    server = get_server()
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

pocketsmith_mcp/client/__init__.py

@@ -0,0 +1,14 @@
+"""PocketSmith API client with retry, rate limiting, and circuit breaker."""
+
+from pocketsmith_mcp.client.api_client import PocketSmithClient
+from pocketsmith_mcp.client.circuit_breaker import CircuitBreaker, CircuitState
+from pocketsmith_mcp.client.rate_limiter import RateLimiter
+from pocketsmith_mcp.client.retry import retry_with_backoff
+
+__all__ = [
+    "CircuitBreaker",
+    "CircuitState",
+    "PocketSmithClient",
+    "RateLimiter",
+    "retry_with_backoff",
+]

pocketsmith_mcp/client/api_client.py

@@ -0,0 +1,269 @@
+"""Async HTTP client for PocketSmith API with retry, rate limiting, circuit breaker."""
+
+from typing import Any
+
+import httpx
+
+from pocketsmith_mcp.client.circuit_breaker import CircuitBreaker
+from pocketsmith_mcp.client.rate_limiter import RateLimiter
+from pocketsmith_mcp.client.retry import retry_with_backoff
+from pocketsmith_mcp.errors import APIError, AuthError, CircuitBreakerOpenError, RateLimitError
+from pocketsmith_mcp.logger import get_logger
+
+logger = get_logger("api_client")
+
+
+class PocketSmithClient:
+    """
+    Production-ready async client for PocketSmith API v2.
+
+    Features:
+    - Rate limiting (token bucket algorithm)
+    - Retry with exponential backoff and jitter
+    - Circuit breaker for fault tolerance
+    - Comprehensive error handling
+    """
+
+    BASE_URL = "https://api.pocketsmith.com/v2"
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        rate_limit_per_minute: int = 60,
+    ):
+        """
+        Initialize the PocketSmith API client.
+
+        Args:
+            api_key: PocketSmith API key (X-Developer-Key)
+            base_url: API base URL (default: https://api.pocketsmith.com/v2)
+            timeout: Request timeout in seconds
+            max_retries: Maximum retry attempts for failed requests
+            rate_limit_per_minute: Maximum requests per minute
+        """
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self.api_key = api_key
+        self.base_url = base_url or self.BASE_URL
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={
+                "X-Developer-Key": api_key,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+        )
+
+        self._rate_limiter = RateLimiter(
+            tokens_per_interval=rate_limit_per_minute,
+            interval_seconds=60,
+        )
+
+        self._circuit_breaker = CircuitBreaker(
+            failure_threshold=5,
+            reset_timeout_seconds=60,
+        )
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[Any]:
+        """
+        Make an authenticated API request with retry, rate limiting, and circuit breaker.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE)
+            path: API endpoint path
+            params: Query parameters
+            json_data: JSON request body
+
+        Returns:
+            Parsed JSON response
+
+        Raises:
+            AuthError: Authentication failed (401)
+            RateLimitError: Rate limit exceeded (429)
+            APIError: Other API errors
+            CircuitBreakerOpenError: Circuit breaker is open
+        """
+        # Check circuit breaker
+        if not self._circuit_breaker.can_execute():
+            raise CircuitBreakerOpenError()
+
+        # Rate limiting
+        await self._rate_limiter.acquire()
+
+        async def execute_request() -> dict[str, Any] | list[Any]:
+            # Clean up params - remove None values
+            clean_params = None
+            if params:
+                clean_params = {k: v for k, v in params.items() if v is not None}
+
+            logger.debug(f"Request: {method} {path} params={clean_params}")
+
+            response = await self._client.request(
+                method=method,
+                url=path,
+                params=clean_params,
+                json=json_data,
+            )
+
+            logger.debug(f"Response: {response.status_code}")
+
+            # Handle errors
+            if response.status_code == 401:
+                raise AuthError("Invalid API key")
+
+            if response.status_code == 429:
+                retry_after = response.headers.get("Retry-After", "60")
+                raise RateLimitError(
+                    f"Rate limit exceeded. Retry after {retry_after}s",
+                    retry_after=int(retry_after),
+                )
+
+            if response.status_code >= 500:
+                self._circuit_breaker.record_failure()
+                raise APIError(
+                    f"Server error: {response.status_code}",
+                    status_code=response.status_code,
+                    response_body=response.text,
+                )
+
+            if response.status_code >= 400:
+                error_body = response.text
+                try:
+                    error_json = response.json()
+                    if "error" in error_json:
+                        error_body = error_json["error"]
+                except Exception:
+                    pass
+                raise APIError(
+                    f"Client error: {response.status_code}",
+                    status_code=response.status_code,
+                    response_body=error_body,
+                )
+
+            # Record success
+            self._circuit_breaker.record_success()
+
+            # Handle empty responses
+            if response.status_code == 204:
+                return {}
+
+            result: dict[str, Any] | list[Any] = response.json()
+            return result
+
+        # Retry with backoff for retryable errors
+        return await retry_with_backoff(
+            execute_request,
+            max_attempts=self.max_retries,
+            base_delay=1.0,
+            max_delay=30.0,
+            retryable_errors=(httpx.TimeoutException, httpx.NetworkError),
+        )
+
+    async def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[Any]:
+        """
+        Make a GET request.
+
+        Args:
+            path: API endpoint path
+            params: Query parameters
+
+        Returns:
+            Parsed JSON response
+        """
+        return await self._request("GET", path, params=params)
+
+    async def post(
+        self,
+        path: str,
+        json_data: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[Any]:
+        """
+        Make a POST request.
+
+        Args:
+            path: API endpoint path
+            json_data: JSON request body
+
+        Returns:
+            Parsed JSON response
+        """
+        return await self._request("POST", path, json_data=json_data)
+
+    async def put(
+        self,
+        path: str,
+        json_data: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[Any]:
+        """
+        Make a PUT request.
+
+        Args:
+            path: API endpoint path
+            json_data: JSON request body
+
+        Returns:
+            Parsed JSON response
+        """
+        return await self._request("PUT", path, json_data=json_data)
+
+    async def delete(self, path: str) -> dict[str, Any] | list[Any]:
+        """
+        Make a DELETE request.
+
+        Args:
+            path: API endpoint path
+
+        Returns:
+            Parsed JSON response (usually empty)
+        """
+        return await self._request("DELETE", path)
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "PocketSmithClient":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Async context manager exit."""
+        await self.close()
+
+    def get_stats(self) -> dict[str, Any]:
+        """
+        Get client statistics.
+
+        Returns:
+            Dictionary with rate limiter and circuit breaker stats
+        """
+        return {
+            "rate_limiter": {
+                "available_tokens": self._rate_limiter.available_tokens,
+                "max_tokens": self._rate_limiter.max_tokens,
+            },
+            "circuit_breaker": self._circuit_breaker.get_stats(),
+        }

pocketsmith_mcp/client/circuit_breaker.py

@@ -0,0 +1,179 @@
+"""Circuit breaker pattern for fault tolerance."""
+
+import time
+from enum import Enum
+from threading import Lock
+from typing import Any
+
+from pocketsmith_mcp.logger import get_logger
+
+logger = get_logger("circuit_breaker")
+
+
+class CircuitState(str, Enum):
+    """Circuit breaker states."""
+
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"  # Blocking all calls
+    HALF_OPEN = "half_open"  # Testing if service recovered
+
+
+class CircuitBreaker:
+    """
+    Circuit breaker for external service calls.
+
+    Implements the circuit breaker pattern to prevent cascading failures
+    when an external service is unhealthy.
+
+    States:
+    - CLOSED: Normal operation, all calls pass through
+    - OPEN: Service is unhealthy, all calls fail immediately
+    - HALF_OPEN: Testing if service recovered, limited calls allowed
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        reset_timeout_seconds: float = 60.0,
+        half_open_max_calls: int = 1,
+    ):
+        """
+        Initialize the circuit breaker.
+
+        Args:
+            failure_threshold: Number of failures before opening circuit
+            reset_timeout_seconds: Time to wait before testing recovery
+            half_open_max_calls: Number of test calls allowed in half-open state
+        """
+        if failure_threshold < 1:
+            raise ValueError("failure_threshold must be at least 1")
+        if reset_timeout_seconds <= 0:
+            raise ValueError("reset_timeout_seconds must be positive")
+        if half_open_max_calls < 1:
+            raise ValueError("half_open_max_calls must be at least 1")
+
+        self.failure_threshold = failure_threshold
+        self.reset_timeout_seconds = reset_timeout_seconds
+        self.half_open_max_calls = half_open_max_calls
+
+        self._state = CircuitState.CLOSED
+        self._failures = 0
+        self._successes = 0
+        self._last_failure_time: float = 0.0
+        self._half_open_calls = 0
+        self._lock = Lock()
+
+    @property
+    def state(self) -> CircuitState:
+        """Get the current circuit state."""
+        with self._lock:
+            self._check_state_transition()
+            return self._state
+
+    @property
+    def failures(self) -> int:
+        """Get the current failure count."""
+        return self._failures
+
+    @property
+    def is_closed(self) -> bool:
+        """Check if the circuit is closed (normal operation)."""
+        return self.state == CircuitState.CLOSED
+
+    @property
+    def is_open(self) -> bool:
+        """Check if the circuit is open (blocking calls)."""
+        return self.state == CircuitState.OPEN
+
+    def can_execute(self) -> bool:
+        """
+        Check if the circuit allows execution.
+
+        Returns:
+            True if a call can be made, False if blocked
+        """
+        with self._lock:
+            self._check_state_transition()
+
+            if self._state == CircuitState.CLOSED:
+                return True
+
+            if self._state == CircuitState.OPEN:
+                return False
+
+            # HALF_OPEN: Allow limited test calls
+            if self._half_open_calls < self.half_open_max_calls:
+                self._half_open_calls += 1
+                return True
+            return False
+
+    def record_success(self) -> None:
+        """Record a successful call."""
+        with self._lock:
+            self._successes += 1
+
+            if self._state == CircuitState.HALF_OPEN:
+                # Service recovered, close the circuit
+                logger.info("Circuit breaker: Service recovered, closing circuit")
+                self._state = CircuitState.CLOSED
+
+            # Reset failure count on success
+            self._failures = 0
+            self._half_open_calls = 0
+
+    def record_failure(self) -> None:
+        """Record a failed call."""
+        with self._lock:
+            self._failures += 1
+            self._last_failure_time = time.monotonic()
+
+            if self._state == CircuitState.HALF_OPEN:
+                # Test call failed, reopen circuit
+                logger.warning("Circuit breaker: Test call failed, reopening circuit")
+                self._state = CircuitState.OPEN
+                return
+
+            if self._failures >= self.failure_threshold:
+                # Too many failures, open circuit
+                logger.warning(
+                    f"Circuit breaker: {self._failures} failures reached threshold, "
+                    f"opening circuit for {self.reset_timeout_seconds}s"
+                )
+                self._state = CircuitState.OPEN
+
+    def _check_state_transition(self) -> None:
+        """Check if state should transition based on timeout."""
+        if self._state == CircuitState.OPEN:
+            elapsed = time.monotonic() - self._last_failure_time
+            if elapsed >= self.reset_timeout_seconds:
+                logger.info("Circuit breaker: Reset timeout elapsed, entering half-open state")
+                self._state = CircuitState.HALF_OPEN
+                self._half_open_calls = 0
+
+    def reset(self) -> None:
+        """Reset the circuit breaker to initial state."""
+        with self._lock:
+            self._state = CircuitState.CLOSED
+            self._failures = 0
+            self._successes = 0
+            self._last_failure_time = 0.0
+            self._half_open_calls = 0
+            logger.info("Circuit breaker: Reset to closed state")
+
+    def force_open(self) -> None:
+        """Force the circuit to open state."""
+        with self._lock:
+            self._state = CircuitState.OPEN
+            self._last_failure_time = time.monotonic()
+            logger.warning("Circuit breaker: Forced to open state")
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get circuit breaker statistics."""
+        with self._lock:
+            return {
+                "state": self._state.value,
+                "failures": self._failures,
+                "successes": self._successes,
+                "failure_threshold": self.failure_threshold,
+                "reset_timeout_seconds": self.reset_timeout_seconds,
+            }

pocketsmith_mcp/client/rate_limiter.py

@@ -0,0 +1,106 @@
+"""Token bucket rate limiter for API calls."""
+
+import asyncio
+import time
+
+
+class RateLimiter:
+    """
+    Token bucket rate limiter with async support.
+
+    Implements a token bucket algorithm that allows a certain number of
+    requests per time interval. Tokens are refilled continuously based
+    on elapsed time.
+    """
+
+    def __init__(
+        self,
+        tokens_per_interval: int,
+        interval_seconds: float,
+        initial_tokens: int | None = None,
+    ):
+        """
+        Initialize the rate limiter.
+
+        Args:
+            tokens_per_interval: Number of tokens to add per interval
+            interval_seconds: Length of the interval in seconds
+            initial_tokens: Initial number of tokens (defaults to tokens_per_interval)
+        """
+        if tokens_per_interval <= 0:
+            raise ValueError("tokens_per_interval must be positive")
+        if interval_seconds <= 0:
+            raise ValueError("interval_seconds must be positive")
+
+        self.tokens_per_interval = tokens_per_interval
+        self.interval_seconds = interval_seconds
+        self.tokens = float(initial_tokens if initial_tokens is not None else tokens_per_interval)
+        self.max_tokens = float(tokens_per_interval)
+        self.last_refill = time.monotonic()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self, tokens: int = 1) -> None:
+        """
+        Acquire tokens, waiting if necessary.
+
+        Args:
+            tokens: Number of tokens to acquire (default: 1)
+
+        Raises:
+            ValueError: If tokens requested exceeds max_tokens
+        """
+        if tokens > self.max_tokens:
+            raise ValueError(f"Cannot acquire {tokens} tokens (max: {self.max_tokens})")
+
+        async with self._lock:
+            self._refill()
+
+            if self.tokens >= tokens:
+                self.tokens -= tokens
+                return
+
+            # Calculate wait time until we have enough tokens
+            tokens_needed = tokens - self.tokens
+            wait_time = (tokens_needed / self.tokens_per_interval) * self.interval_seconds
+
+            await asyncio.sleep(wait_time)
+            self._refill()
+            self.tokens -= tokens
+
+    def try_acquire(self, tokens: int = 1) -> bool:
+        """
+        Try to acquire tokens without waiting.
+
+        Args:
+            tokens: Number of tokens to acquire (default: 1)
+
+        Returns:
+            True if tokens were acquired, False otherwise
+        """
+        self._refill()
+
+        if self.tokens >= tokens:
+            self.tokens -= tokens
+            return True
+        return False
+
+    def _refill(self) -> None:
+        """Refill tokens based on elapsed time."""
+        now = time.monotonic()
+        elapsed = now - self.last_refill
+
+        # Calculate tokens to add based on elapsed time
+        tokens_to_add = (elapsed / self.interval_seconds) * self.tokens_per_interval
+        self.tokens = min(self.max_tokens, self.tokens + tokens_to_add)
+        self.last_refill = now
+
+    @property
+    def available_tokens(self) -> float:
+        """Get the current number of available tokens."""
+        self._refill()
+        return self.tokens
+
+    def reset(self) -> None:
+        """Reset the rate limiter to full capacity."""
+        self.tokens = self.max_tokens
+        self.last_refill = time.monotonic()

pocketsmith_mcp/client/retry.py

@@ -0,0 +1,106 @@
+"""Exponential backoff retry with jitter."""
+
+import asyncio
+import random
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from pocketsmith_mcp.logger import get_logger
+
+T = TypeVar("T")
+logger = get_logger("retry")
+
+
+async def retry_with_backoff(
+    func: Callable[[], Awaitable[T]],
+    max_attempts: int = 3,
+    base_delay: float = 1.0,
+    max_delay: float = 30.0,
+    jitter_factor: float = 0.2,
+    retryable_errors: tuple[type[Exception], ...] = (Exception,),
+    on_retry: Callable[[Exception, int], None] | None = None,
+) -> T:
+    """
+    Retry an async function with exponential backoff and jitter.
+
+    Args:
+        func: Async function to retry (no arguments)
+        max_attempts: Maximum number of attempts (default: 3)
+        base_delay: Base delay in seconds (default: 1.0)
+        max_delay: Maximum delay in seconds (default: 30.0)
+        jitter_factor: Jitter factor (0.0-1.0) to randomize delay (default: 0.2)
+        retryable_errors: Tuple of exception types to retry (default: all)
+        on_retry: Optional callback called on each retry with (exception, attempt)
+
+    Returns:
+        Result of the function
+
+    Raises:
+        The last exception if all retries fail
+    """
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be at least 1")
+    if base_delay <= 0:
+        raise ValueError("base_delay must be positive")
+    if max_delay <= 0:
+        raise ValueError("max_delay must be positive")
+    if not 0 <= jitter_factor <= 1:
+        raise ValueError("jitter_factor must be between 0 and 1")
+
+    last_error: Exception = Exception("No attempts made")
+
+    for attempt in range(1, max_attempts + 1):
+        try:
+            return await func()
+        except retryable_errors as e:
+            last_error = e
+
+            if attempt == max_attempts:
+                logger.warning(
+                    f"All {max_attempts} attempts failed. Last error: {e}"
+                )
+                break
+
+            # Calculate delay with exponential backoff
+            delay = min(base_delay * (2 ** (attempt - 1)), max_delay)
+
+            # Add jitter
+            jitter = delay * jitter_factor * random.random()
+            total_delay = delay + jitter
+
+            logger.info(
+                f"Attempt {attempt}/{max_attempts} failed: {e}. "
+                f"Retrying in {total_delay:.2f}s"
+            )
+
+            if on_retry:
+                on_retry(e, attempt)
+
+            await asyncio.sleep(total_delay)
+
+    raise last_error
+
+
+def calculate_delay(
+    attempt: int,
+    base_delay: float = 1.0,
+    max_delay: float = 30.0,
+    jitter_factor: float = 0.2,
+) -> float:
+    """
+    Calculate delay for a given attempt number.
+
+    Args:
+        attempt: Current attempt number (1-based)
+        base_delay: Base delay in seconds
+        max_delay: Maximum delay in seconds
+        jitter_factor: Jitter factor (0.0-1.0)
+
+    Returns:
+        Calculated delay in seconds
+    """
+    delay = min(base_delay * (2 ** (attempt - 1)), max_delay)
+    rand_val: float = random.random()
+    jitter = delay * jitter_factor * rand_val
+    total_delay: float = delay + jitter
+    return total_delay