SearXNG MCP Server

# Contributing to SearXNG MCP Server Thank you for your interest in contributing to SearXNG MCP Server! This document provides guidelines and instructions for contributing. ## Code of Conduct By participating in this project, you agree to maintain a respectful and inclusive environment for everyone. ## How to Contribute ### Reporting Bugs Before creating a bug report, please check existing issues to avoid duplicates. When creating a bug report, include: - A clear and descriptive title - Steps to reproduce the behavior - Expected behavior - Actual behavior - SearXNG instance details (version, configuration) - Python version and environment details - Any relevant logs or error messages ### Suggesting Enhancements Enhancement suggestions are welcome! Please provide: - A clear and descriptive title - Detailed description of the proposed feature - Use cases and examples - Any relevant code or mockups ### Pull Requests 1. Fork the repository 2. Create a new branch from `main`: ```bash git checkout -b feature/your-feature-name ``` 3. Make your changes following the coding standards 4. Add or update tests as needed 5. Update documentation if required 6. Ensure all tests pass 7. Commit your changes with clear messages 8. Push to your fork 9. Submit a pull request ## Development Setup ### Prerequisites - Python 3.10 or higher - Git - A SearXNG instance (local or remote) ### Setup Instructions 1. Clone your fork: ```bash git clone https://github.com/YOUR_USERNAME/searxng-mcp-server.git cd searxng-mcp-server ``` 2. Create a virtual environment: ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. Install development dependencies: ```bash pip install -e ".[dev]" ``` 4. Set up environment variables: ```bash cp examples/.env.example .env # Edit .env with your SearXNG instance URL ``` ## Coding Standards ### Style Guide This project follows: - PEP 8 style guide - Black for code formatting (line length: 100) - Ruff for linting - Type hints for all functions - Docstrings for all public functions and classes ### Running Code Quality Tools ```bash # Format code with Black black src tests # Lint with Ruff ruff check src tests # Type check with mypy mypy src # Run all quality checks black src tests && ruff check src tests && mypy src ``` ### Writing Tests - Write tests for all new features - Maintain or improve code coverage - Use pytest for testing - Use async fixtures for async code - Mock external HTTP calls Example test structure: ```python import pytest from unittest.mock import AsyncMock, patch class TestYourFeature: @pytest.mark.asyncio async def test_your_function(self): # Arrange # Act # Assert pass ``` ### Running Tests ```bash # Run all tests pytest # Run with coverage pytest --cov=searxng_mcp_server --cov-report=html # Run specific test file pytest tests/test_client.py # Run specific test pytest tests/test_client.py::TestSearXNGClient::test_search_success ``` ## Documentation ### Updating Documentation - Keep README.md up to date - Update CHANGELOG.md for all changes - Add docstrings to new functions/classes - Update examples if adding new features - Include type hints in all function signatures ### Documentation Style ```python def function_name(param1: str, param2: int) -> bool: """Brief description of the function. Longer description if needed, explaining the function's purpose and behavior in detail. Args: param1: Description of param1 param2: Description of param2 Returns: Description of return value Raises: ExceptionType: When and why this exception is raised """ pass ``` ## Commit Messages Follow conventional commit format: ``` type(scope): subject body footer ``` Types: - `feat`: New feature - `fix`: Bug fix - `docs`: Documentation changes - `style`: Code style changes (formatting, etc.) - `refactor`: Code refactoring - `test`: Adding or updating tests - `chore`: Maintenance tasks Examples: ``` feat(search): add support for video category filtering fix(client): handle connection timeout errors gracefully docs(readme): update installation instructions for Windows ``` ## Release Process 1. Update version in `pyproject.toml` 2. Update `CHANGELOG.md` with changes 3. Create a git tag: `git tag -a v0.x.0 -m "Release v0.x.0"` 4. Push the tag: `git push origin v0.x.0` 5. Create a GitHub release ## Project Structure ``` searxng-mcp-server/ ├── src/ │ └── searxng_mcp_server/ │ ├── __init__.py # Package initialization │ ├── server.py # MCP server implementation │ └── client.py # SearXNG API client ├── tests/ │ ├── __init__.py │ ├── test_server.py │ └── test_client.py ├── examples/ # Configuration examples ├── docs/ # Additional documentation ├── pyproject.toml # Project configuration ├── README.md # Main documentation ├── CHANGELOG.md # Version history └── CONTRIBUTING.md # This file ``` ## Getting Help - Check existing [issues](https://github.com/martinchen448/searxng-mcp-server/issues) - Review [documentation](https://github.com/martinchen448/searxng-mcp-server/wiki) - Ask questions in [discussions](https://github.com/martinchen448/searxng-mcp-server/discussions) ## Recognition Contributors will be recognized in: - README.md contributors section - Release notes - CHANGELOG.md Thank you for contributing to SearXNG MCP Server!