Gradle MCP Server

# Code Style and Conventions ## Python Version - Minimum Python 3.10 required - Uses modern Python features (type hints, walrus operator, etc.) ## Formatting - **Black** for code formatting - Line length: 100 characters - Target version: py310 ## Linting - **Ruff** for linting - Enabled rules: - E (pycodestyle errors) - W (pycodestyle warnings) - F (pyflakes) - I (isort - import sorting) - B (flake8-bugbear) - C4 (flake8-comprehensions) - UP (pyupgrade) - Line too long (E501) ignored (handled by Black) ## Type Hints - **mypy** for type checking (strict mode) - All function definitions must have type hints - `disallow_untyped_defs = true` - `disallow_incomplete_defs = true` - Use `Optional[T]` for nullable types - Use `list[T]` instead of `List[T]` (Python 3.10+) ## Docstrings - Google-style docstrings - Required for all public functions, methods, and classes - Include: - Brief description - Args section with parameter descriptions - Returns section with return value description - Raises section for exceptions Example: ```python def example_function(param1: str, param2: int | None = None) -> dict: """Brief description of function. Args: param1: Description of param1. param2: Description of param2. Defaults to None. Returns: Dictionary with result keys. Raises: ValueError: If param1 is invalid. """ ``` ## Naming Conventions - **Classes**: PascalCase (e.g., `GradleWrapper`, `GradleProject`) - **Functions/Methods**: snake_case (e.g., `list_projects`, `run_task`) - **Constants**: UPPER_SNAKE_CASE (e.g., `SAFE_GRADLE_ARGS`) - **Private methods**: Leading underscore (e.g., `_is_cleaning_task`) - **Variables**: snake_case ## Async/Await - Async functions used for I/O operations - `asyncio.sleep()` for non-blocking waits - FastMCP context used for progress reporting ## Imports - Standard library imports first - Third-party imports second - Local imports last - Sorted alphabetically within groups (enforced by ruff) ## Error Handling - Use specific exception types - Provide descriptive error messages - Wrap low-level exceptions in domain-specific ones ## Testing - pytest with pytest-asyncio - Test classes prefixed with `Test` - Test methods prefixed with `test_` - Use descriptive test names explaining what is being tested - Docstrings for test methods explaining the test purpose