Release v0.2.0: Custom exceptions, server refactor, 230 tests, Beta status

- Add custom exception hierarchy (13 classes) replacing ~45 bare except catches
- Refactor server.py (962 → ~100 lines) into handlers.py + tool_definitions.py
- Expand test suite from 45 to 230 tests across 7 test files
- Fix bug in WindowGroupManager.delete_group (empty group falsiness)
- Add type annotations across all modules
- Update metadata: Beta classifier, project URLs, author email
- Add PRIVACY_POLICY.md, CLAUDE.md, update CHANGELOG.md
- Fix placeholder URLs in README.md and CONTRIBUTING.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: anbeckham

CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-02-25
+
+### Added
+- Custom exception hierarchy (`LinuxDesktopMCPError` base) with 13 specific exception classes for AT-SPI, input, overlay, window, and reference errors
+- 185+ new tests across 7 test files (total: ~230 tests), covering window manager, detection, input backends, handlers, window discovery, and overlay
+- `PRIVACY_POLICY.md` standalone privacy document
+- `CLAUDE.md` project guide for AI-assisted development
+- `[project.urls]` in pyproject.toml (Repository, Documentation, Issues, Changelog)
+- `Typing :: Typed` classifier
+
+### Changed
+- Refactored `server.py` (962 lines) into 3 focused modules: `server.py` (~100 lines), `handlers.py` (~620 lines), `tool_definitions.py` (~250 lines)
+- `ServerContext` dataclass replaces monolithic server class for handler state
+- `HANDLER_MAP` dispatcher dict replaces if/elif chain in `call_tool`
+- Narrowed ~45 bare `except Exception` catches to specific types (`_GLibError`, `FileNotFoundError`, `OSError`, custom exceptions)
+- Replaced `Dict` with `dict` and added `-> None`, `-> Any`, `-> dict[str, Any]` return types across all modules
+- Development status classifier updated from Alpha to Beta
+- Version bumped to 0.2.0
+
+### Fixed
+- Bug in `WindowGroupManager.delete_group` where empty `WindowGroup` was treated as falsy due to `__len__` returning 0, preventing active group ID updates
+- Fixed `yourusername` placeholder URLs in README.md and CONTRIBUTING.md
+
 ## [0.1.0] - 2025-01-07
 
 ### Added

CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+Project guide for AI-assisted development of linux-desktop-mcp.
+
+## Project Overview
+
+An MCP server providing Chrome-extension-level semantic element targeting for native Linux desktop applications using AT-SPI2. Exposes 11 tools for desktop automation (snapshot, find, click, type, key, capabilities, context, target_window, create_window_group, release_window).
+
+## Layout
+
+```
+src/linux_desktop_mcp/
+  __init__.py          # Package entry, version, exception exports
+  server.py            # MCP server setup, initialization, tool dispatch
+  handlers.py          # ServerContext dataclass + 10 async handler functions
+  tool_definitions.py  # get_tool_definitions() with all 11 Tool schemas
+  exceptions.py        # Custom exception hierarchy (LinuxDesktopMCPError base)
+  atspi_bridge.py      # AT-SPI2 tree building, element interaction (ThreadPoolExecutor)
+  references.py        # ElementReference, ReferenceManager, GC
+  input_backends.py    # InputManager + YdotoolBackend, XdotoolBackend, WtypeBackend
+  window_manager.py    # WindowGroup, WindowTarget, WindowGroupManager
+  window_discovery.py  # Window enumeration via AT-SPI desktop
+  overlay.py           # GTK3 border overlay windows (X11 backend)
+  detection.py         # Display server, compositor, and tool detection
+tests/
+  conftest.py          # MCP module mocks, shared fixtures
+  test_server.py       # Handler tests via ServerContext
+  test_window_manager.py
+  test_detection.py
+  test_input_backends_manager.py
+  test_window_discovery.py
+  test_overlay.py
+```
+
+## Build & Test
+
+```bash
+# Run tests (mocks MCP + AT-SPI, no desktop needed)
+PYTHONPATH=src pytest tests/ -v
+
+# Lint and format
+ruff check .
+ruff format .
+
+# Import check
+python -c "from linux_desktop_mcp import __version__; print(__version__)"
+```
+
+## Code Conventions
+
+- **Python 3.10+** target. Use `X | None` union syntax, `dict[str, Any]` (not `Dict`).
+- **Exception handling**: Use custom exceptions from `exceptions.py`. AT-SPI modules use `_GLibError` conditional import pattern. Never use bare `except Exception` except in the top-level `call_tool` safety net.
+- **Async handlers**: Each tool handler is a standalone async function in `handlers.py` receiving `(ctx: ServerContext, args: dict)` and returning `list[TextContent]`.
+- **Input backends**: Subprocess-based, mock `asyncio.create_subprocess_exec` in tests.
+- **AT-SPI bridge**: Runs blocking AT-SPI calls in `ThreadPoolExecutor` via `asyncio.to_thread`. Uses `threading.Lock` for thread safety.
+- **Tests**: Pure Python where possible (dataclasses, enums). MCP modules mocked at conftest level. No real desktop or AT-SPI required.
+- **Formatting**: ruff with line-length=100, double quotes, isort-compatible imports.

CONTRIBUTING.md

@@ -20,7 +20,7 @@ We're very open to contributions of all kinds:
 
 1. **Clone the repository**
    ```bash
-   git clone https://github.com/yourusername/linux-desktop-mcp.git
+   git clone https://github.com/BeckhamLabsLLC/linux-desktop-mcp.git
    cd linux-desktop-mcp
    ```
 

PRIVACY_POLICY.md

@@ -0,0 +1,41 @@
+# Privacy Policy
+
+**Linux Desktop MCP** is a local desktop automation tool. This document describes what data it accesses and how it is handled.
+
+## Data Collection
+
+Linux Desktop MCP **does not collect any data**. Specifically:
+
+- No analytics or telemetry
+- No usage tracking
+- No crash reports sent externally
+- No personal information gathered
+
+## Data Access
+
+The server accesses the following local system information during operation:
+
+- **Accessibility tree** (AT-SPI2): UI element names, roles, states, and positions for applications you interact with. This data is read on-demand and not persisted.
+- **Environment variables**: Display server type (`WAYLAND_DISPLAY`, `DISPLAY`, `XDG_SESSION_TYPE`) and compositor detection variables, used solely to select the correct input backend.
+- **Process information**: `shutil.which` checks for the presence of input tools (`ydotool`, `xdotool`, `wtype`, `scrot`, `grim`).
+
+None of this information is stored, logged, or transmitted.
+
+## Third-Party Services
+
+Linux Desktop MCP **does not communicate with any external services**. It:
+
+- Runs entirely on your local machine
+- Requires no network connectivity
+- Makes no outbound HTTP requests
+- Does not store credentials or tokens
+
+The MCP protocol communication occurs exclusively over local stdio between the MCP client (e.g., Claude Code) and this server.
+
+## Data Storage
+
+No data is written to disk during normal operation. The server holds state (element references, window groups) in memory only, and this state is discarded when the server exits.
+
+## Contact
+
+For privacy-related questions, open an issue on [GitHub](https://github.com/BeckhamLabsLLC/linux-desktop-mcp/issues).

README.md

@@ -41,7 +41,7 @@ sudo ydotoold &
 pip install linux-desktop-mcp
 
 # Or from source
-git clone https://github.com/yourusername/linux-desktop-mcp.git
+git clone https://github.com/BeckhamLabsLLC/linux-desktop-mcp.git
 cd linux-desktop-mcp
 pip install -e .
 ```
@@ -312,17 +312,7 @@ We're very open to help and collaboration. See [CONTRIBUTING.md](CONTRIBUTING.md
 
 ## Privacy Policy
 
-Linux Desktop MCP is a local desktop automation tool that:
-
-- **Runs entirely on your local machine** - No data is transmitted to external servers
-- **Does not collect any personal data** - No analytics, telemetry, or usage tracking
-- **Does not store credentials** - All authentication and authorization is handled by your local system
-- **Accesses only what you explicitly target** - The accessibility tree is read only for windows/applications you interact with
-- **No network connectivity required** - The MCP server operates completely offline
-
-The only data accessed is the accessibility tree information exposed by your desktop applications (UI element names, roles, and states), which is used solely for local automation and is not persisted or transmitted anywhere.
-
-**Contact:** For privacy-related questions, open an issue on [GitHub](https://github.com/BeckhamLabsLLC/linux-desktop-mcp/issues).
+See [PRIVACY_POLICY.md](PRIVACY_POLICY.md) for our full privacy policy. In short: Linux Desktop MCP runs entirely on your local machine, collects no data, and requires no network connectivity.
 
 ## License
 

pyproject.toml

@@ -4,17 +4,17 @@ build-backend = "hatchling.build"
 
 [project]
 name = "linux-desktop-mcp"
-version = "0.1.0"
+version = "0.2.0"
 description = "MCP server for Linux desktop automation using AT-SPI2"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 authors = [
-    { name = "Austin Beck" }
+    { name = "Austin Beck", email = "austin@beckhamlabs.com" }
 ]
 keywords = ["mcp", "linux", "desktop", "automation", "accessibility", "at-spi"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
@@ -25,6 +25,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Topic :: Desktop Environment",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
 ]
 dependencies = [
     "mcp>=1.0.0",
@@ -42,6 +43,12 @@ dev = [
     "ruff>=0.1.0",
 ]
 
+[project.urls]
+Repository = "https://github.com/BeckhamLabsLLC/linux-desktop-mcp"
+Documentation = "https://github.com/BeckhamLabsLLC/linux-desktop-mcp#readme"
+Issues = "https://github.com/BeckhamLabsLLC/linux-desktop-mcp/issues"
+Changelog = "https://github.com/BeckhamLabsLLC/linux-desktop-mcp/blob/main/CHANGELOG.md"
+
 [project.scripts]
 linux-desktop-mcp = "linux_desktop_mcp:main"
 

src/linux_desktop_mcp/__init__.py

@@ -4,14 +4,52 @@
 desktop applications using AT-SPI2 (Assistive Technology Service Provider Interface).
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
+from .exceptions import (
+    ATSPIActionError,
+    ATSPIError,
+    ATSPINotAvailableError,
+    ATSPITreeBuildError,
+    DisplayServerError,
+    GtkInitError,
+    InputBackendNotAvailableError,
+    InputCommandError,
+    InputError,
+    InputValidationError,
+    LinuxDesktopMCPError,
+    OverlayError,
+    ReferenceExpiredError,
+    ReferenceNotFoundError,
+    WindowInvalidError,
+    WindowNotFoundError,
+)
 
-def main():
+
+def main() -> None:
     """Entry point for the MCP server."""
     from .server import main as _main
 
     _main()
 
 
-__all__ = ["main", "__version__"]
+__all__ = [
+    "main",
+    "__version__",
+    "LinuxDesktopMCPError",
+    "ATSPIError",
+    "ATSPINotAvailableError",
+    "ATSPITreeBuildError",
+    "ATSPIActionError",
+    "WindowNotFoundError",
+    "WindowInvalidError",
+    "ReferenceNotFoundError",
+    "ReferenceExpiredError",
+    "InputError",
+    "InputBackendNotAvailableError",
+    "InputCommandError",
+    "InputValidationError",
+    "OverlayError",
+    "GtkInitError",
+    "DisplayServerError",
+]