atlas-chat 0.1.0__py3-none-any.whl

atlas/mcp/filesystem/main.py

@@ -0,0 +1,348 @@
+#!/usr/bin/env python3
+"""
+Filesystem MCP Server using FastMCP
+Provides file system read/write operations through MCP protocol.
+"""
+
+from pathlib import Path
+from typing import Any, Dict
+
+from fastmcp import FastMCP
+
+# Initialize the MCP server
+mcp = FastMCP("Filesystem")
+
+# Base path for file operations (security constraint)
+BASE_PATH = Path(".").resolve()
+
+
+def _safe_path(path: str) -> Path:
+    """Ensure path is within base directory for security."""
+    requested_path = Path(path)
+    if requested_path.is_absolute():
+        full_path = requested_path
+    else:
+        full_path = BASE_PATH / requested_path
+
+    resolved_path = full_path.resolve()
+
+    # Ensure the path is within BASE_PATH
+    try:
+        resolved_path.relative_to(BASE_PATH)
+    except ValueError:
+        raise PermissionError("Access denied: path outside base directory")
+
+    return resolved_path
+
+
+@mcp.tool
+def read_file(path: str) -> Dict[str, Any]:
+    """
+    Read the complete contents of a text file from the secure filesystem.
+
+    This tool provides safe file reading capabilities with security restrictions:
+    - Only allows access to files within the designated base directory
+    - Supports both absolute and relative paths (relative paths are resolved from base)
+    - Automatically handles UTF-8 text encoding
+    - Returns file metadata along with content
+
+    **Security Features:**
+    - Path traversal protection (no access outside base directory)
+    - File existence validation
+    - Error handling for permission and access issues
+
+    **Use Cases:**
+    - Reading configuration files, logs, documentation
+    - Loading data files for processing
+    - Inspecting file contents for analysis
+
+    Args:
+        path: File path to read (string). Can be relative to base directory or absolute within allowed area.
+
+    Returns:
+        Dictionary containing:
+        - success: boolean indicating operation success
+        - content: string with complete file contents (UTF-8)
+        - path: resolved relative path from base directory
+        - size: file size in bytes
+        Or error message if operation fails
+    """
+    try:
+        file_path = _safe_path(path)
+        if not file_path.exists():
+            return {"results": {"error": f"File not found: {path}"}}
+
+        if file_path.is_dir():
+            return {"results": {"error": f"Path is a directory: {path}"}}
+
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+
+        return {
+            "results": {
+                "content": content,
+                "size": len(content),
+                "path": str(file_path.relative_to(BASE_PATH))
+            }
+        }
+    except PermissionError as e:
+        return {"results": {"error": str(e)}}
+    except Exception as e:
+        return {"results": {"error": f"Error reading file: {str(e)}"}}
+
+
+@mcp.tool
+def write_file(path: str, content: str) -> Dict[str, Any]:
+    """
+    Write text content to a file, creating the file and any necessary parent directories.
+
+    This tool provides safe file writing capabilities with automatic directory creation:
+    - Creates parent directories if they don't exist
+    - Overwrites existing files completely with new content
+    - Uses UTF-8 encoding for text files
+    - Security restrictions apply (no access outside base directory)
+
+    **Security Features:**
+    - Path traversal protection
+    - Safe directory creation with proper permissions
+    - Error handling for permission and access issues
+
+    **Use Cases:**
+    - Creating configuration files, reports, logs
+    - Saving processed data, analysis results
+    - Generating documentation or output files
+    - Creating backup copies of modified content
+
+    Args:
+        path: File path to write (string). Can be relative to base directory or absolute within allowed area.
+        content: Text content to write to the file (string, UTF-8 encoded)
+
+    Returns:
+        Dictionary containing:
+        - success: boolean indicating operation success
+        - path: resolved relative path from base directory
+        - size: number of characters written
+        Or error message if operation fails
+    """
+    try:
+        file_path = _safe_path(path)
+
+        # Create parent directories if they don't exist
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(file_path, 'w', encoding='utf-8') as f:
+            f.write(content)
+
+        return {
+            "results": {
+                "success": True,
+                "path": str(file_path.relative_to(BASE_PATH)),
+                "size": len(content)
+            }
+        }
+    except PermissionError as e:
+        return {"results": {"error": str(e)}}
+    except Exception as e:
+        return {"results": {"error": f"Error writing file: {str(e)}"}}
+
+
+@mcp.tool
+def list_directory(path: str = ".") -> Dict[str, Any]:
+    """
+    List all files and subdirectories within a specified directory with detailed metadata.
+
+    This tool provides comprehensive directory browsing capabilities:
+    - Lists both files and subdirectories with type identification
+    - Provides metadata including size, modification time, and permissions
+    - Supports recursive directory exploration within security boundaries
+    - Defaults to current working directory if no path specified
+
+    **Security Features:**
+    - Path traversal protection (no access outside base directory)
+    - Directory existence validation
+    - Safe handling of permission-restricted items
+
+    **Returned Information:**
+    - Item name and type (file/directory)
+    - File size (for files)
+    - Last modification timestamp
+    - Basic permission information
+
+    **Use Cases:**
+    - Exploring project structure and organization
+    - Finding specific files or directories
+    - Checking file metadata before processing
+    - Navigating filesystem for file operations
+
+    Args:
+        path: Directory path to list (string, defaults to current directory)
+
+    Returns:
+        Dictionary containing:
+        - path: resolved directory path
+        - items: list of dictionaries with file/directory information
+        Each item includes: name, type, size (if file), modified_time, is_directory
+        Or error message if operation fails
+    """
+    try:
+        dir_path = _safe_path(path)
+        if not dir_path.exists():
+            return {"results": {"error": f"Directory not found: {path}"}}
+
+        if not dir_path.is_dir():
+            return {"results": {"error": f"Path is not a directory: {path}"}}
+
+        items = []
+        for item in dir_path.iterdir():
+            items.append({
+                "name": item.name,
+                "type": "directory" if item.is_dir() else "file",
+                "size": item.stat().st_size if item.is_file() else None
+            })
+
+        return {
+            "results": {
+                "path": str(dir_path.relative_to(BASE_PATH)),
+                "items": sorted(items, key=lambda x: (x["type"], x["name"]))
+            }
+        }
+    except PermissionError as e:
+        return {"results": {"error": str(e)}}
+    except Exception as e:
+        return {"results": {"error": f"Error listing directory: {str(e)}"}}
+
+
+@mcp.tool
+def create_directory(path: str) -> Dict[str, Any]:
+    """
+    Create a new directory, including any necessary parent directories in the path.
+
+    This tool provides comprehensive directory creation capabilities:
+    - Creates the target directory and all parent directories if they don't exist
+    - Uses safe permissions and follows system defaults
+    - Handles existing directories gracefully (no error if already exists)
+    - Security restrictions apply (no access outside base directory)
+
+    **Security Features:**
+    - Path traversal protection
+    - Safe directory creation with proper permissions
+    - Error handling for permission and access issues
+
+    **Use Cases:**
+    - Setting up project folder structures
+    - Creating organized storage for different file types
+    - Preparing directories for batch file operations
+    - Establishing workspace organization
+
+    Args:
+        path: Directory path to create (string). Can be relative to base or absolute within allowed area.
+
+    Returns:
+        Dictionary containing:
+        - success: boolean indicating operation success
+        - path: resolved relative path from base directory
+        Or error message if operation fails
+    """
+    try:
+        dir_path = _safe_path(path)
+        dir_path.mkdir(parents=True, exist_ok=True)
+
+        return {
+            "results": {
+                "success": True,
+                "path": str(dir_path.relative_to(BASE_PATH))
+            }
+        }
+    except PermissionError as e:
+        return {"results": {"error": str(e)}}
+    except Exception as e:
+        return {"results": {"error": f"Error creating directory: {str(e)}"}}
+
+
+@mcp.tool
+def delete_file(path: str) -> Dict[str, Any]:
+    """
+    Permanently delete a single file from the filesystem with safety validations.
+
+    This tool provides secure file deletion capabilities:
+    - Only deletes files (not directories - use appropriate directory removal tools)
+    - Validates file existence before attempting deletion
+    - Provides clear error messages for different failure conditions
+    - Security restrictions apply (no access outside base directory)
+
+    **Security Features:**
+    - Path traversal protection
+    - File vs directory validation (prevents accidental directory deletion)
+    - File existence verification
+    - Error handling for permission issues
+
+    **Important Notes:**
+    - This operation is permanent and cannot be undone
+    - Only works on files, not directories
+    - Will fail safely if target is a directory or doesn't exist
+
+    **Use Cases:**
+    - Cleaning up temporary or outdated files
+    - Removing processed files after successful operations
+    - Managing storage space by removing unnecessary files
+    - Maintaining clean project directories
+
+    Args:
+        path: File path to delete (string). Can be relative to base or absolute within allowed area.
+
+    Returns:
+        Dictionary containing:
+        - success: boolean indicating operation success
+        - path: resolved relative path of deleted file
+        Or error message if operation fails (file not found, is directory, permission denied)
+    """
+    try:
+        file_path = _safe_path(path)
+        if not file_path.exists():
+            return {"results": {"error": f"File not found: {path}"}}
+
+        if file_path.is_dir():
+            return {"results": {"error": f"Path is a directory (use rmdir): {path}"}}
+
+        file_path.unlink()
+        return {
+            "results": {
+                "success": True,
+                "path": str(file_path.relative_to(BASE_PATH))
+            }
+        }
+    except PermissionError as e:
+        return {"error": str(e)}
+    except Exception as e:
+        return {"error": f"Error deleting file: {str(e)}"}
+
+
+@mcp.tool
+def file_exists(path: str) -> Dict[str, Any]:
+    """
+    Check if a file or directory exists.
+
+    Args:
+        path: Path to check
+
+    Returns:
+        Dictionary with existence status and file type information
+    """
+    try:
+        file_path = _safe_path(path)
+        return {
+            "results": {
+                "exists": file_path.exists(),
+                "is_file": file_path.is_file(),
+                "is_directory": file_path.is_dir(),
+                "path": str(file_path.relative_to(BASE_PATH))
+            }
+        }
+    except PermissionError as e:
+        return {"results": {"error": str(e)}}
+    except Exception as e:
+        return {"results": {"error": f"Error checking file: {str(e)}"}}
+
+
+if __name__ == "__main__":
+    mcp.run()

atlas/mcp/image_demo/main.py

@@ -0,0 +1,113 @@
+"""
+MCP server that demonstrates returning ImageContent.
+This is a test server to validate image display functionality.
+"""
+
+import base64
+from io import BytesIO
+
+from fastmcp import FastMCP
+from fastmcp.tools.tool import ToolResult
+from mcp.types import ImageContent, TextContent
+
+mcp = FastMCP("Image Demo MCP")
+
+
+@mcp.tool()
+def generate_test_image() -> ToolResult:
+    """
+    Generate a simple test PNG image and return it as ImageContent.
+    This demonstrates the ImageContent return type for MCP tools.
+    """
+    try:
+        from PIL import Image, ImageDraw, ImageFont
+    except ImportError:
+        # If PIL is not available, return a minimal 1x1 PNG
+        # This is a valid 1x1 red pixel PNG in base64
+        minimal_png = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
+        return ToolResult(
+            content=[
+                TextContent(type="text", text="Success: Generated fallback image (PIL not available). Returned image_0.png"),
+                ImageContent(type="image", data=minimal_png, mimeType="image/png")
+            ]
+        )
+
+    # Create a 400x300 image with a gradient background
+    img = Image.new('RGB', (400, 300), color='white')
+    draw = ImageDraw.Draw(img)
+
+    # Draw a gradient
+    for y in range(300):
+        color_val = int(255 * (y / 300))
+        draw.rectangle([(0, y), (400, y+1)], fill=(color_val, 100, 255 - color_val))
+
+    # Draw some text
+    try:
+        # Try to use a default font
+        font = ImageFont.load_default()
+    except Exception:
+        font = None
+
+    draw.text((50, 130), "Test Image from MCP Tool", fill=(255, 255, 255), font=font)
+    draw.text((50, 160), "This demonstrates ImageContent", fill=(255, 255, 255), font=font)
+
+    # Convert to base64
+    buffer = BytesIO()
+    img.save(buffer, format='PNG')
+    img_base64 = base64.b64encode(buffer.getvalue()).decode('utf-8')
+
+    return ToolResult(
+        content=[
+            TextContent(type="text", text="Success: Generated 400x300 PNG test image with gradient background. Returned image_0.png - the image should now be visible in the canvas panel."),
+            ImageContent(type="image", data=img_base64, mimeType="image/png")
+        ]
+    )
+
+
+@mcp.tool()
+def generate_multiple_images() -> ToolResult:
+    """
+    Generate multiple test images and return them as a list of ImageContent.
+    This tests handling multiple images in a single tool response.
+    """
+    try:
+        from PIL import Image, ImageDraw
+    except ImportError:
+        # Return minimal PNGs if PIL not available
+        minimal_png = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
+        return ToolResult(
+            content=[
+                TextContent(type="text", text="Success: Generated 2 fallback images (PIL not available). Returned image_0.png, image_1.png"),
+                ImageContent(type="image", data=minimal_png, mimeType="image/png"),
+                ImageContent(type="image", data=minimal_png, mimeType="image/png")
+            ]
+        )
+
+    content_blocks = [
+        TextContent(type="text", text="Success: Generated 3 colored PNG images (200x200 each: red, green, blue with white circles). Returned image_0.png, image_1.png, image_2.png - images should now be visible in the canvas panel.")
+    ]
+    colors = [(255, 100, 100), (100, 255, 100), (100, 100, 255)]
+
+    for i, color in enumerate(colors):
+        img = Image.new('RGB', (200, 200), color=color)
+        draw = ImageDraw.Draw(img)
+
+        # Draw a circle
+        draw.ellipse([50, 50, 150, 150], fill=(255, 255, 255))
+
+        # Convert to base64
+        buffer = BytesIO()
+        img.save(buffer, format='PNG')
+        img_base64 = base64.b64encode(buffer.getvalue()).decode('utf-8')
+
+        content_blocks.append(ImageContent(
+            type="image",
+            data=img_base64,
+            mimeType="image/png"
+        ))
+
+    return ToolResult(content=content_blocks)
+
+
+if __name__ == "__main__":
+    mcp.run()

atlas/mcp/image_demo/requirements.txt

@@ -0,0 +1,4 @@
+# Optional dependencies for image_demo MCP server
+# The server has fallbacks if Pillow is not installed
+
+Pillow>=10.0.0

atlas/mcp/logging_demo/README.md

@@ -0,0 +1,72 @@
+# Logging Demo MCP Server
+
+A demonstration MCP server that showcases the logging capabilities of Atlas UI 3's MCP integration.
+
+## Purpose
+
+This server provides a simple tool that emits log messages at various levels to test and demonstrate the MCP logging infrastructure.
+
+## Usage
+
+### Configuration
+
+Add to your `mcp.json`:
+
+```json
+{
+  "logging_demo": {
+    "command": ["python", "main.py"],
+    "cwd": "backend/mcp/logging_demo",
+    "transport": "stdio"
+  }
+}
+```
+
+### Tool: test_logging
+
+Test MCP server logging at various levels.
+
+**Parameters:**
+- `operation` (string): Which logging levels to test
+  - `"all"` - Test all log levels (debug, info, warning, error)
+  - `"debug"` - Debug level only
+  - `"info"` - Info level only
+  - `"warning"` - Warning level only
+  - `"error"` - Error level only
+  - `"mixed"` - A realistic mix of levels simulating an operation
+
+**Examples:**
+
+```
+Use the tool: logging_demo_test_logging with operation="all"
+```
+
+```
+Use the tool: logging_demo_test_logging with operation="mixed"
+```
+
+## Expected Output
+
+When you call this tool with `operation="all"`, you should see:
+1. The tool result showing success
+2. Log messages appearing in the chat window with colored badges:
+   - DEBUG (gray) - "This is a DEBUG message..."
+   - INFO (blue) - "This is an INFO message..."
+   - WARNING (yellow) - "This is a WARNING message..."
+   - ERROR (red) - "This is an ERROR message..."
+
+**Note:** DEBUG logs will only appear if `LOG_LEVEL=DEBUG` is set in your environment.
+
+## Testing Log Levels
+
+To test filtering:
+
+1. Set `LOG_LEVEL=WARNING` in `.env`
+2. Restart the backend
+3. Call the tool with `operation="all"`
+4. You should only see WARNING and ERROR messages (INFO and DEBUG filtered out)
+
+## See Also
+
+- [MCP Server Logging Documentation](../../docs/developer/mcp-server-logging.md)
+- [FastMCP Logging Documentation](https://gofastmcp.com/clients/logging)

atlas/mcp/logging_demo/main.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+Logging Demo MCP Server using FastMCP
+Demonstrates MCP server logging at various levels.
+"""
+
+import asyncio
+import time
+from typing import Any, Dict
+
+from fastmcp import Context, FastMCP
+
+# Initialize the MCP server
+mcp = FastMCP("Logging Demo")
+
+
+@mcp.tool
+async def test_logging(operation: str, ctx: Context) -> Dict[str, Any]:
+    """Test MCP server logging at various levels.
+
+    This tool demonstrates log output from an MCP server. It emits log messages
+    at different levels (debug, info, warning, error) to test the logging infrastructure.
+
+    Args:
+        operation: Which logging levels to test. Options:
+            - "all": Test all log levels
+            - "debug": Debug level only
+            - "info": Info level only
+            - "warning": Warning level only
+            - "error": Error level only
+            - "mixed": A realistic mix of levels
+            - "mixed-delay": Like "mixed", but with short delays between log calls
+
+    Returns:
+        Dict with results and logs emitted
+    """
+    start = time.perf_counter()
+
+    logs_emitted = []
+
+    if operation == "all" or operation == "debug":
+        await ctx.debug("This is a DEBUG message - detailed information for diagnostics")
+        logs_emitted.append("debug")
+
+    if operation == "all" or operation == "info":
+        await ctx.info("This is an INFO message - general informational message")
+        logs_emitted.append("info")
+
+    if operation == "all" or operation == "warning":
+        await ctx.warning("This is a WARNING message - something unexpected happened")
+        logs_emitted.append("warning")
+
+    if operation == "all" or operation == "error":
+        await ctx.error("This is an ERROR message - something went wrong")
+        logs_emitted.append("error")
+
+    if operation == "mixed":
+        await ctx.info("Starting operation...")
+        await ctx.debug("Processing step 1")
+        await ctx.debug("Processing step 2")
+        await ctx.info("Operation in progress (50% complete)")
+        await ctx.debug("Processing step 3")
+        await ctx.warning("Encountered a minor issue, continuing...")
+        await ctx.debug("Processing step 4")
+        await ctx.info("Operation completed successfully")
+        logs_emitted = ["info", "debug", "debug", "info", "debug", "warning", "debug", "info"]
+
+    if operation == "mixed-delay":
+        delay_s = 0.35
+        await ctx.info("Starting operation...")
+        await asyncio.sleep(delay_s)
+        await ctx.debug("Processing step 1")
+        await asyncio.sleep(delay_s)
+        await ctx.debug("Processing step 2")
+        await asyncio.sleep(delay_s)
+        await ctx.info("Operation in progress (50% complete)")
+        await asyncio.sleep(delay_s)
+        await ctx.debug("Processing step 3")
+        await asyncio.sleep(delay_s)
+        await ctx.warning("Encountered a minor issue, continuing...")
+        await asyncio.sleep(delay_s)
+        await ctx.debug("Processing step 4")
+        await asyncio.sleep(delay_s)
+        await ctx.info("Operation completed successfully")
+        logs_emitted = ["info", "debug", "debug", "info", "debug", "warning", "debug", "info"]
+
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 3)
+
+    return {
+        "results": {
+            "operation": operation,
+            "logs_emitted": logs_emitted,
+            "message": f"Successfully tested {operation} logging level(s)"
+        },
+        "meta_data": {
+            "is_error": False,
+            "elapsed_ms": elapsed_ms
+        }
+    }
+
+
+if __name__ == "__main__":
+    mcp.run()

atlas/mcp/many_tools_demo/main.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""
+MCP Server with 64 tools for testing UI with many tools.
+Demonstrates that the collapsible UI can handle servers with large numbers of tools.
+"""
+
+from fastmcp import FastMCP
+
+# Create the MCP server
+mcp = FastMCP("ManyToolsDemo")
+
+# Generate 64 tools dynamically to test UI scalability
+# Categories: data, analytics, file, network, system, database, security, report
+
+TOOL_CATEGORIES = [
+    ("data", 10, "Process and transform data"),
+    ("analytics", 10, "Analyze data and generate insights"),
+    ("file", 8, "File operations and management"),
+    ("network", 8, "Network operations and monitoring"),
+    ("system", 8, "System administration tasks"),
+    ("database", 8, "Database operations"),
+    ("security", 6, "Security and encryption tasks"),
+    ("report", 6, "Report generation and formatting"),
+]
+
+# Dynamically create tools for each category
+for category, count, description_base in TOOL_CATEGORIES:
+    for i in range(1, count + 1):
+        tool_name = f"{category}_operation_{i}"
+        tool_description = f"{description_base} - Operation {i}"
+
+        # Use exec to create properly named functions
+        exec(f"""
+@mcp.tool()
+def {tool_name}(input_data: str = "default") -> str:
+    '''
+    {tool_description}
+
+    Args:
+        input_data: Input data to process
+
+    Returns:
+        str: Result of the operation
+    '''
+    return f"Executed {tool_name} with input: {{input_data}}"
+""")
+
+if __name__ == "__main__":
+    mcp.run()
+