smartify-ai 0.1.0__py3-none-any.whl

smartify/tools/builtin/shell.py

@@ -0,0 +1,137 @@
+"""Shell command execution tool."""
+
+import asyncio
+import logging
+import shlex
+from typing import Any, Dict, Optional
+
+from smartify.tools.base import Tool, ToolResult
+
+logger = logging.getLogger(__name__)
+
+
+class ShellTool(Tool):
+    """Execute shell commands.
+    
+    Runs commands in a subprocess with configurable timeout and working directory.
+    """
+    
+    name = "shell"
+    description = "Execute a shell command and return its output. Use for running CLI tools, scripts, or system commands."
+    
+    def __init__(
+        self,
+        default_timeout: float = 60.0,
+        allowed_commands: Optional[list[str]] = None,
+        blocked_commands: Optional[list[str]] = None,
+        working_dir: Optional[str] = None,
+    ):
+        """Initialize shell tool.
+        
+        Args:
+            default_timeout: Default command timeout in seconds
+            allowed_commands: If set, only these command prefixes are allowed
+            blocked_commands: Commands to block (e.g., ["rm -rf", "sudo"])
+            working_dir: Default working directory
+        """
+        self.default_timeout = default_timeout
+        self.allowed_commands = allowed_commands
+        self.blocked_commands = blocked_commands or ["rm -rf /", "sudo rm", ":(){ :|:& };:"]
+        self.working_dir = working_dir
+    
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "The shell command to execute"
+                },
+                "timeout": {
+                    "type": "number",
+                    "description": f"Timeout in seconds (default: {self.default_timeout})"
+                },
+                "working_dir": {
+                    "type": "string",
+                    "description": "Working directory for the command"
+                },
+            },
+            "required": ["command"]
+        }
+    
+    async def execute(
+        self,
+        command: str,
+        timeout: Optional[float] = None,
+        working_dir: Optional[str] = None,
+        **kwargs
+    ) -> ToolResult:
+        """Execute a shell command.
+        
+        Args:
+            command: Shell command to run
+            timeout: Command timeout in seconds
+            working_dir: Working directory
+            
+        Returns:
+            ToolResult with stdout/stderr
+        """
+        # Security checks
+        for blocked in self.blocked_commands:
+            if blocked in command:
+                return ToolResult(
+                    success=False,
+                    error=f"Blocked command pattern: {blocked}"
+                )
+        
+        if self.allowed_commands:
+            cmd_prefix = command.split()[0] if command.split() else ""
+            if cmd_prefix not in self.allowed_commands:
+                return ToolResult(
+                    success=False,
+                    error=f"Command not in allowlist: {cmd_prefix}"
+                )
+        
+        timeout = timeout or self.default_timeout
+        cwd = working_dir or self.working_dir
+        
+        try:
+            process = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=cwd,
+            )
+            
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(),
+                timeout=timeout
+            )
+            
+            stdout_text = stdout.decode("utf-8", errors="replace")
+            stderr_text = stderr.decode("utf-8", errors="replace")
+            
+            return ToolResult(
+                success=process.returncode == 0,
+                output={
+                    "stdout": stdout_text,
+                    "stderr": stderr_text,
+                    "exit_code": process.returncode,
+                },
+                error=stderr_text if process.returncode != 0 else None,
+                metadata={"command": command, "cwd": cwd}
+            )
+            
+        except asyncio.TimeoutError:
+            return ToolResult(
+                success=False,
+                error=f"Command timed out after {timeout}s",
+                metadata={"command": command}
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                error=f"Command execution failed: {str(e)}",
+                metadata={"command": command}
+            )

smartify/tools/mcp/__init__.py

@@ -0,0 +1,33 @@
+"""MCP (Model Context Protocol) integration for Smartify.
+
+This module provides plug-and-play integration with external MCP servers,
+allowing grids to use tools from any MCP-compatible server.
+
+Install the optional dependency:
+    pip install smartify[mcp]
+
+Example usage in a grid:
+    tools:
+      mcpServers:
+        - id: filesystem
+          transport: stdio
+          command: npx
+          args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+          prefix: fs
+"""
+
+from smartify.tools.mcp.client import (
+    McpClient,
+    McpServerConfig,
+    McpTransport,
+)
+from smartify.tools.mcp.adapter import McpToolWrapper
+from smartify.tools.mcp.registry import register_mcp_server
+
+__all__ = [
+    "McpClient",
+    "McpServerConfig",
+    "McpTransport",
+    "McpToolWrapper",
+    "register_mcp_server",
+]

smartify/tools/mcp/adapter.py

@@ -0,0 +1,157 @@
+"""MCP tool adapter for Smartify.
+
+Wraps MCP tools to implement the Smartify Tool interface, allowing
+MCP server tools to be used seamlessly in grid execution.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional, TYPE_CHECKING
+
+from smartify.tools.base import Tool, ToolResult
+
+if TYPE_CHECKING:
+    from smartify.tools.mcp.client import McpClient, McpToolDef
+
+logger = logging.getLogger(__name__)
+
+
+class McpToolWrapper(Tool):
+    """Wraps an MCP tool to implement the Smartify Tool interface.
+
+    This adapter allows MCP server tools to be registered in the Smartify
+    ToolRegistry and used by grid nodes just like builtin tools.
+
+    Example:
+        client = McpClient(config)
+        await client.connect()
+
+        tools = await client.list_tools()
+        for tool_def in tools:
+            wrapper = McpToolWrapper(client, tool_def, prefix="mcp")
+            registry.register(wrapper)
+    """
+
+    def __init__(
+        self,
+        client: "McpClient",
+        tool_def: "McpToolDef",
+        prefix: Optional[str] = None,
+    ):
+        """Initialize the MCP tool wrapper.
+
+        Args:
+            client: Connected MCP client instance
+            tool_def: Tool definition from MCP server
+            prefix: Optional prefix for the tool name (e.g. "mcp" -> "mcp_read_file")
+        """
+        self._client = client
+        self._tool_def = tool_def
+        self._prefix = prefix
+
+        # Build the Smartify tool name
+        if prefix:
+            self._name = f"{prefix}_{tool_def.name}"
+        else:
+            self._name = tool_def.name
+
+        # Store the original MCP tool name for calling
+        self._mcp_tool_name = tool_def.name
+
+    @property
+    def name(self) -> str:
+        """Tool name (possibly prefixed)."""
+        return self._name
+
+    @property
+    def description(self) -> str:
+        """Tool description from MCP server."""
+        return self._tool_def.description
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        """JSON Schema for tool parameters from MCP server."""
+        return self._tool_def.parameters
+
+    @property
+    def mcp_server_id(self) -> str:
+        """ID of the MCP server this tool belongs to."""
+        return self._client.config.id
+
+    @property
+    def mcp_tool_name(self) -> str:
+        """Original tool name on the MCP server."""
+        return self._mcp_tool_name
+
+    async def execute(self, **kwargs) -> ToolResult:
+        """Execute the MCP tool.
+
+        Args:
+            **kwargs: Tool arguments matching the parameter schema
+
+        Returns:
+            ToolResult with success status and output/error
+        """
+        if not self._client.is_connected:
+            return ToolResult(
+                success=False,
+                error=f"MCP server '{self._client.config.id}' is not connected",
+            )
+
+        logger.debug(
+            f"Executing MCP tool '{self._mcp_tool_name}' on server "
+            f"'{self._client.config.id}' with args: {kwargs}"
+        )
+
+        try:
+            result = await self._client.call_tool(self._mcp_tool_name, kwargs)
+
+            return ToolResult(
+                success=result["success"],
+                output=result["output"],
+                error=result.get("error"),
+                metadata={
+                    "mcp_server": self._client.config.id,
+                    "mcp_tool": self._mcp_tool_name,
+                },
+            )
+
+        except Exception as e:
+            logger.error(
+                f"MCP tool execution failed: {self._mcp_tool_name} - {e}"
+            )
+            return ToolResult(
+                success=False,
+                error=f"MCP tool execution failed: {e}",
+                metadata={
+                    "mcp_server": self._client.config.id,
+                    "mcp_tool": self._mcp_tool_name,
+                },
+            )
+
+    def to_openai_format(self) -> Dict[str, Any]:
+        """Convert to OpenAI function calling format."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def to_anthropic_format(self) -> Dict[str, Any]:
+        """Convert to Anthropic tool format."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.parameters,
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"McpToolWrapper(name={self.name!r}, "
+            f"mcp_server={self._client.config.id!r}, "
+            f"mcp_tool={self._mcp_tool_name!r})"
+        )

smartify/tools/mcp/client.py

@@ -0,0 +1,334 @@
+"""MCP client wrapper for Smartify.
+
+Provides a thin wrapper around the MCP Python SDK for connecting to
+MCP servers and calling their tools.
+"""
+
+from __future__ import annotations
+
+import logging
+from contextlib import AsyncExitStack
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Check for MCP SDK availability
+try:
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+    from mcp.client.sse import sse_client
+    from mcp.client.streamable_http import streamable_http_client
+    import mcp.types as mcp_types
+
+    MCP_AVAILABLE = True
+except ImportError:
+    MCP_AVAILABLE = False
+    ClientSession = None
+    StdioServerParameters = None
+    stdio_client = None
+    sse_client = None
+    streamable_http_client = None
+    mcp_types = None
+
+
+class McpTransport(str, Enum):
+    """Transport type for connecting to MCP servers."""
+
+    STDIO = "stdio"
+    SSE = "sse"
+    STREAMABLE_HTTP = "streamable_http"
+
+
+@dataclass
+class McpToolDef:
+    """Definition of a tool from an MCP server."""
+
+    name: str
+    description: str
+    parameters: Dict[str, Any]  # JSON Schema
+    output_schema: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class McpServerConfig:
+    """Configuration for connecting to an MCP server."""
+
+    id: str
+    transport: McpTransport = McpTransport.STDIO
+
+    # For stdio transport
+    command: Optional[str] = None
+    args: List[str] = field(default_factory=list)
+    env: Optional[Dict[str, str]] = None
+    cwd: Optional[str] = None
+
+    # For SSE/HTTP transport
+    url: Optional[str] = None
+    headers: Optional[Dict[str, str]] = None
+
+    # Tool naming
+    prefix: Optional[str] = None  # Prefix for tool names (e.g. "mcp_" -> "mcp_read_file")
+
+    # Optional: only expose specific tools
+    tools: Optional[List[str]] = None  # If set, only these tools are registered
+
+
+def _check_mcp_available() -> None:
+    """Raise ImportError if MCP SDK is not installed."""
+    if not MCP_AVAILABLE:
+        raise ImportError(
+            "MCP SDK not installed. Install with: pip install smartify[mcp]"
+        )
+
+
+class McpClient:
+    """Client for connecting to and interacting with an MCP server.
+
+    Usage:
+        config = McpServerConfig(
+            id="filesystem",
+            transport=McpTransport.STDIO,
+            command="npx",
+            args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+        )
+
+        async with McpClient(config) as client:
+            tools = await client.list_tools()
+            result = await client.call_tool("read_file", {"path": "/tmp/test.txt"})
+    """
+
+    def __init__(self, config: McpServerConfig):
+        _check_mcp_available()
+        self.config = config
+        self._exit_stack: Optional[AsyncExitStack] = None
+        self._session: Optional[ClientSession] = None
+        self._connected = False
+
+    async def __aenter__(self) -> "McpClient":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.disconnect()
+
+    async def connect(self) -> None:
+        """Connect to the MCP server."""
+        if self._connected:
+            return
+
+        _check_mcp_available()
+
+        self._exit_stack = AsyncExitStack()
+
+        try:
+            if self.config.transport == McpTransport.STDIO:
+                await self._connect_stdio()
+            elif self.config.transport == McpTransport.SSE:
+                await self._connect_sse()
+            elif self.config.transport == McpTransport.STREAMABLE_HTTP:
+                await self._connect_streamable_http()
+            else:
+                raise ValueError(f"Unknown transport: {self.config.transport}")
+
+            # Initialize the session
+            await self._session.initialize()
+            self._connected = True
+
+            logger.info(
+                f"Connected to MCP server '{self.config.id}' via {self.config.transport.value}"
+            )
+
+        except Exception as e:
+            # Clean up on connection failure
+            if self._exit_stack:
+                await self._exit_stack.aclose()
+                self._exit_stack = None
+            raise ConnectionError(
+                f"Failed to connect to MCP server '{self.config.id}': {e}"
+            ) from e
+
+    async def _connect_stdio(self) -> None:
+        """Connect via stdio transport."""
+        if not self.config.command:
+            raise ValueError("stdio transport requires 'command' in config")
+
+        server_params = StdioServerParameters(
+            command=self.config.command,
+            args=self.config.args,
+            env=self.config.env,
+            cwd=self.config.cwd,
+        )
+
+        transport = await self._exit_stack.enter_async_context(
+            stdio_client(server_params)
+        )
+        read_stream, write_stream = transport
+
+        self._session = await self._exit_stack.enter_async_context(
+            ClientSession(read_stream, write_stream)
+        )
+
+    async def _connect_sse(self) -> None:
+        """Connect via SSE transport."""
+        if not self.config.url:
+            raise ValueError("SSE transport requires 'url' in config")
+
+        transport = await self._exit_stack.enter_async_context(
+            sse_client(url=self.config.url, headers=self.config.headers)
+        )
+        read_stream, write_stream = transport
+
+        self._session = await self._exit_stack.enter_async_context(
+            ClientSession(read_stream, write_stream)
+        )
+
+    async def _connect_streamable_http(self) -> None:
+        """Connect via streamable HTTP transport."""
+        if not self.config.url:
+            raise ValueError("streamable_http transport requires 'url' in config")
+
+        transport = await self._exit_stack.enter_async_context(
+            streamable_http_client(url=self.config.url)
+        )
+        read_stream, write_stream, _ = transport
+
+        self._session = await self._exit_stack.enter_async_context(
+            ClientSession(read_stream, write_stream)
+        )
+
+    async def disconnect(self) -> None:
+        """Disconnect from the MCP server."""
+        if self._exit_stack:
+            await self._exit_stack.aclose()
+            self._exit_stack = None
+        self._session = None
+        self._connected = False
+        logger.debug(f"Disconnected from MCP server '{self.config.id}'")
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if connected to the server."""
+        return self._connected and self._session is not None
+
+    async def list_tools(self) -> List[McpToolDef]:
+        """List available tools from the MCP server.
+
+        Returns:
+            List of tool definitions with name, description, and parameter schema.
+        """
+        if not self.is_connected:
+            raise RuntimeError("Not connected to MCP server")
+
+        result = await self._session.list_tools()
+
+        tools = []
+        for tool in result.tools:
+            # Filter if specific tools are requested
+            if self.config.tools and tool.name not in self.config.tools:
+                continue
+
+            tools.append(
+                McpToolDef(
+                    name=tool.name,
+                    description=tool.description or "",
+                    parameters=tool.inputSchema or {"type": "object", "properties": {}},
+                    output_schema=tool.outputSchema,
+                )
+            )
+
+        logger.debug(
+            f"Listed {len(tools)} tools from MCP server '{self.config.id}': "
+            f"{[t.name for t in tools]}"
+        )
+        return tools
+
+    async def call_tool(
+        self, name: str, arguments: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Call a tool on the MCP server.
+
+        Args:
+            name: Tool name (without prefix)
+            arguments: Tool arguments
+
+        Returns:
+            Dict with 'success', 'output', and optionally 'error' keys.
+        """
+        if not self.is_connected:
+            raise RuntimeError("Not connected to MCP server")
+
+        try:
+            result = await self._session.call_tool(name, arguments or {})
+
+            # Process the result
+            if result.isError:
+                # Extract error message from content
+                error_msg = self._extract_text_content(result.content)
+                return {
+                    "success": False,
+                    "output": None,
+                    "error": error_msg or "Tool execution failed",
+                }
+
+            # Extract output from content
+            output = self._extract_content(result)
+            return {
+                "success": True,
+                "output": output,
+                "error": None,
+            }
+
+        except Exception as e:
+            logger.error(f"MCP tool call failed: {name} - {e}")
+            return {
+                "success": False,
+                "output": None,
+                "error": str(e),
+            }
+
+    def _extract_text_content(self, content: List) -> Optional[str]:
+        """Extract text from MCP content list."""
+        if not content:
+            return None
+
+        texts = []
+        for item in content:
+            if hasattr(item, "text"):
+                texts.append(item.text)
+            elif hasattr(item, "type") and item.type == "text":
+                texts.append(getattr(item, "text", str(item)))
+
+        return "\n".join(texts) if texts else None
+
+    def _extract_content(self, result) -> Any:
+        """Extract output from MCP CallToolResult."""
+        # If there's structured content, prefer that
+        if hasattr(result, "structuredContent") and result.structuredContent:
+            return result.structuredContent
+
+        # Otherwise extract from content list
+        if not result.content:
+            return None
+
+        # Single text item -> return as string
+        if len(result.content) == 1:
+            item = result.content[0]
+            if hasattr(item, "text"):
+                return item.text
+            elif hasattr(item, "data"):
+                # Binary/image content
+                return {"type": getattr(item, "type", "blob"), "data": item.data}
+
+        # Multiple items -> return as list
+        outputs = []
+        for item in result.content:
+            if hasattr(item, "text"):
+                outputs.append(item.text)
+            elif hasattr(item, "data"):
+                outputs.append({"type": getattr(item, "type", "blob"), "data": item.data})
+            else:
+                outputs.append(str(item))
+
+        return outputs