onetool-mcp 1.0.0b1__py3-none-any.whl → 1.0.0rc2__py3-none-any.whl

ot/meta.py

@@ -102,6 +102,7 @@ __all__ = [
     "packs",
     "reload",
     "result",
+    "security",
     "snippets",
     "stats",
     "timed",
@@ -122,6 +123,45 @@ def version() -> str:
     return __version__
 
 
+def security(*, check: str = "") -> dict[str, Any]:
+    """Check security rules for code validation.
+
+    OneTool uses an allowlist-based security model: everything is blocked
+    by default, and only explicitly allowed builtins, imports, and calls
+    are permitted. Tool namespaces (ot.*, brave.*, etc.) are auto-allowed.
+
+    Args:
+        check: Pattern to check (e.g., "os", "json.loads", "pickle.*").
+               If empty, returns a summary of all security rules.
+
+    Returns:
+        If check is provided: Dict with 'pattern', 'status' (allowed/blocked/warned),
+            'category', and 'reason' explaining why.
+        If check is empty: Dict with summary of all security categories
+            (builtins, imports, calls, dunders, tool_namespaces).
+
+    Example:
+        ot.security()                      # Show all rules
+        ot.security(check="os")            # "blocked: import"
+        ot.security(check="json")          # "allowed: import"
+        ot.security(check="json.loads")    # "allowed: module in imports"
+        ot.security(check="pickle.load")   # "blocked: calls"
+        ot.security(check="brave.search")  # "allowed: tool namespace"
+    """
+    from ot.executor.validator import get_security_status, get_security_summary
+
+    with log(span="ot.security", check=check or None) as s:
+        if check:
+            result = get_security_status(check)
+            s.add("status", result["status"])
+            s.add("category", result["category"])
+            return result
+        else:
+            summary = get_security_summary()
+            s.add("status", summary.get("status", "unknown"))
+            return summary
+
+
 def timed(func: _Callable[..., _T], **kwargs: Any) -> dict[str, Any]:
     """Execute a function and return result with timing info.
 
@@ -155,12 +195,14 @@ def get_ot_pack_functions() -> dict[str, Any]:
     return {
         "tools": tools,
         "packs": packs,
+        "servers": servers,
         "aliases": aliases,
         "snippets": snippets,
         "config": config,
         "health": health,
         "help": help,
         "result": result,
+        "security": security,
         "stats": stats,
         "notify": notify,
         "reload": reload,
@@ -178,7 +220,7 @@ def _get_doc_url(pack: str) -> str:
     """Get documentation URL for a pack.
 
     Args:
-        pack: Pack name (e.g., "brave", "firecrawl")
+        pack: Pack name (e.g., "brave", "file")
 
     Returns:
         Documentation URL for the pack
@@ -227,7 +269,8 @@ def _format_general_help() -> str:
 ## Discovery
   ot.tools()              - List all tools
   ot.tools(pattern="web") - Filter by pattern
-  ot.packs()              - List all packs
+  ot.packs()              - List all packs (local + MCP)
+  ot.servers()            - List MCP proxy servers
   ot.snippets()           - List all snippets
   ot.aliases()            - List all aliases
   ot.help(query="..")     - Search for help
@@ -235,7 +278,7 @@ def _format_general_help() -> str:
 ## Info Levels
   info="list" - Names only
   info="min"  - Name + description (default)
-  info="full" - Everything
+  info="full" - Everything (includes instructions)
 
 ## Quick Examples
   brave.search(query="AI news")
@@ -448,7 +491,8 @@ def _format_search_results(
         lines.append("")
         lines.append("Try browsing with:")
         lines.append("  ot.tools()    - List all tools")
-        lines.append("  ot.packs()    - List all packs")
+        lines.append("  ot.packs()    - List all packs (local + MCP)")
+        lines.append("  ot.servers()  - List MCP proxy servers")
         lines.append("  ot.snippets() - List all snippets")
         lines.append("  ot.aliases()  - List all aliases")
 
@@ -504,7 +548,7 @@ def _build_tool_info(
     Args:
         full_name: Full tool name (e.g., "brave.search")
         func: The function object
-        source: Source identifier (e.g., "local", "proxy:github")
+        source: Source identifier (e.g., "local", "mcp:github")
         info: Output verbosity level ("list", "min", "full")
 
     Returns:
@@ -577,7 +621,20 @@ def _schema_to_signature(full_name: str, schema: dict[str, Any]) -> str:
             "array": "list",
             "object": "dict",
         }
-        py_type = type_map.get(prop_type, prop_type)
+
+        # Handle JSON Schema union types (e.g., ["string", "null"])
+        if isinstance(prop_type, list):
+            # Filter out "null" and map remaining types
+            non_null = [t for t in prop_type if t != "null"]
+            if non_null:
+                mapped = [type_map.get(t, t) for t in non_null]
+                py_type = " | ".join(mapped)
+                if "null" in prop_type:
+                    py_type = f"{py_type} | None"
+            else:
+                py_type = "None"
+        else:
+            py_type = type_map.get(prop_type, prop_type)
 
         if prop_name in required:
             params.append(f"{prop_name}: {py_type}")
@@ -626,7 +683,7 @@ def _build_proxy_tool_info(
         full_name: Full tool name (e.g., "github.search")
         description: Tool description from MCP server
         input_schema: JSON Schema for tool input
-        source: Source identifier (e.g., "proxy:github")
+        source: Source identifier (e.g., "mcp:github")
         info: Output verbosity level ("list", "min", "full")
 
     Returns:
@@ -718,7 +775,7 @@ def tools(
                     tool_name,
                     proxy_tool.description or "",
                     proxy_tool.input_schema,
-                    f"proxy:{proxy_tool.server}",
+                    f"mcp:{proxy_tool.server}",
                     info,
                 )
             )
@@ -777,22 +834,44 @@ def packs(
         # info="full" - detailed info for each matching pack
         if info == "full":
             results: list[dict[str, Any] | str] = []
+            cfg = get_config()
+
             for pack_name in all_pack_names:
                 is_local = pack_name in local_packs
 
                 # Build detailed pack info
                 lines = [f"# {pack_name} pack", ""]
 
-                # Get instructions
+                # Show source type
+                if is_local:
+                    lines.append("**Type:** Local")
+                else:
+                    lines.append("**Type:** MCP Proxy Server")
+                lines.append("")
+
+                # Get instructions from prompts.yaml
                 try:
                     prompts_config = get_prompts()
                     configured = get_pack_instructions(prompts_config, pack_name)
                     if configured:
+                        lines.append("## Instructions")
+                        lines.append("")
                         lines.append(configured)
                         lines.append("")
                 except PromptsError:
                     pass
 
+                # For proxy packs, also check server config for instructions
+                if not is_local and pack_name in cfg.servers:
+                    server_cfg = cfg.servers[pack_name]
+                    if server_cfg.instructions:
+                        # Only add header if not already added from prompts
+                        if "## Instructions" not in "\n".join(lines):
+                            lines.append("## Instructions")
+                            lines.append("")
+                        lines.append(server_cfg.instructions.strip())
+                        lines.append("")
+
                 # List tools in this pack
                 lines.append("## Tools")
                 lines.append("")
@@ -827,7 +906,7 @@ def packs(
 
         for pack_name in all_pack_names:
             is_local = pack_name in local_packs
-            source = "local" if is_local else "proxy"
+            source = "local" if is_local else "mcp"
 
             # Count tools in pack
             if is_local:
@@ -851,6 +930,127 @@ def packs(
         return packs_list
 
 
+def servers(
+    *,
+    pattern: str = "",
+    info: InfoLevel = "min",
+) -> list[dict[str, Any] | str]:
+    """List configured MCP proxy servers with optional filtering.
+
+    Shows all MCP servers configured in servers.yaml, including their
+    connection status, tool count, and instructions.
+
+    Args:
+        pattern: Filter servers by name pattern (case-insensitive substring)
+        info: Output verbosity level - "list" (names only), "min" (name + status + tool_count),
+              or "full" (detailed info with instructions and tools)
+
+    Returns:
+        List of server names (info="list") or server dicts/strings (info="min"/"full")
+
+    Example:
+        ot.servers()
+        ot.servers(pattern="github")
+        ot.servers(info="full")
+        ot.servers(pattern="devtools", info="full")
+    """
+    proxy = get_proxy_manager()
+    cfg = get_config()
+
+    with log(span="ot.servers", pattern=pattern or None, info=info) as s:
+        # Get all configured servers
+        all_server_names = sorted(cfg.servers.keys())
+
+        # Filter by pattern
+        if pattern:
+            all_server_names = [
+                name for name in all_server_names if pattern.lower() in name.lower()
+            ]
+
+        # info="list" - just names
+        if info == "list":
+            s.add("count", len(all_server_names))
+            return all_server_names  # type: ignore[return-value]
+
+        # info="full" - detailed info for each server
+        if info == "full":
+            results: list[dict[str, Any] | str] = []
+
+            for server_name in all_server_names:
+                server_cfg = cfg.servers[server_name]
+                conn = proxy.get_connection(server_name)
+                status = "connected" if conn else "disconnected"
+                tool_count = len(proxy.list_tools(server=server_name)) if conn else 0
+
+                lines = [f"# {server_name} server", ""]
+                lines.append(f"**Type:** MCP Proxy Server ({server_cfg.type})")
+                lines.append(f"**Status:** {status}")
+                lines.append(f"**Enabled:** {server_cfg.enabled}")
+                if server_cfg.type == "http" and server_cfg.url:
+                    lines.append(f"**URL:** {server_cfg.url}")
+                elif server_cfg.type == "stdio" and server_cfg.command:
+                    cmd = f"{server_cfg.command} {' '.join(server_cfg.args)}"
+                    lines.append(f"**Command:** {cmd}")
+                lines.append("")
+
+                # Show instructions if configured
+                if server_cfg.instructions:
+                    lines.append("## Instructions")
+                    lines.append("")
+                    lines.append(server_cfg.instructions.strip())
+                    lines.append("")
+
+                # List tools if connected
+                if conn:
+                    lines.append(f"## Tools ({tool_count})")
+                    lines.append("")
+                    proxy_tools = proxy.list_tools(server=server_name)
+                    for tool in sorted(proxy_tools, key=lambda t: t.name):
+                        desc = tool.description or "(no description)"
+                        first_line = desc.split("\n")[0].strip()
+                        lines.append(f"- **{server_name}.{tool.name}**: {first_line}")
+                elif server_cfg.enabled:
+                    lines.append("## Tools")
+                    lines.append("")
+                    lines.append("(not connected)")
+                    # Show error if available
+                    error = proxy.get_error(server_name)
+                    if error:
+                        lines.append("")
+                        lines.append(f"**Error:** {error}")
+
+                results.append("\n".join(lines))
+
+            s.add("count", len(results))
+            return results
+
+        # info="min" (default) - summary for each server
+        servers_list: list[dict[str, Any] | str] = []
+
+        for server_name in all_server_names:
+            server_cfg = cfg.servers[server_name]
+            conn = proxy.get_connection(server_name)
+            status = "connected" if conn else "disconnected"
+            tool_count = len(proxy.list_tools(server=server_name)) if conn else 0
+
+            server_info: dict[str, Any] = {
+                "name": server_name,
+                "type": server_cfg.type,
+                "enabled": server_cfg.enabled,
+                "status": status,
+                "tool_count": tool_count,
+            }
+            # Include error if disconnected
+            if not conn:
+                error = proxy.get_error(server_name)
+                if error:
+                    server_info["error"] = error
+            servers_list.append(server_info)
+
+        s.add("count", len(servers_list))
+        return servers_list
+
+
 # ============================================================================
 # Messaging Functions
 # ============================================================================
@@ -1035,14 +1235,21 @@ def health() -> dict[str, Any]:
             "tool_count": tool_count,
         }
 
-        server_statuses: dict[str, str] = {}
+        server_statuses: dict[str, Any] = {}
         for server_name in cfg.servers:
             conn = proxy.get_connection(server_name)
-            server_statuses[server_name] = "connected" if conn else "disconnected"
+            if conn:
+                server_statuses[server_name] = "connected"
+            else:
+                error = proxy.get_error(server_name)
+                server_statuses[server_name] = {"status": "disconnected", "error": error} if error else "disconnected"
 
         proxy_status: dict[str, Any] = {
             "status": "ok"
-            if all(status == "connected" for status in server_statuses.values())
+            if all(
+                (s == "connected" if isinstance(s, str) else s.get("status") == "connected")
+                for s in server_statuses.values()
+            )
             or not server_statuses
             else "degraded",
             "server_count": len(cfg.servers),
@@ -1074,6 +1281,7 @@ def reload() -> str:
     - Prompts
     - MCP proxy connections
     - Parameter resolution caches
+    - Security validation caches
 
     Use after modifying config files, adding/removing tools, or
     changing secrets during a session.
@@ -1121,6 +1329,11 @@ def reload() -> str:
         ot.executor.param_resolver.get_tool_param_names.cache_clear()
         ot.executor.param_resolver._mcp_param_cache.clear()
 
+        # Clear security validator caches (depends on config and registry)
+        import ot.executor.validator
+        ot.executor.validator._get_tool_namespaces.cache_clear()
+        ot.executor.validator._get_security_config.cache_clear()
+
         # Reload config to validate and report stats
         cfg = get_config()
 
@@ -1471,7 +1684,7 @@ def help(*, query: str = "", info: InfoLevel = "min") -> str:
     Example:
         ot.help()
         ot.help(query="brave.search")
-        ot.help(query="firecrawl")
+        ot.help(query="brave")
         ot.help(query="$b_q")
         ot.help(query="web fetch", info="list")
     """
@@ -1494,6 +1707,15 @@ def help(*, query: str = "", info: InfoLevel = "min") -> str:
                     s.add("match", query)
                     return _format_tool_help(tool, pack)
 
+        # Check for exact server match (MCP proxy servers)
+        server_names = servers(info="list")
+        if query in server_names:
+            server_results = servers(pattern=query, info="full")
+            if server_results:
+                s.add("type", "server")
+                s.add("match", query)
+                return str(server_results[0])
+
         # Check for exact pack match
         pack_names = packs(info="list")
         if query in pack_names:

ot/paths.py

@@ -1,7 +1,6 @@
 """Path resolution for OneTool global and project directories.
 
-OneTool uses a three-tier directory structure:
-- Bundled: package data in ot.config.defaults — read-only defaults
+OneTool uses a two-tier directory structure:
 - Global: ~/.onetool/ — user-wide settings, secrets
 - Project: .onetool/ — project-specific config
 
@@ -9,10 +8,10 @@ Each .onetool/ directory uses subdirectories to organise files by purpose:
 - config/ — YAML configuration files
 - logs/ — Application log files
 - stats/ — Statistics data (stats.jsonl)
-- sessions/ — Browser session state
 - tools/ — Reserved for installed tool packs
 
 Directories are created lazily on first use, not on install.
+Templates in ot.config.global_templates are copied to ~/.onetool/ on init.
 """
 
 from __future__ import annotations
@@ -30,13 +29,9 @@ PROJECT_DIR_NAME = ".onetool"
 CONFIG_SUBDIR = "config"
 LOGS_SUBDIR = "logs"
 STATS_SUBDIR = "stats"
-SESSIONS_SUBDIR = "sessions"
 TOOLS_SUBDIR = "tools"
 
-# Package containing bundled config defaults
-BUNDLED_CONFIG_PACKAGE = "ot.config.defaults"
-
-# Package containing global templates (copied to ~/.onetool/ on first run)
+# Package containing global templates (copied to ~/.onetool/ on init)
 GLOBAL_TEMPLATES_PACKAGE = "ot.config.global_templates"
 
 
@@ -49,7 +44,7 @@ def _resolve_package_dir(package_name: str, description: str) -> Path:
     - Development mode
 
     Args:
-        package_name: Dotted package name (e.g., "ot.config.defaults")
+        package_name: Dotted package name (e.g., "ot.config.global_templates")
         description: Human-readable description for error messages
 
     Returns:
@@ -105,29 +100,13 @@ def _resolve_package_dir(package_name: str, description: str) -> Path:
     )
 
 
-def get_bundled_config_dir() -> Path:
-    """Get the bundled config defaults directory path.
-
-    Uses importlib.resources to access package data. Works correctly across:
-    - Regular pip/uv install (wheel)
-    - Editable install (uv tool install -e .)
-    - Development mode
-
-    Returns:
-        Path to bundled defaults directory (read-only package data)
-
-    Raises:
-        FileNotFoundError: If bundled defaults package is not found or not on filesystem
-    """
-    return _resolve_package_dir(BUNDLED_CONFIG_PACKAGE, "Bundled config")
-
-
 def get_global_templates_dir() -> Path:
     """Get the global templates directory path.
 
     Global templates are user-facing config files with commented examples,
-    copied to ~/.onetool/ on first run. Unlike bundled defaults (which are
-    minimal working configs), these provide rich documentation and examples.
+    copied to ~/.onetool/ on init. These provide documentation and examples
+    for configuration. Also contains subdirectories like diagram-templates/
+    and tool_templates/ for tool-specific resources.
 
     Returns:
         Path to global templates directory (read-only package data)
@@ -156,9 +135,14 @@ def get_effective_cwd() -> Path:
 def get_global_dir() -> Path:
     """Get the global OneTool directory path.
 
+    Can be overridden via OT_GLOBAL_DIR environment variable.
+
     Returns:
-        Path to ~/.onetool/ (not necessarily existing)
+        Path to ~/.onetool/ or OT_GLOBAL_DIR if set (not necessarily existing)
     """
+    env_global = os.getenv("OT_GLOBAL_DIR")
+    if env_global:
+        return Path(env_global).resolve()
     return Path.home() / GLOBAL_DIR_NAME
 
 
@@ -232,11 +216,9 @@ def create_backup(file_path: Path) -> Path:
 def ensure_global_dir(quiet: bool = False, force: bool = False) -> Path:
     """Ensure the global OneTool directory exists with subdirectory structure.
 
-    Creates ~/.onetool/ with subdirectories (config/, logs/, stats/, sessions/, tools/)
+    Creates ~/.onetool/ with subdirectories (config/, logs/, stats/, tools/)
     and copies template config files from global_templates to config/.
     Templates are user-facing files with commented examples for customization.
-    Subdirectories (like diagram-templates/) are NOT copied - they remain in
-    bundled defaults and are accessed via config inheritance.
 
     Args:
         quiet: Suppress creation messages
@@ -255,12 +237,12 @@ def ensure_global_dir(quiet: bool = False, force: bool = False) -> Path:
 
     # Create directory structure with subdirectories
     global_dir.mkdir(parents=True, exist_ok=True)
-    subdirs = [CONFIG_SUBDIR, LOGS_SUBDIR, STATS_SUBDIR, SESSIONS_SUBDIR, TOOLS_SUBDIR]
+    subdirs = [CONFIG_SUBDIR, LOGS_SUBDIR, STATS_SUBDIR, TOOLS_SUBDIR]
     for subdir in subdirs:
         (global_dir / subdir).mkdir(exist_ok=True)
 
     # Copy template config files to config/ subdirectory
-    # Only YAML files are copied; subdirectories stay in bundled defaults
+    # Only YAML files are copied from global_templates/
     # Files named *-template.yaml are copied without the -template suffix
     # (to avoid gitignore patterns on secrets.yaml)
     config_dir = global_dir / CONFIG_SUBDIR
@@ -275,6 +257,20 @@ def ensure_global_dir(quiet: bool = False, force: bool = False) -> Path:
             if not dest.exists() or force:
                 shutil.copy(config_file, dest)
                 copied_items.append(f"config/{dest_name}")
+
+        # Copy resource subdirectories (e.g., diagram-templates/)
+        # These contain user-customizable template files
+        for template_subdir in templates_dir.iterdir():
+            if template_subdir.is_dir() and not template_subdir.name.startswith("_"):
+                # Skip tool_templates - those are code templates accessed via get_global_templates_dir()
+                if template_subdir.name == "tool_templates":
+                    continue
+                dest_subdir = config_dir / template_subdir.name
+                if not dest_subdir.exists() or force:
+                    if dest_subdir.exists():
+                        shutil.rmtree(dest_subdir)
+                    shutil.copytree(template_subdir, dest_subdir)
+                    copied_items.append(f"config/{template_subdir.name}/")
     except FileNotFoundError:
         # Global templates not available (dev environment without package install)
         pass
@@ -295,7 +291,7 @@ def ensure_project_dir(path: Path | None = None, quiet: bool = False) -> Path:
     """Ensure the project OneTool directory exists with subdirectory structure.
 
     Creates .onetool/ in the specified directory or effective cwd,
-    including subdirectories (config/, logs/, stats/, sessions/, tools/).
+    including subdirectories (config/, logs/, stats/, tools/).
 
     Args:
         path: Project root (default: get_effective_cwd())
@@ -312,7 +308,7 @@ def ensure_project_dir(path: Path | None = None, quiet: bool = False) -> Path:
 
     # Create directory structure with subdirectories
     project_dir.mkdir(parents=True, exist_ok=True)
-    subdirs = [CONFIG_SUBDIR, LOGS_SUBDIR, STATS_SUBDIR, SESSIONS_SUBDIR, TOOLS_SUBDIR]
+    subdirs = [CONFIG_SUBDIR, LOGS_SUBDIR, STATS_SUBDIR, TOOLS_SUBDIR]
     for subdir in subdirs:
         (project_dir / subdir).mkdir(exist_ok=True)
 
@@ -409,19 +405,6 @@ def get_stats_dir(base_dir: Path | None = None) -> Path:
     return base / STATS_SUBDIR
 
 
-def get_sessions_dir(base_dir: Path | None = None) -> Path:
-    """Get the sessions directory path within a .onetool directory.
-
-    Args:
-        base_dir: Base .onetool directory (default: global dir)
-
-    Returns:
-        Path to sessions/ subdirectory
-    """
-    base = base_dir or get_global_dir()
-    return base / SESSIONS_SUBDIR
-
-
 def resolve_cwd_path(path: str) -> Path:
     """Resolve a path relative to the project working directory (OT_CWD).