Contributing Guide¶

Help Improve RivalSearchMCP

We welcome contributions from the community! This guide explains how to contribute to RivalSearchMCP, whether it's fixing bugs, adding features, or improving documentation.

How to Contribute¶

Types of Contributions¶

Bug fixes - Fix issues and improve reliability
New features - Add new search engines or tools
Documentation - Improve guides and examples
Testing - Add tests and improve coverage
Performance - Optimize speed and efficiency

Before You Start¶

Check existing issues to see what needs work
Read the API Reference to understand the codebase
Set up your development environment using the Installation Guide

Development Workflow¶

1. Fork and Clone¶

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/RivalSearchMCP.git
cd RivalSearchMCP

2. Create a Branch¶

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

3. Make Changes¶

Follow the coding standards (see below)
Write tests for new functionality
Update documentation if needed

4. Test Your Changes¶

# Run the test suite
python -m pytest

# Check code quality
black src/
isort src/
flake8 src/
pylint src/

5. Commit and Push¶

git add .
git commit -m "Add feature: description of your changes"
git push origin feature/your-feature-name

6. Create a Pull Request¶

Describe your changes clearly
Link related issues if applicable
Include test results if you added tests

Coding Standards¶

Python Style¶

Follow PEP 8 for code style
Use type hints for function parameters and returns
Write docstrings for all public functions and classes
Keep functions focused and under 50 lines when possible

Code Quality¶

Use meaningful variable names
Add comments for complex logic
Handle errors gracefully with proper exception handling
Write tests for new functionality

Example Code¶

from typing import List, Optional
from pydantic import BaseModel

class SearchResult(BaseModel):
    """Represents a single search result."""

    title: str
    url: str
    snippet: str
    source: str

    def get_display_title(self) -> str:
        """Return a formatted title for display."""
        return f"{self.title} - {self.source}"

async def search_web(query: str, num_results: int = 10) -> List[SearchResult]:
    """
    Search the web for the given query.

    Args:
        query: The search query string
        num_results: Maximum number of results to return

    Returns:
        List of search results

    Raises:
        SearchError: If the search fails
    """
    # Implementation here
    pass

Testing¶

Writing Tests¶

Test all new functionality
Use descriptive test names
Test both success and failure cases
Mock external dependencies

Test Structure¶

import pytest
from src.core.search import GoogleSearchEngine

class TestGoogleSearchEngine:
    """Test the Google search engine functionality."""

    @pytest.fixture
    def search_engine(self):
        """Create a search engine instance for testing."""
        return GoogleSearchEngine()

    async def test_search_returns_results(self, search_engine):
        """Test that search returns results for valid queries."""
        results = await search_engine.search("test query")
        assert len(results) > 0
        assert all(hasattr(r, 'title') for r in results)

    async def test_search_handles_empty_query(self, search_engine):
        """Test that search handles empty queries gracefully."""
        with pytest.raises(ValueError):
            await search_engine.search("")

Running Tests¶

# Run all tests
python -m pytest

# Run specific test file
python -m pytest tests/test_search.py

# Run with coverage
python -m pytest --cov=src

# Run only fast tests
python -m pytest -m "not slow"

Documentation¶

Updating Documentation¶

Keep documentation current with code changes
Add examples for new features
Update installation instructions if needed
Check links work correctly

Documentation Standards¶

Use clear, simple language
Include code examples
Add screenshots for UI changes
Test all code examples

Pull Request Guidelines¶

What to Include¶

Clear description of changes
Screenshots for UI changes
Test results showing everything passes
Related issue numbers if applicable

Review Process¶

Automated checks must pass
Code review by maintainers
Tests must pass on all platforms
Documentation updated if needed

Common Issues¶

Missing tests for new functionality
Code style violations (use black/isort)
Broken documentation links
Missing type hints

Getting Help¶

Questions and Discussion¶

GitHub Discussions for general questions
GitHub Issues for bug reports
Pull Request comments for specific feedback

Resources¶

API Reference for code understanding
Installation Guide for setup help
Examples for usage patterns
FastMCP Documentation for framework details

Recognition¶

Contributors¶

All contributors are listed in the README
Significant contributions get special recognition
Regular contributors may become maintainers

How to Get Recognition¶

Make quality contributions
Help other contributors
Improve documentation
Report and fix bugs

Next Steps¶

Set up your environment using the Installation Guide
Read the API Reference to understand the code
Find an issue to work on
Join the discussion in GitHub Discussions

Thank you for contributing to RivalSearchMCP!