windows-mcp 0.5.2__tar.gz → 0.5.3__tar.gz

{windows_mcp-0.5.2 → windows_mcp-0.5.3}/.gitignore

@@ -165,5 +165,5 @@ cython_debug/
 .mcpregistry_github_token
 .mcpregistry_registry_token
 sandbox
-*.ipynb
+# *.ipynb
 *.mcpb

windows_mcp-0.5.3/.python-version

@@ -0,0 +1 @@
+3.13

windows_mcp-0.5.3/CONTRIBUTING.md

@@ -0,0 +1,384 @@
+# Contributing to Windows-MCP
+
+Thank you for your interest in contributing to Windows-MCP! We welcome contributions from the community to help make this project better. This document provides guidelines and instructions for contributing.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+  - [Prerequisites](#prerequisites)
+  - [Development Environment Setup](#development-environment-setup)
+- [Development Workflow](#development-workflow)
+  - [Branching Strategy](#branching-strategy)
+  - [Making Changes](#making-changes)
+  - [Commit Messages](#commit-messages)
+  - [Code Style](#code-style)
+- [Testing](#testing)
+  - [Running Tests](#running-tests)
+  - [Adding Tests](#adding-tests)
+- [Pull Requests](#pull-requests)
+  - [Before Submitting](#before-submitting)
+  - [Pull Request Process](#pull-request-process)
+  - [Review Process](#review-process)
+- [Documentation](#documentation)
+- [Reporting Issues](#reporting-issues)
+- [Security Vulnerabilities](#security-vulnerabilities)
+- [Getting Help](#getting-help)
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment. We expect all contributors to:
+
+- Be respectful and considerate in communication
+- Welcome newcomers and help them get started
+- Accept constructive criticism gracefully
+- Focus on what's best for the community and project
+
+## Getting Started
+
+### Prerequisites
+
+Before you begin, ensure you have:
+
+- **Windows OS**: Windows 7, 8, 8.1, 10, or 11
+- **Python 3.13+**: [Download Python](https://www.python.org/downloads/)
+- **UV Package Manager**: Install with `pip install uv` or see [UV documentation](https://github.com/astral-sh/uv)
+- **Git**: [Download Git](https://git-scm.com/downloads)
+- **A GitHub account**: [Sign up here](https://github.com/join)
+
+### Development Environment Setup
+
+1. **Fork the Repository**
+   
+   Click the "Fork" button on the [Windows-MCP repository](https://github.com/CursorTouch/Windows-MCP) to create your own copy.
+
+2. **Clone Your Fork**
+   
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/Windows-MCP.git
+   cd Windows-MCP
+   ```
+
+3. **Add Upstream Remote**
+   
+   ```bash
+   git remote add upstream https://github.com/CursorTouch/Windows-MCP.git
+   ```
+
+4. **Install Dependencies**
+   
+   ```bash
+   uv sync
+   ```
+
+5. **Verify Installation**
+   
+   ```bash
+   uv run main.py --help
+   ```
+
+## Development Workflow
+
+### Branching Strategy
+
+- **`main`** branch contains the latest stable code
+- Create feature branches from `main` using descriptive names:
+  - Features: `feature/add-new-tool`
+  - Bug fixes: `fix/click-tool-coordinates`
+  - Documentation: `docs/update-readme`
+  - Refactoring: `refactor/desktop-service`
+
+### Making Changes
+
+1. **Create a New Branch**
+   
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make Your Changes**
+   
+   - Write clean, readable code
+   - Follow the existing code structure
+   - Add comments for complex logic
+   - Update documentation as needed
+
+3. **Test Your Changes**
+   
+   - Test manually in a safe environment (VM recommended)
+   - Add automated tests if applicable
+   - Ensure existing functionality isn't broken
+
+4. **Commit Your Changes**
+   
+   ```bash
+   git add .
+   git commit -m "Add feature: description of your changes"
+   ```
+
+### Commit Messages
+
+While we don't enforce a strict commit message format, please make your commits informative:
+
+**Good examples:**
+- `Add support for multi-monitor setups in State-Tool`
+- `Fix Click-Tool coordinate offset on high DPI displays`
+- `Update README with Perplexity Desktop installation steps`
+- `Refactor Desktop class to improve error handling`
+
+**Avoid:**
+- `fix bug`
+- `update`
+- `changes`
+
+### Code Style
+
+We use **[Ruff](https://github.com/astral-sh/ruff)** for code formatting and linting.
+
+**Key Guidelines:**
+- **Line length**: 100 characters maximum
+- **Quotes**: Use double quotes for strings
+- **Naming conventions**: Follow PEP 8
+  - `snake_case` for functions and variables
+  - `PascalCase` for classes
+  - `UPPER_CASE` for constants
+- **Type hints**: Add type annotations to function signatures
+- **Docstrings**: Use Google-style docstrings for all public functions and classes
+
+**Example:**
+
+```python
+def click_tool(
+    loc: list[int],
+    button: Literal['left', 'right', 'middle'] = 'left',
+    clicks: int = 1
+) -> str:
+    """Click on UI elements at specific coordinates.
+    
+    Args:
+        loc: List of [x, y] coordinates to click
+        button: Mouse button to use (left, right, or middle)
+        clicks: Number of clicks (1=single, 2=double, 3=triple)
+    
+    Returns:
+        Confirmation message describing the action performed
+    
+    Raises:
+        ValueError: If loc doesn't contain exactly 2 integers
+    """
+    if len(loc) != 2:
+        raise ValueError("Location must be a list of exactly 2 integers [x, y]")
+    # Implementation...
+```
+
+**Format Code:**
+
+```bash
+ruff format .
+```
+
+**Run Linter:**
+
+```bash
+ruff check .
+```
+
+## Testing
+
+### Running Tests
+
+If the project has tests (check the `tests/` directory):
+
+```bash
+pytest
+```
+
+Run specific test files:
+
+```bash
+pytest tests/test_desktop.py
+```
+
+Run with coverage:
+
+```bash
+pytest --cov=src tests/
+```
+
+### Adding Tests
+
+When adding new features:
+
+1. **Create test files** in the `tests/` directory matching the module structure
+2. **Write unit tests** for individual functions
+3. **Write integration tests** for tool workflows
+4. **Use fixtures** for common test setup
+5. **Mock external dependencies** (Windows API calls, file system operations)
+
+**Example Test:**
+
+```python
+import pytest
+from src.desktop.service import Desktop
+
+def test_click_tool_validates_coordinates():
+    """Test that click_tool raises ValueError for invalid coordinates."""
+    with pytest.raises(ValueError, match="exactly 2 integers"):
+        click_tool([100])  # Missing y coordinate
+```
+
+## Pull Requests
+
+### Before Submitting
+
+- [ ] Code follows the project's style guidelines
+- [ ] All tests pass (if applicable)
+- [ ] Documentation is updated (README, docstrings, etc.)
+- [ ] Commit messages are clear and descriptive
+- [ ] Changes are tested in a safe environment (VM recommended)
+- [ ] No sensitive information (API keys, passwords) is included
+
+### Pull Request Process
+
+1. **Update Your Branch**
+   
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+2. **Push to Your Fork**
+   
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+3. **Create Pull Request**
+   
+   - Go to the [Windows-MCP repository](https://github.com/CursorTouch/Windows-MCP)
+   - Click "New Pull Request"
+   - Select your fork and branch
+   - Fill out the PR template with:
+     - **Description**: What does this PR do?
+     - **Motivation**: Why is this change needed?
+     - **Testing**: How was this tested?
+     - **Screenshots**: If applicable (UI changes, new features)
+     - **Related Issues**: Link any related issues
+
+4. **Respond to Feedback**
+   
+   - Address reviewer comments promptly
+   - Make requested changes in new commits
+   - Push updates to the same branch
+
+### Review Process
+
+- Maintainers will review your PR within a few days
+- You may be asked to make changes or provide clarification
+- Once approved, a maintainer will merge your PR
+- Your contribution will be acknowledged in release notes
+
+## Documentation
+
+Good documentation is crucial! When contributing:
+
+### Code Documentation
+
+- **Docstrings**: Add to all public functions, classes, and methods
+- **Comments**: Explain complex logic or non-obvious decisions
+- **Type hints**: Help users and tools understand your code
+
+### User Documentation
+
+Update relevant documentation files:
+
+- **README.md**: For user-facing features or installation changes
+- **SECURITY.md**: For security-related changes
+- **CONTRIBUTING.md**: For development process changes
+
+### Tool Documentation
+
+When adding or modifying tools:
+
+1. Update the tool's `description` parameter in `main.py`
+2. Add appropriate `ToolAnnotations`
+3. Update the tools list in `README.md`
+4. Update `manifest.json` if needed
+
+## Reporting Issues
+
+Found a bug or have a feature request? Please open an issue!
+
+### Bug Reports
+
+Include:
+- **Description**: Clear description of the bug
+- **Steps to Reproduce**: Detailed steps to recreate the issue
+- **Expected Behavior**: What should happen
+- **Actual Behavior**: What actually happens
+- **Environment**: Windows version, Python version, MCP client
+- **Screenshots/Logs**: If applicable
+
+### Feature Requests
+
+Include:
+- **Description**: What feature do you want?
+- **Use Case**: Why is this feature needed?
+- **Proposed Solution**: How might this be implemented?
+- **Alternatives**: Other approaches you've considered
+
+## Security Vulnerabilities
+
+**DO NOT** report security vulnerabilities through public GitHub issues.
+
+Instead, please:
+1. Email the maintainers at [jeogeoalukka@gmail.com](mailto:jeogeoalukka@gmail.com)
+2. Or use [GitHub Security Advisories](https://github.com/CursorTouch/Windows-MCP/security/advisories)
+
+See our [Security Policy](SECURITY.md) for more details.
+
+## Getting Help
+
+Need help with your contribution?
+
+- **Discord**: Join our [Discord Community](https://discord.com/invite/Aue9Yj2VzS)
+- **Twitter/X**: Follow [@CursorTouch](https://x.com/CursorTouch)
+- **GitHub Discussions**: Ask questions in [Discussions](https://github.com/CursorTouch/Windows-MCP/discussions)
+- **Issues**: Open an issue for technical questions
+
+## Types of Contributions
+
+We welcome many types of contributions:
+
+### Code Contributions
+
+- **New Tools**: Add new MCP tools for Windows automation
+- **Bug Fixes**: Fix issues in existing tools
+- **Performance Improvements**: Optimize code for speed or efficiency
+- **Refactoring**: Improve code structure and maintainability
+
+### Non-Code Contributions
+
+- **Documentation**: Improve README, guides, or docstrings
+- **Testing**: Add test cases or improve test coverage
+- **Bug Reports**: Report issues with detailed information
+- **Feature Requests**: Suggest new features or improvements
+- **Community Support**: Help others in Discord or Discussions
+- **Translations**: Help translate documentation (future)
+
+## Recognition
+
+Contributors are recognized in:
+- GitHub contributors page
+- Release notes for significant contributions
+- Special mentions for major features or fixes
+
+## License
+
+By contributing to Windows-MCP, you agree that your contributions will be licensed under the [MIT License](LICENSE.md).
+
+---
+
+Thank you for contributing to Windows-MCP! Your efforts help make this project better for everyone. 🙏
+
+Made with ❤️ by the CursorTouch community

{windows_mcp-0.5.2 → windows_mcp-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: windows-mcp
-Version: 0.5.2
+Version: 0.5.3
 Summary: Lightweight MCP Server for interacting with Windows Operating System.
 Project-URL: homepage, https://github.com/CursorTouch
 Author-email: Jeomon George <jeogeoalukka@gmail.com>
@@ -44,7 +44,6 @@ Requires-Dist: python-levenshtein>=0.27.1
 Requires-Dist: pywinauto>=0.6.9
 Requires-Dist: requests>=2.32.3
 Requires-Dist: tabulate>=0.9.0
-Requires-Dist: twine>=6.2.0
 Requires-Dist: uiautomation>=2.0.24
 Description-Content-Type: text/markdown
 
@@ -114,6 +113,58 @@ mcp-name: io.github.CursorTouch/Windows-MCP
 - **Real-Time Interaction**  
   Typical latency between actions (e.g., from one mouse click to the next) ranges from **0.7 to 2.5 secs**, and may slightly vary based on the number of active applications and system load, also the inferencing speed of the llm.
 
+- **DOM Mode for Browser Automation**  
+  Special `use_dom=True` mode for State-Tool that focuses exclusively on web page content, filtering out browser UI elements for cleaner, more efficient web automation.
+
+## 🌐 DOM Mode for Browser Automation
+
+Windows-MCP includes a powerful **DOM Mode** feature that enhances browser automation by focusing on web page content rather than browser UI elements.
+
+### What is DOM Mode?
+
+When `use_dom=True` is set in the State-Tool, the MCP server:
+- **Filters out browser UI**: Removes address bars, tabs, toolbars, and other browser chrome elements
+- **Returns only web content**: Provides interactive elements (links, buttons, forms) from the actual web page
+- **Reduces token usage**: Cleaner output means fewer tokens sent to the LLM
+- **Improves accuracy**: LLM focuses only on relevant web page elements
+
+### When to Use DOM Mode
+
+✅ **Use `use_dom=True` when:**
+- Automating web applications or websites
+- Scraping web content
+- Filling out web forms
+- Clicking links or buttons on web pages
+- Testing web interfaces
+- You want to ignore browser UI and focus on page content
+
+❌ **Use `use_dom=False` (default) when:**
+- Interacting with browser controls (address bar, tabs, bookmarks)
+- Working with desktop applications
+- Need to see all UI elements including browser chrome
+- Managing browser settings or extensions
+
+### Example Usage
+
+```python
+# Get web page content only (no browser UI)
+state_tool(use_vision=False, use_dom=True)
+
+# Get full desktop state including browser UI
+state_tool(use_vision=False, use_dom=False)
+
+# Get web page content with screenshot
+state_tool(use_vision=True, use_dom=True)
+```
+
+### Benefits
+
+1. **Token Efficiency**: Reduces the amount of data sent to LLM by filtering irrelevant browser UI
+2. **Better Focus**: LLM concentrates on actionable web page elements
+3. **Cleaner Output**: Only relevant interactive elements from the DOM are returned
+4. **Faster Processing**: Less data means faster LLM inference
+5. **Cost Savings**: Fewer tokens = lower API costs for cloud LLMs
+
 ## 🛠️Installation
 
 ### Prerequisites
@@ -317,7 +368,7 @@ MCP Client can access the following tools to interact with Windows:
 - `Move-Tool`: Move mouse pointer.
 - `Shortcut-Tool`: Press keyboard shortcuts (`Ctrl+c`, `Alt+Tab`, etc).
 - `Wait-Tool`: Pause for a defined duration.
-- `State-Tool`: Combined snapshot of default language, browser, active apps and interactive, textual and scrollable elements along with screenshot of the desktop..
+- `State-Tool`: Combined snapshot of default language, browser, active apps and interactive, textual and scrollable elements along with screenshot of the desktop. Supports `use_dom=True` for browser content extraction (web page elements only) and `use_vision=True` for including screenshots.
 - `App-Tool`: To launch an application from the start menu, resize or move the window and switch between apps.
 - `Shell-Tool`: To execute PowerShell commands.
 - `Scrape-Tool`: To scrape the entire webpage for information.

{windows_mcp-0.5.2 → windows_mcp-0.5.3}/README.md

@@ -64,6 +64,58 @@ mcp-name: io.github.CursorTouch/Windows-MCP
 - **Real-Time Interaction**  
   Typical latency between actions (e.g., from one mouse click to the next) ranges from **0.7 to 2.5 secs**, and may slightly vary based on the number of active applications and system load, also the inferencing speed of the llm.
 
+- **DOM Mode for Browser Automation**  
+  Special `use_dom=True` mode for State-Tool that focuses exclusively on web page content, filtering out browser UI elements for cleaner, more efficient web automation.
+
+## 🌐 DOM Mode for Browser Automation
+
+Windows-MCP includes a powerful **DOM Mode** feature that enhances browser automation by focusing on web page content rather than browser UI elements.
+
+### What is DOM Mode?
+
+When `use_dom=True` is set in the State-Tool, the MCP server:
+- **Filters out browser UI**: Removes address bars, tabs, toolbars, and other browser chrome elements
+- **Returns only web content**: Provides interactive elements (links, buttons, forms) from the actual web page
+- **Reduces token usage**: Cleaner output means fewer tokens sent to the LLM
+- **Improves accuracy**: LLM focuses only on relevant web page elements
+
+### When to Use DOM Mode
+
+✅ **Use `use_dom=True` when:**
+- Automating web applications or websites
+- Scraping web content
+- Filling out web forms
+- Clicking links or buttons on web pages
+- Testing web interfaces
+- You want to ignore browser UI and focus on page content
+
+❌ **Use `use_dom=False` (default) when:**
+- Interacting with browser controls (address bar, tabs, bookmarks)
+- Working with desktop applications
+- Need to see all UI elements including browser chrome
+- Managing browser settings or extensions
+
+### Example Usage
+
+```python
+# Get web page content only (no browser UI)
+state_tool(use_vision=False, use_dom=True)
+
+# Get full desktop state including browser UI
+state_tool(use_vision=False, use_dom=False)
+
+# Get web page content with screenshot
+state_tool(use_vision=True, use_dom=True)
+```
+
+### Benefits
+
+1. **Token Efficiency**: Reduces the amount of data sent to LLM by filtering irrelevant browser UI
+2. **Better Focus**: LLM concentrates on actionable web page elements
+3. **Cleaner Output**: Only relevant interactive elements from the DOM are returned
+4. **Faster Processing**: Less data means faster LLM inference
+5. **Cost Savings**: Fewer tokens = lower API costs for cloud LLMs
+
 ## 🛠️Installation
 
 ### Prerequisites
@@ -267,7 +319,7 @@ MCP Client can access the following tools to interact with Windows:
 - `Move-Tool`: Move mouse pointer.
 - `Shortcut-Tool`: Press keyboard shortcuts (`Ctrl+c`, `Alt+Tab`, etc).
 - `Wait-Tool`: Pause for a defined duration.
-- `State-Tool`: Combined snapshot of default language, browser, active apps and interactive, textual and scrollable elements along with screenshot of the desktop..
+- `State-Tool`: Combined snapshot of default language, browser, active apps and interactive, textual and scrollable elements along with screenshot of the desktop. Supports `use_dom=True` for browser content extraction (web page elements only) and `use_vision=True` for including screenshots.
 - `App-Tool`: To launch an application from the start menu, resize or move the window and switch between apps.
 - `Shell-Tool`: To execute PowerShell commands.
 - `Scrape-Tool`: To scrape the entire webpage for information.