MCP Template

# Contributing to MCP Template Thank you for your interest in contributing to MCP Template! This document provides guidelines and instructions for contributing. ## Development Setup 1. **Fork and Clone** ```bash git clone https://github.com/yourusername/mcp-template.git cd mcp-template ``` 2. **Create Virtual Environment** ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. **Install Development Dependencies** ```bash make install-dev # Or: pip install -e ".[dev]" ``` 4. **Install Pre-commit Hooks** ```bash make pre-commit # Or: pre-commit install ``` ## Development Workflow ### 1. Create a Branch ```bash git checkout -b feature/your-feature-name # Or for bug fixes: git checkout -b fix/bug-description ``` ### 2. Make Your Changes - Write clear, concise code - Follow the existing code style - Add docstrings to functions and classes - Update tests as needed ### 3. Run Tests ```bash # Run all tests make test # Run specific test types make test-unit make test-integration # Run with coverage make test-cov ``` ### 4. Check Code Quality ```bash # Format code make format # Run linters make lint # Run type checking make typecheck # Run all checks make check ``` ### 5. Commit Your Changes ```bash git add . git commit -m "feat: add new feature description" ``` #### Commit Message Convention We follow conventional commits: - `feat:` - New feature - `fix:` - Bug fix - `docs:` - Documentation changes - `style:` - Code style changes (formatting, etc.) - `refactor:` - Code refactoring - `test:` - Test additions or changes - `chore:` - Build process or auxiliary tool changes ### 6. Push and Create Pull Request ```bash git push origin feature/your-feature-name ``` Then create a pull request on GitHub. ## Code Style Guidelines ### Python Style - Follow PEP 8 - Use Black for formatting (line length: 100) - Use type hints for all function parameters and returns - Write docstrings for all public functions, classes, and modules Example: ```python def calculate_sum(a: int, b: int) -> int: """ Calculate the sum of two integers. Args: a: First integer b: Second integer Returns: Sum of a and b """ return a + b ``` ### Documentation - Use Google-style docstrings - Include type information in docstrings - Document exceptions that can be raised - Provide usage examples for complex functions ### Testing - Write tests for all new features - Aim for >80% code coverage - Use descriptive test names - Use fixtures for common setup Example: ```python @pytest.mark.asyncio async def test_calculator_adds_numbers_correctly(): """Test that calculator correctly adds two numbers.""" result = await calculator_handler({"operation": "add", "a": 5, "b": 3}) assert "8.0" in result ``` ## Adding New Features ### Adding a Tool 1. Create file in `src/mcp_template/tools/` 2. Implement handler function and schema 3. Add tests in `tests/unit/test_tools.py` 4. Register in `src/mcp_template/app.py` 5. Update configuration in `config/config.yaml` 6. Document in README.md ### Adding a Resource Similar process to tools - create handler, tests, register, and document. ### Adding a Prompt Similar process to tools - create handler, tests, register, and document. ## Testing Guidelines ### Unit Tests - Test individual functions in isolation - Mock external dependencies - Place in `tests/unit/` - Mark with `@pytest.mark.unit` if needed ### Integration Tests - Test component interactions - May use real dependencies - Place in `tests/integration/` - Mark with `@pytest.mark.integration` ### Running Specific Tests ```bash # Run a specific test file pytest tests/unit/test_tools.py # Run a specific test pytest tests/unit/test_tools.py::test_calculator_add # Run tests matching a pattern pytest -k "calculator" ``` ## Pull Request Process 1. **Update Documentation** - Update README.md if needed - Add docstrings to new code - Update CHANGELOG.md (if exists) 2. **Ensure CI Passes** - All tests pass - Code coverage is maintained - Linting passes - Type checking passes 3. **Request Review** - Assign reviewers - Respond to feedback - Make requested changes 4. **Merge** - Squash commits if needed - Update version number if appropriate - Delete branch after merge ## Code Review Guidelines ### For Reviewers - Be constructive and respectful - Check for: - Code correctness - Test coverage - Documentation - Performance implications - Security concerns ### For Authors - Respond to all comments - Make requested changes or explain why not - Keep PRs focused and reasonably sized - Update based on feedback ## Issue Guidelines ### Reporting Bugs Include: - Description of the bug - Steps to reproduce - Expected behavior - Actual behavior - Environment details (Python version, OS, etc.) - Error messages and stack traces ### Feature Requests Include: - Clear description of the feature - Use case and motivation - Proposed implementation (if any) - Alternatives considered ### Questions - Check existing issues and documentation first - Provide context about what you're trying to do - Include relevant code snippets ## Release Process (For maintainers) 1. Update version number in `pyproject.toml` and `__init__.py` 2. Update CHANGELOG.md 3. Create and push version tag 4. Build distribution: `make build` 5. Publish to PyPI (if applicable) ## Getting Help - Open an issue for bugs or feature requests - Check existing documentation - Ask questions in issues with the "question" label ## License By contributing, you agree that your contributions will be licensed under the MIT License. ## Thank You! Thank you for contributing to MCP Template! Your efforts help make this project better for everyone.