Shortcut Tools

Shortcut tools wrap common D-Bus interactions into single calls with friendly parameters. They target specific well-known services and handle the service name, object path, interface, and method details internally.

Each shortcut could be replicated using call_method, get_property, and get_all_properties from the interaction tools, but shortcuts save the discovery round-trip and produce formatted output.

---

send_notification

Send a desktop notification via the freedesktop Notifications service on the session bus.

Parameters

Parameter	Type	Default	Description
summary	string	required	Notification title
body	string	""	Notification body text
icon	string	""	Icon name or file path (empty for default)
timeout	int	5000	Display duration in milliseconds

D-Bus details

Calls org.freedesktop.Notifications.Notify on the session bus with app_name set to "mcdbus" and replaces_id of 0 (always creates a new notification).

Return format

Notification sent (id: 42)

The returned ID can be used with call_method to call CloseNotification if needed.

---

list_systemd_units

List systemd units, optionally filtered by a glob pattern.

Parameters

Parameter	Type	Default	Description
bus	string	"system"	"session" for user units, "system" for system units
pattern	string	""	Glob filter using fnmatch syntax (e.g. "docker*", "*.service", "ssh*")

D-Bus details

Calls org.freedesktop.systemd1.Manager.ListUnits and extracts the first five fields from each unit tuple: name, description, load state, active state, and sub state.

Return format

Markdown table sorted alphabetically by unit name.

## Systemd units on system bus -- 3 matches

| Unit | Load | Active | Sub | Description |
|------|------|--------|-----|-------------|
| `docker.service` | loaded | active | running | Docker Application Container Engine |
| `docker.socket` | loaded | active | listening | Docker Socket for the API |
| `docker-compose@media.service` | loaded | active | running | Docker Compose stack: media |

---

media_player_control

Control an MPRIS2-compatible media player on the session bus.

Parameters

Parameter	Type	Default	Description
action	string	required	One of: play, pause, next, previous, stop, play-pause
player	string	""	Full MPRIS service name; auto-discovers the first available player if empty

Auto-discovery

When player is empty, the tool lists all session bus services matching org.mpris.MediaPlayer2.*, sorts them alphabetically, and uses the first one. If multiple players are found, the others are logged via context info.

Return format

Player: org.mpris.MediaPlayer2.firefox
Action: play-pause
Status: Paused
Now: David Bowie -- Starman

The current track is read from the player’s Metadata property (xesam:artist and xesam:title fields). If metadata is unavailable, both fields show "Unknown".

Returns "No MPRIS media players found on session bus." if no players are discovered.

---

network_status

Show NetworkManager connection status and active connections. Takes no parameters.

D-Bus details

Reads all properties from org.freedesktop.NetworkManager on the system bus, then iterates over each active connection path to read its Id, Type, and State properties.

State mapping

The numeric State property is mapped to a human-readable string:

Code	State
0	Unknown
10	Asleep
20	Disconnected
30	Disconnecting
40	Connecting
50	Connected (local)
60	Connected (site)
70	Connected (global)

Return format

## Network Status

- **State:** Connected (global)
- **Wireless:** enabled

| Connection | Type | State |
|------------|------|-------|
| Wired connection 1 | 802-3-ethernet | Activated |
| MyWiFi | 802-11-wireless | Activated |

---

battery_status

Show battery status from UPower on the system bus. Takes no parameters.

D-Bus details

Calls org.freedesktop.UPower.EnumerateDevices, then reads properties from each device via org.freedesktop.UPower.Device. Only devices with Type=2 (Battery) are included.

State mapping

Code	State
0	Unknown
1	Charging
2	Discharging
3	Empty
4	Fully charged
5	Pending charge
6	Pending discharge

Return format

## Battery Status

### BAT0
- **Charge:** 73%
- **State:** Discharging
- **Time:** 4h 12m remaining
- **Power draw:** 8.3 W

Time remaining is calculated from TimeToEmpty (when discharging) or TimeToFull (when charging). Power draw is shown only when EnergyRate is greater than zero. Returns "No batteries found." if no battery-type devices are present.

---

bluetooth_devices

List discovered and paired Bluetooth devices from bluez on the system bus. Takes no parameters.

D-Bus details

Calls org.freedesktop.DBus.ObjectManager.GetManagedObjects on org.bluez at /, then filters for objects that implement the org.bluez.Device1 interface.

Return format

Markdown table sorted by connection priority: connected devices first, then paired devices, then alphabetically by name.

## Bluetooth Devices -- 4 found

| Name | Address | Connected | Paired | Trusted |
|------|---------|-----------|--------|---------|
| WH-1000XM4 | `AA:BB:CC:DD:EE:01` | yes | yes | yes |
| Keyboard K380 | `AA:BB:CC:DD:EE:02` | no | yes | yes |
| MX Master 3 | `AA:BB:CC:DD:EE:03` | no | yes | no |
| [Unknown] | `AA:BB:CC:DD:EE:04` | no | no | no |

Returns "No Bluetooth devices found." if no org.bluez.Device1 objects exist, or raises a ToolError if bluez is not available.

---

kwin_windows

List open windows from KDE KWin via the KRunner window runner on the session bus. Takes no parameters. Requires a running KDE Plasma session.

D-Bus details

Calls org.kde.krunner1.Match on org.kde.KWin at /WindowsRunner with an empty query string, which returns all windows. Each match contains an ID, caption, icon name, type code, relevance score, and properties. Type code 8 indicates a virtual desktop entry; all other types are treated as windows.

Return format

Window table sorted by application name then caption, followed by virtual desktop names if present.

## KWin Windows -- 5 open

| Window | Application |
|--------|-------------|
| mcdbus reference -- Firefox | firefox |
| ~/projects/mcdbus -- Konsole | konsole |
| server.py -- Kate | kate |
| Dolphin | dolphin |
| System Settings | systemsettings |

**Virtual desktops:** Desktop 1, Desktop 2

Returns "No windows found (KWin WindowsRunner returned empty)." if KWin reports no matches, or raises a ToolError if KWin is not available.