Contributing to Moondream FastMCP

Thank you for your interest in contributing to the Moondream FastMCP server! This document provides guidelines and information for contributors.

Code of Conduct
Getting Started
Development Setup
Contributing Process
Coding Standards
Testing
Documentation
Release Process

Code of Conduct

This project adheres to a code of conduct that we expect all contributors to follow. Please be respectful and constructive in all interactions.

Our Standards

Use welcoming and inclusive language
Be respectful of differing viewpoints and experiences
Gracefully accept constructive criticism
Focus on what is best for the community
Show empathy towards other community members

Getting Started

Prerequisites

Python 3.10 or higher
Git
Basic understanding of FastMCP and Model Context Protocol
Familiarity with async Python programming

Types of Contributions

We welcome several types of contributions:

Bug Reports: Help us identify and fix issues
Feature Requests: Suggest new functionality
Code Contributions: Implement features or fix bugs
Documentation: Improve or add documentation
Testing: Add or improve test coverage
Performance: Optimize existing code

Development Setup

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/ColeMurray/moondream-mcp.git
cd moondream-mcp

2. Set Up Development Environment

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e ".[dev]"

3. Verify Setup

# Run tests to ensure everything works
pytest tests/

# Run linting
black --check src/ tests/
isort --check-only src/ tests/
mypy src/

4. Set Up Pre-commit Hooks (Optional)

# Install pre-commit
pip install pre-commit

# Set up hooks
pre-commit install

Contributing Process

1. Create an Issue

Before starting work, create an issue to discuss:

Bug reports with reproduction steps
Feature requests with use cases
Questions about implementation

2. Create a Branch

# Create a feature branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/issue-description

3. Make Changes

Follow the coding standards below
Add tests for new functionality
Update documentation as needed
Ensure all tests pass

4. Commit Changes

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "feat: add new vision analysis tool

- Implement semantic segmentation capability
- Add comprehensive tests
- Update documentation
- Closes #123"

Commit Message Format

We follow the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

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

5. Push and Create Pull Request

# Push your branch
git push origin feature/your-feature-name

# Create a pull request on GitHub

Pull Request Guidelines

Use a clear, descriptive title
Reference related issues
Provide a detailed description of changes
Include screenshots for UI changes
Ensure all CI checks pass

Coding Standards

Python Style

We use several tools to maintain code quality:

Black: Code formatting
isort: Import sorting
mypy: Type checking
Bandit: Security analysis

Code Quality Rules

Type Hints: All functions must have type hints
Docstrings: All public functions and classes must have docstrings
Error Handling: Use appropriate exception types and error messages
Async/Await: Use async/await for I/O operations
Resource Management: Use context managers for resource cleanup

Example Code Style

"""
Module for image processing utilities.
"""

import asyncio
from pathlib import Path
from typing import Optional, Union

from PIL import Image

from moondream_mcp.models import ProcessingResult


async def process_image(
    image_path: Union[str, Path],
    max_size: Optional[tuple[int, int]] = None,
) -> ProcessingResult:
    """
    Process an image with optional resizing.
    
    Args:
        image_path: Path to the image file
        max_size: Optional maximum dimensions (width, height)
        
    Returns:
        ProcessingResult with success status and processed image
        
    Raises:
        ImageProcessingError: If image cannot be processed
    """
    try:
        # Implementation here
        pass
    except Exception as e:
        raise ImageProcessingError(f"Failed to process image: {e}") from e

File Organization

Keep modules focused and cohesive
Use clear, descriptive names
Organize imports: standard library, third-party, local
Limit line length to 88 characters (Black default)

Testing

Test Structure

tests/
├── __init__.py
├── test_config.py          # Configuration tests
├── test_moondream.py       # Client tests
├── test_server.py          # Server tests
└── test_tools/
    ├── __init__.py
    └── test_vision.py      # Tool tests

Writing Tests

Unit Tests: Test individual functions and classes
Integration Tests: Test component interactions
Mock External Dependencies: Use mocks for PyTorch, HTTP requests
Test Error Conditions: Include negative test cases
Use Fixtures: Create reusable test data

Test Example

import pytest
from unittest.mock import AsyncMock, patch

from moondream_mcp.moondream import MoondreamClient
from moondream_mcp.models import CaptionResult


class TestMoondreamClient:
    @pytest.fixture
    def client(self) -> MoondreamClient:
        """Create test client."""
        config = Config()
        return MoondreamClient(config)

    @pytest.mark.asyncio
    async def test_caption_image_success(self, client: MoondreamClient) -> None:
        """Test successful image captioning."""
        with patch.object(client, '_load_image') as mock_load:
            mock_load.return_value = Mock()
            
            result = await client.caption_image("test.jpg")
            
            assert result.success is True
            assert result.caption is not None

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src/moondream_mcp

# Run specific test file
pytest tests/test_config.py

# Run with verbose output
pytest -v

# Run only failed tests
pytest --lf

Documentation

Types of Documentation

Code Documentation: Docstrings and type hints
API Documentation: Tool descriptions and examples
User Documentation: Installation and usage guides
Developer Documentation: Architecture and contributing guides

Documentation Standards

Use clear, concise language
Provide examples for complex concepts
Keep documentation up-to-date with code changes
Use proper Markdown formatting

Building Documentation

# Install documentation dependencies
pip install -e ".[docs]"

# Build documentation (if using Sphinx)
cd docs/
make html

Release Process

Version Numbering

We follow Semantic Versioning:

MAJOR: Incompatible API changes
MINOR: New functionality (backward compatible)
PATCH: Bug fixes (backward compatible)

Release Steps

Update Version: Update version in pyproject.toml
Update Changelog: Add release notes to CHANGELOG.md
Create Tag: git tag v1.0.0
Push Tag: git push origin v1.0.0
GitHub Actions: Automatically builds and publishes to PyPI

Pre-release Testing

Before releasing:

Run full test suite
Test installation from built package
Verify documentation is current
Check all CI/CD pipelines pass

Getting Help

Communication Channels

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and ideas
Pull Request Reviews: Code-specific discussions

Resources

Recognition

Contributors will be recognized in:

CONTRIBUTORS.md file
Release notes
GitHub contributor graphs

Thank you for contributing to Moondream FastMCP! 🚀

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History