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

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

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

windows_mcp-0.5.4/.python-version

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

windows_mcp-0.5.4/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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: windows-mcp
-Version: 0.5.2
+Version: 0.5.4
 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
 
@@ -76,7 +75,7 @@ Description-Content-Type: text/markdown
 mcp-name: io.github.CursorTouch/Windows-MCP
 
 ## Updates
-
+- Windows-MCP is now available on [PyPI](https://pypi.org/project/windows-mcp/) (thus supports `uvx`)
 - Windows-MCP is added to [MCP Registry](https://github.com/modelcontextprotocol/registry)
 - Try out 🪟[Windows-Use](https://github.com/CursorTouch/Windows-Use)!!, an agent built using Windows-MCP.
 - Windows-MCP is now featured as Desktop Extension in `Claude Desktop`.
@@ -114,6 +113,9 @@ 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.
+
 ## 🛠️Installation
 
 ### Prerequisites
@@ -131,23 +133,56 @@ mcp-name: io.github.CursorTouch/Windows-MCP
 npm install -g @anthropic-ai/mcpb
 ```
 
-  2. Clone the repository.
 
-```shell
-git clone https://github.com/CursorTouch/Windows-MCP.git
+  2. Configure the extension:
 
-cd Windows-MCP
-```
+  **Option A: Install from PyPI (Recommended)**
+  
+  Use `uvx` to run the latest version directly from PyPI.
+
+  Add this to your `claude_desktop_config.json`:
+  ```json
+  {
+    "mcpServers": {
+      "windows-mcp": {
+        "command": "uvx",
+        "args": [
+          "windows-mcp"
+        ]
+      }
+    }
+  }
+  ```
+
+  **Option B: Install from Source**
+
+  1. Clone the repository:
+  ```shell
+  git clone https://github.com/CursorTouch/Windows-MCP.git
+  cd Windows-MCP
+  ```
+
+  2. Add this to your `claude_desktop_config.json`:
+  ```json
+  {
+    "mcpServers": {
+      "windows-mcp": {
+        "command": "uv",
+        "args": [
+          "--directory",
+          "<path to the windows-mcp directory>",
+          "run",
+          "windows-mcp"
+        ]
+      }
+    }
+  }
+  ```
 
-  3. Build Desktop Extension `MCPB`:
 
-```shell
-npx @anthropic-ai/mcpb pack
-```
 
-  4. Open Claude Desktop:
+  3. Open Claude Desktop and enjoy! 🥳
 
-Go to `Settings->Extensions->Advance Settings->Install Extension` (locate the `.mcpb` file)-> Install
 
   5. Enjoy 🥳.
 
@@ -173,17 +208,32 @@ Go to `Settings->Connectors->Add Connector->Advanced`
 
   4. Enter the name as `Windows-MCP`, then paste the following JSON in the text area.
 
-```json
-{
-  "command": "uv",
-  "args": [
-    "--directory",
-    "<path to the windows-mcp directory>",
-    "run",
-    "main.py"
-  ]
-}
-```
+
+  **Option A: Install from PyPI (Recommended)**
+
+  ```json
+  {
+    "command": "uvx",
+    "args": [
+      "windows-mcp"
+    ]
+  }
+  ```
+
+  **Option B: Install from Source**
+
+  ```json
+  {
+    "command": "uv",
+    "args": [
+      "--directory",
+      "<path to the windows-mcp directory>",
+      "run",
+      "windows-mcp"
+    ]
+  }
+  ```
+
 
 5. Click `Save` and Enjoy 🥳.
 
@@ -199,13 +249,9 @@ For additional Claude Desktop integration troubleshooting, see the [Perplexity M
 npm install -g @google/gemini-cli
 ```
 
-  2. Clone the repository.
 
-```shell
-git clone https://github.com/CursorTouch/Windows-MCP.git
+  2. Configure the server in `%USERPROFILE%/.gemini/settings.json`:
 
-cd Windows-MCP
-```
 
   3. Navigate to `%USERPROFILE%/.gemini` in File Explorer and open `settings.json`.
 
@@ -218,17 +264,16 @@ cd Windows-MCP
 //MCP Server Config
   "mcpServers": {
     "windows-mcp": {
-      "command": "uv",
+      "command": "uvx",
       "args": [
-        "--directory",
-        "<path to the windows-mcp directory>",
-        "run",
-        "main.py"
+        "windows-mcp"
       ]
     }
   }
 }
 ```
+*Note: To run from source, replace the command with `uv` and args with `["--directory", "<path>", "run", "windows-mcp"]`.*
+
 
   5. Rerun Gemini CLI in terminal. Enjoy 🥳
 </details>
@@ -240,13 +285,9 @@ cd Windows-MCP
 ```shell
 npm install -g @qwen-code/qwen-code@latest
 ```
-  2. Clone the repository.
 
-```shell
-git clone https://github.com/CursorTouch/Windows-MCP.git
+   2. Configure the server in `%USERPROFILE%/.qwen/settings.json`:
 
-cd Windows-MCP
-```
 
   3. Navigate to `%USERPROFILE%/.qwen/settings.json`.
 
@@ -257,17 +298,16 @@ cd Windows-MCP
 //MCP Server Config
   "mcpServers": {
     "windows-mcp": {
-      "command": "uv",
+      "command": "uvx",
       "args": [
-        "--directory",
-        "<path to the windows-mcp directory>",
-        "run",
-        "main.py"
+        "windows-mcp"
       ]
     }
   }
 }
 ```
+*Note: To run from source, replace the command with `uv` and args with `["--directory", "<path>", "run", "windows-mcp"]`.*
+
 
   5. Rerun Qwen Code in terminal. Enjoy 🥳
 </details>
@@ -279,27 +319,22 @@ cd Windows-MCP
 ```shell
 npm install -g @openai/codex
 ```
-  2. Clone the repository.
 
-```shell
-git clone https://github.com/CursorTouch/Windows-MCP.git
+  2. Configure the server in `%USERPROFILE%/.codex/config.toml`:
 
-cd Windows-MCP
-```
   3. Navigate to `%USERPROFILE%/.codex/config.toml`.
 
   4. Add the `windows-mcp` config in the `config.toml` and save it.
 
 ```toml
 [mcp_servers.windows-mcp]
-command="uv"
+command="uvx"
 args=[
-  "--directory",
-  "<path to the windows-mcp directory>",
-  "run",
-  "main.py"
+  "windows-mcp"
 ]
 ```
+*Note: To run from source, replace the command with `uv` and args with `["--directory", "<path>", "run", "windows-mcp"]`.*
+
 
   5. Rerun Codex CLI in terminal. Enjoy 🥳
 </details>
@@ -317,7 +352,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.