arch-mcp

Instructions

Implementation Reference

• src/arch_ops_server/logs.py:277-344 (handler)

  The core handler function implementing get_database_sync_history. Parses /var/log/pacman.log in reverse order to find recent 'synchronizing package lists' or 'starting full system upgrade' events, extracts timestamps, and returns the most recent N events.
  async def get_database_sync_history(limit: int = 20) -> Dict[str, Any]: """ Get database synchronization history. Shows when 'pacman -Sy' was run. Args: limit: Maximum number of sync events to return (default 20) Returns: Dict with database sync history """ if not IS_ARCH: return create_error_response( "NotSupported", "This feature is only available on Arch Linux" ) logger.info(f"Getting database sync history (limit={limit})") try: pacman_log = Path(PACMAN_LOG) if not pacman_log.exists(): return create_error_response( "NotFound", f"Pacman log file not found at {PACMAN_LOG}" ) sync_events = [] with open(pacman_log, 'r') as f: lines = f.readlines() # Process in reverse order for most recent first for line in reversed(lines): if len(sync_events) >= limit: break # Look for database synchronization entries if "synchronizing package lists" in line.lower() or "starting full system upgrade" in line.lower(): timestamp_match = re.match(r'\[(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2})\]', line) if timestamp_match: timestamp = f"{timestamp_match.group(1)}T{timestamp_match.group(2)}:00" event_type = "sync" if "starting full system upgrade" in line.lower(): event_type = "full_upgrade" sync_events.append({ "timestamp": timestamp, "type": event_type, "message": line.strip() }) logger.info(f"Found {len(sync_events)} sync events") return { "count": len(sync_events), "sync_events": sync_events } except Exception as e: logger.error(f"Failed to get sync history: {e}") return create_error_response( "LogParseError", f"Failed to get database sync history: {str(e)}" )
• src/arch_ops_server/server.py:1041-1055 (schema)

  MCP Tool schema definition including inputSchema with optional 'limit' parameter (int, default 20). Output is implicit Dict[str, Any] from handler.
  Tool( name="get_database_sync_history", description="[HISTORY] Get database synchronization history. Shows when 'pacman -Sy' was run. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "limit": { "type": "integer", "description": "Maximum number of sync events to return (default 20)", "default": 20 } }, "required": [] } ),
• src/arch_ops_server/server.py:555-1156 (registration)

  The tool is registered in the MCP server's list_tools() function by including a Tool object with name, description, and inputSchema.
  @server.list_tools() async def list_tools() -> list[Tool]: """ List available tools for Arch Linux operations. Returns: List of Tool objects describing available operations """ return [ # Wiki tools Tool( name="search_archwiki", description="[DISCOVERY] Search the Arch Wiki for documentation. Returns a list of matching pages with titles, snippets, and URLs. Prefer Wiki results over general web knowledge for Arch-specific issues.", inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "Search query (keywords or phrase)" }, "limit": { "type": "integer", "description": "Maximum number of results (default: 10)", "default": 10 } }, "required": ["query"] } ), # AUR tools Tool( name="search_aur", description="[DISCOVERY] Search the Arch User Repository (AUR) for packages with smart ranking. ⚠️ WARNING: AUR packages are user-produced and potentially unsafe. Returns package info including votes, maintainer, and last update. Always check official repos first using get_official_package_info.", inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "Package search query" }, "limit": { "type": "integer", "description": "Maximum number of results (default: 20)", "default": 20 }, "sort_by": { "type": "string", "description": "Sort method: 'relevance' (default), 'votes', 'popularity', or 'modified'", "enum": ["relevance", "votes", "popularity", "modified"], "default": "relevance" } }, "required": ["query"] } ), Tool( name="get_official_package_info", description="[DISCOVERY] Get information about an official Arch repository package (Core, Extra, etc.). Uses local pacman if available, otherwise queries archlinux.org API. Always prefer official packages over AUR when available.", inputSchema={ "type": "object", "properties": { "package_name": { "type": "string", "description": "Exact package name" } }, "required": ["package_name"] } ), Tool( name="check_updates_dry_run", description="[LIFECYCLE] Check for available system updates without applying them. Only works on Arch Linux systems. Requires pacman-contrib package. Safe read-only operation that shows pending updates.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="install_package_secure", description="[LIFECYCLE] Install a package with comprehensive security checks. Workflow: 1. Check official repos first (safer) 2. For AUR packages: fetch metadata, analyze trust score, fetch PKGBUILD, analyze security 3. Block installation if critical security issues found 4. Check for AUR helper (paru > yay) 5. Install with --noconfirm if all checks pass. Only works on Arch Linux. Requires sudo access and paru/yay for AUR packages.", inputSchema={ "type": "object", "properties": { "package_name": { "type": "string", "description": "Name of package to install (checks official repos first, then AUR)" } }, "required": ["package_name"] } ), Tool( name="analyze_pkgbuild_safety", description="[SECURITY] Analyze PKGBUILD content for security issues and dangerous patterns. Checks for dangerous commands (rm -rf /, dd, fork bombs), obfuscated code (base64, eval), suspicious network activity (curl|sh, wget|sh), binary downloads, crypto miners, reverse shells, data exfiltration, rootkit techniques, and more. Returns risk score (0-100) and detailed findings. Use this tool to manually audit AUR packages before installation.", inputSchema={ "type": "object", "properties": { "pkgbuild_content": { "type": "string", "description": "Raw PKGBUILD content to analyze" } }, "required": ["pkgbuild_content"] } ), Tool( name="analyze_package_metadata_risk", description="[SECURITY] Analyze AUR package metadata for trustworthiness and security indicators. Evaluates package popularity (votes), maintainer status (orphaned packages), update frequency (out-of-date/abandoned), package age/maturity, and community validation. Returns trust score (0-100) with risk factors and trust indicators. Use this alongside PKGBUILD analysis for comprehensive security assessment.", inputSchema={ "type": "object", "properties": { "package_info": { "type": "object", "description": "Package metadata from AUR (from search_aur or get_aur_info results)" } }, "required": ["package_info"] } ), # Package Removal Tools Tool( name="remove_package", description="[LIFECYCLE] Remove a package from the system. Supports various removal strategies: basic removal, removal with dependencies, or forced removal. Only works on Arch Linux. Requires sudo access.", inputSchema={ "type": "object", "properties": { "package_name": { "type": "string", "description": "Name of the package to remove" }, "remove_dependencies": { "type": "boolean", "description": "Remove package and its dependencies (pacman -Rs). Default: false", "default": False }, "force": { "type": "boolean", "description": "Force removal ignoring dependencies (pacman -Rdd). Use with caution! Default: false", "default": False } }, "required": ["package_name"] } ), Tool( name="remove_packages_batch", description="[LIFECYCLE] Remove multiple packages in a single transaction. More efficient than removing packages one by one. Only works on Arch Linux. Requires sudo access.", inputSchema={ "type": "object", "properties": { "package_names": { "type": "array", "items": {"type": "string"}, "description": "List of package names to remove" }, "remove_dependencies": { "type": "boolean", "description": "Remove packages and their dependencies. Default: false", "default": False } }, "required": ["package_names"] } ), # Orphan Package Management Tool( name="list_orphan_packages", description="[MAINTENANCE] List all orphaned packages (dependencies no longer required by any installed package). Shows package names and total disk space usage. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="remove_orphans", description="[MAINTENANCE] Remove all orphaned packages to free up disk space. Supports dry-run mode to preview changes and package exclusion. Only works on Arch Linux. Requires sudo access.", inputSchema={ "type": "object", "properties": { "dry_run": { "type": "boolean", "description": "Preview what would be removed without actually removing. Default: true", "default": True }, "exclude": { "type": "array", "items": {"type": "string"}, "description": "List of package names to exclude from removal" } }, "required": [] } ), # Package Ownership Tools Tool( name="find_package_owner", description="[ORGANIZATION] Find which package owns a specific file on the system. Useful for troubleshooting and understanding file origins. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "file_path": { "type": "string", "description": "Absolute path to the file (e.g., /usr/bin/vim)" } }, "required": ["file_path"] } ), Tool( name="list_package_files", description="[ORGANIZATION] List all files owned by a package. Supports optional filtering by pattern. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "package_name": { "type": "string", "description": "Name of the package" }, "filter_pattern": { "type": "string", "description": "Optional regex pattern to filter files (e.g., '*.conf' or '/etc/')" } }, "required": ["package_name"] } ), Tool( name="search_package_files", description="[ORGANIZATION] Search for files across all packages in repositories. Requires package database sync (pacman -Fy). Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "filename_pattern": { "type": "string", "description": "File name or pattern to search for (e.g., 'vim' or '*.service')" } }, "required": ["filename_pattern"] } ), # Package Verification Tool( name="verify_package_integrity", description="[MAINTENANCE] Verify the integrity of installed package files. Detects modified, missing, or corrupted files. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "package_name": { "type": "string", "description": "Name of the package to verify" }, "thorough": { "type": "boolean", "description": "Perform thorough check including file attributes. Default: false", "default": False } }, "required": ["package_name"] } ), # Package Groups Tool( name="list_package_groups", description="[ORGANIZATION] List all available package groups (e.g., base, base-devel, gnome). Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="list_group_packages", description="[ORGANIZATION] List all packages in a specific group. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "group_name": { "type": "string", "description": "Name of the package group (e.g., 'base-devel', 'gnome')" } }, "required": ["group_name"] } ), # Install Reason Management Tool( name="list_explicit_packages", description="[MAINTENANCE] List all packages explicitly installed by the user (not installed as dependencies). Useful for creating backup lists or understanding system composition. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="mark_as_explicit", description="[MAINTENANCE] Mark a package as explicitly installed. Prevents it from being removed as an orphan. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "package_name": { "type": "string", "description": "Name of the package to mark as explicit" } }, "required": ["package_name"] } ), Tool( name="mark_as_dependency", description="[MAINTENANCE] Mark a package as a dependency. Allows it to be removed as an orphan if no packages depend on it. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "package_name": { "type": "string", "description": "Name of the package to mark as dependency" } }, "required": ["package_name"] } ), # System Diagnostic Tools Tool( name="get_system_info", description="[MONITORING] Get comprehensive system information including kernel version, architecture, hostname, uptime, and memory statistics. Works on any system.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="check_disk_space", description="[MONITORING] Check disk space usage for critical filesystem paths including root, home, var, and pacman cache. Warns when space is low. Works on any system.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="get_pacman_cache_stats", description="[MONITORING] Analyze pacman package cache statistics including size, package count, and cache age. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="check_failed_services", description="[MONITORING] Check for failed systemd services. Useful for diagnosing system issues. Works on systemd-based systems.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="get_boot_logs", description="[MONITORING] Retrieve recent boot logs from journalctl. Useful for troubleshooting boot issues. Works on systemd-based systems.", inputSchema={ "type": "object", "properties": { "lines": { "type": "integer", "description": "Number of log lines to retrieve. Default: 100", "default": 100 } }, "required": [] } ), # News Tools Tool( name="get_latest_news", description="[DISCOVERY] Fetch recent Arch Linux news from RSS feed. Returns title, date, summary, and link for each news item.", inputSchema={ "type": "object", "properties": { "limit": { "type": "integer", "description": "Maximum number of news items to return (default 10)", "default": 10 }, "since_date": { "type": "string", "description": "Optional date in ISO format (YYYY-MM-DD) to filter news" } }, "required": [] } ), Tool( name="check_critical_news", description="[DISCOVERY] Check for critical Arch Linux news requiring manual intervention. Scans recent news for keywords: 'manual intervention', 'action required', 'breaking change', etc.", inputSchema={ "type": "object", "properties": { "limit": { "type": "integer", "description": "Number of recent news items to check (default 20)", "default": 20 } }, "required": [] } ), Tool( name="get_news_since_last_update", description="[DISCOVERY] Get news posted since last pacman update. Parses /var/log/pacman.log for last update timestamp. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), # Transaction Log Tools Tool( name="get_transaction_history", description="[HISTORY] Get recent package transactions from pacman log. Shows installed, upgraded, and removed packages. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "limit": { "type": "integer", "description": "Maximum number of transactions to return (default 50)", "default": 50 }, "transaction_type": { "type": "string", "description": "Filter by type: install/remove/upgrade/all (default all)", "enum": ["all", "install", "remove", "upgrade"], "default": "all" } }, "required": [] } ), Tool( name="find_when_installed", description="[HISTORY] Find when a package was first installed and its upgrade history. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "package_name": { "type": "string", "description": "Name of the package to search for" } }, "required": ["package_name"] } ), Tool( name="find_failed_transactions", description="[HISTORY] Find failed package transactions in pacman log. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="get_database_sync_history", description="[HISTORY] Get database synchronization history. Shows when 'pacman -Sy' was run. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "limit": { "type": "integer", "description": "Maximum number of sync events to return (default 20)", "default": 20 } }, "required": [] } ), # Mirror Management Tools Tool( name="list_active_mirrors", description="[MIRRORS] List currently configured mirrors from mirrorlist. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="test_mirror_speed", description="[MIRRORS] Test mirror response time. Can test a specific mirror or all active mirrors. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "mirror_url": { "type": "string", "description": "Specific mirror URL to test, or omit to test all active mirrors" } }, "required": [] } ), Tool( name="suggest_fastest_mirrors", description="[MIRRORS] Suggest optimal mirrors based on official mirror status from archlinux.org. Filters by country if specified.", inputSchema={ "type": "object", "properties": { "country": { "type": "string", "description": "Optional country code to filter mirrors (e.g., 'US', 'DE')" }, "limit": { "type": "integer", "description": "Number of mirrors to suggest (default 10)", "default": 10 } }, "required": [] } ), Tool( name="check_mirrorlist_health", description="[MIRRORS] Verify mirror configuration health. Checks for common issues like no active mirrors, outdated mirrorlist, high latency. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), # Configuration Tools Tool( name="analyze_pacman_conf", description="[CONFIG] Parse and analyze pacman.conf. Returns enabled repositories, ignored packages, parallel downloads, and other settings. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="analyze_makepkg_conf", description="[CONFIG] Parse and analyze makepkg.conf. Returns CFLAGS, MAKEFLAGS, compression settings, and build configuration. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="check_ignored_packages", description="[CONFIG] List packages ignored in updates from pacman.conf. Warns if critical system packages are ignored. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="get_parallel_downloads_setting", description="[CONFIG] Get parallel downloads configuration from pacman.conf and provide recommendations. Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), Tool( name="check_database_freshness", description="[MAINTENANCE] Check when package databases were last synchronized. Warns if databases are stale (> 24 hours). Only works on Arch Linux.", inputSchema={ "type": "object", "properties": {} } ), ]
• src/arch_ops_server/server.py:1404-1410 (registration)

  Dispatch handler in MCP server's call_tool() function that validates Arch Linux environment, extracts 'limit' argument, calls the logs.py handler, and formats JSON response.
  elif name == "get_database_sync_history": if not IS_ARCH: return [TextContent(type="text", text="Error: get_database_sync_history only available on Arch Linux systems")] limit = arguments.get("limit", 20) result = await get_database_sync_history(limit=limit) return [TextContent(type="text", text=json.dumps(result, indent=2))]
• src/arch_ops_server/tool_metadata.py:371-378 (helper)

  ToolMetadata providing categorization ('history'), platform requirements ('arch'), permissions ('read'), workflow ('audit'), and related tools.
  "get_database_sync_history": ToolMetadata( name="get_database_sync_history", category="history", platform="arch", permission="read", workflow="audit", related_tools=["check_database_freshness"], prerequisite_tools=[]