mseep-rmcp 0.3.3__py3-none-any.whl

rmcp/registries/tools.py

@@ -0,0 +1,223 @@
+"""
+Tools registry for MCP server.
+
+Provides:
+- @tool decorator for declarative tool registration
+- Schema validation with proper error codes
+- Tool discovery and dispatch
+- Context-aware execution
+
+Following the principle: "Registries are discoverable and testable."
+"""
+
+from typing import Any, Dict, List, Optional, Callable, Awaitable, Union
+from functools import wraps
+from dataclasses import dataclass
+import inspect
+import logging
+
+from ..core.context import Context
+from ..core.schemas import validate_schema, SchemaError, statistical_result_schema
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ToolDefinition:
+    """Tool metadata and handler."""
+    
+    name: str
+    handler: Callable[[Context, Dict[str, Any]], Awaitable[Dict[str, Any]]]
+    input_schema: Dict[str, Any]
+    output_schema: Optional[Dict[str, Any]] = None
+    title: Optional[str] = None
+    description: Optional[str] = None
+    annotations: Optional[Dict[str, Any]] = None
+
+
+class ToolsRegistry:
+    """Registry for MCP tools with schema validation."""
+    
+    def __init__(self):
+        self._tools: Dict[str, ToolDefinition] = {}
+    
+    def register(
+        self,
+        name: str,
+        handler: Callable[[Context, Dict[str, Any]], Awaitable[Dict[str, Any]]],
+        input_schema: Dict[str, Any],
+        output_schema: Optional[Dict[str, Any]] = None,
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+        annotations: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Register a tool with the registry."""
+        
+        if name in self._tools:
+            logger.warning(f"Tool '{name}' already registered, overwriting")
+        
+        self._tools[name] = ToolDefinition(
+            name=name,
+            handler=handler,
+            input_schema=input_schema,
+            output_schema=output_schema,
+            title=title or name,
+            description=description or f"Execute {name}",
+            annotations=annotations or {},
+        )
+        
+        logger.debug(f"Registered tool: {name}")
+    
+    async def list_tools(self, context: Context) -> Dict[str, Any]:
+        """List available tools for MCP tools/list."""
+        
+        tools = []
+        for tool_def in self._tools.values():
+            tool_info = {
+                "name": tool_def.name,
+                "title": tool_def.title,
+                "description": tool_def.description,
+                "inputSchema": tool_def.input_schema,
+            }
+            
+            if tool_def.output_schema:
+                tool_info["outputSchema"] = tool_def.output_schema
+            
+            if tool_def.annotations:
+                tool_info["annotations"] = tool_def.annotations
+            
+            tools.append(tool_info)
+        
+        await context.info(f"Listed {len(tools)} available tools")
+        
+        return {"tools": tools}
+    
+    async def call_tool(
+        self, 
+        context: Context, 
+        name: str, 
+        arguments: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Call a tool with validation."""
+        
+        if name not in self._tools:
+            raise ValueError(f"Unknown tool: {name}")
+        
+        tool_def = self._tools[name]
+        
+        try:
+            # Validate input schema
+            validate_schema(arguments, tool_def.input_schema, f"tool '{name}' arguments")
+            
+            await context.info(f"Calling tool: {name}", arguments=arguments)
+            
+            # Check cancellation before execution
+            context.check_cancellation()
+            
+            # Execute tool handler
+            result = await tool_def.handler(context, arguments)
+            
+            # Validate output schema if provided
+            if tool_def.output_schema:
+                validate_schema(result, tool_def.output_schema, f"tool '{name}' output")
+            
+            await context.info(f"Tool completed: {name}")
+            
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": str(result)
+                    }
+                ]
+            }
+        
+        except SchemaError as e:
+            await context.error(f"Schema validation failed for tool '{name}': {e}")
+            return {
+                "content": [
+                    {
+                        "type": "text", 
+                        "text": f"Error: {e}"
+                    }
+                ],
+                "isError": True
+            }
+        
+        except Exception as e:
+            await context.error(f"Tool execution failed for '{name}': {e}")
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Tool execution error: {e}"
+                    }
+                ],
+                "isError": True
+            }
+
+
+def tool(
+    name: str,
+    input_schema: Dict[str, Any],
+    output_schema: Optional[Dict[str, Any]] = None,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    annotations: Optional[Dict[str, Any]] = None,
+):
+    """
+    Decorator to register a function as an MCP tool.
+    
+    Usage:
+        @tool(
+            name="analyze_data",
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "data": table_schema(),
+                    "method": choice_schema(["mean", "median", "mode"])
+                },
+                "required": ["data"]
+            },
+            description="Analyze dataset with specified method"
+        )
+        async def analyze_data(context: Context, params: Dict[str, Any]) -> Dict[str, Any]:
+            # Tool implementation
+            return {"result": "analysis complete"}
+    """
+    
+    def decorator(func: Callable[[Context, Dict[str, Any]], Awaitable[Dict[str, Any]]]):
+        
+        # Ensure function is async
+        if not inspect.iscoroutinefunction(func):
+            raise ValueError(f"Tool handler '{name}' must be an async function")
+        
+        # Store tool metadata on function for registration
+        func._mcp_tool_name = name
+        func._mcp_tool_input_schema = input_schema
+        func._mcp_tool_output_schema = output_schema
+        func._mcp_tool_title = title
+        func._mcp_tool_description = description
+        func._mcp_tool_annotations = annotations
+        
+        return func
+    
+    return decorator
+
+
+def register_tool_functions(registry: ToolsRegistry, *functions) -> None:
+    """Register multiple functions decorated with @tool."""
+    
+    for func in functions:
+        if hasattr(func, '_mcp_tool_name'):
+            registry.register(
+                name=func._mcp_tool_name,
+                handler=func,
+                input_schema=func._mcp_tool_input_schema,
+                output_schema=func._mcp_tool_output_schema,
+                title=func._mcp_tool_title,
+                description=func._mcp_tool_description,
+                annotations=func._mcp_tool_annotations,
+            )
+        else:
+            logger.warning(f"Function {func.__name__} not decorated with @tool, skipping")

rmcp/scripts/__init__.py

@@ -0,0 +1,9 @@
+"""
+Build and development scripts.
+
+Contains scripts for:
+- Code formatting and linting
+- Test execution  
+- Build processes
+- Development workflows
+"""

rmcp/security/__init__.py

@@ -0,0 +1,15 @@
+"""
+Security components for MCP server.
+
+Implements:
+- Virtual File System (VFS) with allowlists and sandboxing
+- Path traversal protection
+- Content type validation
+- Size limits and safety checks
+
+Following the principle: "Security by default."
+"""
+
+from .vfs import VFS, VFSError
+
+__all__ = ["VFS", "VFSError"]

rmcp/security/vfs.py

@@ -0,0 +1,233 @@
+"""
+Virtual File System for secure file access.
+
+Implements mature MCP server patterns:
+- Explicit allowed roots (mounts)
+- Path normalization and traversal checks
+- MIME type detection and size caps
+- Read-only enforcement
+
+Following the pattern: "Gate filesystem access with a tiny VFS."
+"""
+
+import os
+import mimetypes
+from pathlib import Path
+from typing import List, Optional, Dict, Any, Union
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class VFSError(Exception):
+    """VFS access error."""
+    pass
+
+
+class VFS:
+    """
+    Virtual File System with security controls.
+    
+    Provides safe file access with:
+    - Allowlisted root directories (explicit mounts)
+    - Path traversal protection
+    - File type and size limits
+    - Read-only enforcement
+    """
+    
+    def __init__(
+        self,
+        allowed_roots: List[Path],
+        read_only: bool = True,
+        max_file_size: int = 50 * 1024 * 1024,  # 50MB
+        allowed_mime_types: Optional[List[str]] = None,
+    ):
+        self.allowed_roots = [root.resolve() for root in allowed_roots]
+        self.read_only = read_only
+        self.max_file_size = max_file_size
+        
+        # Default allowed MIME types for data analysis
+        self.allowed_mime_types = allowed_mime_types or [
+            'text/plain',
+            'text/csv', 
+            'application/json',
+            'application/xml',
+            'text/xml',
+            'application/pdf',
+            'text/tab-separated-values',
+            'application/vnd.ms-excel',
+            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        ]
+        
+        logger.info(
+            f"VFS initialized: {len(self.allowed_roots)} roots, "
+            f"read_only={read_only}, max_size={max_file_size}"
+        )
+    
+    def _resolve_and_validate_path(self, path: Union[str, Path]) -> Path:
+        """Resolve path and validate against allowed roots."""
+        
+        try:
+            # Resolve path to handle symlinks and relative paths
+            resolved_path = Path(path).resolve()
+        except (OSError, ValueError) as e:
+            raise VFSError(f"Invalid path: {path} ({e})")
+        
+        # Check if path is under any allowed root
+        for allowed_root in self.allowed_roots:
+            try:
+                resolved_path.relative_to(allowed_root)
+                return resolved_path
+            except ValueError:
+                continue
+        
+        # Not under any allowed root
+        allowed_roots_str = ", ".join(str(root) for root in self.allowed_roots)
+        raise VFSError(
+            f"Path access denied: {resolved_path}. "
+            f"Allowed roots: [{allowed_roots_str}]"
+        )
+    
+    def _check_file_constraints(self, path: Path) -> None:
+        """Check file size and type constraints."""
+        
+        if not path.exists():
+            raise VFSError(f"File not found: {path}")
+        
+        if not path.is_file():
+            raise VFSError(f"Not a regular file: {path}")
+        
+        # Check file size
+        file_size = path.stat().st_size
+        if file_size > self.max_file_size:
+            raise VFSError(
+                f"File too large: {path} ({file_size} bytes, max {self.max_file_size})"
+            )
+        
+        # Check MIME type
+        mime_type, _ = mimetypes.guess_type(str(path))
+        if mime_type and mime_type not in self.allowed_mime_types:
+            raise VFSError(
+                f"File type not allowed: {path} ({mime_type}). "
+                f"Allowed types: {self.allowed_mime_types}"
+            )
+    
+    def read_file(self, path: Union[str, Path]) -> bytes:
+        """Read file with security checks."""
+        
+        resolved_path = self._resolve_and_validate_path(path)
+        self._check_file_constraints(resolved_path)
+        
+        try:
+            with open(resolved_path, 'rb') as f:
+                content = f.read()
+            
+            logger.debug(f"Read file: {resolved_path} ({len(content)} bytes)")
+            return content
+            
+        except (OSError, IOError) as e:
+            raise VFSError(f"Failed to read file {resolved_path}: {e}")
+    
+    def read_text(self, path: Union[str, Path], encoding: str = 'utf-8') -> str:
+        """Read text file with security checks."""
+        
+        content = self.read_file(path)
+        try:
+            return content.decode(encoding)
+        except UnicodeDecodeError as e:
+            raise VFSError(f"Failed to decode file {path} as {encoding}: {e}")
+    
+    def list_directory(self, path: Union[str, Path]) -> List[Dict[str, Any]]:
+        """List directory contents with security checks."""
+        
+        resolved_path = self._resolve_and_validate_path(path)
+        
+        if not resolved_path.is_dir():
+            raise VFSError(f"Not a directory: {resolved_path}")
+        
+        try:
+            entries = []
+            for entry in resolved_path.iterdir():
+                try:
+                    stat = entry.stat()
+                    mime_type, _ = mimetypes.guess_type(str(entry))
+                    
+                    entries.append({
+                        "name": entry.name,
+                        "path": str(entry),
+                        "type": "directory" if entry.is_dir() else "file",
+                        "size": stat.st_size if entry.is_file() else None,
+                        "modified": stat.st_mtime,
+                        "mime_type": mime_type,
+                    })
+                except (OSError, IOError):
+                    # Skip entries we can't stat
+                    continue
+            
+            logger.debug(f"Listed directory: {resolved_path} ({len(entries)} entries)")
+            return entries
+            
+        except (OSError, IOError) as e:
+            raise VFSError(f"Failed to list directory {resolved_path}: {e}")
+    
+    def write_file(self, path: Union[str, Path], content: bytes) -> None:
+        """Write file with security checks."""
+        
+        if self.read_only:
+            raise VFSError("VFS is configured as read-only")
+        
+        resolved_path = self._resolve_and_validate_path(path)
+        
+        # Check content size
+        if len(content) > self.max_file_size:
+            raise VFSError(
+                f"Content too large: {len(content)} bytes, max {self.max_file_size}"
+            )
+        
+        try:
+            # Ensure parent directory exists
+            resolved_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            with open(resolved_path, 'wb') as f:
+                f.write(content)
+            
+            logger.debug(f"Wrote file: {resolved_path} ({len(content)} bytes)")
+            
+        except (OSError, IOError) as e:
+            raise VFSError(f"Failed to write file {resolved_path}: {e}")
+    
+    def write_text(self, path: Union[str, Path], content: str, encoding: str = 'utf-8') -> None:
+        """Write text file with security checks."""
+        
+        try:
+            encoded_content = content.encode(encoding)
+            self.write_file(path, encoded_content)
+        except UnicodeEncodeError as e:
+            raise VFSError(f"Failed to encode content as {encoding}: {e}")
+    
+    def file_info(self, path: Union[str, Path]) -> Dict[str, Any]:
+        """Get file information with security checks."""
+        
+        resolved_path = self._resolve_and_validate_path(path)
+        
+        if not resolved_path.exists():
+            raise VFSError(f"File not found: {resolved_path}")
+        
+        try:
+            stat = resolved_path.stat()
+            mime_type, encoding = mimetypes.guess_type(str(resolved_path))
+            
+            return {
+                "path": str(resolved_path),
+                "name": resolved_path.name,
+                "type": "directory" if resolved_path.is_dir() else "file",
+                "size": stat.st_size,
+                "modified": stat.st_mtime,
+                "mime_type": mime_type,
+                "encoding": encoding,
+                "readable": os.access(resolved_path, os.R_OK),
+                "writable": os.access(resolved_path, os.W_OK) and not self.read_only,
+            }
+            
+        except (OSError, IOError) as e:
+            raise VFSError(f"Failed to get file info for {resolved_path}: {e}")