Skip to content

Commit 1981bb4

Browse files
anbeckhamclaude
anbeckham
and
claude
committed
Initial release v0.1.0
Linux Desktop MCP - Chrome extension-level semantic element targeting for native Linux desktop applications using AT-SPI2. Features: - 11 MCP tools for desktop automation - Semantic element references (ref_1, ref_2, etc.) - AT-SPI2 accessibility tree support - X11, Wayland, and XWayland input backends - Window grouping with visual overlays - Input validation and security hardening Built with Claude Code. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
0 parents  commit 1981bb4

22 files changed

Lines changed: 4978 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ['3.10', '3.11', '3.12']
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python ${{ matrix.python-version }}
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: ${{ matrix.python-version }}
23+
24+
- name: Install system dependencies
25+
run: |
26+
sudo apt-get update
27+
sudo apt-get install -y python3-pyatspi gir1.2-atspi-2.0 at-spi2-core libgirepository1.0-dev
28+
29+
- name: Install Python dependencies
30+
run: |
31+
python -m pip install --upgrade pip
32+
pip install -e ".[dev]"
33+
34+
- name: Run tests
35+
run: |
36+
pytest tests/ -v
37+
38+
lint:
39+
runs-on: ubuntu-latest
40+
41+
steps:
42+
- uses: actions/checkout@v4
43+
44+
- name: Set up Python
45+
uses: actions/setup-python@v5
46+
with:
47+
python-version: '3.11'
48+
49+
- name: Install ruff
50+
run: pip install ruff
51+
52+
- name: Run linter
53+
run: ruff check .
54+
55+
- name: Check formatting
56+
run: ruff format --check .

‎.github/workflows/publish.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Publish to PyPI
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
build:
9+
runs-on: ubuntu-latest
10+
11+
steps:
12+
- uses: actions/checkout@v4
13+
14+
- name: Set up Python
15+
uses: actions/setup-python@v5
16+
with:
17+
python-version: '3.11'
18+
19+
- name: Install build dependencies
20+
run: |
21+
python -m pip install --upgrade pip
22+
pip install build twine
23+
24+
- name: Build package
25+
run: python -m build
26+
27+
- name: Check package
28+
run: twine check dist/*
29+
30+
- name: Upload artifacts
31+
uses: actions/upload-artifact@v4
32+
with:
33+
name: dist
34+
path: dist/
35+
36+
publish:
37+
needs: build
38+
runs-on: ubuntu-latest
39+
environment: pypi
40+
permissions:
41+
id-token: write
42+
43+
steps:
44+
- name: Download artifacts
45+
uses: actions/download-artifact@v4
46+
with:
47+
name: dist
48+
path: dist/
49+
50+
- name: Publish to PyPI
51+
uses: pypa/gh-action-pypi-publish@release/v1
52+
with:
53+
password: ${{ secrets.PYPI_API_TOKEN }}

‎.gitignore‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
16+
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
share/python-wheels/
24+
*.egg-info/
25+
.installed.cfg
26+
*.egg
27+
MANIFEST
28+
29+
# PyInstaller
30+
*.manifest
31+
*.spec
32+
33+
# Installer logs
34+
pip-log.txt
35+
pip-delete-this-directory.txt
36+
37+
# Unit test / coverage reports
38+
htmlcov/
39+
.tox/
40+
.nox/
41+
.coverage
42+
.coverage.*
43+
.cache
44+
nosetests.xml
45+
coverage.xml
46+
*.cover
47+
*.py,cover
48+
.hypothesis/
49+
.pytest_cache/
50+
pytest_cache/
51+
52+
# Translations
53+
*.mo
54+
*.pot
55+
56+
# Environments
57+
.env
58+
.venv
59+
env/
60+
venv/
61+
ENV/
62+
env.bak/
63+
venv.bak/
64+
65+
# Spyder project settings
66+
.spyderproject
67+
.spyproject
68+
69+
# Rope project settings
70+
.ropeproject
71+
72+
# mkdocs documentation
73+
/site
74+
75+
# mypy
76+
.mypy_cache/
77+
.dmypy.json
78+
dmypy.json
79+
80+
# Pyre type checker
81+
.pyre/
82+
83+
# pytype static type analyzer
84+
.pytype/
85+
86+
# Cython debug symbols
87+
cython_debug/
88+
89+
# IDE
90+
.idea/
91+
.vscode/
92+
*.swp
93+
*.swo
94+
*~
95+
96+
# OS
97+
.DS_Store
98+
Thumbs.db
99+
100+
# Project specific
101+
*.log
102+
.mcp.json

‎CHANGELOG.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.1.0] - 2025-01-07
9+
10+
### Added
11+
- Initial release of Linux Desktop MCP
12+
- 11 MCP tools for desktop automation:
13+
- `desktop_snapshot` - Capture accessibility tree with semantic refs
14+
- `desktop_find` - Find elements by natural language query
15+
- `desktop_click` - Click elements by ref or coordinates
16+
- `desktop_type` - Type text into elements
17+
- `desktop_key` - Press keyboard keys/shortcuts
18+
- `desktop_capabilities` - Check available automation capabilities
19+
- `desktop_context` - Get window group context
20+
- `desktop_target_window` - Target specific windows with colored borders
21+
- `desktop_create_window_group` - Create window groups
22+
- `desktop_release_window` - Release windows from tracking
23+
- AT-SPI2 accessibility tree support for semantic element targeting
24+
- Reference system (`ref_1`, `ref_2`, etc.) similar to Chrome extension
25+
- Input backends:
26+
- ydotool (Wayland + X11)
27+
- xdotool (X11 only)
28+
- wtype (Wayland keyboard only)
29+
- Window grouping with visual border overlays
30+
- X11, Wayland, and XWayland support
31+
- Automatic garbage collection for stale references
32+
- Input validation for security
33+
- Comprehensive documentation and examples
34+
35+
### Security
36+
- Added input validation for coordinates (0-65535 range)
37+
- Added text length limits (10,000 characters max)
38+
- Added query length limits (1,000 characters max)
39+
- Safe subprocess execution for input tools

‎CONTRIBUTING.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Contributing to Linux Desktop MCP
2+
3+
First off, thank you for considering contributing to Linux Desktop MCP!
4+
5+
## Built with Claude Code
6+
7+
This entire project was built using [Claude Code](https://claude.ai/claude-code), Anthropic's AI-powered coding assistant. We believe in the power of AI-assisted development and welcome contributions from both humans and AI-assisted developers alike.
8+
9+
## Ways to Contribute
10+
11+
We're very open to contributions of all kinds:
12+
13+
- **Bug Reports**: Found a bug? Open an issue with details about your environment and steps to reproduce.
14+
- **Feature Requests**: Have an idea? We'd love to hear it! Open an issue to discuss.
15+
- **Pull Requests**: Code contributions are welcome! See below for guidelines.
16+
- **Documentation**: Help improve our docs, add examples, or fix typos.
17+
- **Forks**: Feel free to fork this project and build your own version! We'd love to see what you create.
18+
19+
## Development Setup
20+
21+
1. **Clone the repository**
22+
```bash
23+
git clone https://github.com/yourusername/linux-desktop-mcp.git
24+
cd linux-desktop-mcp
25+
```
26+
27+
2. **Install system dependencies**
28+
```bash
29+
# Ubuntu/Debian
30+
sudo apt install python3-pyatspi gir1.2-atspi-2.0 at-spi2-core
31+
32+
# For input simulation (pick one or more)
33+
sudo apt install ydotool # Wayland + X11
34+
sudo apt install xdotool # X11 only
35+
```
36+
37+
3. **Create a virtual environment**
38+
```bash
39+
python3 -m venv venv
40+
source venv/bin/activate
41+
```
42+
43+
4. **Install in development mode**
44+
```bash
45+
pip install -e ".[dev]"
46+
```
47+
48+
5. **Run tests**
49+
```bash
50+
pytest tests/
51+
```
52+
53+
## Code Style
54+
55+
We use [ruff](https://github.com/astral-sh/ruff) for linting. Before submitting:
56+
57+
```bash
58+
pip install ruff
59+
ruff check .
60+
ruff format .
61+
```
62+
63+
### Guidelines
64+
65+
- Follow PEP 8 style guidelines
66+
- Add type hints to function signatures
67+
- Write docstrings for public functions and classes
68+
- Keep functions focused and reasonably sized
69+
- Add tests for new functionality
70+
71+
## Pull Request Process
72+
73+
1. **Fork the repository** and create your branch from `main`
74+
2. **Make your changes** with clear, descriptive commits
75+
3. **Add tests** if you're adding new functionality
76+
4. **Run the test suite** to ensure nothing is broken
77+
5. **Update documentation** if needed
78+
6. **Open a Pull Request** with a clear description of changes
79+
80+
### PR Title Format
81+
82+
Use clear, descriptive titles:
83+
- `feat: Add support for Wayland layer shell`
84+
- `fix: Handle closed windows gracefully`
85+
- `docs: Add troubleshooting section`
86+
- `test: Add tests for reference manager`
87+
88+
## Reporting Bugs
89+
90+
When reporting bugs, please include:
91+
92+
1. **Your environment**: Linux distro, display server (X11/Wayland), compositor
93+
2. **Steps to reproduce**: Clear steps to trigger the bug
94+
3. **Expected behavior**: What should happen
95+
4. **Actual behavior**: What actually happens
96+
5. **Logs**: Any relevant error messages or logs
97+
98+
## Feature Requests
99+
100+
For feature requests, please describe:
101+
102+
1. **The problem** you're trying to solve
103+
2. **Your proposed solution** (if you have one)
104+
3. **Alternatives** you've considered
105+
106+
## Code of Conduct
107+
108+
- Be respectful and inclusive
109+
- Welcome newcomers
110+
- Focus on constructive feedback
111+
- Assume good intentions
112+
113+
## License
114+
115+
By contributing, you agree that your contributions will be licensed under the MIT License.
116+
117+
## Questions?
118+
119+
Feel free to open an issue for any questions about contributing. We're happy to help!

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Austin Beck
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)