atlas-chat 0.1.0__py3-none-any.whl

atlas/mcp/duckduckgo/main.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""
+MCP Server for Web Search using DuckDuckGo.
+Provides a tool to search DuckDuckGo, fetch the content of a result,
+and return it.
+"""
+
+from typing import Any, Dict, Union
+
+import requests
+from bs4 import BeautifulSoup
+from duckduckgo_search import DDGS
+from fastmcp import FastMCP
+
+# Initialize the MCP server
+mcp = FastMCP("WebSearcher")
+
+
+def get_page_content(url: str) -> str:
+    """
+    Fetches and parses the text content of a given URL.
+
+    Args:
+        url: The URL of the webpage to parse.
+
+    Returns:
+        The cleaned text content of the page, or an error message.
+    """
+    try:
+        headers = {
+            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+            'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8',
+            'Accept-Language': 'en-US,en;q=0.5',
+            'Accept-Encoding': 'gzip, deflate',
+            'Referer': 'https://www.google.com/',
+            'Connection': 'keep-alive',
+            'Upgrade-Insecure-Requests': '1',
+        }
+
+        response = requests.get(url, headers=headers, timeout=15, allow_redirects=True)
+        response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)
+
+        soup = BeautifulSoup(response.text, 'html.parser')
+
+        # Remove script and style elements
+        for script_or_style in soup(["script", "style"]):
+            script_or_style.decompose()
+
+        # Get text and clean it up
+        text = soup.get_text()
+        lines = (line.strip() for line in text.splitlines())
+        chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
+        cleaned_text = '\n'.join(chunk for chunk in chunks if chunk)
+
+        return cleaned_text
+
+    except requests.RequestException as e:
+        return f"Error fetching URL {url}: {e}"
+    except Exception as e:
+        return f"An error occurred during page parsing: {e}"
+
+
+@mcp.tool
+def search_and_fetch(query: str, max_results: Union[str, int] = 3) -> Dict[str, Any]:
+    """
+    Search the web using DuckDuckGo and intelligently fetch full content from the most relevant results.
+
+    This powerful web search tool combines search and content retrieval:
+    - Uses DuckDuckGo search engine for privacy-focused web searching
+    - Automatically attempts to fetch and parse content from multiple results
+    - Returns the first successfully retrieved page content along with metadata
+    - Handles various content types and website structures intelligently
+
+    **Search Capabilities:**
+    - Natural language queries and specific search terms
+    - Multiple search result evaluation for best content retrieval
+    - Fallback strategy: tries multiple URLs if the first fails
+    - Respects website robots.txt and rate limiting
+
+    **Content Extraction:**
+    - Removes navigation, ads, and formatting for clean text
+    - Extracts main article/content body from web pages
+    - Handles dynamic content and various website layouts
+    - Provides webpage title and URL for reference
+
+    **Privacy & Ethics:**
+    - Uses DuckDuckGo for privacy-conscious searching
+    - Includes proper user agent and headers
+    - Respects website terms and handles errors gracefully
+
+    **Use Cases:**
+    - Research on current events, technical topics, or general information
+    - Fact-checking and information verification
+    - Content analysis and summarization preparation
+    - Market research and competitive analysis
+    - Academic research and reference gathering
+
+    **Examples:**
+    - "latest developments in AI" → Recent news and articles
+    - "Python pandas tutorial" → Educational content and documentation
+    - "climate change statistics 2024" → Current data and reports
+
+    Args:
+        query: Search query (string). Use natural language or specific keywords.
+        max_results: Maximum number of search results to attempt content fetch from (1-10, default 3)
+
+    Returns:
+        Dictionary containing:
+        - title: Title of the successfully fetched webpage
+        - url: URL of the source page
+        - content: Cleaned text content from the webpage
+        - query: Original search query used
+        Or error message if no content could be retrieved from any results
+    """
+    try:
+        # convert to int. max = 10, min = 1
+        max_results = int(max_results)
+        if max_results < 1:
+            max_results = 1
+        elif max_results > 10:
+            max_results = 10
+        with DDGS() as ddgs:
+            # Get multiple results to try if first one fails
+            results = list(ddgs.text(query, max_results=max_results))
+
+        if not results:
+            return {"results": {"error": "No results found for your query."}}
+
+        # Try each result until we successfully fetch content
+        errors_encountered = []
+
+        for i, result in enumerate(results):
+            result_title = result.get('title')
+            result_url = result.get('href')
+
+            if not result_url:
+                errors_encountered.append(f"Result {i+1}: No URL found")
+                continue
+
+            print(f"[DEBUG] Attempting to fetch content from: {result_url}")
+
+            # Fetch and parse the content of the page
+            content = get_page_content(result_url)
+
+            if content.startswith("Error"):
+                errors_encountered.append(f"Result {i+1} ({result_title}): {content}")
+                print(f"[DEBUG] Failed to fetch {result_url}: {content}")
+                continue
+
+            # Success! Return the content
+            print(f"[DEBUG] Successfully fetched content from {result_url}")
+            return {
+                "results": {
+                    "operation": "search_and_fetch",
+                    "query": query,
+                    "result_title": result_title,
+                    "result_url": result_url,
+                    "content": content,
+                    "attempt": i + 1,
+                    "total_results": len(results)
+                }
+            }
+
+        # If we get here, all results failed
+        return {
+            "results": {
+                "operation": "search_and_fetch",
+                "query": query,
+                "error": f"Failed to fetch content from all {len(results)} search results",
+                "errors": errors_encountered,
+                "total_results": len(results)
+            }
+        }
+
+    except Exception as e:
+        return {"results": {"error": f"An unexpected error occurred: {str(e)}"}}
+
+
+if __name__ == "__main__":
+    # To run this server, you need to install the required libraries:
+    # pip install fastmcp duckduckgo-search requests beautifulsoup4
+    mcp.run()

atlas/mcp/elicitation_demo/README.md

@@ -0,0 +1,171 @@
+# Elicitation Demo MCP Server
+
+This MCP server demonstrates **user elicitation** capabilities introduced in FastMCP 2.10.0+. Elicitation allows tools to pause execution and request structured input from users during tool execution, rather than requiring all inputs upfront.
+
+## Overview
+
+User elicitation enables interactive workflows where tools can:
+- Request missing or clarifying information mid-execution
+- Collect complex data step-by-step across multiple prompts
+- Ask for user approval or confirmation
+- Adapt behavior based on user responses
+
+## Available Tools
+
+### Basic Elicitation Types
+
+1. **`get_user_name`** - String Input
+   - Demonstrates basic string elicitation
+   - Asks for user's name and returns a greeting
+
+2. **`pick_a_number`** - Integer Input  
+   - Demonstrates numeric elicitation
+   - Asks for a number between 1-100 and performs calculation
+
+3. **`confirm_action`** - Boolean Input
+   - Demonstrates boolean confirmation
+   - Asks yes/no question and proceeds based on response
+
+4. **`set_priority`** - Enum Input (Python Enum)
+   - Demonstrates enum-based selection  
+   - User chooses from predefined priority levels (low/medium/high)
+
+5. **`choose_option`** - Enum Input (String List)
+   - Demonstrates string literal selection
+   - User picks favorite color from list of options
+
+### Advanced Elicitation
+
+6. **`create_task`** - Structured Multi-field Form
+   - Demonstrates structured data collection
+   - Collects task with title, description, priority, and due date in single form
+
+7. **`multi_turn_survey`** - Multi-turn Elicitation
+   - Demonstrates progressive data collection
+   - Asks 4 questions sequentially: name, age, favorite food, satisfaction rating
+   - Can be cancelled at any step
+
+8. **`approve_deletion`** - Approval-only (No Data)
+   - Demonstrates confirmation without additional data
+   - Simple approve/decline for sensitive actions
+
+## Usage Examples
+
+### In Atlas UI Chat
+
+After the elicitation_demo server is enabled, you can test it with prompts like:
+
+```
+"Get my name using the elicitation demo"
+"Ask me to pick a number"
+"Create a task by asking me for the details"
+"Run a survey about my preferences"
+"Test the approval process for deletion"
+```
+
+### Expected User Experience
+
+When a tool calls `ctx.elicit()`:
+
+1. **Dialog Appears**: A modal dialog pops up with the prompt message
+2. **Form Fields**: Input fields are shown based on the requested type:
+   - Text boxes for strings
+   - Number inputs for integers/numbers
+   - Checkboxes for booleans
+   - Dropdowns for enums
+   - Multiple fields for structured types
+3. **User Actions**:
+   - **Accept**: Submit the provided data (only enabled if required fields are filled)
+   - **Decline**: Skip providing data (tool can handle this case)
+   - **Cancel**: Abort the entire operation
+
+## Technical Details
+
+### Response Schema
+
+The tool specifies what type of data it expects using JSON Schema. Atlas UI parses this schema to render appropriate form fields:
+
+- **Scalar types**: Wrapped in object with `value` field, then unwrapped for tool
+- **Enums**: Rendered as dropdown selects
+- **Structured**: Multiple fields in a form
+- **None/Empty**: Approval-only, no data fields shown
+
+### Elicitation Actions
+
+Tools receive a response with:
+- `action`: "accept" | "decline" | "cancel"  
+- `data`: The user's input (only present on "accept")
+
+### Timeouts
+
+Elicitation requests timeout after 5 minutes of waiting. The tool receives a "cancel" response if timeout occurs.
+
+## Configuration
+
+This server is configured in `config/overrides/mcp.json`:
+
+```json
+{
+  "elicitation_demo": {
+    "command": ["python", "mcp/elicitation_demo/main.py"],
+    "cwd": "atlas",
+    "groups": ["users"],
+    "description": "Demonstrates MCP user elicitation capabilities...",
+    "compliance_level": "Public"
+  }
+}
+```
+
+## Development
+
+To run the server standalone for testing:
+
+```bash
+cd atlas
+python mcp/elicitation_demo/main.py
+```
+
+The FastMCP framework will display available tools and their schemas.
+
+## References
+
+- [FastMCP Elicitation Documentation](https://gofastmcp.com/clients/elicitation)
+- [MCP Specification - Elicitation](https://spec.modelcontextprotocol.io/)
+- FastMCP Version: 2.10.0+
+
+## Example Tool Implementation
+
+```python
+from fastmcp import FastMCP, Context
+from dataclasses import dataclass
+
+mcp = FastMCP("My Server")
+
+@dataclass
+class UserInfo:
+    name: str
+    age: int
+
+@mcp.tool
+async def collect_info(ctx: Context) -> str:
+    """Collect user information interactively."""
+    result = await ctx.elicit(
+        message="Please provide your information",
+        response_type=UserInfo
+    )
+    
+    if result.action == "accept":
+        user = result.data
+        return f"Hello {user.name}, age {user.age}!"
+    elif result.action == "decline":
+        return "Information not provided"
+    else:  # cancel
+        return "Operation cancelled"
+```
+
+## Support
+
+For issues or questions about elicitation:
+- Check Atlas UI documentation in `/docs` folder
+- Review FastMCP elicitation docs at https://gofastmcp.com
+- Report bugs via GitHub issues

atlas/mcp/elicitation_demo/main.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""
+Elicitation Demo MCP Server using FastMCP
+
+This server demonstrates user elicitation capabilities - requesting
+structured input from users during tool execution.
+
+Supports:
+- Scalar types (string, int, bool)
+- Enum/constrained options
+- Structured multi-field responses
+- Multi-turn elicitation
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+from fastmcp import Context, FastMCP
+
+# Initialize the MCP server
+mcp = FastMCP("Elicitation Demo")
+
+
+@mcp.tool
+async def get_user_name(ctx: Context) -> str:
+    """
+    Simple elicitation example that asks for a string input.
+
+    This tool demonstrates basic string elicitation - asking the user
+    for their name and using it in the response.
+
+    Returns:
+        Greeting message with the user's name, or indication if not provided
+    """
+    result = await ctx.elicit("What's your name?", response_type=str)
+
+    if result.action == "accept":
+        return f"Hello, {result.data}! Nice to meet you."
+    elif result.action == "decline":
+        return "No name provided. That's okay!"
+    else:  # cancel
+        return "Operation cancelled."
+
+
+@mcp.tool
+async def pick_a_number(ctx: Context) -> str:
+    """
+    Elicitation example that requests an integer input.
+
+    This tool demonstrates numeric elicitation - asking the user
+    for a number and performing a simple calculation.
+
+    Returns:
+        Information about the picked number, or indication if not provided
+    """
+    result = await ctx.elicit("Pick a number between 1 and 100!", response_type=int)
+
+    if result.action == "accept":
+        number = result.data
+        doubled = number * 2
+        return f"You picked {number}! Doubled, that's {doubled}."
+    elif result.action == "decline":
+        return "No number provided."
+    else:  # cancel
+        return "Operation cancelled."
+
+
+@mcp.tool
+async def confirm_action(ctx: Context) -> str:
+    """
+    Elicitation example that requests boolean confirmation.
+
+    This tool demonstrates boolean elicitation - asking the user
+    to confirm or reject an action.
+
+    Returns:
+        Result of the confirmation decision
+    """
+    result = await ctx.elicit("Do you want to proceed with this action?", response_type=bool)
+
+    if result.action == "accept":
+        if result.data:
+            return "Action confirmed! Proceeding..."
+        else:
+            return "Action not confirmed. Cancelled."
+    elif result.action == "decline":
+        return "No response provided."
+    else:  # cancel
+        return "Operation cancelled."
+
+
+class Priority(Enum):
+    """Priority levels for task creation."""
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+@mcp.tool
+async def set_priority(ctx: Context) -> str:
+    """
+    Elicitation example using enum for constrained options.
+
+    This tool demonstrates enum-based elicitation - asking the user
+    to choose from a predefined set of priority levels.
+
+    Returns:
+        Confirmation of the selected priority level
+    """
+    result = await ctx.elicit("What priority level?", response_type=Priority)
+
+    if result.action == "accept":
+        return f"Priority set to: {result.data.value}"
+    elif result.action == "decline":
+        return "No priority set."
+    else:  # cancel
+        return "Operation cancelled."
+
+
+@mcp.tool
+async def choose_option(ctx: Context) -> str:
+    """
+    Elicitation example using list of strings for simple options.
+
+    This tool demonstrates string literal elicitation - asking the user
+    to choose from a list of options provided as strings.
+
+    Returns:
+        Confirmation of the selected option
+    """
+    result = await ctx.elicit(
+        "Choose your favorite color:",
+        response_type=["red", "blue", "green", "yellow"]
+    )
+
+    if result.action == "accept":
+        return f"You chose: {result.data}"
+    elif result.action == "decline":
+        return "No color chosen."
+    else:  # cancel
+        return "Operation cancelled."
+
+
+@dataclass
+class TaskDetails:
+    """Structured data for task creation."""
+    title: str
+    description: str
+    priority: Literal["low", "medium", "high"]
+    due_date: str
+
+
+@mcp.tool
+async def create_task(ctx: Context) -> str:
+    """
+    Elicitation example with structured multi-field response.
+
+    This tool demonstrates structured elicitation - asking the user
+    to provide multiple fields at once using a dataclass.
+
+    Returns:
+        Summary of the created task with all provided details
+    """
+    result = await ctx.elicit(
+        "Please provide task details",
+        response_type=TaskDetails
+    )
+
+    if result.action == "accept":
+        task = result.data
+        return (
+            f"Task created successfully!\n"
+            f"Title: {task.title}\n"
+            f"Description: {task.description}\n"
+            f"Priority: {task.priority}\n"
+            f"Due Date: {task.due_date}"
+        )
+    elif result.action == "decline":
+        return "Task creation declined."
+    else:  # cancel
+        return "Task creation cancelled."
+
+
+@mcp.tool
+async def multi_turn_survey(ctx: Context) -> str:
+    """
+    Multi-turn elicitation example that collects information step by step.
+
+    This tool demonstrates progressive elicitation - asking multiple
+    questions in sequence to gather information gradually.
+
+    Returns:
+        Summary of all collected survey responses
+    """
+    # Step 1: Get name
+    name_result = await ctx.elicit("What's your name?", response_type=str)
+    if name_result.action != "accept":
+        return "Survey cancelled at name question."
+    name = name_result.data
+
+    # Step 2: Get age
+    age_result = await ctx.elicit("What's your age?", response_type=int)
+    if age_result.action != "accept":
+        return f"Survey cancelled at age question. Thanks anyway, {name}!"
+    age = age_result.data
+
+    # Step 3: Get favorite food
+    food_result = await ctx.elicit(
+        "What's your favorite food?",
+        response_type=["pizza", "sushi", "tacos", "burgers", "other"]
+    )
+    if food_result.action != "accept":
+        return f"Survey cancelled at food question. Thanks for participating, {name}!"
+    favorite_food = food_result.data
+
+    # Step 4: Get satisfaction rating
+    rating_result = await ctx.elicit(
+        "How satisfied are you with this survey? (1-10)",
+        response_type=int
+    )
+    if rating_result.action != "accept":
+        return f"Survey almost complete! Thanks for your responses, {name}!"
+    rating = rating_result.data
+
+    # All responses collected successfully
+    return (
+        f"Survey Complete! Thank you, {name}!\n\n"
+        f"Name: {name}\n"
+        f"Age: {age}\n"
+        f"Favorite Food: {favorite_food}\n"
+        f"Satisfaction Rating: {rating}/10\n\n"
+        f"We appreciate your time!"
+    )
+
+
+@mcp.tool
+async def approve_deletion(ctx: Context) -> str:
+    """
+    Elicitation example requesting approval with no data response.
+
+    This tool demonstrates approval-only elicitation - asking the user
+    to simply approve or reject without providing any additional data.
+
+    Returns:
+        Result of the deletion approval
+    """
+    result = await ctx.elicit(
+        "Are you sure you want to delete this item? This action cannot be undone.",
+        response_type=None
+    )
+
+    if result.action == "accept":
+        return "Item deleted successfully."
+    elif result.action == "decline":
+        return "Deletion declined. Item was not deleted."
+    else:  # cancel
+        return "Operation cancelled. Item was not deleted."
+
+
+if __name__ == "__main__":
+    mcp.run()