onetool-mcp 1.0.0b1__py3-none-any.whl

ot/http_client.py

@@ -0,0 +1,145 @@
+"""Shared HTTP client utilities.
+
+Provides a unified http_get() function for making HTTP GET requests with:
+- Consistent error handling and message format
+- Optional headers (for auth tokens)
+- Optional timeout (defaults from config)
+- Optional LogSpan integration for observability
+- Content-type aware response parsing (JSON or text)
+- Connection pooling via shared client singleton
+
+Usage:
+    from ot.http_client import http_get
+
+    # Basic GET
+    success, result = http_get("https://api.example.com/data")
+
+    # With headers and params
+    success, result = http_get(
+        "https://api.example.com/search",
+        params={"q": "test"},
+        headers={"Authorization": "Bearer token"},
+    )
+
+    # With LogSpan for observability
+    success, result = http_get(
+        url,
+        log_span="api.fetch",
+        log_data={"query": query},
+    )
+"""
+
+from __future__ import annotations
+
+import atexit
+import contextlib
+import threading
+from typing import Any
+
+import httpx
+
+# Global shared HTTP client with connection pooling
+_client: httpx.Client | None = None
+_client_lock = threading.Lock()
+
+
+def _get_shared_client() -> httpx.Client:
+    """Get or create the shared HTTP client with connection pooling."""
+    global _client
+    if _client is None:
+        with _client_lock:
+            if _client is None:
+                _client = httpx.Client(
+                    timeout=30.0,
+                    limits=httpx.Limits(
+                        max_keepalive_connections=20,
+                        max_connections=100,
+                        keepalive_expiry=30.0,
+                    ),
+                )
+                atexit.register(_shutdown_client)
+    return _client
+
+
+def _shutdown_client() -> None:
+    """Close the shared client on exit."""
+    global _client
+    if _client is not None:
+        with contextlib.suppress(Exception):
+            _client.close()
+        _client = None
+
+
+def http_get(
+    url: str,
+    *,
+    params: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+    timeout: float | None = None,
+    log_span: str | None = None,
+    log_data: dict[str, Any] | None = None,
+) -> tuple[bool, dict[str, Any] | str]:
+    """Make HTTP GET request with unified error handling.
+
+    Args:
+        url: Full URL to request
+        params: Optional query parameters
+        headers: Optional HTTP headers (e.g., auth tokens)
+        timeout: Request timeout in seconds (defaults to 30.0)
+        log_span: Optional LogSpan name for observability
+        log_data: Optional data to include in LogSpan
+
+    Returns:
+        Tuple of (success, result). If success, result is parsed JSON dict
+        or response text. If failure, result is error message string.
+    """
+    from ot.logging import LogSpan as LogSpanClass
+
+    # Default timeout
+    if timeout is None:
+        timeout = 30.0
+
+    # Optional LogSpan wrapper
+    span: LogSpanClass | None = None
+    if log_span:
+        span = LogSpanClass(span=log_span, **(log_data or {}))
+        span.__enter__()
+
+    try:
+        client = _get_shared_client()
+        response = client.get(url, params=params, headers=headers, timeout=timeout)
+        response.raise_for_status()
+
+        # Parse based on content type
+        content_type = response.headers.get("content-type", "")
+        if "application/json" in content_type:
+            result = response.json()
+        else:
+            result = response.text
+
+        if span:
+            span.add("status", response.status_code)
+
+        return True, result
+
+    except httpx.HTTPStatusError as e:
+        error_msg = f"HTTP error ({e.response.status_code}): {e.response.text[:200]}"
+        if span:
+            span.add("error", f"HTTP {e.response.status_code}")
+        return False, error_msg
+
+    except httpx.RequestError as e:
+        error_msg = f"Request failed: {e}"
+        if span:
+            span.add("error", str(e))
+        return False, error_msg
+
+    except Exception as e:
+        error_msg = f"Error: {e}"
+        if span:
+            span.add("error", str(e))
+        return False, error_msg
+
+    finally:
+        if span:
+            span.__exit__(None, None, None)

ot/logging/__init__.py

@@ -0,0 +1,37 @@
+"""Structured logging for OneTool MCP server.
+
+Provides JSON-structured logging with:
+- LogEntry: Fluent API for building log entries with auto-timing
+- LogSpan: Context manager for auto-logging operations
+- File-only JSON output
+"""
+
+from loguru import logger
+
+# Remove Loguru's default console handler immediately.
+# This prevents logs from appearing on console before configure_logging() is called.
+logger.remove()
+
+from ot.logging.config import (  # noqa: E402
+    configure_logging,
+    configure_test_logging,
+)
+from ot.logging.entry import LogEntry  # noqa: E402
+from ot.logging.format import (  # noqa: E402
+    format_log_entry,
+    format_value,
+    sanitize_for_output,
+    sanitize_url,
+)
+from ot.logging.span import LogSpan  # noqa: E402
+
+__all__ = [
+    "LogEntry",
+    "LogSpan",
+    "configure_logging",
+    "configure_test_logging",
+    "format_log_entry",
+    "format_value",
+    "sanitize_for_output",
+    "sanitize_url",
+]

ot/logging/config.py

@@ -0,0 +1,315 @@
+"""Loguru-based logging configuration.
+
+Outputs structured JSON logs to file only.
+
+Settings from onetool.yaml:
+- log_level: INFO (default), DEBUG, WARNING, ERROR
+- log_dir: Directory for log files (default: ../logs, relative to config dir)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import UTC, datetime
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from ot.config.loader import get_config
+
+
+class InterceptHandler(logging.Handler):
+    """Intercept standard logging and redirect to Loguru."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Redirect log record to Loguru."""
+        level: str | int
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        # Store caller info from LogRecord in extra, used by json_serializer
+        logger.bind(
+            _intercepted_file=record.filename,
+            _intercepted_func=record.funcName,
+            _intercepted_line=record.lineno,
+        ).opt(exception=record.exc_info).log(level, record.getMessage())
+
+
+class JSONEncoder(json.JSONEncoder):
+    """Custom JSON encoder for log fields."""
+
+    def default(self, o: Any) -> Any:
+        """Handle non-serializable types."""
+        if isinstance(o, datetime):
+            if o.tzinfo is None:
+                o = o.replace(tzinfo=UTC)
+            return o.isoformat().replace("+00:00", "Z")
+        elif isinstance(o, Decimal):
+            return float(o)
+        elif isinstance(o, Path):
+            return str(o)
+        elif hasattr(o, "__dict__"):
+            return o.__dict__
+        return super().default(o)
+
+
+def json_serializer(record: dict[str, Any]) -> str:
+    """Serialize log record to JSON.
+
+    The message is expected to be JSON from LogEntry.__str__, so we parse
+    and merge it into the log data.
+    """
+    extra = record["extra"]
+
+    # Use intercepted caller info if available (from standard logging redirect)
+    if "_intercepted_file" in extra:
+        source = f"{extra['_intercepted_file']}:{extra['_intercepted_func']}:{extra['_intercepted_line']}"
+    else:
+        source = f"{record['file'].name}:{record['function']}:{record['line']}"
+
+    # Parse source into file, func, line
+    src_parts = source.split(":")
+    src_file = src_parts[0] if len(src_parts) > 0 else ""
+    src_func = src_parts[1] if len(src_parts) > 1 else ""
+    src_line = int(src_parts[2]) if len(src_parts) > 2 and src_parts[2].isdigit() else 0
+
+    log_data: dict[str, Any] = {
+        "timestamp": record["time"].strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z",
+        "level": record["level"].name,
+        "src_file": src_file,
+        "src_func": src_func,
+        "src_line": src_line,
+    }
+
+    msg = record["message"]
+    # Try to parse message as JSON (from LogEntry.__str__)
+    if msg.startswith("{") and msg.endswith("}"):
+        try:
+            parsed = json.loads(msg)
+            log_data.update(parsed)
+        except json.JSONDecodeError:
+            log_data["message"] = msg
+    elif msg and msg not in ("Structured log entry", "MCP stage", "MCP tool executed"):
+        log_data["message"] = msg
+
+    # Add any extra fields (excluding internal keys)
+    public_extra = {k: v for k, v in extra.items() if not k.startswith("_")}
+    if public_extra:
+        log_data.update(public_extra)
+
+    if record["exception"] is not None:
+        log_data["exc_info"] = str(record["exception"])
+
+    return json.dumps(log_data, separators=(",", ":"), cls=JSONEncoder)
+
+
+def dev_formatter(record: dict[str, Any]) -> str:
+    """Format log record as dev-friendly single line.
+
+    Format: HH:MM:SS.mmm | LEVL | file:line | span | key=value | ...
+    """
+    extra = record["extra"]
+
+    # Short timestamp (time only, date is in filename)
+    timestamp = record["time"].strftime("%H:%M:%S.%f")[:-3]
+
+    # 6-char level with padding
+    level_map = {
+        "DEBUG": "DEBUG ",
+        "INFO": "INFO  ",
+        "WARNING": "WARN  ",
+        "ERROR": "ERROR ",
+        "CRITICAL": "CRIT  ",
+        "TRACE": "TRACE ",
+        "SUCCESS": "OK    ",
+    }
+    level = level_map.get(record["level"].name, record["level"].name[:6].ljust(6))
+
+    # Short source: file:line (skip function name)
+    if "_intercepted_file" in extra:
+        src = f"{extra['_intercepted_file'].replace('.py', '')}:{extra['_intercepted_line']}"
+    else:
+        src = f"{record['file'].name.replace('.py', '')}:{record['line']}"
+
+    parts = [timestamp, level, src]
+
+    # Parse message if it's JSON from LogEntry
+    msg = record["message"]
+    fields: dict[str, Any] = {}
+
+    if msg.startswith("{") and msg.endswith("}"):
+        try:
+            fields = json.loads(msg)
+        except json.JSONDecodeError:
+            if msg.strip():
+                fields["message"] = msg
+    elif msg.strip():
+        fields["message"] = msg
+
+    # Add extra fields (excluding internal keys)
+    for k, v in extra.items():
+        if not k.startswith("_") and k not in ("serialized", "dev"):
+            fields[k] = v
+
+    # Extract span first (most important context)
+    span = fields.pop("span", None)
+    if span:
+        parts.append(str(span))
+
+    # Format remaining fields
+    for k, v in fields.items():
+        if k == "duration" and v == 0.0:
+            continue
+        if isinstance(v, list):
+            if len(v) > 10:
+                list_items = ", ".join(str(x) for x in v[:10])
+                parts.append(f"{k}=[{list_items}, ...]")
+            else:
+                parts.append(f"{k}={v}")
+        elif isinstance(v, dict):
+            # Show full dict: key={k1=v1, k2=v2, ...}
+            dict_items: list[str] = [f"{dk}={dv}" for dk, dv in list(v.items())[:10]]
+            if len(v) > 10:
+                dict_items.append("...")
+            parts.append(f"{k}={{{', '.join(dict_items)}}}")
+        elif k == "message":
+            # Plain message without key=
+            parts.append(str(v))
+        else:
+            parts.append(f"{k}={v}")
+
+    return " | ".join(parts)
+
+
+def patching(record: Any) -> None:
+    """Patch record with serialized JSON and dev-friendly format."""
+    record["extra"]["serialized"] = json_serializer(record)
+    record["extra"]["dev"] = dev_formatter(record)
+
+
+def configure_logging(log_name: str = "onetool", level: str | None = None) -> None:
+    """Configure Loguru for file-only output with dev-friendly format.
+
+    Args:
+        log_name: Name for the log file (e.g., "serve" -> logs/serve.log)
+        level: Optional log level override. If None, uses config value.
+
+    Settings from onetool.yaml:
+    - log_level: Log level (default: INFO)
+    - log_dir: Directory for log files (default: ../logs, relative to config dir)
+    """
+    logger.remove()
+
+    config = get_config()
+    level = (level or config.log_level).upper()
+    log_dir = config.get_log_dir_path()
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / f"{log_name}.log"
+
+    logger.configure(patcher=patching)
+
+    # Dev-friendly output to log file
+    logger.add(
+        log_file,
+        level=level,
+        format="{extra[dev]}",
+        colorize=False,
+        backtrace=True,
+        diagnose=True,
+        rotation="10 MB",
+        retention="5 days",
+    )
+
+    # Intercept standard logging
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+    # Intercept FastMCP and related loggers
+    for logger_name in ["fastmcp", "mcp", "uvicorn"]:
+        logging.getLogger(logger_name).handlers = [InterceptHandler()]
+        logging.getLogger(logger_name).propagate = False
+
+    # Silence noisy HTTP/network loggers - set to WARNING to suppress DEBUG spam
+    for logger_name in ["httpcore", "httpx", "hpack"]:
+        logging.getLogger(logger_name).setLevel(logging.WARNING)
+
+    logger.debug("Logging configured", level=level, file=str(log_file))
+
+
+def configure_test_logging(
+    module_name: str,
+    dev_output: bool = True,
+    dev_file: bool = False,
+) -> None:
+    """Configure Loguru for test file logging with optional dev-friendly output.
+
+    Creates a separate log file for each test module in logs/.
+
+    Args:
+        module_name: Test module name (e.g., "test_tools")
+        dev_output: If True, output dev-friendly logs to stderr
+        dev_file: If True, also write dev-friendly logs to {module_name}.dev.log
+    """
+    import sys
+
+    logger.remove()
+
+    config = get_config()
+    level = config.log_level.upper() if config.log_level != "INFO" else "DEBUG"
+
+    # Create logs directory (resolved relative to config dir)
+    log_dir = config.get_log_dir_path()
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    # Test-specific log file - append mode
+    log_file = log_dir / f"{module_name}.log"
+
+    logger.configure(patcher=patching)
+
+    # JSON output to file
+    logger.add(
+        str(log_file),
+        level=level,
+        format="{extra[serialized]}",
+        colorize=False,
+        backtrace=True,
+        diagnose=True,
+    )
+
+    # Dev-friendly output to stderr
+    if dev_output:
+        logger.add(
+            sys.stderr,
+            level=level,
+            format="{extra[dev]}",
+            colorize=False,
+        )
+
+    # Dev-friendly output to file
+    if dev_file:
+        dev_log_file = log_dir / f"{module_name}.dev.log"
+        logger.add(
+            str(dev_log_file),
+            level=level,
+            format="{extra[dev]}",
+            colorize=False,
+        )
+
+    # Intercept standard logging
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+    # Silence noisy HTTP/network/client loggers - set to WARNING to suppress DEBUG/INFO spam
+    for logger_name in [
+        "httpcore",
+        "httpx",
+        "mcp",
+        "anyio",
+        "hpack",
+        "openai",
+        "openai._base_client",
+    ]:
+        logging.getLogger(logger_name).setLevel(logging.WARNING)

ot/logging/entry.py

@@ -0,0 +1,213 @@
+"""LogEntry class for structured logging.
+
+A simple struct for building log entries with automatic timing.
+Supports fluent API, dict-style access, and lazy duration calculation.
+
+Example:
+    # Inline - all fields in constructor
+    logger.debug(LogEntry(event="command.received", command=command))
+
+    # Fluent - chain adds
+    logger.debug(LogEntry(event="tool.lookup")
+        .add("function", func_name)
+        .add("found", True))
+
+    # Multiple logs show increasing duration (no caching)
+    entry = LogEntry(event="multi_step")
+    do_step_1()
+    logger.debug(entry)  # duration: 0.1s
+    do_step_2()
+    logger.info(entry)   # duration: 0.3s
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+
+class LogEntry:
+    """Structured log entry with automatic timing.
+
+    Timing starts automatically on creation. Duration is calculated
+    lazily in __str__ without caching, so multiple logs show increasing
+    duration.
+    """
+
+    def __init__(self, **initial_fields: Any) -> None:
+        """Initialize a log entry with optional initial fields.
+
+        Args:
+            **initial_fields: Initial fields for the log entry
+        """
+        self._start_time = time.perf_counter()
+        self._fields: dict[str, Any] = dict(initial_fields)
+        self._status: str | None = None
+        self._status_code: int | None = None
+        self._error_type: str | None = None
+        self._error_message: str | None = None
+
+    def add(self, key: str | None = None, value: Any = None, **kwargs: Any) -> LogEntry:
+        """Add one or more fields to the entry.
+
+        Can be called with a single key-value pair or with keyword arguments.
+
+        Args:
+            key: Field name (optional if using kwargs)
+            value: Field value (required if key is provided)
+            **kwargs: Bulk field additions
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            entry.add("function", func_name)
+            entry.add(function=func_name, found=True)
+        """
+        if key is not None:
+            self._fields[key] = value
+        self._fields.update(kwargs)
+        return self
+
+    def success(self, status_code: int | None = None) -> LogEntry:
+        """Mark the entry as successful.
+
+        Args:
+            status_code: Optional HTTP status code
+
+        Returns:
+            Self for method chaining
+        """
+        self._status = "SUCCESS"
+        self._status_code = status_code
+        return self
+
+    def failure(
+        self,
+        error: Exception | None = None,
+        error_type: str | None = None,
+        error_message: str | None = None,
+    ) -> LogEntry:
+        """Mark the entry as failed.
+
+        Args:
+            error: Exception that caused the failure
+            error_type: Type name of the error
+            error_message: Error message
+
+        Returns:
+            Self for method chaining
+        """
+        self._status = "FAILED"
+        if error is not None:
+            self._error_type = type(error).__name__
+            self._error_message = str(error)
+        if error_type is not None:
+            self._error_type = error_type
+        if error_message is not None:
+            self._error_message = error_message
+        return self
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set a field using dict-style access.
+
+        Args:
+            key: Field name
+            value: Field value
+        """
+        self._fields[key] = value
+
+    def __getitem__(self, key: str) -> Any:
+        """Get a field using dict-style access.
+
+        Args:
+            key: Field name
+
+        Returns:
+            Field value
+
+        Raises:
+            KeyError: If field doesn't exist
+        """
+        return self._fields[key]
+
+    def __contains__(self, key: str) -> bool:
+        """Check if a field exists.
+
+        Args:
+            key: Field name
+
+        Returns:
+            True if field exists
+        """
+        return key in self._fields
+
+    @property
+    def fields(self) -> dict[str, Any]:
+        """Return a copy of the fields for testing access.
+
+        Returns:
+            Copy of internal fields dictionary
+        """
+        return dict(self._fields)
+
+    @property
+    def duration(self) -> float:
+        """Return current duration since entry creation.
+
+        Returns:
+            Duration in seconds (not cached, calculated fresh each call)
+        """
+        return round(time.perf_counter() - self._start_time, 3)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return all fields with duration for output.
+
+        Returns:
+            Dict with all fields, duration, and status info
+        """
+        output = dict(self._fields)
+        output["duration"] = self.duration
+
+        if self._status is not None:
+            output["status"] = self._status
+        if self._status_code is not None:
+            output["statusCode"] = self._status_code
+        if self._error_type is not None:
+            output["errorType"] = self._error_type
+        if self._error_message is not None:
+            output["errorMessage"] = self._error_message
+
+        return output
+
+    def __str__(self) -> str:
+        """Serialize to JSON with duration.
+
+        Duration is calculated lazily (not cached) so multiple
+        calls show increasing duration.
+
+        Returns:
+            JSON string with fields and duration
+        """
+        output = dict(self._fields)
+        output["duration"] = round(time.perf_counter() - self._start_time, 3)
+
+        if self._status is not None:
+            output["status"] = self._status
+        if self._status_code is not None:
+            output["statusCode"] = self._status_code
+        if self._error_type is not None:
+            output["errorType"] = self._error_type
+        if self._error_message is not None:
+            output["errorMessage"] = self._error_message
+
+        return json.dumps(output, separators=(",", ":"), default=str)
+
+    def __repr__(self) -> str:
+        """Return a debug representation.
+
+        Returns:
+            String showing LogEntry fields
+        """
+        return f"LogEntry({self._fields!r})"