my-pal-mcp-server/CONTRIBUTING.md

Contributing to Gemini MCP Server

Thank you for your interest in contributing! This guide explains how to set up the development environment and contribute to the project.

Development Setup

1. Clone the repository

   git clone https://github.com/BeehiveInnovations/gemini-mcp-server.git
   cd gemini-mcp-server
   

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

Testing Strategy

Two Types of Tests

1. Unit Tests (Mandatory - No API Key Required)

• Location: tests/test_*.py (except test_live_integration.py)
• Purpose: Test logic, mocking, and functionality without API calls
• Run with: python -m pytest tests/ --ignore=tests/test_live_integration.py -v
• GitHub Actions: ✅ Always runs
• Coverage: Measures code coverage

2. Live Integration Tests (Optional - API Key Required)

• Location: tests/test_live_integration.py
• Purpose: Verify actual API integration works
• Run with: python tests/test_live_integration.py (requires GEMINI_API_KEY)
• GitHub Actions: 🔒 Only runs if GEMINI_API_KEY secret is set

Running Tests

# Run all unit tests (CI-friendly, no API key needed)
python -m pytest tests/ --ignore=tests/test_live_integration.py -v

# Run with coverage
python -m pytest tests/ --ignore=tests/test_live_integration.py --cov=. --cov-report=html

# Run live integration tests (requires API key)
export GEMINI_API_KEY=your-api-key-here
python tests/test_live_integration.py

Code Quality

Formatting and Linting

# Install development tools
pip install black ruff

# Format code
black .

# Lint code
ruff check .

Pre-commit Checks

Before submitting a PR, ensure:

• All unit tests pass: python -m pytest tests/ --ignore=tests/test_live_integration.py -v
• Code is formatted: black --check .
• Code passes linting: ruff check .
• Live tests work (if you have API access): python tests/test_live_integration.py

Adding New Features

Adding a New Tool

1. Create tool file: tools/your_tool.py
2. Inherit from BaseTool: Implement all required methods
3. Add system prompt: Include prompt in prompts/tool_prompts.py
4. Register tool: Add to TOOLS dict in server.py
5. Write tests: Add unit tests that use mocks
6. Test live: Verify with live API calls

Testing New Tools

# Unit test example (tools/test_your_tool.py)
@pytest.mark.asyncio
@patch("tools.base.BaseTool.create_model")
async def test_your_tool(self, mock_create_model):
    mock_model = Mock()
    mock_model.generate_content.return_value = Mock(
        candidates=[Mock(content=Mock(parts=[Mock(text="Expected response")]))]
    )
    mock_create_model.return_value = mock_model
    
    tool = YourTool()
    result = await tool.execute({"param": "value"})
    
    assert len(result) == 1
    assert "Expected response" in result[0].text

CI/CD Pipeline

The GitHub Actions workflow:

1. Unit Tests: Run on all Python versions (3.10, 3.11, 3.12)
2. Linting: Check code formatting and style
3. Live Tests: Only run if GEMINI_API_KEY secret is available

Key Features:

• ✅ No API key required for PRs - All contributors can run tests
• 🔒 Live verification available - Maintainers can verify API integration
• 📊 Coverage reporting - Track test coverage
• 🐍 Multi-Python support - Ensure compatibility

Contribution Guidelines

Pull Request Process

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Add/update tests
5. Run tests locally: Ensure unit tests pass
6. Choose appropriate PR title prefix (see below)
7. Submit PR: Include description of changes

PR Title Prefixes and Automation

The project uses automated versioning and Docker builds based on PR title prefixes:

Version Bumping Prefixes (trigger version bump + Docker build):

• feat: <description> - New features → MINOR version bump (1.X.0)
• fix: <description> - Bug fixes → PATCH version bump (1.0.X)
• breaking: <description> - Breaking changes → MAJOR version bump (X.0.0)
• perf: <description> - Performance improvements → PATCH version bump
• refactor: <description> - Code refactoring → PATCH version bump

Non-Version Prefixes (no version bump):

• docs: <description> - Documentation only
• chore: <description> - Maintenance tasks
• test: <description> - Test additions/changes
• ci: <description> - CI/CD changes
• style: <description> - Code style changes

Docker Build Options:

For contributors who want to test Docker builds without version bumps:

• docker: <description> - Force Docker build only
• docs+docker: <description> - Documentation + Docker build
• chore+docker: <description> - Maintenance + Docker build
• test+docker: <description> - Tests + Docker build
• ci+docker: <description> - CI changes + Docker build
• style+docker: <description> - Style changes + Docker build

What Happens When PR is Merged:

For version bumping prefixes:

1. Version in config.py is automatically updated
2. Git tag is created (e.g., v1.2.0)
3. GitHub release is published
4. Docker image is built and pushed to GHCR with version tag

For Docker build prefixes:

1. Docker image is built and pushed to GHCR
2. Image tagged with pr-{number} and main-{commit-sha}
3. No version bump or release created

For standard non-version prefixes:

1. Changes are merged without automation
2. No version bump, Docker build, or release

Code Standards

• Follow existing patterns: Look at existing tools for examples
• Add comprehensive tests: Both unit tests (required) and live tests (recommended)
• Update documentation: Update README if adding new features
• Use type hints: All new code should include proper type annotations
• Keep it simple: Follow SOLID principles and keep functions focused

Security Considerations

• Never commit API keys: Use environment variables
• Validate inputs: Always validate user inputs in tools
• Handle errors gracefully: Provide meaningful error messages
• Follow security best practices: Sanitize file paths, validate file access

Getting Help

• Issues: Open an issue for bugs or feature requests
• Discussions: Use GitHub Discussions for questions
• Documentation: Check the README for usage examples

License

By contributing, you agree that your contributions will be licensed under the MIT License.