chuk-tool-processor 0.9.2__py3-none-any.whl → 0.10__py3-none-any.whl

chuk_tool_processor/logging/context.py

@@ -77,11 +77,8 @@ class LibraryLoggingManager:
         self._initialized = False
         self._lock = threading.Lock()
 
-    def initialize(self):
+    def initialize(self) -> None:
         """Initialize clean shutdown behavior for the library."""
-        if self._initialized:
-            return
-
         with self._lock:
             if self._initialized:
                 return
@@ -299,7 +296,7 @@ class StructuredAdapter(logging.LoggerAdapter):
         return msg, kwargs
 
     # ----------------------- convenience wrappers ------------------------ #
-    def _forward(self, method_name: str, msg, *args, **kwargs):
+    def _forward(self, method_name: str, msg: str, *args: Any, **kwargs: Any) -> None:
         """Common helper: process + forward to `self.logger.<method_name>`."""
         msg, kwargs = self.process(msg, kwargs)
         getattr(self.logger, method_name)(msg, *args, **kwargs)

chuk_tool_processor/mcp/__init__.py

@@ -9,6 +9,7 @@ Updated to support the latest MCP transports:
 """
 
 from chuk_tool_processor.mcp.mcp_tool import MCPTool
+from chuk_tool_processor.mcp.models import MCPServerConfig, MCPTransport
 from chuk_tool_processor.mcp.register_mcp_tools import register_mcp_tools
 from chuk_tool_processor.mcp.setup_mcp_http_streamable import setup_mcp_http_streamable
 from chuk_tool_processor.mcp.setup_mcp_sse import setup_mcp_sse
@@ -23,6 +24,8 @@ __all__ = [
     "HTTPStreamableTransport",
     "StreamManager",
     "MCPTool",
+    "MCPServerConfig",
+    "MCPTransport",
     "register_mcp_tools",
     "setup_mcp_stdio",
     "setup_mcp_sse",

chuk_tool_processor/mcp/mcp_tool.py

@@ -237,7 +237,12 @@ class MCPTool:
                 await self._record_failure()
 
                 if attempt == max_attempts - 1:
-                    return {"error": error_msg, "tool_name": self.tool_name, "available": False, "reason": "timeout"}
+                    return {
+                        "error": error_msg,
+                        "tool_name": self.tool_name,
+                        "available": False,
+                        "reason": "timeout",
+                    }
 
             except Exception as e:
                 error_str = str(e)
@@ -260,12 +265,12 @@ class MCPTool:
                     await asyncio.sleep(backoff)
                     backoff = min(backoff * self.recovery_config.backoff_multiplier, self.recovery_config.max_backoff)
 
-        # Should never reach here
+        # Should never reach here, but return error if we do
         return {
             "error": f"Tool '{self.tool_name}' failed after all attempts",
             "tool_name": self.tool_name,
             "available": False,
-            "reason": "exhausted_retries",
+            "reason": "execution_failed",
         }
 
     async def _execute_with_timeout(self, timeout: float, **kwargs: Any) -> Any:

chuk_tool_processor/mcp/models.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python
+# chuk_tool_processor/mcp/models.py
+"""
+Pydantic models for MCP server configurations.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class MCPTransport(str, Enum):
+    """Supported MCP transport types."""
+
+    STDIO = "stdio"
+    SSE = "sse"
+    HTTP = "http"
+
+
+class MCPServerConfig(BaseModel):
+    """Unified configuration for MCP servers (all transport types)."""
+
+    name: str = Field(description="Server identifier name")
+    transport: MCPTransport = Field(default=MCPTransport.STDIO, description="Transport protocol")
+
+    # STDIO fields
+    command: str | None = Field(default=None, description="Command to execute (stdio only)")
+    args: list[str] = Field(default_factory=list, description="Command arguments (stdio only)")
+    env: dict[str, str] | None = Field(default=None, description="Environment variables (stdio only)")
+
+    # SSE/HTTP fields
+    url: str | None = Field(default=None, description="Server URL (sse/http)")
+    headers: dict[str, str] = Field(default_factory=dict, description="HTTP headers (sse/http)")
+    timeout: float = Field(default=10.0, description="Connection timeout in seconds")
+    sse_read_timeout: float = Field(default=300.0, description="SSE read timeout in seconds (sse only)")
+    api_key: str | None = Field(default=None, description="API key extracted from Authorization header")
+    session_id: str | None = Field(default=None, description="Session ID for HTTP transport")
+
+    @model_validator(mode="after")
+    def validate_transport_fields(self) -> MCPServerConfig:
+        """Validate required fields based on transport type."""
+        if self.transport == MCPTransport.STDIO:
+            if not self.command:
+                raise ValueError("command is required for stdio transport")
+        else:
+            # SSE/HTTP
+            if not self.url:
+                raise ValueError(f"url is required for {self.transport} transport")
+            # Extract API key from Authorization header if present
+            if not self.api_key and self.headers:
+                auth_header = self.headers.get("Authorization", "")
+                if "Bearer " in auth_header:
+                    self.api_key = auth_header.split("Bearer ")[-1]
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for internal use."""
+        if self.transport == MCPTransport.STDIO:
+            result = {
+                "name": self.name,
+                "command": self.command,
+                "args": self.args,
+            }
+            if self.env:
+                result["env"] = self.env
+            return result
+        else:
+            # SSE/HTTP
+            result = {
+                "name": self.name,
+                "url": self.url,
+                "headers": self.headers,
+                "timeout": self.timeout,
+            }
+            if self.transport == MCPTransport.SSE:
+                result["sse_read_timeout"] = self.sse_read_timeout
+            if self.api_key:
+                result["api_key"] = self.api_key
+            if self.session_id:
+                result["session_id"] = self.session_id
+            return result
+
+
+__all__ = ["MCPServerConfig", "MCPTransport"]

chuk_tool_processor/mcp/setup_mcp_stdio.py

@@ -13,11 +13,16 @@ It:
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Any
+
 from chuk_tool_processor.core.processor import ToolProcessor
 from chuk_tool_processor.logging import get_logger
 from chuk_tool_processor.mcp.register_mcp_tools import register_mcp_tools
 from chuk_tool_processor.mcp.stream_manager import StreamManager
 
+if TYPE_CHECKING:
+    from chuk_tool_processor.mcp.models import MCPServerConfig
+
 logger = get_logger("chuk_tool_processor.mcp.setup_stdio")
 
 
@@ -26,8 +31,8 @@ logger = get_logger("chuk_tool_processor.mcp.setup_stdio")
 # --------------------------------------------------------------------------- #
 async def setup_mcp_stdio(  # noqa: C901 - long but just a config facade
     *,
-    config_file: str,
-    servers: list[str],
+    config_file: str | None = None,  # NOW OPTIONAL - for backward compatibility
+    servers: list[str] | list[dict[str, Any]] | list[MCPServerConfig],  # Can be server names, dicts, OR Pydantic models
     server_names: dict[int, str] | None = None,
     default_timeout: float = 10.0,
     initialization_timeout: float = 60.0,
@@ -45,17 +50,92 @@ async def setup_mcp_stdio(  # noqa: C901 - long but just a config facade
     Initialise stdio-transport MCP + a :class:`ToolProcessor`.
 
     Call with ``await`` from your async context.
+
+    Args:
+        config_file: Optional config file path (legacy mode)
+        servers: Can be:
+            - List of server names (legacy, requires config_file)
+            - List of server config dicts (new DX)
+            - List of MCPServerConfig Pydantic models (best DX)
+        server_names: Optional server name mapping
+        default_timeout: Default timeout for operations
+        initialization_timeout: Timeout for initialization
+        max_concurrency: Maximum concurrent operations
+        enable_caching: Enable result caching
+        cache_ttl: Cache time-to-live
+        enable_rate_limiting: Enable rate limiting
+        global_rate_limit: Global rate limit
+        tool_rate_limits: Per-tool rate limits
+        enable_retries: Enable retries
+        max_retries: Maximum retry attempts
+        namespace: Tool namespace
+
+    Returns:
+        Tuple of (ToolProcessor, StreamManager)
+
+    Examples:
+        # Best DX (Pydantic models):
+        from chuk_tool_processor.mcp import MCPServerConfig, MCPTransport
+
+        processor, manager = await setup_mcp_stdio(
+            servers=[
+                MCPServerConfig(
+                    name="echo",
+                    transport=MCPTransport.STDIO,
+                    command="uvx",
+                    args=["chuk-mcp-echo", "stdio"],
+                ),
+            ],
+            namespace="tools",
+        )
+
+        # New DX (dicts, no config file):
+        processor, manager = await setup_mcp_stdio(
+            servers=[
+                {"name": "echo", "command": "uvx", "args": ["chuk-mcp-echo", "stdio"]},
+            ],
+            namespace="tools",
+        )
+
+        # Legacy (with config file):
+        processor, manager = await setup_mcp_stdio(
+            config_file="mcp_config.json",
+            servers=["echo"],
+            namespace="tools",
+        )
     """
-    # 1️⃣  create & connect the stream-manager
-    # FIXED: Pass the default_timeout parameter to StreamManager.create
-    stream_manager = await StreamManager.create(
-        config_file=config_file,
-        servers=servers,
-        server_names=server_names,
-        transport_type="stdio",
-        default_timeout=default_timeout,  # 🔧 ADD THIS LINE
-        initialization_timeout=initialization_timeout,
-    )
+    # Import here to avoid circular dependency at module level
+    from chuk_tool_processor.mcp.models import MCPServerConfig as MCPServerConfigModel
+
+    # Check what format the servers are in
+    if servers and isinstance(servers[0], str):
+        # LEGACY: servers are names, config_file is required
+        if config_file is None:
+            raise ValueError("config_file is required when servers is a list of strings")
+
+        stream_manager = await StreamManager.create(
+            config_file=config_file,
+            servers=servers,  # type: ignore[arg-type]
+            server_names=server_names,
+            transport_type="stdio",
+            default_timeout=default_timeout,
+            initialization_timeout=initialization_timeout,
+        )
+    else:
+        # NEW DX: servers are config dicts or Pydantic models
+        # Convert Pydantic models to dicts if needed
+        server_dicts: list[dict[str, Any]]
+        if servers and isinstance(servers[0], MCPServerConfigModel):
+            server_dicts = [s.to_dict() for s in servers]  # type: ignore[union-attr]
+        else:
+            server_dicts = servers  # type: ignore[assignment]
+
+        stream_manager = await StreamManager.create_with_stdio(
+            servers=server_dicts,
+            server_names=server_names,
+            default_timeout=default_timeout,
+            initialization_timeout=initialization_timeout,
+        )
 
     # 2️⃣  pull the remote tool list and register each one locally
     registered = await register_mcp_tools(stream_manager, namespace=namespace)

chuk_tool_processor/mcp/stream_manager.py

@@ -96,6 +96,24 @@ class StreamManager:
         )
         return inst
 
+    @classmethod
+    async def create_with_stdio(
+        cls,
+        servers: list[dict[str, Any]],
+        server_names: dict[int, str] | None = None,
+        default_timeout: float = 30.0,
+        initialization_timeout: float = 60.0,
+    ) -> StreamManager:
+        """Create StreamManager with STDIO transport and timeout protection (no config file needed)."""
+        inst = cls()
+        await inst.initialize_with_stdio(
+            servers,
+            server_names,
+            default_timeout=default_timeout,
+            initialization_timeout=initialization_timeout,
+        )
+        return inst
+
     @classmethod
     async def create_with_http_streamable(
         cls,
@@ -373,6 +391,82 @@ class StreamManager:
                 len(self.all_tools),
             )
 
+    async def initialize_with_stdio(
+        self,
+        servers: list[dict[str, Any]],
+        server_names: dict[int, str] | None = None,
+        default_timeout: float = 30.0,
+        initialization_timeout: float = 60.0,
+    ) -> None:
+        """Initialize with STDIO transport directly from server configs (no config file needed)."""
+        if self._closed:
+            raise RuntimeError("Cannot initialize a closed StreamManager")
+
+        async with self._lock:
+            self.server_names = server_names or {}
+
+            for idx, cfg in enumerate(servers):
+                name = cfg.get("name")
+                command = cfg.get("command")
+                args = cfg.get("args", [])
+                env = cfg.get("env")
+
+                if not (name and command):
+                    logger.error("Bad STDIO server config (missing name or command): %s", cfg)
+                    continue
+
+                try:
+                    # Build STDIO transport parameters
+                    transport_params = {
+                        "command": command,
+                        "args": args,
+                    }
+                    if env:
+                        transport_params["env"] = env
+
+                    logger.debug("STDIO %s: command=%s, args=%s", name, command, args)
+
+                    transport = StdioTransport(
+                        transport_params, connection_timeout=initialization_timeout, default_timeout=default_timeout
+                    )
+
+                    try:
+                        if not await asyncio.wait_for(transport.initialize(), timeout=initialization_timeout):
+                            logger.warning("Failed to init STDIO %s", name)
+                            continue
+                    except TimeoutError:
+                        logger.error("Timeout initialising STDIO %s (timeout=%ss)", name, initialization_timeout)
+                        continue
+
+                    self.transports[name] = transport
+
+                    # Ping and get tools with timeout protection
+                    status = (
+                        "Up"
+                        if await asyncio.wait_for(transport.send_ping(), timeout=self.timeout_config.operation)
+                        else "Down"
+                    )
+                    tools = await asyncio.wait_for(transport.get_tools(), timeout=self.timeout_config.operation)
+
+                    for t in tools:
+                        tname = t.get("name")
+                        if tname:
+                            self.tool_to_server_map[tname] = name
+                    self.all_tools.extend(tools)
+
+                    self.server_info.append({"id": idx, "name": name, "tools": len(tools), "status": status})
+                    logger.debug("Initialised STDIO %s - %d tool(s)", name, len(tools))
+                except TimeoutError:
+                    logger.error("Timeout initialising STDIO %s", name)
+                except Exception as exc:
+                    logger.error("Error initialising STDIO %s: %s", name, exc)
+
+            logger.debug(
+                "StreamManager ready - %d STDIO server(s), %d tool(s)",
+                len(self.transports),
+                len(self.all_tools),
+            )
+
     async def initialize_with_http_streamable(
         self,
         servers: list[dict[str, str]],

chuk_tool_processor/mcp/transport/http_streamable_transport.py

@@ -239,13 +239,13 @@ class HTTPStreamableTransport(MCPBaseTransport):
             await self._cleanup()
             if self.enable_metrics and self._metrics:
                 self._metrics.connection_errors += 1
-            return False
+            raise  # Re-raise for OAuth error detection in mcp-cli
         except Exception as e:
             logger.error("Error initializing HTTP Streamable transport: %s", e, exc_info=True)
             await self._cleanup()
             if self.enable_metrics and self._metrics:
                 self._metrics.connection_errors += 1
-            return False
+            raise  # Re-raise for OAuth error detection in mcp-cli
 
     async def _attempt_recovery(self) -> bool:
         """Attempt to recover from connection issues (NEW - like SSE resilience)."""

chuk_tool_processor/models/tool_export_mixin.py

@@ -1,6 +1,6 @@
 # chuk_tool_processor/models/tool_export_mix_in.py
 
-from typing import Any, Protocol, runtime_checkable
+from typing import Any, Protocol, cast, runtime_checkable
 
 from pydantic import BaseModel
 
@@ -18,7 +18,7 @@ class ToolExportMixin:
     @classmethod
     def to_openai(cls) -> dict[str, Any]:
         assert hasattr(cls, "Arguments"), f"{cls.__name__} must have an Arguments attribute"
-        schema = cls.Arguments.model_json_schema()  # type: ignore[attr-defined]
+        schema = cls.Arguments.model_json_schema()  # noqa: ANN401
         return {
             "type": "function",
             "function": {
@@ -31,13 +31,13 @@ class ToolExportMixin:
     @classmethod
     def to_json_schema(cls) -> dict[str, Any]:
         assert hasattr(cls, "Arguments"), f"{cls.__name__} must have an Arguments attribute"
-        return cls.Arguments.model_json_schema()  # type: ignore[attr-defined, no-any-return]
+        return cast(dict[str, Any], cls.Arguments.model_json_schema())
 
     @classmethod
     def to_xml(cls) -> str:
         """Very small helper so existing XML-based parsers still work."""
         assert hasattr(cls, "Arguments"), f"{cls.__name__} must have an Arguments attribute"
         name = cls.__name__.removesuffix("Tool").lower()
-        params = cls.Arguments.model_json_schema()["properties"]  # type: ignore[attr-defined]
+        params = cls.Arguments.model_json_schema()["properties"]  # noqa: ANN401
         args = ", ".join(params)
         return f'<tool name="{name}" args="{{{args}}}"/>'

chuk_tool_processor/observability/metrics.py

@@ -7,12 +7,12 @@ Provides drop-in Prometheus metrics with a /metrics HTTP endpoint.
 from __future__ import annotations
 
 import time
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from chuk_tool_processor.logging import get_logger
 
 if TYPE_CHECKING:
-    from prometheus_client import Counter, Gauge, Histogram  # type: ignore[import-not-found]
+    from prometheus_client import Counter, Gauge, Histogram
 
 logger = get_logger("chuk_tool_processor.observability.metrics")
 
@@ -299,7 +299,7 @@ class MetricsTimer:
         self.start_time = time.perf_counter()
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         self.end_time = time.perf_counter()
 
     @property

chuk_tool_processor/observability/tracing.py

@@ -6,13 +6,14 @@ Provides drop-in distributed tracing with standardized span names and attributes
 
 from __future__ import annotations
 
+from collections.abc import Generator
 from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any
 
 from chuk_tool_processor.logging import get_logger
 
 if TYPE_CHECKING:
-    from opentelemetry.trace import Span, Tracer  # type: ignore[import-not-found]
+    from opentelemetry.trace import Span, Tracer
 
 logger = get_logger("chuk_tool_processor.observability.tracing")
 
@@ -34,13 +35,13 @@ def init_tracer(service_name: str = "chuk-tool-processor") -> Tracer | NoOpTrace
     global _tracer, _tracing_enabled
 
     try:
-        from opentelemetry import trace  # type: ignore[import-not-found]
-        from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (  # type: ignore[import-not-found]
+        from opentelemetry import trace
+        from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
             OTLPSpanExporter,
         )
-        from opentelemetry.sdk.resources import Resource  # type: ignore[import-not-found]
-        from opentelemetry.sdk.trace import TracerProvider  # type: ignore[import-not-found]
-        from opentelemetry.sdk.trace.export import BatchSpanProcessor  # type: ignore[import-not-found]
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
 
         # Create resource with service name
         resource = Resource.create({"service.name": service_name})
@@ -89,7 +90,7 @@ def trace_tool_execution(
     tool: str,
     namespace: str | None = None,
     attributes: dict[str, Any] | None = None,
-):
+) -> Generator[None, None, None]:
     """
     Context manager for tracing tool execution.
 
@@ -135,7 +136,7 @@ def trace_cache_operation(
     tool: str,
     hit: bool | None = None,
     attributes: dict[str, Any] | None = None,
-):
+) -> Generator[None, None, None]:
     """
     Context manager for tracing cache operations.
 
@@ -179,7 +180,7 @@ def trace_retry_attempt(
     attempt: int,
     max_retries: int,
     attributes: dict[str, Any] | None = None,
-):
+) -> Generator[None, None, None]:
     """
     Context manager for tracing retry attempts.
 
@@ -220,7 +221,7 @@ def trace_circuit_breaker(
     tool: str,
     state: str,
     attributes: dict[str, Any] | None = None,
-):
+) -> Generator[None, None, None]:
     """
     Context manager for tracing circuit breaker operations.
 
@@ -259,7 +260,7 @@ def trace_rate_limit(
     tool: str,
     allowed: bool,
     attributes: dict[str, Any] | None = None,
-):
+) -> Generator[None, None, None]:
     """
     Context manager for tracing rate limiting.
 
@@ -340,6 +341,6 @@ class NoOpTracer:
     """No-op tracer when OpenTelemetry is not available."""
 
     @contextmanager
-    def start_as_current_span(self, _name: str, **_kwargs):
+    def start_as_current_span(self, _name: str, **_kwargs: Any) -> Generator[None, None, None]:
         """No-op span context manager."""
         yield None

chuk_tool_processor/registry/interface.py

@@ -36,7 +36,7 @@ class ToolRegistryInterface(Protocol):
             namespace: Namespace for the tool (default: "default").
             metadata: Optional additional metadata for the tool.
         """
-        ...
+        ...  # pragma: no cover
 
     async def get_tool(self, name: str, namespace: str = "default") -> Any | None:
         """
@@ -49,7 +49,7 @@ class ToolRegistryInterface(Protocol):
         Returns:
             The tool implementation or None if not found.
         """
-        ...
+        ...  # pragma: no cover
 
     async def get_tool_strict(self, name: str, namespace: str = "default") -> Any:
         """
@@ -65,7 +65,7 @@ class ToolRegistryInterface(Protocol):
         Raises:
             ToolNotFoundError: If the tool is not found in the registry.
         """
-        ...
+        ...  # pragma: no cover
 
     async def get_metadata(self, name: str, namespace: str = "default") -> ToolMetadata | None:
         """
@@ -78,7 +78,7 @@ class ToolRegistryInterface(Protocol):
         Returns:
             ToolMetadata if found, None otherwise.
         """
-        ...
+        ...  # pragma: no cover
 
     async def list_tools(self, namespace: str | None = None) -> list[tuple[str, str]]:
         """
@@ -90,7 +90,7 @@ class ToolRegistryInterface(Protocol):
         Returns:
             List of (namespace, name) tuples.
         """
-        ...
+        ...  # pragma: no cover
 
     async def list_namespaces(self) -> list[str]:
         """
@@ -99,7 +99,7 @@ class ToolRegistryInterface(Protocol):
         Returns:
             List of namespace names.
         """
-        ...
+        ...  # pragma: no cover
 
     async def list_metadata(self, namespace: str | None = None) -> list[ToolMetadata]:
         """
@@ -113,4 +113,4 @@ class ToolRegistryInterface(Protocol):
         Returns:
             List of ToolMetadata objects.
         """
-        ...
+        ...  # pragma: no cover

chuk_tool_processor/registry/providers/__init__.py

@@ -5,6 +5,7 @@ Async registry provider implementations and factory functions.
 
 import asyncio
 import os
+from typing import Any
 
 from chuk_tool_processor.registry.interface import ToolRegistryInterface
 
@@ -13,7 +14,7 @@ _REGISTRY_CACHE: dict[str, ToolRegistryInterface] = {}
 _REGISTRY_LOCKS: dict[str, asyncio.Lock] = {}
 
 
-async def get_registry(provider_type: str | None = None, **kwargs) -> ToolRegistryInterface:
+async def get_registry(provider_type: str | None = None, **kwargs: Any) -> ToolRegistryInterface:
     """
     Factory function to get a registry implementation asynchronously.
 

chuk_tool_processor/registry/tool_export.py

@@ -28,13 +28,8 @@ async def _build_openai_name_cache() -> None:
     """
     global _OPENAI_NAME_CACHE
 
-    # Fast path - cache already exists
-    if _OPENAI_NAME_CACHE is not None:
-        return
-
-    # Slow path - build the cache with proper locking
+    # Build the cache with proper locking
     async with _CACHE_LOCK:
-        # Double-check pattern: check again after acquiring the lock
         if _OPENAI_NAME_CACHE is not None:
             return