Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
217 lines (161 loc) · 4.58 KB

CONTRIBUTING.md

File metadata and controls

217 lines (161 loc) · 4.58 KB

Contributing to UniProt MCP

Thank you for your interest in contributing! This guide will help you get started.

Development Setup

Prerequisites

  • Python 3.11 or 3.12
  • uv package manager
  • Git

Getting Started

# Fork and clone the repository
git clone https://github.com/josefdc/Uniprot-MCP.git
cd Uniprot-MCP

# Install dependencies
uv sync --group dev

# Install development tools
uv tool install ruff
uv tool install mypy

Making Changes

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

2. Development Workflow

# Run tests frequently
uv run pytest

# Check code quality before committing
uv tool run ruff check .
uv tool run ruff format .
uv tool run mypy src

3. Commit Guidelines

Use Conventional Commits:

  • feat: New features
  • fix: Bug fixes
  • docs: Documentation changes
  • test: Test additions or changes
  • refactor: Code refactoring
  • chore: Maintenance tasks

Examples:

git commit -m "feat: add support for protein structure predictions"
git commit -m "fix: handle missing GO annotations gracefully"
git commit -m "docs: update installation instructions"

Testing

Running Tests

# All tests
uv run pytest

# With coverage
uv run pytest --cov=uniprot_mcp --cov-report=term-missing

# Specific test file
uv run pytest tests/unit/test_parsers.py -v

Writing Tests

  • Unit tests: Test individual functions/classes in isolation
  • Integration tests: Test complete workflows with VCR fixtures
  • Aim for ≥85% code coverage
  • Include both success and error cases

Example:

def test_parse_entry_basic():
    """Test parsing a minimal UniProt entry."""
    raw_data = load_fixture("minimal_entry.json")
    entry = parse_entry(raw_data)
    assert entry.primary_accession == "P12345"
    assert entry.organism is not None

Code Quality

Style Guide

  • Follow PEP 8
  • Use type hints for all functions
  • Write docstrings for public functions
  • Keep functions focused and small

Pre-commit Checks

Before submitting a PR, ensure all checks pass:

# Format code
uv tool run ruff format .

# Lint
uv tool run ruff check .

# Type check
uv tool run mypy src

# Run tests
uv run pytest --maxfail=1 --cov=uniprot_mcp

Pull Request Process

  1. Update documentation if you've changed APIs or added features
  2. Add tests for new functionality
  3. Ensure CI passes (all tests, linting, type checks)
  4. Update CHANGELOG (if applicable)
  5. Request review from maintainers

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
How have these changes been tested?

## Checklist
- [ ] Tests pass locally
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

Architecture Guidelines

Project Structure

src/uniprot_mcp/
├── adapters/      # External API interactions
├── models/        # Data models (Pydantic)
├── server.py      # MCP server logic
├── http_app.py    # HTTP transport
├── prompts.py     # MCP prompts
└── obs.py         # Observability

Adding New Tools

  1. Define the tool in server.py using @mcp.tool()
  2. Add corresponding adapter method in adapters/uniprot_client.py
  3. Define response model in models/domain.py
  4. Add parser in adapters/parsers.py
  5. Write tests in tests/unit/ and tests/integration/

Example:

@mcp.tool()
async def my_new_tool(accession: str) -> MyResult:
    """Tool description for LLMs."""
    client = get_uniprot_client()
    raw_data = await client.fetch_something(accession)
    return parse_my_result(raw_data)

Reporting Issues

Bug Reports

Include:

  • Python version
  • uv version
  • Error message/traceback
  • Minimal reproduction steps
  • Expected vs actual behavior

Feature Requests

Include:

  • Use case description
  • Proposed API/interface
  • Example usage
  • Potential implementation approach

Getting Help

  • Documentation: Check README and docs/
  • Issues: Search existing issues before creating new ones
  • Discussions: Use GitHub Discussions for questions
  • Code of Conduct: All interactions must follow our Code of Conduct
  • Security: Report vulnerabilities via our Security Policy

License

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