# 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