statuspro-mcp-server 0.1.0__py3-none-any.whl

statuspro_mcp/README.md

@@ -0,0 +1 @@
+# StatusPro MCP Server

statuspro_mcp/__init__.py

@@ -0,0 +1,36 @@
+"""StatusPro MCP Server.
+
+A Model Context Protocol (MCP) server for the StatusPro API. Exposes order
+status lookup and update operations as tools for AI assistants.
+
+Key Features:
+- 9 tools across Orders and Statuses
+- Two-step confirm pattern on mutations
+- Built on statuspro-openapi-client — inherits retries, rate-limit awareness,
+  and auto-pagination for free
+
+Example:
+    Configure in Claude Desktop's MCP settings:
+
+    ```json
+    {
+      "mcpServers": {
+        "statuspro": {
+          "command": "uvx",
+          "args": ["statuspro-mcp-server"],
+          "env": {
+            "STATUSPRO_API_KEY": "your-api-key"
+          }
+        }
+      }
+    }
+    ```
+
+See https://github.com/dougborg/statuspro-openapi-client for docs.
+"""
+
+from importlib.metadata import version
+
+__version__ = version("statuspro-mcp-server")
+
+__all__ = ["__version__"]

statuspro_mcp/__main__.py

@@ -0,0 +1,46 @@
+"""Entry point for running StatusPro MCP Server as a module.
+
+Usage:
+    python -m statuspro_mcp [--transport stdio|sse|http|streamable-http] [--host HOST] [--port PORT]
+
+Examples:
+    # Run with stdio (default, for Claude Desktop/CLI)
+    python -m statuspro_mcp
+
+    # Run with streamable-http for Claude.ai co-work or remote clients
+    python -m statuspro_mcp --transport streamable-http --host 0.0.0.0 --port 8765
+
+    # Run with SSE transport for Cursor IDE
+    python -m statuspro_mcp --transport sse --port 8765
+
+    # Run with HTTP transport
+    python -m statuspro_mcp --transport http --port 8765
+"""
+
+import argparse
+
+from statuspro_mcp.server import main
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="StatusPro MCP Server - Manufacturing ERP tools for AI assistants"
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse", "http", "streamable-http"],
+        default="stdio",
+        help="Transport protocol (default: stdio)",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host to bind to for HTTP/SSE (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8765,
+        help="Port to bind to for HTTP/SSE (default: 8765)",
+    )
+    args = parser.parse_args()
+    main(transport=args.transport, host=args.host, port=args.port)

statuspro_mcp/_fastmcp_patches.py

@@ -0,0 +1,182 @@
+"""Patches for FastMCP compatibility issues.
+
+This module patches FastMCP's get_cached_typeadapter to work correctly with
+Pydantic 2.12+ and functions that use custom signatures.
+
+The issue: FastMCP's get_cached_typeadapter creates new function objects with
+updated __annotations__ but preserves the original __signature__. When Pydantic's
+TypeAdapter iterates over signature parameters and looks them up in type_hints
+(derived from __annotations__), it fails with KeyError for parameters that were
+removed from __annotations__ but still exist in __signature__.
+
+This patch updates __signature__ to match __annotations__ when creating
+new function objects.
+
+Note: The create_function_without_params fix was merged upstream in FastMCP 2.14+,
+so only the get_cached_typeadapter patch is needed now.
+"""
+
+from __future__ import annotations
+
+import inspect
+import types
+from collections.abc import Callable
+from functools import lru_cache
+from typing import Annotated, Any, get_args, get_origin, get_type_hints
+
+from pydantic import Field, TypeAdapter
+
+# Track whether patches have been applied (mutable container avoids global statement)
+_state: dict[str, bool] = {"patched": False}
+
+
+def _pin_annotate(target: Any, annotations: dict[str, Any]) -> None:
+    """Override __annotate__ to return a frozen copy of the given annotations.
+
+    Python 3.14+ (PEP 749) added __annotate__ which Pydantic prefers over
+    __annotations__. When functools.wraps or __dict__.update() copies the
+    original function's __annotate__, it returns stale annotations that don't
+    match the modified __annotations__/__signature__, causing KeyError.
+
+    This helper overrides __annotate__ with a lambda returning the correct
+    annotations. For bound methods, patches __func__ since methods don't
+    allow direct attribute assignment.
+    """
+    if inspect.ismethod(target):
+        target = target.__func__
+    if hasattr(target, "__annotate__"):
+        frozen = dict(annotations)
+        target.__annotate__ = lambda fmt: frozen
+
+
+def _update_signature_to_match_annotations(
+    fn: Callable[..., Any], new_annotations: dict[str, Any]
+) -> None:
+    """Update a function's __signature__ to only include parameters in new_annotations.
+
+    This ensures __signature__ is consistent with __annotations__, which is required
+    for Pydantic's TypeAdapter to work correctly.
+
+    IMPORTANT: We must always SET __signature__ because inspect.signature() falls back
+    to introspecting the code object when __signature__ doesn't exist. By setting
+    __signature__, we override that fallback behavior.
+    """
+    sig = inspect.signature(fn)
+
+    new_params = [
+        p
+        for param_name, p in sig.parameters.items()
+        if param_name in new_annotations or param_name in ("args", "kwargs")
+    ]
+    # __signature__ is a valid but dynamic attribute on functions; assigning
+    # it overrides inspect.signature()'s fallback to code-object introspection.
+    # Use __dict__ to avoid static-typing friction around the dynamic attribute.
+    fn.__dict__["__signature__"] = sig.replace(parameters=new_params)
+
+
+@lru_cache(maxsize=5000)
+def _patched_get_cached_typeadapter[T](cls: T) -> TypeAdapter[T]:
+    """Patched version of FastMCP's get_cached_typeadapter.
+
+    This version also updates __signature__ when creating new function objects,
+    ensuring consistency with the updated __annotations__.
+    """
+    if (
+        (inspect.isfunction(cls) or inspect.ismethod(cls))
+        and hasattr(cls, "__annotations__")
+        and cls.__annotations__
+    ):
+        try:
+            resolved_hints = get_type_hints(cls, include_extras=True)
+        except Exception:
+            resolved_hints = cls.__annotations__
+
+        # Process annotations to convert string descriptions to Fields
+        processed_hints = {}
+
+        for name, annotation in resolved_hints.items():
+            if (
+                get_origin(annotation) is Annotated
+                and len(get_args(annotation)) == 2
+                and isinstance(get_args(annotation)[1], str)
+            ):
+                base_type, description = get_args(annotation)
+                processed_hints[name] = Annotated[
+                    base_type, Field(description=description)
+                ]
+            else:
+                processed_hints[name] = annotation
+
+        # Create new function if annotations changed
+        if processed_hints != cls.__annotations__:
+            if inspect.ismethod(cls):
+                actual_func = cls.__func__
+                code = actual_func.__code__
+                globals_dict = actual_func.__globals__
+                name = actual_func.__name__
+                defaults = actual_func.__defaults__
+                closure = actual_func.__closure__
+            else:
+                code = cls.__code__
+                globals_dict = cls.__globals__
+                name = cls.__name__
+                defaults = cls.__defaults__
+                closure = cls.__closure__
+
+            new_func = types.FunctionType(
+                code,
+                globals_dict,
+                name,
+                defaults,
+                closure,
+            )
+            new_func.__dict__.update(cls.__dict__)
+            new_func.__module__ = cls.__module__
+            new_func.__qualname__ = getattr(cls, "__qualname__", cls.__name__)
+            new_func.__annotations__ = processed_hints
+
+            _pin_annotate(new_func, processed_hints)
+
+            # PATCH: Also update __signature__ to match annotations
+            _update_signature_to_match_annotations(new_func, processed_hints)
+
+            if inspect.ismethod(cls):
+                new_method = types.MethodType(new_func, cls.__self__)
+                return TypeAdapter(new_method)
+            else:
+                return TypeAdapter(new_func)
+
+    if (inspect.isfunction(cls) or inspect.ismethod(cls)) and hasattr(
+        cls, "__annotations__"
+    ):
+        _pin_annotate(cls, cls.__annotations__)
+
+    return TypeAdapter(cls)
+
+
+def apply_fastmcp_patches() -> None:
+    """Apply patches to FastMCP for Pydantic 2.12+ compatibility.
+
+    This function should be called before any FastMCP tools are registered.
+    It patches get_cached_typeadapter to update __signature__ when creating
+    new function objects with modified annotations.
+    """
+    import fastmcp.tools.function_parsing
+    import fastmcp.tools.function_tool
+    import fastmcp.tools.tool_transform
+    import fastmcp.utilities.types
+
+    if _state["patched"]:
+        return
+
+    # Each fastmcp submodule imports get_cached_typeadapter by name at module
+    # load time, so patching the source alone is not enough — we have to rebind
+    # the local references in every submodule that imports it. Assign via
+    # __dict__ so pyright doesn't flag the dynamic attribute write.
+    patch = _patched_get_cached_typeadapter
+    fastmcp.utilities.types.__dict__["get_cached_typeadapter"] = patch
+    fastmcp.tools.function_parsing.__dict__["get_cached_typeadapter"] = patch
+    fastmcp.tools.function_tool.__dict__["get_cached_typeadapter"] = patch
+    fastmcp.tools.tool_transform.__dict__["get_cached_typeadapter"] = patch
+
+    _state["patched"] = True

statuspro_mcp/logging.py

@@ -0,0 +1,321 @@
+"""Structured logging configuration for StatusPro MCP Server.
+
+This module provides structured logging using structlog with contextual information,
+trace IDs, and performance metrics.
+
+Features:
+- JSON or text (console) output formats
+- Configurable log levels via environment
+- Trace ID support for request correlation
+- Performance metrics (duration, counts)
+- Error context with stack traces
+- No sensitive data logging (API keys, credentials)
+
+Environment Variables:
+- STATUSPRO_MCP_LOG_LEVEL: Log level (DEBUG, INFO, WARNING, ERROR) - default INFO
+- STATUSPRO_MCP_LOG_FORMAT: Output format (json, text) - default json
+
+Example Usage:
+    from statuspro_mcp.logging import get_logger
+
+    logger = get_logger()
+    logger.info("tool_executed", tool_name="search_items", result_count=15)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import time
+from collections.abc import Callable
+from contextvars import ContextVar
+from functools import wraps
+from typing import Any, TypeVar
+
+import structlog
+from structlog.typing import EventDict, WrappedLogger
+
+# Context variable for trace IDs
+trace_id_var: ContextVar[str] = ContextVar("trace_id", default="")
+
+
+def add_trace_id(
+    logger: WrappedLogger, method_name: str, event_dict: EventDict
+) -> EventDict:
+    """Add trace ID to log events if available.
+
+    Args:
+        logger: The wrapped logger instance
+        method_name: The name of the method being called
+        event_dict: The event dictionary to modify
+
+    Returns:
+        Modified event dictionary with trace_id if available
+    """
+    trace_id = trace_id_var.get()
+    if trace_id:
+        event_dict["trace_id"] = trace_id
+    return event_dict
+
+
+def filter_sensitive_data(
+    logger: WrappedLogger, method_name: str, event_dict: EventDict
+) -> EventDict:
+    """Filter sensitive data from logs.
+
+    Removes or redacts API keys, credentials, and other sensitive information.
+
+    Args:
+        logger: The wrapped logger instance
+        method_name: The name of the method being called
+        event_dict: The event dictionary to modify
+
+    Returns:
+        Modified event dictionary with sensitive data filtered
+    """
+    # List of sensitive keys to redact
+    sensitive_keys = {
+        "api_key",
+        "password",
+        "secret",
+        "token",
+        "auth",
+        "credential",
+        "authorization",
+    }
+
+    # Redact sensitive keys (case-insensitive)
+    for key in list(event_dict.keys()):
+        if any(sensitive in key.lower() for sensitive in sensitive_keys):
+            event_dict[key] = "***REDACTED***"
+
+    return event_dict
+
+
+def setup_logging(log_level: str | None = None, log_format: str | None = None) -> None:
+    """Configure structured logging for MCP server.
+
+    Args:
+        log_level: Log level (DEBUG, INFO, WARNING, ERROR).
+                  If None, reads from STATUSPRO_MCP_LOG_LEVEL env var.
+                  Defaults to INFO.
+        log_format: Output format (json or text).
+                   If None, reads from STATUSPRO_MCP_LOG_FORMAT env var.
+                   Defaults to json.
+    """
+    # Get configuration from environment or parameters
+    level = log_level or os.getenv("STATUSPRO_MCP_LOG_LEVEL", "INFO").upper()
+    format_type = log_format or os.getenv("STATUSPRO_MCP_LOG_FORMAT", "json").lower()
+
+    # Validate log level
+    valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR"}
+    if level not in valid_levels:
+        level = "INFO"
+
+    # Configure standard library logging to use structlog
+    logging.basicConfig(
+        format="%(message)s",
+        stream=sys.stderr,
+        level=getattr(logging, level),
+    )
+
+    # Common processors for all formats
+    processors: list[structlog.types.Processor] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso", utc=True),
+        add_trace_id,
+        filter_sensitive_data,
+        structlog.processors.StackInfoRenderer(),
+    ]
+
+    # Add format-specific processors
+    if format_type == "json":
+        processors.append(structlog.processors.JSONRenderer())
+    else:
+        # Text/console format
+        processors.extend(
+            [
+                structlog.processors.ExceptionRenderer(),
+                structlog.dev.ConsoleRenderer(),
+            ]
+        )
+
+    # Configure structlog
+    structlog.configure(
+        processors=processors,
+        wrapper_class=structlog.make_filtering_bound_logger(getattr(logging, level)),
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str | None = None) -> structlog.stdlib.BoundLogger:
+    """Get a structured logger instance.
+
+    Args:
+        name: Optional logger name. If None, uses the calling module's name.
+
+    Returns:
+        Configured structlog logger instance
+    """
+    return structlog.get_logger(name)
+
+
+def set_trace_id(trace_id: str) -> None:
+    """Set trace ID for current context.
+
+    Args:
+        trace_id: Unique identifier for request tracing
+    """
+    trace_id_var.set(trace_id)
+
+
+def clear_trace_id() -> None:
+    """Clear trace ID from current context."""
+    trace_id_var.set("")
+
+
+def observe_tool[F: Callable[..., Any]](func: F) -> F:
+    """Decorator to add observability to MCP tool functions.
+
+    Logs:
+    - Tool invocation with parameters
+    - Execution duration
+    - Success/failure status
+    - Error details if failed
+
+    Usage:
+        @observe_tool
+        @mcp.tool()
+        async def my_tool(param: str, ctx: Context) -> str:
+            return "result"
+    """
+
+    @wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        tool_name = func.__name__
+        start_time = time.perf_counter()
+
+        # Get logger
+        logger = get_logger(__name__)
+
+        # Extract parameters (excluding ctx/context)
+        params = {k: v for k, v in kwargs.items() if k not in ("ctx", "context")}
+
+        logger.info(
+            "tool_invoked",
+            tool_name=tool_name,
+            params=params,
+        )
+
+        try:
+            result = await func(*args, **kwargs)
+            duration_ms = (time.perf_counter() - start_time) * 1000
+
+            logger.info(
+                "tool_completed",
+                tool_name=tool_name,
+                duration_ms=round(duration_ms, 2),
+                success=True,
+            )
+
+            return result
+
+        except Exception as e:
+            duration_ms = (time.perf_counter() - start_time) * 1000
+
+            logger.error(
+                "tool_failed",
+                tool_name=tool_name,
+                duration_ms=round(duration_ms, 2),
+                error=str(e),
+                error_type=type(e).__name__,
+                success=False,
+            )
+
+            raise
+
+    return wrapper  # type: ignore[return-value]
+
+
+# Type variable for observe_service decorator
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def observe_service(operation: str) -> Callable[[F], F]:
+    """Decorator to add observability to service layer operations.
+
+    Args:
+        operation: Name of the operation (e.g., "get_product", "create_order")
+
+    Usage:
+        class MyService:
+            @observe_service("get_item")
+            async def get(self, item_id: int) -> Item:
+                return item
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            start_time = time.perf_counter()
+
+            # Get logger
+            logger = get_logger(__name__)
+
+            # Get class name if available
+            class_name = args[0].__class__.__name__ if args else "unknown"
+
+            logger.debug(
+                "service_operation_started",
+                service=class_name,
+                operation=operation,
+                params=kwargs,
+            )
+
+            try:
+                result = await func(*args, **kwargs)
+                duration_ms = (time.perf_counter() - start_time) * 1000
+
+                logger.debug(
+                    "service_operation_completed",
+                    service=class_name,
+                    operation=operation,
+                    duration_ms=round(duration_ms, 2),
+                    success=True,
+                )
+
+                return result
+
+            except Exception as e:
+                duration_ms = (time.perf_counter() - start_time) * 1000
+
+                logger.error(
+                    "service_operation_failed",
+                    service=class_name,
+                    operation=operation,
+                    duration_ms=round(duration_ms, 2),
+                    error=str(e),
+                    error_type=type(e).__name__,
+                    success=False,
+                )
+
+                raise
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+__all__ = [
+    "clear_trace_id",
+    "get_logger",
+    "observe_service",
+    "observe_tool",
+    "set_trace_id",
+    "setup_logging",
+    "trace_id_var",
+]

statuspro_mcp/prompts/__init__.py

@@ -0,0 +1,15 @@
+"""MCP prompts for the StatusPro API.
+
+Prompts are optional guided multi-step templates. None are currently registered;
+this module exists as an extension point.
+"""
+
+from fastmcp import FastMCP
+
+
+def register_all_prompts(mcp: FastMCP) -> None:
+    """Register all prompts with the FastMCP server (no-op placeholder)."""
+    return None
+
+
+__all__ = ["register_all_prompts"]

statuspro_mcp/resources/__init__.py

@@ -0,0 +1,25 @@
+"""MCP resources for the StatusPro API.
+
+Resources expose stable, read-only reference data so AI agents can orient
+themselves without calling mutating tools.
+
+Available resources:
+- statuspro://statuses — the full status catalog
+- statuspro://help — tool reference
+"""
+
+from __future__ import annotations
+
+from fastmcp import FastMCP
+
+
+def register_all_resources(mcp: FastMCP) -> None:
+    """Register all resources with the FastMCP server."""
+    from .help import register_resources as register_help_resources
+    from .statuses import register_resources as register_statuses_resources
+
+    register_statuses_resources(mcp)
+    register_help_resources(mcp)
+
+
+__all__ = ["register_all_resources"]