pyResToolbox MCP Server

# Contributing to pyResToolbox MCP Server Thank you for your interest in contributing to the pyResToolbox MCP Server! ## Code of Conduct This project adheres to the principles of open source collaboration. Please be respectful and constructive in all interactions. ## How to Contribute ### Reporting Bugs 1. Check if the bug is already reported in [Issues](../../issues) 2. If not, create a new issue with: - Clear description of the problem - Steps to reproduce - Expected vs actual behavior - Environment details (OS, Python version, UV version) ### Suggesting Enhancements 1. Check existing issues and discussions 2. Create an issue describing: - The enhancement and its benefits - Use cases - Potential implementation approach ### Pull Requests 1. **Fork the repository** 2. **Create a feature branch** (`git checkout -b feature/amazing-feature`) 3. **Make your changes** 4. **Test thoroughly:** ```bash uv run python test_tools.py # All 47 tools must pass uv run python test_server.py uv run python examples/basic_usage.py ``` 5. **Follow code style:** ```bash uv run black src/ tests/ uv run ruff check src/ tests/ ``` 6. **Commit your changes** (`git commit -m 'Add amazing feature'`) 7. **Push to the branch** (`git push origin feature/amazing-feature`) 8. **Open a Pull Request** ## Development Setup ```bash # Clone your fork git clone https://github.com/YOUR_USERNAME/pyrestoolbox-mcp.git cd pyrestoolbox-mcp # Install UV curl -LsSf https://astral.sh/uv/install.sh | sh # Setup project make uv-install # Run tests uv run python test_tools.py uv run pytest ``` ## Code Guidelines ### Python Style - Use type hints for all function parameters and return values - Follow PEP 8 style guide - Use Black for code formatting - Use Ruff for linting ### Docstrings - Use Google-style docstrings - Include parameter descriptions - Provide usage examples - Document return values ### Testing - Write tests for all new tools - Ensure existing tests pass - Add to `test_tools.py` for integration testing ## Adding New Tools 1. **Define Pydantic model** in `src/pyrestoolbox_mcp/models/` 2. **Implement tool function** in appropriate `src/pyrestoolbox_mcp/tools/` file 3. **Register tool** in the register function 4. **Add tests** in `test_tools.py` 5. **Update documentation** in README.md Example: ```python # In models/oil_models.py class NewCalculationRequest(BaseModel): param1: float = Field(..., description="Parameter 1") param2: float = Field(..., description="Parameter 2") # In tools/oil_tools.py @mcp.tool() def new_calculation(request: NewCalculationRequest) -> dict: \"\"\"Calculate something new.\"\"\" result = oil.some_function( param1=request.param1, param2=request.param2, ) return { "value": float(result), "method": "Method name", "units": "units", "inputs": request.model_dump(), } # In test_tools.py ("new_calculation", {"request": {"param1": 1.0, "param2": 2.0}}), ``` ## License By contributing, you agree that your contributions will be licensed under the GNU General Public License v3.0 (GPL-3.0), the same license as the original [pyResToolbox](https://github.com/mwburgoyne/pyResToolbox) library. ## Questions? Feel free to open an issue for any questions about contributing! ## Acknowledgments This project builds on the excellent [pyResToolbox](https://github.com/mwburgoyne/pyResToolbox) library by Mark Burgoyne. Please also consider contributing to the upstream project!