arch-ops-server 0.1.0__py3-none-any.whl

arch_ops_server/utils.py

@@ -0,0 +1,272 @@
+"""
+Utility functions for Arch Linux MCP Server.
+Provides platform detection, subprocess execution, and error handling.
+"""
+
+import asyncio
+import logging
+import os
+import platform
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+# Configure logging to stderr (STDIO server requirement)
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[logging.StreamHandler()]
+)
+
+logger = logging.getLogger(__name__)
+
+
+def is_arch_linux() -> bool:
+    """
+    Detect if the current system is Arch Linux.
+    
+    Checks for:
+    1. /etc/arch-release file existence
+    2. Platform identification
+    
+    Returns:
+        bool: True if running on Arch Linux, False otherwise
+    """
+    # Check for Arch release file
+    if Path("/etc/arch-release").exists():
+        logger.info("Detected Arch Linux via /etc/arch-release")
+        return True
+    
+    # Fallback check via platform info
+    try:
+        with open("/etc/os-release", "r") as f:
+            content = f.read()
+            if "Arch Linux" in content or "ID=arch" in content:
+                logger.info("Detected Arch Linux via /etc/os-release")
+                return True
+    except FileNotFoundError:
+        pass
+    
+    logger.info("Not running on Arch Linux")
+    return False
+
+
+# Cache the result since it won't change during runtime
+IS_ARCH = is_arch_linux()
+
+
+async def run_command(
+    cmd: list[str],
+    timeout: int = 10,
+    check: bool = True
+) -> tuple[int, str, str]:
+    """
+    Execute a command asynchronously with timeout protection.
+    
+    Args:
+        cmd: Command and arguments as list
+        timeout: Timeout in seconds (default: 10)
+        check: If True, raise exception on non-zero exit code
+    
+    Returns:
+        Tuple of (exit_code, stdout, stderr)
+    
+    Raises:
+        asyncio.TimeoutError: If command exceeds timeout
+        RuntimeError: If check=True and command fails
+    """
+    logger.debug(f"Executing command: {' '.join(cmd)}")
+    
+    try:
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE
+        )
+        
+        stdout, stderr = await asyncio.wait_for(
+            process.communicate(),
+            timeout=timeout
+        )
+        
+        exit_code = process.returncode
+        stdout_str = stdout.decode('utf-8', errors='replace')
+        stderr_str = stderr.decode('utf-8', errors='replace')
+        
+        logger.debug(f"Command exit code: {exit_code}")
+        
+        if check and exit_code != 0:
+            raise RuntimeError(
+                f"Command failed with exit code {exit_code}: {stderr_str}"
+            )
+        
+        return exit_code, stdout_str, stderr_str
+        
+    except asyncio.TimeoutError:
+        logger.error(f"Command timed out after {timeout}s: {' '.join(cmd)}")
+        raise
+    except Exception as e:
+        logger.error(f"Command execution failed: {e}")
+        raise
+
+
+def add_aur_warning(data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Wrap AUR data with prominent safety warning.
+    
+    The AUR contains user-produced content that may be outdated,
+    broken, or malicious. Always inspect PKGBUILDs before installation.
+    
+    Args:
+        data: Original AUR response data
+    
+    Returns:
+        Dict with added warning metadata
+    """
+    return {
+        "warning": (
+            "⚠️  AUR PACKAGE WARNING ⚠️\n"
+            "AUR packages are USER-PRODUCED content and are not officially supported.\n"
+            "These packages may be outdated, broken, or even malicious.\n"
+            "ALWAYS review the PKGBUILD and other files before installing.\n"
+            "Use at your own risk."
+        ),
+        "data": data
+    }
+
+
+def create_error_response(
+    error_type: str,
+    message: str,
+    details: Optional[str] = None,
+    suggest_wiki_search: bool = True
+) -> Dict[str, Any]:
+    """
+    Create a structured error response with Wiki suggestions.
+    
+    Args:
+        error_type: Type of error (e.g., "NetworkError", "NotFound")
+        message: Human-readable error message
+        details: Optional additional details
+        suggest_wiki_search: Whether to suggest related Wiki searches (default: True)
+    
+    Returns:
+        Structured error dict with Wiki suggestions
+    """
+    response = {
+        "error": True,
+        "type": error_type,
+        "message": message
+    }
+    
+    if details:
+        response["details"] = details
+    
+    # Add Wiki suggestions for common error types
+    if suggest_wiki_search:
+        wiki_suggestions = _get_wiki_suggestions_for_error(error_type, message)
+        if wiki_suggestions:
+            response["wiki_suggestions"] = wiki_suggestions
+            response["help_text"] = (
+                "💡 Search the Arch Wiki for these topics to find solutions. "
+                "Use the search_archwiki tool with these keywords."
+            )
+    
+    logger.error(f"{error_type}: {message}")
+    
+    return response
+
+
+def _get_wiki_suggestions_for_error(error_type: str, message: str) -> list[str]:
+    """
+    Generate relevant Arch Wiki search suggestions based on error type.
+    
+    Args:
+        error_type: Type of error
+        message: Error message
+    
+    Returns:
+        List of suggested Wiki search terms
+    """
+    suggestions = []
+    message_lower = message.lower()
+    
+    # Map error types to Wiki topics
+    error_wiki_map = {
+        "NotFound": ["Package management", "AUR"],
+        "TimeoutError": ["Network configuration", "Mirrors"],
+        "HTTPError": ["Network configuration", "Proxy"],
+        "CommandNotFound": ["Pacman", "System maintenance"],
+        "NotSupported": ["Installation guide", "System requirements"],
+        "RateLimitError": ["AUR", "Mirror"],
+    }
+    
+    # Add general suggestions based on error type
+    if error_type in error_wiki_map:
+        suggestions.extend(error_wiki_map[error_type])
+    
+    # Add context-specific suggestions based on message keywords
+    keyword_map = {
+        "pacman": ["Pacman", "Pacman/Rosetta"],
+        "package": ["Package management", "Official repositories"],
+        "dependency": ["Dependency", "Package management"],
+        "mirror": ["Mirrors", "Reflector"],
+        "network": ["Network configuration", "Systemd-networkd"],
+        "update": ["System maintenance", "Pacman#Upgrading packages"],
+        "gpg": ["Pacman/Package signing", "GnuPG"],
+        "disk": ["File systems", "Partitioning"],
+        "boot": ["Boot process", "Arch boot process"],
+        "kernel": ["Kernel", "Kernel modules"],
+        "driver": ["Kernel modules", "Xorg"],
+        "graphics": ["Xorg", "NVIDIA", "AMD"],
+    }
+    
+    for keyword, topics in keyword_map.items():
+        if keyword in message_lower:
+            suggestions.extend(topics)
+    
+    # Remove duplicates while preserving order
+    seen = set()
+    unique_suggestions = []
+    for suggestion in suggestions:
+        if suggestion not in seen:
+            seen.add(suggestion)
+            unique_suggestions.append(suggestion)
+    
+    return unique_suggestions[:5]  # Limit to top 5 suggestions
+
+
+def check_command_exists(command: str) -> bool:
+    """
+    Check if a command exists in the system PATH.
+    
+    Args:
+        command: Command name to check
+    
+    Returns:
+        bool: True if command exists, False otherwise
+    """
+    try:
+        result = os.system(f"which {command} > /dev/null 2>&1")
+        return result == 0
+    except Exception:
+        return False
+
+
+def get_aur_helper() -> Optional[str]:
+    """
+    Detect available AUR helper with priority: paru > yay.
+    
+    Returns:
+        str: Name of available AUR helper ('paru' or 'yay'), or None if neither exists
+    """
+    # Check in priority order
+    if check_command_exists("paru"):
+        logger.info("Found AUR helper: paru")
+        return "paru"
+    elif check_command_exists("yay"):
+        logger.info("Found AUR helper: yay")
+        return "yay"
+    else:
+        logger.warning("No AUR helper found (paru or yay)")
+        return None
+

arch_ops_server/wiki.py

@@ -0,0 +1,244 @@
+"""
+Arch Wiki interface module.
+Provides search and page retrieval via MediaWiki API with BeautifulSoup fallback.
+"""
+
+import logging
+from typing import List, Dict, Any, Optional
+import httpx
+from bs4 import BeautifulSoup
+from markdownify import markdownify as md
+
+from .utils import create_error_response
+
+logger = logging.getLogger(__name__)
+
+# Arch Wiki API endpoint
+WIKI_API_URL = "https://wiki.archlinux.org/api.php"
+WIKI_BASE_URL = "https://wiki.archlinux.org"
+
+# HTTP client settings
+DEFAULT_TIMEOUT = 10.0
+
+
+async def search_wiki(query: str, limit: int = 10) -> Dict[str, Any]:
+    """
+    Search the Arch Wiki using MediaWiki API.
+    
+    Uses the opensearch action which returns suggestions.
+    
+    Args:
+        query: Search term
+        limit: Maximum number of results (default: 10)
+    
+    Returns:
+        Dict containing search results with titles, snippets, and URLs
+    """
+    logger.info(f"Searching Arch Wiki for: {query}")
+    
+    params = {
+        "action": "opensearch",
+        "search": query,
+        "limit": limit,
+        "namespace": "0",  # Main namespace only
+        "format": "json"
+    }
+    
+    try:
+        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+            response = await client.get(WIKI_API_URL, params=params)
+            response.raise_for_status()
+            
+            data = response.json()
+            
+            # OpenSearch returns: [query, [titles], [descriptions], [urls]]
+            if len(data) >= 4:
+                titles = data[1]
+                descriptions = data[2]
+                urls = data[3]
+                
+                results = [
+                    {
+                        "title": title,
+                        "snippet": desc,
+                        "url": url
+                    }
+                    for title, desc, url in zip(titles, descriptions, urls)
+                ]
+                
+                logger.info(f"Found {len(results)} results for '{query}'")
+                
+                return {
+                    "query": query,
+                    "count": len(results),
+                    "results": results
+                }
+            else:
+                return {
+                    "query": query,
+                    "count": 0,
+                    "results": []
+                }
+                
+    except httpx.TimeoutException:
+        logger.error(f"Wiki search timed out for query: {query}")
+        return create_error_response(
+            "TimeoutError",
+            f"Arch Wiki search timed out for query: {query}",
+            "The Wiki server did not respond in time. Try again later."
+        )
+    except httpx.HTTPStatusError as e:
+        logger.error(f"Wiki search HTTP error: {e}")
+        return create_error_response(
+            "HTTPError",
+            f"Wiki search failed with status {e.response.status_code}",
+            str(e)
+        )
+    except Exception as e:
+        logger.error(f"Wiki search failed: {e}")
+        return create_error_response(
+            "SearchError",
+            f"Failed to search Arch Wiki: {str(e)}"
+        )
+
+
+async def get_wiki_page(title: str, as_markdown: bool = True) -> str:
+    """
+    Fetch a Wiki page using MediaWiki API, with scraping fallback.
+    
+    Args:
+        title: Page title (e.g., "Installation_guide")
+        as_markdown: Convert HTML to Markdown (default: True)
+    
+    Returns:
+        Page content as Markdown or HTML string
+    """
+    logger.info(f"Fetching Wiki page: {title}")
+    
+    # Try MediaWiki API first
+    content = await _fetch_via_api(title)
+    
+    # Fallback to scraping if API fails
+    if content is None:
+        logger.warning(f"API fetch failed for {title}, falling back to scraping")
+        content = await _fetch_via_scraping(title)
+    
+    if content is None:
+        error_msg = f"Page '{title}' not found or could not be retrieved"
+        logger.error(error_msg)
+        raise ValueError(error_msg)
+    
+    # Convert to Markdown if requested
+    if as_markdown and content:
+        try:
+            content = md(content, heading_style="ATX", strip=['script', 'style'])
+        except Exception as e:
+            logger.warning(f"Markdown conversion failed: {e}, returning HTML")
+    
+    return content
+
+
+async def _fetch_via_api(title: str) -> Optional[str]:
+    """
+    Fetch page content via MediaWiki API.
+    
+    Args:
+        title: Page title
+    
+    Returns:
+        HTML content or None if failed
+    """
+    params = {
+        "action": "parse",
+        "page": title,
+        "format": "json",
+        "prop": "text",
+        "disableeditsection": "1",
+        "disabletoc": "1"
+    }
+    
+    try:
+        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+            response = await client.get(WIKI_API_URL, params=params)
+            response.raise_for_status()
+            
+            data = response.json()
+            
+            # Check for errors in response
+            if "error" in data:
+                logger.warning(f"API error: {data['error'].get('info', 'Unknown error')}")
+                return None
+            
+            # Extract HTML content
+            if "parse" in data and "text" in data["parse"]:
+                html_content = data["parse"]["text"]["*"]
+                logger.info(f"Successfully fetched {title} via API")
+                return html_content
+            
+            return None
+            
+    except Exception as e:
+        logger.warning(f"API fetch failed for {title}: {e}")
+        return None
+
+
+async def _fetch_via_scraping(title: str) -> Optional[str]:
+    """
+    Fetch page content via direct HTTP scraping (fallback).
+    
+    Args:
+        title: Page title
+    
+    Returns:
+        HTML content or None if failed
+    """
+    # Construct URL
+    url = f"{WIKI_BASE_URL}/title/{title}"
+    
+    try:
+        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+            response = await client.get(url, follow_redirects=True)
+            response.raise_for_status()
+            
+            # Parse HTML
+            soup = BeautifulSoup(response.text, 'lxml')
+            
+            # Find main content div
+            content_div = soup.find('div', {'id': 'bodyContent'})
+            
+            if content_div:
+                # Remove unnecessary elements
+                for element in content_div.find_all(['script', 'style', 'nav']):
+                    element.decompose()
+                
+                logger.info(f"Successfully scraped {title}")
+                return str(content_div)
+            
+            return None
+            
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 404:
+            logger.error(f"Page not found: {title}")
+        else:
+            logger.error(f"HTTP error scraping {title}: {e}")
+        return None
+    except Exception as e:
+        logger.error(f"Scraping failed for {title}: {e}")
+        return None
+
+
+async def get_wiki_page_as_text(title: str) -> str:
+    """
+    Convenience wrapper to get Wiki page as clean Markdown text.
+    
+    Args:
+        title: Page title
+    
+    Returns:
+        Markdown content
+    
+    Raises:
+        ValueError: If page cannot be retrieved
+    """
+    return await get_wiki_page(title, as_markdown=True)
+

arch_ops_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.3
+Name: arch-ops-server
+Version: 0.1.0
+Summary: MCP server bridging AI assistants with Arch Linux ecosystem (Wiki, AUR, official repos)
+Keywords: arch-linux,mcp,model-context-protocol,aur,pacman,wiki,ai-assistant
+Author: Nihal
+Author-email: Nihal <2tv8xupqg@mozmail.com>
+License: GPL-3.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Archiving :: Packaging
+Classifier: Topic :: System :: Systems Administration
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: lxml>=5.0.0
+Requires-Dist: markdownify>=0.12.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Arch Linux MCP Server
+
+**Disclaimer:** Unofficial community project, not affiliated with Arch Linux.
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that bridges AI assistants with the Arch Linux ecosystem. Enables intelligent, safe, and efficient access to the Arch Wiki, AUR, and official repositories for AI-assisted Arch Linux usage on Arch and non-Arch systems.
+
+Leverage AI to get  output for digestible, structured results that are ready for follow up questions and actions.
+
+📖 [Complete Documentation with Comfy Guides](https://nxk.mintlify.app/arch-mcp)
+
+## Sneak Peak into what's available
+
+### Resources (URI-based Access)
+
+Direct access to Arch ecosystem data via custom URI schemes:
+
+| URI Scheme | Example | Returns |
+|------------|---------|---------|
+| `archwiki://` | `archwiki://Installation_guide` | Markdown-formatted Wiki page |
+| `aur://*/pkgbuild` | `aur://yay/pkgbuild` | Raw PKGBUILD with safety analysis |
+| `aur://*/info` | `aur://yay/info` | AUR package metadata (votes, maintainer, dates) |
+| `archrepo://` | `archrepo://vim` | Official repository package details |
+| `pacman://installed` | `pacman://installed` | System installed packages list (Arch only) |
+
+### Tools (Executable Functions)
+
+| Category | Tool | Description | Key Features |
+|----------|------|-------------|--------------|
+| **Search** | `search_archwiki` | Query Arch Wiki documentation | Ranked results, keyword extraction |
+| | `search_aur` | Search AUR packages | Smart ranking: relevance/votes/popularity/modified |
+| | `get_official_package_info` | Lookup official packages | Hybrid local/remote, detailed metadata |
+| **System** | `check_updates_dry_run` | Check for updates (Arch only) | Read-only, safe, requires pacman-contrib |
+| **Installation** | `install_package_secure` | Secure package installation | Auto security checks, blocks malicious packages, uses paru/yay |
+| **Security** | `analyze_pkgbuild_safety` | Comprehensive PKGBUILD analysis | Detects: malicious commands based on 50+ red flags |
+| | `analyze_package_metadata_risk` | Package trust evaluation | Analyzes: votes, maintainer, age, updates, trust scoring |
+
+### Prompts (Guided Workflows)
+
+| Prompt | Purpose | Workflow |
+|--------|---------|----------|
+| `troubleshoot_issue` | Diagnose system errors | Extract keywords → Search Wiki → Context-aware suggestions |
+| `audit_aur_package` | Pre-installation safety audit | Fetch metadata → Analyze PKGBUILD → Security recommendations |
+| `analyze_dependencies` | Installation planning | Check repos → Map dependencies → Suggest install order |
+
+---
+
+## Installation
+
+### Prerequisites
+- Python 3.11+
+- [uv](https://github.com/astral-sh/uv) (recommended) or pip
+
+### Quick Install with `uvx`
+
+```bash
+uvx arch-ops-server
+```
+
+---
+
+## Configuration
+
+Claude / Cursor / Any MCP client that supports STDIO transport
+
+```json
+{
+  "mcpServers": {
+    "arch-ops": {
+      "command": "uvx",
+      "args": ["arch-ops-server"]
+    }
+  }
+}
+```
+
+## License
+
+[GPL-3.0-only](https://www.gnu.org/licenses/gpl-3.0.en.html)
+
+---
+
+
+Built with ❤️ for the Arch Linux community

arch_ops_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+arch_ops_server/__init__.py,sha256=m0KiRT4iLqY5eyP3Ul-anwQVdpjTghWWW1QOqk6n1NI,1906
+arch_ops_server/aur.py,sha256=_BoPsKyBPa2KWi9i1J_RSsqUT53wU03guS0V1sasOXg,46328
+arch_ops_server/pacman.py,sha256=nD1B8KgHuwaxHtcO4sd1WpiFcpocjD6yxs1JtVkTjPU,9862
+arch_ops_server/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+arch_ops_server/server.py,sha256=D_8uypCGmWgTjw5VThrsBY_XxrDjHmdVJT6D39Be-Sw,25212
+arch_ops_server/utils.py,sha256=-v47tnfxRP-IqvKeqhpAIYVIPhTIh5DMe9jWvCMNRGM,8145
+arch_ops_server/wiki.py,sha256=P6znxzV2e9JVUq8yyD0e9pP0Fm7EkS9vmDb2HUdwQpc,7303
+arch_ops_server-0.1.0.dist-info/WHEEL,sha256=k57ZwB-NkeM_6AsPnuOHv5gI5KM5kPD6Vx85WmGEcI0,78
+arch_ops_server-0.1.0.dist-info/entry_points.txt,sha256=nD6HtiLT-Xh1b63_LGcYNEjHqVlal7I2d5jeFJMtfiU,63
+arch_ops_server-0.1.0.dist-info/METADATA,sha256=tEmFaZ5X5emaz6rLExwi-QieYk8StI-N0sz0ezSacnk,4183
+arch_ops_server-0.1.0.dist-info/RECORD,,

arch_ops_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.4
+Root-Is-Purelib: true
+Tag: py3-none-any

arch_ops_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+arch-ops-server = arch_ops_server:main_sync
+