arch-mcp

Instructions

Implementation Reference

• src/arch_ops_server/logs.py:137-207 (handler)

  The core handler function that reads and parses the pacman.log file to determine when a specific package was first installed, tracks its upgrades and removals, and returns a structured dictionary with the history.
  async def find_when_installed(package_name: str) -> Dict[str, Any]: """ Find when a package was first installed and its upgrade history. Args: package_name: Name of the package to search for Returns: Dict with installation date and upgrade history """ if not IS_ARCH: return create_error_response( "NotSupported", "This feature is only available on Arch Linux" ) logger.info(f"Finding installation history for package: {package_name}") 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}" ) first_install = None upgrades = [] removals = [] with open(pacman_log, 'r') as f: for line in f: parsed = parse_log_line(line) if not parsed or parsed["package"] != package_name: continue action = parsed["action"].lower() if action == "installed": if first_install is None: first_install = parsed elif action in ["upgraded", "downgraded", "reinstalled"]: upgrades.append(parsed) elif action == "removed": removals.append(parsed) if first_install is None: return create_error_response( "NotFound", f"No installation record found for package: {package_name}" ) logger.info(f"Package {package_name}: installed {first_install['timestamp']}, {len(upgrades)} upgrades, {len(removals)} removals") return { "package": package_name, "first_installed": first_install, "upgrade_count": len(upgrades), "upgrades": upgrades, "removal_count": len(removals), "removals": removals, "currently_removed": len(removals) > 0 and (not upgrades or removals[-1]["timestamp"] > upgrades[-1]["timestamp"]) } except Exception as e: logger.error(f"Failed to find installation history: {e}") return create_error_response( "LogParseError", f"Failed to find installation history: {str(e)}" )
• src/arch_ops_server/server.py:1018-1030 (schema)

  MCP tool schema definition specifying the input parameter 'package_name' as a required string, along with the tool description.
  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"] } ),
• src/arch_ops_server/server.py:1386-1395 (registration)

  Tool dispatcher registration in the MCP server's call_tool method, which validates Arch Linux environment, extracts the package_name argument, calls the handler, and formats the JSON response.
  elif name == "find_when_installed": if not IS_ARCH: return [TextContent(type="text", text="Error: find_when_installed only available on Arch Linux systems")] package_name = arguments.get("package_name") if not package_name: return [TextContent(type="text", text="Error: package_name required")] result = await find_when_installed(package_name) return [TextContent(type="text", text=json.dumps(result, indent=2))]
• src/arch_ops_server/logs.py:24-64 (helper)

  Utility function to parse individual pacman log lines into structured data (timestamp, action, package, version), essential for the find_when_installed logic.
  def parse_log_line(line: str) -> Optional[Dict[str, Any]]: """ Parse a single line from pacman log. Args: line: Log line to parse Returns: Dict with parsed data or None if not a transaction line """ # Format: [YYYY-MM-DD HH:MM] [ACTION] package (version) match = re.match( r'\[(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2})\]\s+\[(\w+)\]\s+(.+)', line ) if not match: return None date_str, time_str, action, details = match.groups() timestamp = f"{date_str}T{time_str}:00" # Parse package details # Format: "package_name (version)" or "package_name (old -> new)" pkg_match = re.match(r'(\S+)\s+\((.+)\)', details) if pkg_match: package = pkg_match.group(1) version_info = pkg_match.group(2) else: # Some log lines don't have version info package = details version_info = "" return { "timestamp": timestamp, "action": action, "package": package, "version_info": version_info, "raw_line": line.strip() }
• src/arch_ops_server/tool_metadata.py:353-361 (helper)

  Tool metadata providing categorization, platform requirements, permissions, workflow context, and related tools for discoverability.
  "find_when_installed": ToolMetadata( name="find_when_installed", category="history", platform="arch", permission="read", workflow="audit", related_tools=["get_transaction_history"], prerequisite_tools=[] ),