UniProt MCP Server

# 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](https://docs.astral.sh/uv/) package manager - Git ### Getting Started ```bash # 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 ```bash git checkout -b feature/your-feature-name # or git checkout -b fix/issue-description ``` ### 2. Development Workflow ```bash # 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](https://www.conventionalcommits.org/): - `feat:` New features - `fix:` Bug fixes - `docs:` Documentation changes - `test:` Test additions or changes - `refactor:` Code refactoring - `chore:` Maintenance tasks Examples: ```bash 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 ```bash # 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: ```python 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: ```bash # 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 ```markdown ## 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: ```python @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](CODE_OF_CONDUCT.md) - **Security**: Report vulnerabilities via our [Security Policy](SECURITY.md) ## License By contributing, you agree that your contributions will be licensed under the MIT License.