# Arch Linux / CachyOS & Niri DE MCP Server (`arch-niri-mcp`)

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP Protocol](https://img.shields.io/badge/MCP-v1.2-purple.svg)](https://modelcontextprotocol.io/)
[![Arch Linux](https://img.shields.io/badge/Arch%20Linux-Supported-1793d1.svg?logo=arch-linux)](https://archlinux.org/)
[![CachyOS](https://img.shields.io/badge/CachyOS-Supported-00a884.svg)](https://cachyos.org/)
[![Niri DE](https://img.shields.io/badge/Niri%20DE-Wayland-ff69b4.svg)](https://github.com/YaLteR/niri)

An enterprise-grade **Model Context Protocol (MCP)** server that enables AI assistants (**Antigravity, Claude Desktop, Cursor, VS Code, Windsurf, Zed**) to seamlessly inspect, control, and automate **Arch Linux**, **CachyOS**, and the **Niri Desktop Environment** (scrollable tiling Wayland compositor).

---

## 🌟 Key Features

- **🔍 Automatic CLI Discovery**: Dynamically scans system `PATH` and categorizes installed package managers, terminals, Wayland helpers, and desktop tools.
- **🖥️ Niri DE Window & Layout Control**: Query windows, workspaces, monitors, layer-shell surfaces, floating states, layout columns, tabbed modes, and focus states via live JSON IPC.
- **💻 Native Terminal Execution**: Execute terminal commands in user's default shell (`fish`, `zsh`, `bash`), or spawn interactive graphical terminal windows (`Alacritty`, `Kitty`, `Foot`, `Ghostty`).
- **⚙️ System & Hardware Management**: Systemd services (`systemctl`), PipeWire audio (`wpctl`), screen brightness (`brightnessctl`), Wayland clipboard (`wl-clipboard`), notifications (`notify-send`), network connections (`nmcli`), battery stats, and hardware summary (`fastfetch`).
- **📦 Package Management**: Query pacman packages and search Arch User Repository (AUR) & CachyOS repos via `yay`.

---

## 🧰 Complete Tools Reference (35 Tools)

### 🔍 1. Auto-Discovery & Terminal Suite (5 Tools)

| Tool | Description |
| :--- | :--- |
| `arch_discover_tools` | Dynamically scans system `PATH` and returns an inventory of installed CLI tools, package managers, terminals, and desktop helpers. |
| `arch_get_shell_info` | Inspects user default shell (`$SHELL`), PATH directories, `$WAYLAND_DISPLAY`, and detected terminal emulator. |
| `arch_exec_terminal_cmd` | Safely executes terminal/CLI commands in the user's shell environment with stdout/stderr capture, working directory, and timeout control. |
| `arch_spawn_terminal` | Launches an interactive graphical terminal window (`Alacritty`, `Kitty`, `Foot`, `Ghostty`) inside Niri DE session. |
| `arch_journalctl` | Fetches systemd service or kernel logs via `journalctl`. |

### 🖥️ 2. Niri Desktop Environment Suite (16 Tools)

| Tool | Description |
| :--- | :--- |
| `niri_get_windows` | Lists open windows with app IDs, titles, window IDs, workspace IDs, and focus state. |
| `niri_get_workspaces` | Lists workspaces, index, names, output monitors, and active status. |
| `niri_get_outputs` | Lists connected display monitors, resolutions, scale, and focus state. |
| `niri_get_layers` | Lists active Wayland layer-shell surfaces (desktop bars, panels, notifications, quickshell). |
| `niri_get_keyboard_layouts` | Lists configured keyboard layouts and active layout index. |
| `niri_get_focused` | Inspects currently focused window and display monitor. |
| `niri_focus_window` | Switches focus to a window by numeric ID or title/app_id search string. |
| `niri_focus_workspace` | Switches active workspace by index or name. |
| `niri_move_window_to_workspace` | Moves focused window/column to target workspace by index or name. |
| `niri_move_window_direction` | Moves window/column (`left`, `right`, `up`, `down`, `first`, `last`). |
| `niri_set_column_width` | Adjusts column width (`50%`, `33%`, `+10%`, `expand`, `switch-preset`). |
| `niri_close_window` | Closes focused window or target window by ID. |
| `niri_reload_config` | Reloads Niri configuration file (`config.kdl`). |
| `niri_perform_action` | Executes any Niri layout action (`maximize-column`, `toggle-window-floating`, `center-column`, `toggle-overview`, `toggle-column-tabbed-display`, etc.). |
| `niri_spawn_app` | Launches applications inside the Niri compositor session. |
| `niri_take_screenshot` | Captures full screen or focused window screenshot. |

### 🐧 3. Arch Linux & CachyOS System Suite (14 Tools)

| Tool | Description |
| :--- | :--- |
| `arch_get_system_info` | Retrieves hardware overview, OS version, kernel, CPU, GPU, memory, and uptime via `fastfetch`. |
| `arch_package_query` | Searches pacman package database (`pacman -Qs` / `pacman -Ss`). |
| `arch_aur_search` | Searches Arch User Repository (AUR) & CachyOS repos via `yay -Ss`. |
| `arch_check_updates` | Lists pending system package updates (`checkupdates` / `pacman -Qu`). |
| `arch_systemctl` | Views status or controls systemd user/system units (`start`, `stop`, `restart`, `enable`, `disable`). |
| `arch_process_list` | Lists processes ordered by CPU/Memory or searches by name. |
| `arch_kill_process` | Terminates process by PID. |
| `arch_audio_control` | Queries audio status, adjusts volume percentage (%), or toggles mute via PipeWire (`wpctl`). |
| `arch_brightness_control` | Queries or sets screen brightness percentage (`brightnessctl`). |
| `arch_send_notification` | Sends desktop notifications to Niri DE via `notify-send` with custom icons & urgency levels. |
| `arch_network_status` | Queries active Wi-Fi, Ethernet, and network devices via `nmcli`. |
| `arch_battery_status` | Queries laptop battery charge level, status, and power draw. |
| `arch_clipboard_get` | Reads Wayland clipboard text (`wl-paste`). |
| `arch_clipboard_set` | Sets Wayland clipboard text (`wl-copy`). |

---

## 📦 Installation

### Option 1: Automated Script

```bash
git clone https://github.com/oki3505F/arch-niri-mcp.git
cd arch-niri-mcp
./install.sh
```

### Option 2: Using `uv` (Recommended)

```bash
git clone https://github.com/oki3505F/arch-niri-mcp.git
cd arch-niri-mcp
uv venv .venv
source .venv/bin/activate
uv pip install -e .
```

---

## ⚙️ AI Client Configuration

### 1. Claude Desktop (`claude_desktop_config.json`)

Add the following to your `~/.config/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "arch-niri-control": {
      "command": "/path/to/arch-niri-mcp/.venv/bin/arch-niri-mcp",
      "args": []
    }
  }
}
```

### 2. Antigravity / Cursor / VS Code / Windsurf (`.mcp.json`)

Add to your project `.mcp.json` or client MCP settings:

```json
{
  "mcpServers": {
    "arch-niri-control": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/arch-niri-mcp",
        "arch-niri-mcp"
      ]
    }
  }
}
```

---

## 🧪 Testing & Verification

Run the server executable directly via stdio:

```bash
/path/to/arch-niri-mcp/.venv/bin/arch-niri-mcp
```

Or verify registered tools in Python:

```bash
source .venv/bin/activate
python3 -c "import arch_niri_mcp.server as s; print('Registered tools:', len(s.mcp._tool_manager._tools))"
```

---

## 🏷️ GitHub Topics & Keywords

`arch-linux` • `cachyos` • `niri` • `niri-de` • `wayland` • `mcp` • `mcp-server` • `model-context-protocol` • `desktop-automation` • `window-management` • `pipewire` • `claude-desktop` • `cursor` • `antigravity`

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.