arch-mcp

Instructions

Implementation Reference

• src/arch_ops_server/pacman.py:1216-1304 (handler)

  The core handler function that executes the tool logic: checks modification times of pacman sync database files (/var/lib/pacman/sync/*.db), computes age, identifies oldest database, provides warnings and recommendations if stale (>24h or >1 week). Returns structured JSON with database info.
  async def check_database_freshness() -> Dict[str, Any]: """ Check when package databases were last synchronized. Returns: Dict with database sync timestamps per repository """ if not IS_ARCH: return create_error_response( "NotSupported", "Database freshness check is only available on Arch Linux" ) logger.info("Checking database freshness") try: from pathlib import Path from datetime import datetime, timedelta sync_dir = Path("/var/lib/pacman/sync") if not sync_dir.exists(): return create_error_response( "NotFound", "Pacman sync directory not found" ) # Get all .db files db_files = list(sync_dir.glob("*.db")) if not db_files: return create_error_response( "NotFound", "No database files found" ) databases = [] now = datetime.now() oldest_db = None oldest_age = timedelta(0) for db_file in db_files: mtime = datetime.fromtimestamp(db_file.stat().st_mtime) age = now - mtime hours_old = age.total_seconds() / 3600 db_info = { "repository": db_file.stem, # Remove .db extension "last_sync": mtime.isoformat(), "hours_old": round(hours_old, 1) } # Warn if older than 24 hours if hours_old > 24: db_info["warning"] = f"Database is {hours_old:.0f} hours old (> 24h)" databases.append(db_info) # Track oldest if oldest_db is None or age > oldest_age: oldest_db = db_info["repository"] oldest_age = age # Sort by hours_old descending (oldest first) databases.sort(key=lambda x: x["hours_old"], reverse=True) logger.info(f"Checked {len(databases)} databases, oldest: {oldest_age.total_seconds() / 3600:.1f}h") recommendations = [] if oldest_age.total_seconds() / 3600 > 24: recommendations.append("Databases are stale (> 24h). Run 'sudo pacman -Sy' to synchronize.") if oldest_age.total_seconds() / 3600 > 168: # 1 week recommendations.append("Databases are very stale (> 1 week). Consider full system update.") return { "database_count": len(databases), "databases": databases, "oldest_database": oldest_db, "oldest_age_hours": round(oldest_age.total_seconds() / 3600, 1), "recommendations": recommendations, "needs_sync": oldest_age.total_seconds() / 3600 > 24 } except Exception as e: logger.error(f"Failed to check database freshness: {e}") return create_error_response( "CheckError", f"Failed to check database freshness: {str(e)}" )
• src/arch_ops_server/server.py:1148-1155 (registration)

  MCP tool registration in list_tools(): defines the tool name, description, and empty inputSchema (no parameters required).
  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/tool_metadata.py:211-219 (schema)

  Tool metadata definition categorizing it as maintenance tool for Arch, read permission, verify workflow, with related tool get_database_sync_history.
  "check_database_freshness": ToolMetadata( name="check_database_freshness", category="maintenance", platform="arch", permission="read", workflow="verify", related_tools=["get_database_sync_history"], prerequisite_tools=[] ),
• src/arch_ops_server/server.py:1470-1475 (registration)

  Tool dispatch in call_tool(): handles the tool invocation, checks Arch platform, calls the handler, serializes result to JSON.
  elif name == "check_database_freshness": if not IS_ARCH: return [TextContent(type="text", text="Error: check_database_freshness only available on Arch Linux systems")] result = await check_database_freshness() return [TextContent(type="text", text=json.dumps(result, indent=2))]
• src/arch_ops_server/__init__.py:143-143 (registration)

  Tool name exported in __all__ list for import convenience.
  "check_database_freshness",