Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
149 lines (100 loc) · 4.79 KB

CONTRIBUTING.md

File metadata and controls

149 lines (100 loc) · 4.79 KB

Contributing to kwin-mcp

Thank you for your interest in contributing to kwin-mcp, an MCP server for Linux desktop GUI automation on KDE Plasma 6 Wayland.

Development Setup

Prerequisites

  • Python 3.12+
  • KDE Plasma 6 on Wayland (for running and testing)
  • uv package manager

System Dependencies

Install the required system packages for your distribution:

Arch Linux / Manjaro:

sudo pacman -S kwin spectacle at-spi2-core python-gobject dbus-python-common

# Optional: for clipboard and Unicode input
sudo pacman -S wl-clipboard wtype wayland-utils

Fedora (KDE Spin):

sudo dnf install kwin-wayland spectacle at-spi2-core python3-gobject dbus-python

# Optional
sudo dnf install wl-clipboard wtype wayland-utils

Kubuntu / KDE Neon:

sudo apt install kwin-wayland spectacle at-spi2-core python3-gi gir1.2-atspi-2.0 python3-dbus

# Optional
sudo apt install wl-clipboard wtype wayland-utils

Clone and Install

git clone https://github.com/isac322/kwin-mcp.git
cd kwin-mcp
uv sync

Documentation Consistency Check

The project includes a docs-seo consistency checker (scripts/check_docs_seo.py) that validates SEO keywords and positioning terms across documentation files. It runs automatically in CI on pull requests and can be invoked locally:

python3 scripts/check_docs_seo.py

In Claude Code sessions, use the /check-docs-seo skill or the @docs-seo agent to evaluate and update documentation after code changes.

Code Style

This project uses ruff for linting and formatting, and ty for type checking.

uv run ruff check .       # Lint
uv run ruff format .      # Format
uv run ty check           # Type check

Key style rules:

  • Python 3.12+ syntax (use type aliases, | unions, etc.)
  • Double quotes for strings
  • Line length: 100 characters
  • Type hints required for all function signatures
  • All code comments and docstrings in English

Testing Changes

After modifying kwin-mcp code, verify your changes via the interactive CLI:

uv run python -m kwin_mcp.cli

The CLI provides the same functionality as the MCP server and allows you to test tools interactively.

Virtual Session Testing (Isolated)

Use session_start to launch an isolated KWin Wayland session — safe for automated tests and CI since it does not touch your real desktop:

> session_start

Live Session Testing

Use session_connect to attach to your existing KDE Plasma desktop session. This is useful when testing features that require a real desktop environment (e.g., clipboard integration, real application interaction):

> session_connect

session_connect defaults to the current session via $DBUS_SESSION_BUS_ADDRESS and $WAYLAND_DISPLAY. You can also pass explicit values:

> session_connect dbus_address=unix:path=/run/user/1000/bus wayland_display=wayland-1

You can also start the CLI in live-session-default mode with --default-live-session:

uv run python -m kwin_mcp.cli --default-live-session

Note: Do not test via the MCP server if it was started before your code changes -- it will still be running the old code. Always use the CLI for verification.

Project Structure

src/kwin_mcp/
├── core.py            # AutomationEngine — MCP-independent automation logic
├── server.py          # MCP server (thin wrappers around AutomationEngine)
├── cli.py             # Interactive REPL + pipe mode
├── session.py         # KWin session management (isolated virtual + live desktop)
├── screenshot.py      # Screenshot capture via KWin ScreenShot2 D-Bus
├── accessibility.py   # AT-SPI2 accessibility tree inspection
└── input.py           # Input injection via KWin EIS D-Bus + libei

Pull Request Process

  1. Fork the repository and create a feature branch
  2. Make your changes following the code style guidelines above
  3. Run all checks: uv run ruff check . && uv run ruff format --check . && uv run ty check
  4. Update CHANGELOG.md if your change is user-facing (new tools, bug fixes, behavior changes)
  5. Update README.md if you add new tools or change existing tool behavior
  6. Open a pull request with a clear description of the changes

Reporting Issues

License

By contributing to kwin-mcp, you agree that your contributions will be licensed under the MIT License.