atlas-chat 0.1.0__py3-none-any.whl

atlas/mcp/env-demo/README.md

@@ -0,0 +1,158 @@
+# Environment Variable Demo MCP Server
+
+This MCP server demonstrates the environment variable passing capability added to Atlas UI 3. It shows how to configure and use environment variables for MCP servers through the `mcp.json` configuration file.
+
+## Purpose
+
+This server provides tools to:
+- Retrieve specific environment variables
+- List all configured environment variables
+- Demonstrate practical usage patterns for environment variables
+
+## Configuration
+
+The server is configured in `config/overrides/mcp.json` (or `config/defaults/mcp.json`) with the `env` field:
+
+```json
+{
+  "env-demo": {
+    "command": ["python", "mcp/env-demo/main.py"],
+    "cwd": "atlas",
+    "env": {
+      "CLOUD_PROFILE": "demo-profile",
+      "CLOUD_REGION": "us-west-2",
+      "DEBUG_MODE": "true",
+      "ENVIRONMENT": "development",
+      "API_KEY": "${DEMO_API_KEY}"
+    },
+    "groups": ["users"],
+    "description": "Demonstrates environment variable passing to MCP servers",
+    "compliance_level": "Public"
+  }
+}
+```
+
+## Environment Variable Features
+
+### Literal Values
+Set environment variables with literal string values:
+```json
+"env": {
+  "CLOUD_REGION": "us-west-2",
+  "DEBUG_MODE": "true"
+}
+```
+
+### Variable Substitution
+Reference system environment variables using `${VAR_NAME}` syntax:
+```json
+"env": {
+  "API_KEY": "${DEMO_API_KEY}"
+}
+```
+
+Before starting Atlas UI, set the system environment variable:
+```bash
+export DEMO_API_KEY="your-secret-key"
+```
+
+## Available Tools
+
+### 1. `get_env_var`
+Retrieves the value of a specific environment variable.
+
+**Input:**
+- `var_name` (string): Name of the environment variable
+
+**Example Usage:**
+```
+Get the value of CLOUD_REGION
+```
+
+### 2. `list_configured_env_vars`
+Lists all configured environment variables that are commonly expected.
+
+**Example Usage:**
+```
+Show me the configured environment variables
+```
+
+### 3. `demonstrate_env_usage`
+Shows practical examples of using environment variables.
+
+**Input:**
+- `operation` (string): Type of demonstration
+  - `"info"`: General information about env var configuration
+  - `"config"`: Demonstrates configuration usage (profile, region)
+  - `"credentials"`: Demonstrates secure credential handling
+
+**Example Usage:**
+```
+Demonstrate how to use environment variables for configuration
+```
+
+## Use Cases
+
+### Cloud Configuration
+```json
+"env": {
+  "CLOUD_PROFILE": "production-profile",
+  "CLOUD_REGION": "us-east-1",
+  "AVAILABILITY_ZONE": "us-east-1a"
+}
+```
+
+### API Credentials
+```json
+"env": {
+  "API_KEY": "${MY_SERVICE_API_KEY}",
+  "API_ENDPOINT": "https://api.example.com"
+}
+```
+
+### Feature Flags
+```json
+"env": {
+  "DEBUG_MODE": "false",
+  "ENABLE_CACHING": "true",
+  "MAX_RETRIES": "3"
+}
+```
+
+## Security Best Practices
+
+1. **Never commit secrets**: Use `${VAR_NAME}` substitution for sensitive values
+2. **Set system env vars**: Configure sensitive values at the system level
+3. **Use appropriate compliance levels**: Mark servers with sensitive access appropriately
+4. **Document required variables**: Clearly document which env vars are needed
+
+## Testing
+
+To test this server:
+
+1. Set any optional environment variables:
+```bash
+export DEMO_API_KEY="test-key-123"
+```
+
+2. Start Atlas UI (the server will automatically load with the configured env vars)
+
+3. In the chat interface, try:
+```
+List all configured environment variables for the env-demo server
+```
+
+```
+Get the value of CLOUD_REGION
+```
+
+```
+Demonstrate how environment variables are used for credentials
+```
+
+## Notes
+
+- Environment variables are only passed to stdio servers (not HTTP/SSE servers)
+- If a `${VAR_NAME}` reference cannot be resolved, server initialization will fail with a clear error message
+- Empty `env: {}` is valid and will set no environment variables
+- The `env` field is optional; servers work without it as before

atlas/mcp/env-demo/main.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""
+Environment Variable Demo MCP Server using FastMCP
+
+This server demonstrates the environment variable passing capability.
+It reads environment variables that are configured in mcp.json and
+exposes them through MCP tools.
+"""
+
+import os
+import time
+from typing import Any, Dict
+
+from fastmcp import FastMCP
+
+# Initialize the MCP server
+mcp = FastMCP("Environment Variable Demo")
+
+
+@mcp.tool
+def get_env_var(var_name: str) -> Dict[str, Any]:
+    """Get the value of a specific environment variable.
+
+    This tool demonstrates how environment variables configured in mcp.json
+    are passed to the MCP server process.
+
+    Args:
+        var_name: Name of the environment variable to retrieve
+
+    Returns:
+        MCP contract shape with the environment variable value:
+        {
+          "results": {
+            "var_name": str,
+            "var_value": str or None,
+            "is_set": bool
+          },
+          "meta_data": {
+            "elapsed_ms": float
+          }
+        }
+    """
+    start = time.perf_counter()
+
+    var_value = os.environ.get(var_name)
+    is_set = var_name in os.environ
+
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 3)
+
+    return {
+        "results": {
+            "var_name": var_name,
+            "var_value": var_value,
+            "is_set": is_set
+        },
+        "meta_data": {
+            "elapsed_ms": elapsed_ms
+        }
+    }
+
+
+@mcp.tool
+def list_configured_env_vars() -> Dict[str, Any]:
+    """List all environment variables that were configured in mcp.json.
+
+    This tool shows which environment variables from the mcp.json configuration
+    are available to this server. It returns commonly expected configuration
+    variables that might be set.
+
+    Returns:
+        MCP contract shape with environment variables:
+        {
+          "results": {
+            "configured_vars": dict of var_name -> var_value,
+            "total_count": int
+          },
+          "meta_data": {
+            "elapsed_ms": float
+          }
+        }
+    """
+    start = time.perf_counter()
+
+    # List of common configuration environment variables
+    # This demonstrates what might be passed from mcp.json
+    common_config_vars = [
+        "CLOUD_PROFILE",
+        "CLOUD_REGION",
+        "API_KEY",
+        "DEBUG_MODE",
+        "MAX_RETRIES",
+        "TIMEOUT_SECONDS",
+        "ENVIRONMENT",
+        "SERVICE_URL"
+    ]
+
+    configured_vars = {}
+    for var_name in common_config_vars:
+        if var_name in os.environ:
+            configured_vars[var_name] = os.environ[var_name]
+
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 3)
+
+    return {
+        "results": {
+            "configured_vars": configured_vars,
+            "total_count": len(configured_vars)
+        },
+        "meta_data": {
+            "elapsed_ms": elapsed_ms
+        }
+    }
+
+
+@mcp.tool
+def demonstrate_env_usage(operation: str = "info") -> Dict[str, Any]:
+    """Demonstrate how environment variables can be used in MCP server operations.
+
+    This tool shows practical examples of using environment variables for:
+    - Configuration (e.g., region, profile)
+    - Feature flags (e.g., debug mode)
+    - API credentials (e.g., API keys)
+
+    Args:
+        operation: Type of demonstration ("info", "config", "credentials")
+
+    Returns:
+        MCP contract shape with demonstration results:
+        {
+          "results": {
+            "operation": str,
+            "example": str,
+            "details": dict
+          },
+          "meta_data": {
+            "elapsed_ms": float
+          }
+        }
+    """
+    start = time.perf_counter()
+
+    if operation == "config":
+        # Demonstrate configuration from environment
+        cloud_profile = os.environ.get("CLOUD_PROFILE", "default")
+        cloud_region = os.environ.get("CLOUD_REGION", "us-east-1")
+
+        example = f"Using cloud profile '{cloud_profile}' in region '{cloud_region}'"
+        details = {
+            "profile": cloud_profile,
+            "region": cloud_region,
+            "source": "environment variables from mcp.json"
+        }
+
+    elif operation == "credentials":
+        # Demonstrate secure credential handling
+        api_key = os.environ.get("API_KEY")
+        has_key = api_key is not None
+
+        example = f"API key is {'configured' if has_key else 'not configured'}"
+        details = {
+            "has_api_key": has_key,
+            "key_length": len(api_key) if api_key else 0,
+            "masked_key": f"{api_key[:4]}...{api_key[-4:]}" if api_key and len(api_key) > 8 else None,
+            "source": "environment variable ${API_KEY} from mcp.json"
+        }
+
+    else:  # info
+        example = "Environment variables can be configured in mcp.json"
+        details = {
+            "usage": "Set env dict in mcp.json server configuration",
+            "syntax": {
+                "literal": "KEY: 'literal-value'",
+                "substitution": "KEY: '${SYSTEM_ENV_VAR}'"
+            },
+            "example_config": {
+                "env": {
+                    "CLOUD_PROFILE": "my-profile-9",
+                    "CLOUD_REGION": "us-east-7",
+                    "API_KEY": "${MY_API_KEY}"
+                }
+            }
+        }
+
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 3)
+
+    return {
+        "results": {
+            "operation": operation,
+            "example": example,
+            "details": details
+        },
+        "meta_data": {
+            "elapsed_ms": elapsed_ms
+        }
+    }
+
+
+if __name__ == "__main__":
+    mcp.run()

atlas/mcp/file_size_test/main.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+"""
+File Size Test MCP Server using FastMCP.
+Simple tool for testing file transfer by returning file size.
+"""
+
+import base64
+import logging
+import os
+from typing import Annotated, Any, Dict
+
+import requests
+from fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+mcp = FastMCP("File_Size_Test")
+
+
+@mcp.tool
+def process_file_demo(
+    filename: Annotated[str, "The file to process (URL or base64)"],
+    username: Annotated[str, "Username for auditing"] = None
+) -> Dict[str, Any]:
+    """
+    Demo tool that processes a file and returns a new transformed file.
+
+    This tool demonstrates the v2 MCP artifacts contract by:
+    - Accepting a file input
+    - Processing it (converting text to uppercase for demo)
+    - Returning a new file as an artifact with proper v2 format
+    - Including display hints for canvas viewing
+
+    **v2 Artifacts Contract:**
+    - Uses artifacts array with base64 content
+    - Includes MIME types and metadata
+    - Provides display hints for canvas behavior
+    - Supports username injection for auditing
+
+    **File Processing:**
+    - For text files: converts content to uppercase
+    - For binary files: demonstrates file modification capability
+    - Preserves original file structure where possible
+
+    **Return Format:**
+    - results: Summary of operation
+    - artifacts: Array containing the processed file
+    - display: Canvas hints (open_canvas: true, primary_file, etc.)
+    - meta_data: Additional processing details
+
+    Args:
+        filename: File reference (URL or base64 data) to process
+        username: Injected user identity for auditing
+
+    Returns:
+        Dictionary with results, artifacts, and display hints per v2 contract
+    """
+    logger.debug(f"process_file_demo called with filename: {filename}")
+    logger.debug(f"username: {username}")
+    try:
+        # Get the file content (reuse logic from get_file_size)
+        is_url = (
+            filename.startswith("http://") or
+            filename.startswith("https://") or
+            filename.startswith("/api/") or
+            filename.startswith("/")
+        )
+        logger.debug(f"is_url determined as: {is_url}")
+
+        if is_url:
+            if filename.startswith("/"):
+                backend_url = os.getenv("BACKEND_URL", "http://localhost:8000")
+                url = f"{backend_url}{filename}"
+            else:
+                url = filename
+            logger.info(f"Downloading file for processing: {url}")
+            response = requests.get(url, timeout=30)
+            response.raise_for_status()
+            file_bytes = response.content
+            original_filename = filename.split('/')[-1] or "processed_file.txt"
+        else:
+            # Assume base64
+            logger.info("Decoding base64 for file processing")
+            file_bytes = base64.b64decode(filename)
+            original_filename = "processed_file.txt"
+
+        logger.debug(f"Original file size: {len(file_bytes)} bytes")
+
+        # Process the file (demo: convert text to uppercase)
+        try:
+            # Try to decode as text for processing
+            original_text = file_bytes.decode('utf-8')
+            processed_text = original_text.upper()
+            processed_bytes = processed_text.encode('utf-8')
+            processed_mime = "text/plain"
+            description = "Processed text (converted to uppercase)"
+        except UnicodeDecodeError:
+            # If not text, do a simple binary modification (demo purpose)
+            processed_bytes = file_bytes + b"\n[DEMO PROCESSED]"
+            processed_mime = "application/octet-stream"
+            description = "Processed binary file (demo modification)"
+
+        # Create artifact
+        processed_b64 = base64.b64encode(processed_bytes).decode('ascii')
+        new_filename = f"processed_{original_filename}"
+
+        # Create display hints
+        display_hints = {
+            "open_canvas": True,
+            "primary_file": new_filename,
+            "mode": "replace",
+            "viewer_hint": "auto"
+        }
+
+        result = {
+            "results": {
+                "operation": "process_file_demo",
+                "original_filename": original_filename,
+                "processed_filename": new_filename,
+                "original_size": len(file_bytes),
+                "processed_size": len(processed_bytes),
+                "processing_type": "text_uppercase" if 'original_text' in locals() else "binary_demo",
+                "status": "success"
+            },
+            "meta_data": {
+                "is_error": False,
+                "processed_by": "process_file_demo_v2",
+                "username": username,
+                "mime_type": processed_mime
+            },
+            "artifacts": [
+                {
+                    "name": new_filename,
+                    "b64": processed_b64,
+                    "mime": processed_mime,
+                    "size": len(processed_bytes),
+                    "description": description,
+                    "viewer": "auto"
+                }
+            ],
+            "display": display_hints
+        }
+        logger.debug(f"About to return processed file result: {result['results']}")
+        return result
+
+    except Exception as e:
+        logger.exception(f"Exception in process_file_demo: {str(e)}")
+        error_result = {
+            "results": {
+                "operation": "process_file_demo",
+                "error": f"File processing failed: {str(e)}",
+                "filename": filename
+            },
+            "meta_data": {
+                "is_error": True,
+                "error_type": type(e).__name__,
+                "username": username
+            }
+        }
+        return error_result
+
+
+@mcp.tool
+def get_file_size(
+    filename: Annotated[str, "The file to check (URL or base64)"]
+) -> Dict[str, Any]:
+    """
+    Test file transfer by returning the size of the transferred file.
+
+    This simple tool is designed for testing file transfer functionality
+    between frontend and backend. It accepts a file and returns its size in bytes.
+
+    **File Input Support:**
+    - URL-based files (http://, https://, or /api/ paths)
+    - Base64-encoded file data
+    - Automatic backend URL construction for relative paths
+
+    **Return Information:**
+    - File size in bytes
+    - File size in human-readable format (KB, MB)
+    - Original filename or URL
+
+    **Use Cases:**
+    - Testing file upload/download workflows
+    - Validating file transfer infrastructure
+    - Debugging file handling issues
+    - Verifying file size limits
+
+    Args:
+        filename: File reference (URL or base64 data)
+
+    Returns:
+        Dictionary containing:
+        - operation: "get_file_size"
+        - filename: Original filename/URL
+        - size_bytes: File size in bytes
+        - size_human: Human-readable size (e.g., "1.5 MB")
+        Or error message if file cannot be accessed
+    """
+    logger.debug(f"get_file_size called with filename: {filename}")
+    logger.debug(f"filename type: {type(filename)}, length: {len(filename) if filename else 0}")
+    try:
+        # Check if filename is a URL (absolute or relative)
+        is_url = (
+            filename.startswith("http://") or
+            filename.startswith("https://") or
+            filename.startswith("/api/") or
+            filename.startswith("/")
+        )
+        logger.debug(f"is_url determined as: {is_url}")
+
+        if is_url:
+            # Convert relative URLs to absolute URLs
+            if filename.startswith("/"):
+                backend_url = os.getenv("BACKEND_URL", "http://localhost:8000")
+                url = f"{backend_url}{filename}"
+                logger.debug(f"Constructing URL from relative path: {filename} -> {url}")
+            else:
+                url = filename
+                logger.debug(f"Using absolute URL: {url}")
+
+            logger.debug(f"About to download from URL: {url}")
+            logger.info(f"Downloading file from URL: {url}")
+            response = requests.get(url, timeout=30)
+            logger.debug(f"HTTP response status: {response.status_code}")
+            response.raise_for_status()
+            file_bytes = response.content
+            logger.debug(f"Successfully downloaded file content, length: {len(file_bytes)} bytes")
+        else:
+            # Assume it's base64-encoded data
+            logger.debug("Treating input as base64 data, attempting to decode")
+            logger.info("Decoding base64 file data")
+            file_bytes = base64.b64decode(filename)
+            logger.debug(f"Successfully decoded base64 data, length: {len(file_bytes)} bytes")
+
+        # Calculate file size
+        size_bytes = len(file_bytes)
+        size_human = _format_size(size_bytes)
+        logger.debug(f"Calculated file size: {size_bytes} bytes ({size_human})")
+
+        result = {
+            "results": {
+                "operation": "get_file_size",
+                "filename": filename,
+                "size_bytes": size_bytes,
+                "size_human": size_human,
+                "status": "success"
+            },
+            "meta_data": {
+                "is_error": False,
+                "transfer_method": "url" if is_url else "base64"
+            }
+        }
+        logger.debug(f"About to return success result: {result}")
+        return result
+
+    except Exception as e:
+        logger.exception(f"Exception occurred while processing file: {str(e)} (type: {type(e).__name__}, filename: {filename})")
+        error_result = {
+            "results": {
+                "operation": "get_file_size",
+                "error": f"File size check failed: {str(e)}",
+                "filename": filename
+            },
+            "meta_data": {
+                "is_error": True,
+                "error_type": type(e).__name__
+            }
+        }
+        logger.debug(f"About to return error result: {error_result}")
+        return error_result
+
+
+def _format_size(size_bytes: int) -> str:
+    """Format file size in human-readable format."""
+    for unit in ['B', 'KB', 'MB', 'GB', 'TB']:
+        if size_bytes < 1024.0:
+            return f"{size_bytes:.2f} {unit}"
+        size_bytes /= 1024.0
+    return f"{size_bytes:.2f} PB"
+
+
+if __name__ == "__main__":
+    mcp.run()