onetool-mcp 1.0.0b1__py3-none-any.whl

ot/utils/factory.py

@@ -0,0 +1,179 @@
+"""Factory utilities for OneTool.
+
+Provides thread-safe lazy initialization patterns for API clients.
+
+Example:
+    from ot.utils import lazy_client
+
+    # Define a client factory
+    def create_my_client():
+        from mylib import Client
+        api_key = get_secret("MY_API_KEY")
+        return Client(api_key=api_key)
+
+    # Create a lazy-initialized getter
+    get_client = lazy_client(create_my_client)
+
+    # Use it anywhere - initialized once, thread-safe
+    client = get_client()
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = ["LazyClient", "lazy_client"]
+
+T = TypeVar("T")
+
+
+def lazy_client(
+    factory: Callable[[], T | None],
+    *,
+    allow_none: bool = False,
+) -> Callable[[], T | None]:
+    """Create a thread-safe lazy-initialized client getter.
+
+    Wraps a factory function with double-checked locking to ensure
+    the client is created exactly once, even under concurrent access.
+
+    The factory function should:
+    - Return the client instance on success
+    - Return None if required credentials are missing
+    - Raise exceptions for other errors
+
+    Args:
+        factory: Callable that creates and returns the client instance
+        allow_none: If True, cache None results. If False (default), retry
+                   factory on each call when it returns None.
+
+    Returns:
+        A callable that returns the lazily-initialized client
+
+    Example:
+        from ot.utils import lazy_client
+        from ot.config import get_secret, get_tool_config
+
+        def create_firecrawl():
+            from firecrawl import FirecrawlApp
+            api_key = get_secret("FIRECRAWL_API_KEY")
+            if not api_key:
+                return None
+            api_url = get_tool_config("firecrawl", Config).api_url
+            return FirecrawlApp(api_key=api_key, api_url=api_url or None)
+
+        get_firecrawl = lazy_client(create_firecrawl)
+
+        # Later, in tool functions:
+        def scrape(url: str) -> str:
+            client = get_firecrawl()
+            if client is None:
+                return "Error: FIRECRAWL_API_KEY not configured"
+            return client.scrape_url(url)
+    """
+    client: T | None = None
+    initialized = False
+    lock = threading.Lock()
+
+    def get_client() -> T | None:
+        nonlocal client, initialized
+
+        # Fast path: already initialized
+        if initialized:
+            return client
+
+        # Slow path: acquire lock and initialize
+        with lock:
+            # Double-check after acquiring lock
+            if initialized:
+                return client
+
+            result = factory()
+
+            # Cache result if successful or allow_none is True
+            if result is not None or allow_none:
+                client = result
+                initialized = True
+
+            return result
+
+    return get_client
+
+
+class LazyClient:
+    """Class-based lazy client for more complex initialization patterns.
+
+    Useful when you need to pass the factory as a method or need
+    additional client management features.
+
+    Example:
+        class MyPack:
+            def __init__(self):
+                self._client = LazyClient(self._create_client)
+
+            def _create_client(self):
+                return SomeClient(api_key=get_secret("API_KEY"))
+
+            def search(self, query: str) -> str:
+                client = self._client.get()
+                if client is None:
+                    return "Error: API_KEY not configured"
+                return client.search(query)
+    """
+
+    def __init__(
+        self,
+        factory: Callable[[], T | None],
+        *,
+        allow_none: bool = False,
+    ) -> None:
+        """Initialize the lazy client wrapper.
+
+        Args:
+            factory: Callable that creates the client
+            allow_none: If True, cache None results
+        """
+        self._factory = factory
+        self._allow_none = allow_none
+        self._client: T | None = None
+        self._initialized = False
+        self._lock = threading.Lock()
+
+    def get(self) -> T | None:
+        """Get the client, initializing if necessary.
+
+        Returns:
+            The client instance, or None if not available
+        """
+        if self._initialized:
+            return self._client  # type: ignore[return-value]
+
+        with self._lock:
+            if self._initialized:
+                return self._client
+
+            result = self._factory()
+
+            if result is not None or self._allow_none:
+                self._client = result
+                self._initialized = True
+
+            return result  # type: ignore[return-value]
+
+    def reset(self) -> None:
+        """Reset the client, forcing re-initialization on next access.
+
+        Useful for testing or when configuration changes.
+        """
+        with self._lock:
+            self._client = None
+            self._initialized = False
+
+    @property
+    def is_initialized(self) -> bool:
+        """Check if the client has been initialized."""
+        return self._initialized

ot/utils/format.py

@@ -0,0 +1,65 @@
+"""Result serialization utilities for MCP responses."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+import yaml
+
+__all__ = ["FormatMode", "serialize_result"]
+
+FormatMode = Literal["json", "json_h", "yml", "yml_h", "raw"]
+
+
+def serialize_result(result: Any, fmt: FormatMode = "json") -> str:
+    """Serialize tool result to string for MCP response.
+
+    Tools return native Python types (dict, list, str). This function
+    serializes them to a string suitable for MCP text content.
+
+    Format modes:
+    - json: Compact JSON (default, no spaces)
+    - json_h: Human-readable JSON (2-space indent)
+    - yml: YAML flow style (compact)
+    - yml_h: YAML block style (human-readable)
+    - raw: str() conversion
+
+    Args:
+        result: Tool result (dict, list, str, or other)
+        fmt: Output format mode (default: "json")
+
+    Returns:
+        String representation suitable for MCP response
+    """
+    # Strings pass through unchanged for all formats except raw
+    if isinstance(result, str) and fmt != "raw":
+        return result
+
+    if fmt == "raw":
+        return str(result)
+
+    if fmt == "json":
+        if isinstance(result, (dict, list)):
+            return json.dumps(result, ensure_ascii=False, separators=(",", ":"))
+        return str(result)
+
+    if fmt == "json_h":
+        if isinstance(result, (dict, list)):
+            return json.dumps(result, ensure_ascii=False, indent=2)
+        return str(result)
+
+    if fmt == "yml":
+        if isinstance(result, (dict, list)):
+            return yaml.dump(result, default_flow_style=True, allow_unicode=True, sort_keys=False).rstrip()
+        return str(result)
+
+    if fmt == "yml_h":
+        if isinstance(result, (dict, list)):
+            return yaml.dump(result, default_flow_style=False, allow_unicode=True, sort_keys=False).rstrip()
+        return str(result)
+
+    # Unknown format, fall back to compact JSON
+    if isinstance(result, (dict, list)):
+        return json.dumps(result, ensure_ascii=False, separators=(",", ":"))
+    return str(result)

ot/utils/http.py

@@ -0,0 +1,202 @@
+"""HTTP request utilities for OneTool.
+
+Provides standardized HTTP error handling and header construction
+for API-based tools.
+
+Example:
+    from ot.utils import safe_request, api_headers
+
+    # Build API headers with authentication
+    headers = api_headers("MY_API_KEY", header_name="Authorization", prefix="Bearer")
+
+    # Make a request with standardized error handling
+    success, result = safe_request(
+        lambda: client.get("/endpoint", headers=headers)
+    )
+    if success:
+        data = result  # Parsed JSON dict
+    else:
+        error_msg = result  # Error message string
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from ot.config.secrets import get_secret
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = ["api_headers", "check_api_key", "safe_request"]
+
+T = TypeVar("T")
+
+
+def api_headers(
+    secret_name: str,
+    *,
+    header_name: str = "Authorization",
+    prefix: str = "Bearer",
+    extra: dict[str, str] | None = None,
+) -> dict[str, str]:
+    """Build API request headers with authentication.
+
+    Retrieves a secret and constructs the appropriate authorization header.
+    Commonly used patterns:
+    - Bearer token: prefix="Bearer" (default)
+    - API key header: header_name="X-API-Key", prefix=""
+
+    Args:
+        secret_name: Name of secret in secrets.yaml (e.g., "MY_API_KEY")
+        header_name: Header name for the auth token (default: "Authorization")
+        prefix: Prefix before the token value (default: "Bearer")
+        extra: Additional headers to include
+
+    Returns:
+        Dict of headers ready for HTTP requests
+
+    Raises:
+        ValueError: If the secret is not configured
+
+    Example:
+        # Bearer token auth
+        headers = api_headers("OPENAI_API_KEY")
+        # {"Authorization": "Bearer sk-..."}
+
+        # Custom API key header
+        headers = api_headers(
+            "BRAVE_API_KEY", header_name="X-Subscription-Token", prefix=""
+        )
+        # {"X-Subscription-Token": "BSA..."}
+
+        # With extra headers
+        headers = api_headers("API_KEY", extra={"Accept": "application/json"})
+    """
+    api_key = get_secret(secret_name)
+    if not api_key:
+        raise ValueError(f"{secret_name} secret not configured in secrets.yaml")
+
+    headers: dict[str, str] = {}
+
+    # Build auth header
+    if prefix:
+        headers[header_name] = f"{prefix} {api_key}"
+    else:
+        headers[header_name] = api_key
+
+    # Add extra headers
+    if extra:
+        headers.update(extra)
+
+    return headers
+
+
+def safe_request(
+    request_fn: Callable[[], T],
+    *,
+    parse_json: bool = True,
+) -> tuple[bool, T | dict[str, Any] | str]:
+    """Execute an HTTP request with standardized error handling.
+
+    Wraps an HTTP request call and handles common error patterns:
+    - Connection errors
+    - HTTP status errors
+    - JSON parsing errors
+    - Timeout errors
+
+    Args:
+        request_fn: Callable that makes the HTTP request and returns response
+        parse_json: If True (default), parse response as JSON
+
+    Returns:
+        Tuple of (success: bool, result).
+        On success: (True, parsed_json_dict or response)
+        On failure: (False, error_message_string)
+
+    Example:
+        # With httpx client
+        success, result = safe_request(
+            lambda: client.get("/api/data", params={"q": "test"})
+        )
+
+        if success:
+            data = result["data"]
+        else:
+            return f"Error: {result}"
+
+        # Without JSON parsing
+        success, result = safe_request(
+            lambda: client.get("/raw/text"),
+            parse_json=False,
+        )
+    """
+    try:
+        response = request_fn()
+
+        # Check for raise_for_status method (httpx/requests response)
+        if hasattr(response, "raise_for_status"):
+            response.raise_for_status()
+
+        if parse_json and hasattr(response, "json"):
+            return True, response.json()
+
+        if hasattr(response, "text"):
+            return True, response.text
+
+        return True, response
+
+    except Exception as e:
+        return False, _format_http_error(e)
+
+
+def _format_http_error(error: Exception) -> str:
+    """Format an HTTP error into a user-friendly message.
+
+    Extracts status code and response text when available.
+
+    Args:
+        error: The exception from the HTTP request
+
+    Returns:
+        Formatted error message string
+    """
+    error_type = type(error).__name__
+
+    # Check for response attribute (HTTPStatusError, etc.)
+    if hasattr(error, "response"):
+        response = error.response
+        status = getattr(response, "status_code", "unknown")
+        text = getattr(response, "text", "")[:200]
+        return f"HTTP error ({status}): {text}" if text else f"HTTP error ({status})"
+
+    # Check for common error types
+    error_str = str(error)
+    if "timeout" in error_str.lower():
+        return f"Request timeout: {error}"
+    if "connection" in error_str.lower():
+        return f"Connection error: {error}"
+
+    return f"Request failed ({error_type}): {error}"
+
+
+def check_api_key(secret_name: str) -> str | None:
+    """Check if an API key is configured and return error message if not.
+
+    Convenience function for early validation in tools.
+
+    Args:
+        secret_name: Name of secret to check
+
+    Returns:
+        None if configured, error message string if not
+
+    Example:
+        if error := check_api_key("BRAVE_API_KEY"):
+            return error
+        # Proceed with API calls
+    """
+    api_key = get_secret(secret_name)
+    if not api_key:
+        return f"Error: {secret_name} secret not configured"
+    return None

ot/utils/platform.py

@@ -0,0 +1,45 @@
+"""Platform detection utilities for cross-platform support."""
+
+from __future__ import annotations
+
+import sys
+
+# Platform-specific install commands for external dependencies
+INSTALL_COMMANDS: dict[str, dict[str, str]] = {
+    "rg": {
+        "darwin": "brew install ripgrep",
+        "linux": "apt install ripgrep  # or: snap install ripgrep",
+        "win32": "winget install BurntSushi.ripgrep.MSVC  # or: scoop install ripgrep",
+    },
+    "playwright": {
+        "darwin": "pip install playwright && playwright install",
+        "linux": "pip install playwright && playwright install",
+        "win32": "pip install playwright && playwright install",
+    },
+}
+
+
+def get_install_hint(tool: str) -> str:
+    """Get platform-appropriate install command for a tool.
+
+    Args:
+        tool: Tool name (e.g., "rg", "playwright")
+
+    Returns:
+        Install command for the current platform, or generic message if unknown.
+
+    Example:
+        >>> get_install_hint("rg")  # On macOS
+        'brew install ripgrep'
+        >>> get_install_hint("rg")  # On Linux
+        'apt install ripgrep  # or: snap install ripgrep'
+        >>> get_install_hint("rg")  # On Windows
+        'winget install BurntSushi.ripgrep.MSVC  # or: scoop install ripgrep'
+    """
+    platform = sys.platform
+    # Normalize Linux variants (linux2, etc.)
+    if platform.startswith("linux"):
+        platform = "linux"
+
+    commands = INSTALL_COMMANDS.get(tool, {})
+    return commands.get(platform, f"Install {tool} for your platform")

ot/utils/sanitize.py

@@ -0,0 +1,130 @@
+"""Output sanitization for prompt injection protection.
+
+Protects against indirect prompt injection by sanitizing tool outputs
+that may contain malicious payloads designed to trick the LLM.
+
+Three-layer defense:
+1. Trigger sanitization: Replace __ot, mcp__onetool patterns
+2. Tag sanitization: Remove <external-content-*> patterns
+3. GUID-tagged boundaries: Wrap content in unpredictable tags
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+
+__all__ = [
+    "sanitize_output",
+    "sanitize_tag_closes",
+    "sanitize_triggers",
+    "wrap_external_content",
+]
+
+# Regex patterns for trigger detection (case-insensitive)
+# Matches: __ot, mcp__onetool, mcp__onetool__run
+TRIGGER_PATTERN = re.compile(
+    r"(__ot\b|mcp__onetool\w*)",
+    re.IGNORECASE,
+)
+
+# Pattern for tag injection attempts (both opening and closing)
+# Matches: <external-content-*> and </external-content-*>
+TAG_PATTERN = re.compile(
+    r"</?external-content-[a-f0-9-]*>?",
+    re.IGNORECASE,
+)
+
+
+def sanitize_triggers(content: str) -> str:
+    """Replace trigger patterns that could invoke OneTool.
+
+    Replaces patterns like __ot, mcp__onetool, mcp__onetool__run
+    with [REDACTED:trigger] to prevent indirect prompt injection.
+
+    Args:
+        content: String content that may contain trigger patterns
+
+    Returns:
+        Content with triggers replaced by [REDACTED:trigger]
+    """
+    if not content:
+        return content
+
+    return TRIGGER_PATTERN.sub("[REDACTED:trigger]", content)
+
+
+def sanitize_tag_closes(content: str) -> str:
+    """Remove boundary tag patterns that could escape or confuse boundaries.
+
+    Attackers may include </external-content-*> to close the boundary early,
+    or <external-content-*> to create fake boundaries and confuse parsing.
+
+    Args:
+        content: String content that may contain boundary tag attempts
+
+    Returns:
+        Content with boundary tag patterns replaced by [REDACTED:tag]
+    """
+    if not content:
+        return content
+
+    return TAG_PATTERN.sub("[REDACTED:tag]", content)
+
+
+def wrap_external_content(
+    content: str,
+    source: str | None = None,
+) -> str:
+    """Wrap external content in GUID-tagged boundaries.
+
+    Applies all three defense layers:
+    1. Sanitize trigger patterns
+    2. Sanitize tag patterns
+    3. Wrap in unpredictable GUID boundary tags
+
+    Args:
+        content: External content to wrap
+        source: Optional source identifier (e.g., URL, tool name)
+
+    Returns:
+        Content wrapped in boundary tags with sanitization applied.
+        Empty content is still wrapped (boundaries always apply).
+    """
+    # Generate unique boundary ID (4 hex chars = 16 bits = 65,536 possibilities)
+    # Sufficient for unpredictability within a single request context
+    boundary_id = uuid.uuid4().hex[:4]
+
+    # Apply sanitization layers
+    content = sanitize_triggers(content)
+    content = sanitize_tag_closes(content)
+
+    # Build source attribute if provided
+    source_attr = f' source="{source}"' if source else ""
+
+    # Wrap in boundary tags
+    return f"<external-content-{boundary_id}{source_attr}>\n{content}\n</external-content-{boundary_id}>"
+
+
+def sanitize_output(
+    content: str,
+    source: str | None = None,
+    enabled: bool = True,
+) -> str:
+    """Sanitize tool output for prompt injection protection.
+
+    Main entry point for output sanitization. When enabled, wraps content
+    in boundary tags and sanitizes trigger patterns.
+
+    Args:
+        content: Tool output content
+        source: Optional source identifier (e.g., tool name, URL)
+        enabled: Whether sanitization is enabled (default True)
+
+    Returns:
+        Sanitized content wrapped in boundary tags, or original if disabled
+    """
+    if not enabled:
+        return content
+
+    return wrap_external_content(content, source=source)

ot/utils/truncate.py

@@ -0,0 +1,69 @@
+"""Text truncation and error formatting utilities."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Any
+
+__all__ = ["format_error", "run_command", "truncate"]
+
+
+def truncate(text: str, max_length: int = 4000, indicator: str = "...") -> str:
+    """Truncate text to a maximum length with an indicator.
+
+    Args:
+        text: Text to truncate
+        max_length: Maximum length including indicator
+        indicator: String to append when truncated (default: "...")
+
+    Returns:
+        Truncated text with indicator, or original if within limit
+    """
+    if len(text) <= max_length:
+        return text
+    return text[: max_length - len(indicator)] + indicator
+
+
+def format_error(message: str, details: dict[str, Any] | None = None) -> str:
+    """Format an error message consistently.
+
+    Args:
+        message: Main error message
+        details: Optional additional details
+
+    Returns:
+        Formatted error string
+    """
+    if details:
+        detail_str = ", ".join(f"{k}={v}" for k, v in details.items())
+        return f"Error: {message} ({detail_str})"
+    return f"Error: {message}"
+
+
+def run_command(
+    args: list[str],
+    *,
+    timeout: float = 30.0,
+    cwd: str | None = None,
+) -> tuple[int, str, str]:
+    """Run a subprocess command with timeout.
+
+    Args:
+        args: Command and arguments
+        timeout: Timeout in seconds (default: 30)
+        cwd: Working directory
+
+    Returns:
+        Tuple of (return_code, stdout, stderr)
+
+    Raises:
+        subprocess.TimeoutExpired: If command times out
+    """
+    result = subprocess.run(
+        args,
+        timeout=timeout,
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode, result.stdout, result.stderr

ot_tools/__init__.py

@@ -0,0 +1,4 @@
+"""OneTool built-in tools.
+
+Tools are auto-discovered from Python files in this directory.
+"""