arch-mcp

Instructions

Implementation Reference

• src/arch_ops_server/pacman.py:475-535 (handler)

  Core handler function that runs 'pacman -Qtdq' to detect orphan packages, parses the output, handles edge cases like no orphans or errors, and returns structured JSON with orphan_count and list of orphans.
  async def list_orphan_packages() -> Dict[str, Any]: """ List all orphaned packages (dependencies no longer required). Returns: Dict with list of orphan packages """ if not IS_ARCH: return create_error_response( "NotSupported", "Orphan package detection is only available on Arch Linux" ) if not check_command_exists("pacman"): return create_error_response( "CommandNotFound", "pacman command not found" ) logger.info("Listing orphan packages") try: exit_code, stdout, stderr = await run_command( ["pacman", "-Qtdq"], timeout=10, check=False ) # Exit code 1 with no output means no orphans if exit_code == 1 and not stdout.strip(): logger.info("No orphan packages found") return { "orphan_count": 0, "orphans": [] } if exit_code != 0: logger.error(f"Failed to list orphans: {stderr}") return create_error_response( "CommandError", f"Failed to list orphan packages: {stderr}", f"Exit code: {exit_code}" ) # Parse output - one package per line orphans = [pkg.strip() for pkg in stdout.strip().split('\n') if pkg.strip()] logger.info(f"Found {len(orphans)} orphan packages") return { "orphan_count": len(orphans), "orphans": orphans } except Exception as e: logger.error(f"Orphan listing failed with exception: {e}") return create_error_response( "CommandError", f"Failed to list orphan packages: {str(e)}" )
• src/arch_ops_server/server.py:730-736 (schema)

  MCP tool schema definition in list_tools(), specifying the tool name, description, and empty inputSchema (no parameters required). Output follows the standard response format.
  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": {} } ),
• src/arch_ops_server/server.py:1240-1245 (registration)

  Registration and dispatch logic in @server.call_tool(), which checks if on Arch Linux and calls the list_orphan_packages function, serializing the result as JSON text content.
  elif name == "list_orphan_packages": if not IS_ARCH: return [TextContent(type="text", text="Error: list_orphan_packages only available on Arch Linux systems")] result = await list_orphan_packages() return [TextContent(type="text", text=json.dumps(result, indent=2))]
• src/arch_ops_server/server.py:26-43 (registration)

  Import statement in server.py that brings list_orphan_packages into the module namespace for use in tool dispatch.
  from . import ( # Wiki functions search_wiki, get_wiki_page_as_text, # AUR functions search_aur, get_aur_info, get_pkgbuild, analyze_pkgbuild_safety, analyze_package_metadata_risk, install_package_secure, # Pacman functions get_official_package_info, check_updates_dry_run, remove_package, remove_packages_batch, list_orphan_packages, remove_orphans,
• src/arch_ops_server/pacman.py:561-565 (helper)

  Usage as a helper function within remove_orphans() to first list orphans before proceeding with removal.
  orphans_result = await list_orphan_packages() if orphans_result.get("error"): return orphans_result