onetool-mcp 1.0.0b1__py3-none-any.whl

ot/config/mcp.py

@@ -0,0 +1,145 @@
+"""MCP server configuration for OneTool proxy.
+
+Defines configuration for connecting to external MCP servers that are
+proxied through OneTool's single `run` tool.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+# Use canonical early secrets loader from secrets.py (eliminates duplication)
+from ot.config.secrets import get_early_secret
+
+
+def expand_secrets(value: str) -> str:
+    """Expand ${VAR} patterns using secrets.yaml ONLY.
+
+    Use this for configuration values that MUST be in secrets.yaml.
+    This enforces that sensitive values are stored in the gitignored secrets file,
+    not in environment variables that might leak into logs or process lists.
+
+    Supports ${VAR_NAME} and ${VAR_NAME:-default} syntax.
+
+    When to use:
+        - Config file values (URLs, API keys, database connections)
+        - Anywhere secrets should be explicit and fail loudly if missing
+
+    When NOT to use:
+        - Subprocess environment pass-through (use expand_subprocess_env instead)
+
+    Args:
+        value: String potentially containing ${VAR} patterns.
+
+    Returns:
+        String with variables expanded from secrets.
+
+    Raises:
+        ValueError: If variable not found in secrets and no default provided.
+    """
+    pattern = re.compile(r"\$\{([^}:]+)(?::-([^}]*))?\}")
+    missing_vars: list[str] = []
+
+    def replace(match: re.Match[str]) -> str:
+        var_name = match.group(1)
+        default_value = match.group(2)
+        # Read from secrets only - no os.environ
+        secret_value = get_early_secret(var_name)
+        if secret_value is not None:
+            return secret_value
+        if default_value is not None:
+            return default_value
+        missing_vars.append(var_name)
+        return match.group(0)
+
+    result = pattern.sub(replace, value)
+
+    if missing_vars:
+        raise ValueError(
+            f"Missing variables in secrets.yaml: {', '.join(missing_vars)}. "
+            f"Add them to .onetool/secrets.yaml or use ${{VAR:-default}} syntax."
+        )
+
+    return result
+
+
+def expand_subprocess_env(value: str) -> str:
+    """Expand ${VAR} for subprocess environment variables.
+
+    Use this ONLY for subprocess env configuration where pass-through is needed.
+    Searches: secrets.yaml first, then os.environ. Returns empty string if not found.
+
+    This is the ONLY place where reading os.environ is allowed. This enables
+    explicit pass-through of system environment variables like ${HOME}, ${PATH},
+    or ${USER} to subprocesses without requiring them to be in secrets.yaml.
+
+    When to use:
+        - MCP server 'env' configuration (subprocess environment)
+        - Any subprocess that needs access to system env vars
+
+    When NOT to use:
+        - Config file values (use expand_secrets instead - it enforces secrets.yaml)
+        - Anything that should fail if the secret is missing
+
+    Args:
+        value: String potentially containing ${VAR} patterns.
+
+    Returns:
+        String with variables expanded. Empty string if not found (silent failure).
+    """
+    import os
+
+    pattern = re.compile(r"\$\{([^}:]+)(?::-([^}]*))?\}")
+
+    def replace(match: re.Match[str]) -> str:
+        var_name = match.group(1)
+        default_value = match.group(2)
+        # Secrets first
+        secret_value = get_early_secret(var_name)
+        if secret_value is not None:
+            return secret_value
+        # Then os.environ (for pass-through like ${HOME})
+        env_val = os.environ.get(var_name)
+        if env_val is not None:
+            return env_val
+        # Use default if provided
+        if default_value is not None:
+            return default_value
+        # Empty string if not found
+        return ""
+
+    return pattern.sub(replace, value)
+
+
+class McpServerConfig(BaseModel):
+    """Configuration for an MCP server connection.
+
+    Compatible with bench ServerConfig format, with additional
+    `enabled` field for toggling servers without removing config.
+    """
+
+    type: Literal["http", "stdio"] = Field(description="Server connection type")
+    enabled: bool = Field(default=True, description="Whether this server is enabled")
+    url: str | None = Field(default=None, description="URL for HTTP servers")
+    headers: dict[str, str] = Field(
+        default_factory=dict, description="Headers for HTTP servers"
+    )
+    command: str | None = Field(default=None, description="Command for stdio servers")
+    args: list[str] = Field(
+        default_factory=list, description="Arguments for stdio command"
+    )
+    env: dict[str, str] = Field(
+        default_factory=dict, description="Environment variables for stdio servers"
+    )
+    timeout: int = Field(default=30, description="Connection timeout in seconds")
+
+    @field_validator("url", "command", mode="before")
+    @classmethod
+    def expand_secrets_validator(cls, v: str | None) -> str | None:
+        """Expand ${VAR} from secrets.yaml in URL and command."""
+        if v is None:
+            return None
+        return expand_secrets(v)

ot/config/secrets.py

@@ -0,0 +1,190 @@
+"""Secrets loading for OneTool.
+
+Loads secrets from secrets.yaml (gitignored) separate from committed configuration.
+Secrets are passed to workers via JSON-RPC, not exposed as environment variables.
+
+The secrets file path is resolved in order:
+1. Explicit path passed to get_secrets()
+2. Config's secrets_file setting (if config loaded and file exists)
+3. Default locations: project (.onetool/config/secrets.yaml) then global (~/.onetool/config/secrets.yaml)
+4. OT_SECRETS_FILE environment variable
+
+Example secrets.yaml:
+
+    BRAVE_API_KEY: "your-brave-api-key"
+    OPENAI_API_KEY: "sk-..."
+    DATABASE_URL: "postgresql://..."
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+from loguru import logger
+
+# Single global secrets cache
+_secrets: dict[str, str] | None = None
+
+
+def load_secrets(secrets_path: Path | str | None = None) -> dict[str, str]:
+    """Load secrets from YAML file.
+
+    Args:
+        secrets_path: Path to secrets file. If None or doesn't exist,
+            returns empty dict (no secrets).
+
+    Returns:
+        Dictionary of secret name -> value
+
+    Raises:
+        ValueError: If YAML is invalid
+    """
+    if secrets_path is None:
+        logger.debug("No secrets path provided")
+        return {}
+
+    secrets_path = Path(secrets_path)
+
+    if not secrets_path.exists():
+        logger.debug(f"Secrets file not found: {secrets_path}")
+        return {}
+
+    logger.debug(f"Loading secrets from {secrets_path}")
+
+    try:
+        with secrets_path.open() as f:
+            raw_data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid YAML in secrets file {secrets_path}: {e}") from e
+    except OSError as e:
+        raise ValueError(f"Error reading secrets file {secrets_path}: {e}") from e
+
+    if raw_data is None:
+        return {}
+
+    if not isinstance(raw_data, dict):
+        raise ValueError(
+            f"Secrets file {secrets_path} must be a YAML mapping, not {type(raw_data).__name__}"
+        )
+
+    # Values are literal - no env var expansion
+    secrets: dict[str, str] = {}
+    for key, value in raw_data.items():
+        if not isinstance(key, str):
+            logger.warning(f"Ignoring non-string secret key: {key}")
+            continue
+
+        if value is None:
+            continue
+
+        # Store as literal string - no ${VAR} expansion
+        secrets[key] = str(value)
+
+    logger.info(f"Loaded {len(secrets)} secrets")
+    return secrets
+
+
+def _load_from_default_locations() -> dict[str, str]:
+    """Load secrets from default project and global locations.
+
+    Searches in order (first found wins):
+    1. Project: {effective_cwd}/.onetool/config/secrets.yaml
+    2. Global: ~/.onetool/config/secrets.yaml
+
+    Returns:
+        Dictionary of secret name -> value (empty if no secrets found)
+    """
+    # Import here to avoid circular imports at module level
+    from ot.paths import CONFIG_SUBDIR, get_effective_cwd, get_global_dir
+
+    # Try project secrets first, then global
+    paths_to_try = [
+        get_effective_cwd() / ".onetool" / CONFIG_SUBDIR / "secrets.yaml",
+        get_global_dir() / CONFIG_SUBDIR / "secrets.yaml",
+    ]
+
+    for secrets_path in paths_to_try:
+        if secrets_path.exists():
+            try:
+                return load_secrets(secrets_path)
+            except ValueError as e:
+                # Silent during bootstrap - don't spam logs
+                logger.debug(f"Error loading secrets from {secrets_path}: {e}")
+                continue
+
+    return {}
+
+
+def get_secrets(
+    secrets_path: Path | str | None = None, reload: bool = False
+) -> dict[str, str]:
+    """Get or load the cached secrets.
+
+    Resolution order (first match wins):
+    1. Explicit secrets_path argument
+    2. Config's secrets_file setting (if config loaded and file exists)
+    3. Default locations (.onetool/config/secrets.yaml)
+    4. OT_SECRETS_FILE environment variable
+
+    Args:
+        secrets_path: Path to secrets file (only used on first load or reload).
+        reload: Force reload secrets from disk.
+
+    Returns:
+        Dictionary of secret name -> value
+    """
+    global _secrets
+
+    if _secrets is None or reload:
+        # Resolution chain: explicit > config (if loaded) > defaults > env var
+        if secrets_path is None:
+            # WARNING: Do NOT call get_config() here!
+            # =========================================
+            # This function is called during config loading via:
+            #   get_config() → load_config() → expand_secrets() → get_early_secret() → get_secrets()
+            #
+            # If we call get_config() here, it triggers config loading again → infinite recursion.
+            # Instead, we check _config directly - if it's None, config is still loading.
+            try:
+                import ot.config.loader
+
+                if ot.config.loader._config is not None:
+                    config_path = ot.config.loader._config.get_secrets_file_path()
+                    if config_path.exists():
+                        secrets_path = config_path
+            except Exception:
+                pass  # Module not loaded yet, fall through
+
+        # Try default locations if still no path
+        if secrets_path is None:
+            loaded = _load_from_default_locations()
+            if loaded:
+                _secrets = loaded
+                return _secrets
+
+        # Final fallback to OT_SECRETS_FILE env var
+        if secrets_path is None:
+            secrets_path = os.getenv("OT_SECRETS_FILE")
+
+        _secrets = load_secrets(secrets_path)
+
+    return _secrets
+
+
+def get_secret(name: str) -> str | None:
+    """Get a single secret value by name.
+
+    Args:
+        name: Secret name (e.g., "BRAVE_API_KEY")
+
+    Returns:
+        Secret value, or None if not found
+    """
+    return get_secrets().get(name)
+
+
+# Alias for backward compatibility and semantic clarity during config loading
+# Both functions now use the same unified cache
+get_early_secret = get_secret

ot/config/tool_config.py

@@ -0,0 +1,125 @@
+"""Runtime tool configuration accessor.
+
+This module provides the primary interface for tools to access their
+configuration at runtime. Tools call get_tool_config() with their pack
+name and optional Config schema class.
+
+Example usage in a tool file:
+    from pydantic import BaseModel, Field
+
+    pack = "brave"
+
+    class Config(BaseModel):
+        timeout: float = Field(default=60.0, ge=1.0, le=300.0)
+
+    def search(query: str) -> str:
+        from ot.config.tool_config import get_tool_config
+        config = get_tool_config("brave", Config)
+        # config.timeout is typed and validated
+        ...
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar, overload
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+@overload
+def get_tool_config(pack: str, schema: type[T]) -> T: ...
+
+
+@overload
+def get_tool_config(pack: str, schema: None = None) -> dict[str, Any]: ...
+
+
+def get_tool_config(
+    pack: str, schema: type[T] | None = None
+) -> T | dict[str, Any]:
+    """Get configuration for a tool pack.
+
+    Args:
+        pack: Pack name (e.g., "brave", "ground", "context7")
+        schema: Optional Pydantic model class to validate and return typed config.
+                If provided, returns an instance of the schema with merged values.
+                If None, returns raw config dict.
+
+    Returns:
+        If schema provided: Instance of schema with config values merged
+        If no schema: Dict with raw config values (empty dict if not configured)
+
+    Example:
+        # With schema (recommended for type safety)
+        class Config(BaseModel):
+            timeout: float = 60.0
+
+        config = get_tool_config("brave", Config)
+        print(config.timeout)  # typed as float
+
+        # Without schema (raw dict)
+        raw = get_tool_config("brave")
+        print(raw.get("timeout", 60.0))
+    """
+    # Get raw config values for this pack
+    raw_config = _get_raw_config(pack)
+
+    if schema is None:
+        return raw_config
+
+    # Validate and return typed config instance
+    try:
+        return schema.model_validate(raw_config)
+    except Exception:
+        # If validation fails, return defaults from schema
+        return schema()
+
+
+def _get_raw_config(pack: str) -> dict[str, Any]:
+    """Get raw config dict for a pack from loaded configuration.
+
+    This function handles both typed tools.X fields and extra fields
+    allowed via model_config. It supports:
+    1. Typed tools.X fields (e.g., tools.stats)
+    2. Extra fields for tool packs (e.g., tools.brave)
+
+    Args:
+        pack: Pack name (e.g., "brave", "ground")
+
+    Returns:
+        Raw config dict for the pack, or empty dict if not configured
+    """
+    from ot.config.loader import get_config
+
+    try:
+        config = get_config()
+    except Exception:
+        # Config not loaded yet - return empty dict
+        return {}
+
+    # Get the tools section
+    tools = config.tools
+
+    # First check for typed attribute (e.g., tools.stats)
+    if hasattr(tools, pack):
+        pack_config = getattr(tools, pack)
+        if hasattr(pack_config, "model_dump"):
+            result: dict[str, Any] = pack_config.model_dump()
+            return result
+        # Handle raw dict from extra fields
+        if isinstance(pack_config, dict):
+            return pack_config
+        return {}
+
+    # Check model_extra for dynamically allowed fields
+    if hasattr(tools, "model_extra") and tools.model_extra:
+        extra = tools.model_extra
+        if pack in extra:
+            pack_data = extra[pack]
+            if isinstance(pack_data, dict):
+                return pack_data
+            return {}
+
+    return {}

ot/decorators.py

@@ -0,0 +1,116 @@
+"""Tool decorators for enhanced metadata.
+
+The @tool decorator attaches metadata to tool functions for better
+LLM comprehension. Plain functions work without decorators.
+
+Example:
+    @tool(
+        description="Search the web using Brave Search",
+        examples=["search(query='Python news')"],
+        tags=["search", "web"],
+    )
+    def brave_search(query: str, count: int = 10) -> str:
+        '''Search the web.'''
+        ...
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass
+class ToolMetadata:
+    """Metadata attached to tool functions by the @tool decorator."""
+
+    description: str | None = None
+    examples: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+    enabled: bool = True
+    deprecated: bool = False
+    deprecated_message: str | None = None
+
+
+# Attribute name used to store metadata on decorated functions
+TOOL_METADATA_ATTR = "_tool_metadata"
+
+
+def tool(
+    description: str | None = None,
+    examples: list[str] | None = None,
+    tags: list[str] | None = None,
+    enabled: bool = True,
+    deprecated: bool = False,
+    deprecated_message: str | None = None,
+) -> Callable[[F], F]:
+    """Decorator to add metadata to a tool function.
+
+    Attaches a ToolMetadata instance to the function for the registry
+    to extract and use for enhanced descriptions.
+
+    Args:
+        description: Override the docstring description
+        examples: List of usage examples
+        tags: Categorization tags
+        enabled: Whether the tool is enabled (default True)
+        deprecated: Mark as deprecated
+        deprecated_message: Message shown when deprecated
+
+    Returns:
+        Decorator function
+
+    Example:
+        @tool(
+            description="Search the web using Brave Search API",
+            examples=[
+                'brave_search(query="Python news", count=5)',
+                'brave_search(query="weather today")',
+            ],
+            tags=["search", "web"],
+        )
+        def brave_search(query: str, count: int = 10) -> str:
+            '''Search the web.'''
+            ...
+    """
+
+    def decorator(func: F) -> F:
+        metadata = ToolMetadata(
+            description=description,
+            examples=examples or [],
+            tags=tags or [],
+            enabled=enabled,
+            deprecated=deprecated,
+            deprecated_message=deprecated_message,
+        )
+        setattr(func, TOOL_METADATA_ATTR, metadata)
+        return func
+
+    return decorator
+
+
+def get_tool_metadata(func: Callable[..., Any]) -> ToolMetadata | None:
+    """Extract ToolMetadata from a function if present.
+
+    Args:
+        func: Function to check for metadata
+
+    Returns:
+        ToolMetadata if decorated with @tool, None otherwise
+    """
+    return getattr(func, TOOL_METADATA_ATTR, None)
+
+
+def has_tool_metadata(func: Callable[..., Any]) -> bool:
+    """Check if a function has @tool decorator metadata.
+
+    Args:
+        func: Function to check
+
+    Returns:
+        True if function has ToolMetadata
+    """
+    return hasattr(func, TOOL_METADATA_ATTR)

ot/executor/__init__.py

@@ -0,0 +1,35 @@
+"""Execution engines for OneTool.
+
+Provides direct host execution via SimpleExecutor.
+The unified runner provides a single entry point for all command execution.
+"""
+
+from ot.executor.base import ExecutionResult
+from ot.executor.fence_processor import strip_fences
+from ot.executor.runner import (
+    CommandResult,
+    PreparedCommand,
+    execute_command,
+    execute_python_code,
+    prepare_command,
+)
+from ot.executor.simple import SimpleExecutor
+from ot.executor.validator import (
+    ValidationResult,
+    validate_for_exec,
+    validate_python_code,
+)
+
+__all__ = [
+    "CommandResult",
+    "ExecutionResult",
+    "PreparedCommand",
+    "SimpleExecutor",
+    "ValidationResult",
+    "execute_command",
+    "execute_python_code",
+    "prepare_command",
+    "strip_fences",
+    "validate_for_exec",
+    "validate_python_code",
+]

ot/executor/base.py

@@ -0,0 +1,16 @@
+"""Base types for executor module."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ExecutionResult:
+    """Result from executing a tool."""
+
+    success: bool
+    result: str
+    duration_seconds: float = 0.0
+    executor: str = "simple"
+    error_type: str | None = None