# cachyos-mcp

All-in-one **Arch/CachyOS deep system control** MCP server. It provides
pacman + AUR package intelligence and system updates, and bundles the complete
[`network-mcp`](../network-mcp) and [`sysprobe-mcp`](../sysprobe-mcp) tool sets
so a single server gives Claude full visibility and control of the machine.

The two generic servers stay independently deployable (e.g. ship `network-mcp`
to a headless server); cachyos-mcp just embeds their `register()` entry points.

## Arch-specific tools

**Package intelligence (read-only)**
- `search_all_repositories` — repos **and** AUR in one call, unified & sorted
  (the anti-hallucination tool: see every available variant + votes + installed)
- `search_system_repos`, `search_aur`
- `get_package_info`, `get_aur_info`, `get_package_dependencies`
- `query_installed_packages`, `which_package_owns`, `list_package_files`
- `list_orphans`, `list_explicit_packages`
- `check_updates` (repos via checkupdates + AUR via paru — no root, safe)
- `get_pacman_log`, `get_mirrorlist`, `list_kernels`, `get_package_cache_info`

**Mutating (needs `SYSCONTROL_ALLOW_ACTIONS=1`)**
- `system_update`, `install_packages`, `install_aur_package`,
  `clean_package_cache`
- `remove_packages` — **never auto-executed**; returns the command only

### Privilege handling

pacman needs root. Gated write tools run via **passwordless sudo if available**,
otherwise they return the exact command for you to run (in Claude Code, prefix
with `!`). To let Claude apply updates directly, add a sudoers rule, e.g.:

```
tom ALL=(root) NOPASSWD: /usr/bin/pacman, /usr/bin/paccache
```

## Bundled tool sets

- **network**: NetworkManager status, `ip -j` interfaces/routes, listening
  ports, throughput, firewall, mtr, DNS, TLS, port scan, whois, WireGuard,
  speedtest, packet capture …
- **sysprobe**: sensors, processes, systemd/journal, coredumps, dmesg, D-Bus,
  hardware inventory, brightness, power profile, CPU governor, audio, media,
  app launch, bluetooth, KDE control, session/power …

## Run / register

```bash
SYSCONTROL_ALLOW_ACTIONS=1 uv run cachyos-mcp
```

```bash
claude mcp add cachyos -s user \
  -e SYSCONTROL_ALLOW_ACTIONS=1 \
  -- uv --directory "/home/tom/Projekte/SE Projects/cachyos-mcp" run cachyos-mcp
```

If you register cachyos-mcp you get everything; you typically would **not** also
register network-mcp / sysprobe-mcp locally (only when deploying them elsewhere).

## Requirements

`pacman` (always), and optionally `pacman-contrib` (checkupdates/paccache),
`paru` (AUR), `pactree`/`expac`. Network/sysprobe optional tools as listed in
their READMEs.