Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
executable file
·
384 lines (271 loc) · 10.4 KB

CONTRIBUTING.md

File metadata and controls

executable file
·
384 lines (271 loc) · 10.4 KB

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

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:

Development Environment Setup

  1. Fork the Repository

    Click the "Fork" button on the Windows-MCP repository to create your own copy.

  2. Clone Your Fork

    git clone https://github.com/YOUR_USERNAME/Windows-MCP.git
cd Windows-MCP

  3. Add Upstream Remote

    git remote add upstream https://github.com/CursorTouch/Windows-MCP.git

  4. Install Dependencies

    uv sync

  5. Verify Installation

    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

    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

    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 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:

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:

ruff format .

Run Linter:

ruff check .

Testing

Running Tests

If the project has tests (check the tests/ directory):

pytest

Run specific test files:

pytest tests/test_desktop.py

Run with coverage:

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:

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

    git fetch upstream
git rebase upstream/main

  2. Push to Your Fork

    git push origin feature/your-feature-name

  3. Create Pull Request

    • Go to the Windows-MCP repository
    • 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
  2. Or use GitHub Security Advisories

See our Security Policy for more details.

Getting Help

Need help with your contribution?

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.

Thank you for contributing to Windows-MCP! Your efforts help make this project better for everyone. 🙏

Made with ❤️ by the CursorTouch community