Local Utilities MCP Server

# Contributing to Local Utilities MCP Server Thank you for your interest in contributing to the Local Utilities MCP Server! We welcome contributions from the community. ## 📋 Table of Contents - [Code of Conduct](#code-of-conduct) - [Getting Started](#getting-started) - [How to Contribute](#how-to-contribute) - [Development Setup](#development-setup) - [Adding New Tools](#adding-new-tools) - [Testing](#testing) - [Pull Request Process](#pull-request-process) - [Coding Standards](#coding-standards) ## Code of Conduct This project follows a simple code of conduct: - Be respectful and inclusive - Focus on constructive feedback - Help create a welcoming environment for all contributors ## Getting Started 1. **Fork the repository** on GitHub 2. **Clone your fork** locally: ```bash git clone https://github.com/aiforhumans/local-utils-mcp.git cd local-utils-mcp ``` 3. **Set up the development environment** (see Development Setup below) ## How to Contribute ### 🐛 Reporting Bugs - Use the GitHub issue tracker - Include a clear title and description - Provide steps to reproduce the issue - Include your Python version and OS information ### 💡 Suggesting Features - Use the GitHub issue tracker with the "enhancement" label - Describe the feature and its use case - Explain why it would be valuable to other users ### 🔧 Code Contributions We welcome contributions such as: - Bug fixes - New utility tools - Performance improvements - Documentation improvements - Test coverage improvements ## Development Setup 1. **Create a virtual environment:** ```bash python -m venv .venv source .venv/bin/activate # Linux/Mac .venv\Scripts\activate # Windows ``` 2. **Install dependencies:** ```bash pip install -r requirements.txt ``` 3. **Verify the setup:** ```bash python test.py ``` ## Adding New Tools To add a new tool to the MCP server: ### 1. Create the Tool Function Add your function to `server.py`: ```python @mcp.tool( description="Brief description of what your tool does" ) async def your_tool_name(param1: str, param2: int = 10) -> str: """ Detailed docstring explaining the tool. Args: param1: Description of the first parameter param2: Description of the second parameter with default value Returns: String describing the result or error message Raises: ValueError: When invalid parameters are provided """ try: # Input validation if not param1: return "Error: param1 cannot be empty" if param2 < 1: return "Error: param2 must be positive" # Your tool logic here result = f"Processed '{param1}' with value {param2}" return f"Success: {result}" except Exception as e: return f"Error: {str(e)}" ``` ### 2. Follow Best Practices - **Clear descriptions**: Write concise but informative tool descriptions - **Input validation**: Always validate input parameters - **Error handling**: Use try-catch blocks and return meaningful error messages - **Type hints**: Use proper type hints for parameters and return values - **Documentation**: Include detailed docstrings - **Consistent naming**: Use descriptive, snake_case function names ### 3. Update Documentation - Add your tool to the README.md API reference section - Include usage examples - Update the tool count in relevant documentation ### 4. Add Tests Add test cases to `test.py` or create a separate test file: ```python def test_your_tool(): """Test the new tool functionality.""" # Test normal operation result = your_tool_logic("test", 5) assert "Success" in result # Test error cases result = your_tool_logic("", 5) assert "Error" in result ``` ## Testing ### Running Tests ```bash # Run the main test suite python test.py # Run specific tests (if using pytest) pytest test_your_tool.py -v ``` ### Test Requirements - All new tools must include tests - Tests should cover both success and error cases - Aim for high test coverage - Tests should be fast and reliable ## Pull Request Process 1. **Create a feature branch:** ```bash git checkout -b feature/your-feature-name ``` 2. **Make your changes** following the coding standards 3. **Test your changes:** ```bash python test.py ``` 4. **Commit your changes:** ```bash git add . git commit -m "Add feature: brief description" ``` 5. **Push to your fork:** ```bash git push origin feature/your-feature-name ``` 6. **Create a Pull Request** on GitHub with: - Clear title and description - Reference any related issues - Include screenshots if relevant - List any breaking changes ### Pull Request Guidelines - Keep PRs focused and atomic (one feature/fix per PR) - Include tests for new functionality - Update documentation as needed - Ensure all tests pass - Follow the existing code style ## Coding Standards ### Python Style - Follow PEP 8 style guidelines - Use 4 spaces for indentation - Maximum line length of 88 characters - Use descriptive variable and function names ### MCP Tool Standards - **Async functions**: All tools must be async functions - **Return strings**: Tools should return string results - **Error messages**: Start error messages with "Error: " - **Success messages**: Provide clear success feedback - **Parameter validation**: Validate all input parameters ### Documentation Standards - **Docstrings**: Use Google-style docstrings - **Type hints**: Include type hints for all parameters - **Comments**: Add comments for complex logic - **Examples**: Include usage examples in docstrings ## Questions? If you have questions about contributing, please: - Check the existing issues and documentation - Open a new issue with the "question" label - Reach out to the maintainers Thank you for contributing to make this MCP server better for everyone! 🎉