Contributing

We welcome contributions to egile-mcp-starter! This guide will help you get started with contributing to the project.

Getting Started

Prerequisites

Python 3.10 or higher
Poetry for dependency management
Git for version control

Development Setup

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/yourusername/egile-mcp-starter.git
cd egile-mcp-starter

Install development dependencies:
```
poetry install --with dev
```
Install pre-commit hooks:
```
poetry run pre-commit install
```

Verify the setup:

poetry run pytest
poetry run egile-mcp-starter --version

Development Workflow

Creating a Feature Branch

# Create and switch to a new branch
git checkout -b feature/amazing-feature

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

Making Changes

Make your changes to the codebase
Add tests for new functionality
Update documentation as needed
Run the test suite:
```
poetry run pytest
```

Code Quality

Before committing, ensure your code meets our quality standards:

# Format code with Black
poetry run black .

# Sort imports with isort
poetry run isort .

# Check linting with Flake8
poetry run flake8 egile_mcp_starter tests

# Type checking with MyPy
poetry run mypy egile_mcp_starter

# Run all pre-commit checks
poetry run pre-commit run --all-files

Testing Your Changes

Run the Test Suite

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=egile_mcp_starter --cov-report=html

# Run specific test files
poetry run pytest tests/test_generator.py -v

Test Template Generation

# Test generating different server types
poetry run egile-mcp-starter --no-input --output-dir /tmp/test-tools
cd /tmp/test-tools/my_mcp_server
poetry install
poetry run pytest

Manual Testing

Test the CLI with various configurations:

# Test interactive mode
poetry run egile-mcp-starter

# Test with config file
echo 'default_context:
  project_name: "Test Server"
  server_type: "tools"' > test-config.yaml
poetry run egile-mcp-starter --config-file test-config.yaml --no-input

Types of Contributions

Bug Reports

When reporting bugs, please include:

Clear description of the issue
Steps to reproduce the problem
Expected vs actual behavior
Environment information (OS, Python version, etc.)
Error messages or logs

Template:

## Bug Description
Brief description of the bug.

## Steps to Reproduce
1. Run command X
2. Configure Y
3. See error

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- OS: Ubuntu 22.04
- Python: 3.11.0
- egile-mcp-starter: 0.1.0

## Additional Context
Any other relevant information.

Feature Requests

For new features, please provide:

Clear description of the feature
Use case and motivation
Proposed implementation (if you have ideas)
Alternatives considered

Code Contributions

We welcome:

Bug fixes
New features
Documentation improvements
Template enhancements
Test improvements
Performance optimizations

Project Structure

Understanding the project structure will help with contributions:

egile-mcp-starter/
├── egile_mcp_starter/          # Main package
│   ├── __init__.py
│   ├── cli.py                  # Command line interface
│   ├── generator.py            # Project generation logic
│   └── template/               # Cookiecutter template
│       ├── cookiecutter.json   # Template configuration
│       └── {{cookiecutter.project_slug}}/  # Generated project template
├── tests/                      # Test suite
│   ├── test_cli.py
│   ├── test_generator.py
│   └── test_package.py
├── docs/                       # Documentation
├── pyproject.toml             # Project configuration
├── README.md
└── CHANGELOG.md

Key Components

cli.py: Command line interface using Click
generator.py: Core logic for project generation
template/: Cookiecutter template files
tests/: Comprehensive test suite
docs/: Sphinx documentation

Template Development

Adding New Template Features

Modify the template in egile_mcp_starter/template/
Update cookiecutter.json with new configuration options
Add conditional logic using Jinja2 templates
Test the changes with different configurations
Update documentation

Template File Structure

template/
├── cookiecutter.json           # Configuration schema
└── {{cookiecutter.project_slug}}/
    ├── src/
    │   └── {{cookiecutter.project_slug}}/
    │       ├── server.py       # Uses Jinja2 conditionals
    │       ├── tools/          # {% if server_type includes tools %}
    │       ├── resources/      # {% if server_type includes resources %}
    │       └── prompts/        # {% if server_type includes prompts %}
    ├── tests/
    ├── pyproject.toml         # Template variables
    └── README.md              # Generated documentation

Testing Template Changes

# Generate test projects
poetry run egile-mcp-starter --no-input --output-dir /tmp/test-full
poetry run egile-mcp-starter --no-input --output-dir /tmp/test-tools \
  --extra-context '{"server_type": "tools"}'

# Verify generated projects work
cd /tmp/test-full/my_mcp_server
poetry install && poetry run pytest

cd /tmp/test-tools/my_mcp_server  
poetry install && poetry run pytest

Documentation

Writing Documentation

Use Markdown for most documentation
Follow the existing style and structure
Include code examples where appropriate
Add cross-references to related sections

Building Documentation

# Install documentation dependencies
poetry install --with docs

# Build documentation
cd docs
poetry run sphinx-build -b html . _build/html

# Serve locally
poetry run python -m http.server 8000 --directory _build/html

Documentation Guidelines

Clear headings and structure
Code examples with proper syntax highlighting
Cross-references using Sphinx directives
Screenshots for UI elements (if applicable)
API documentation using autodoc

Testing Guidelines

Writing Tests

Follow pytest conventions
Use descriptive test names
Test both success and failure cases
Mock external dependencies
Maintain high test coverage

Test Categories

Unit tests: Test individual functions and classes
Integration tests: Test component interactions
End-to-end tests: Test complete workflows
Template tests: Test generated project functionality

Example Test

def test_generate_tools_server(tmp_path):
    """Test generating a tools-only server."""
    output_dir = tmp_path / "output"
    
    result = generate_mcp_server(
        output_dir=str(output_dir),
        no_input=True,
        extra_context={"server_type": "tools"}
    )
    
    project_path = Path(result)
    assert project_path.exists()
    assert (project_path / "src" / "my_mcp_server" / "tools").exists()
    assert not (project_path / "src" / "my_mcp_server" / "resources").exists()

Submitting Changes

Pull Request Process

Push your branch to your fork:

git push origin feature/amazing-feature

Create a pull request on GitHub
Fill out the PR template with:
- Description of changes
- Related issues
- Testing performed
- Breaking changes (if any)
Respond to review feedback
Squash commits if requested

Pull Request Template

## Description
Brief description of the changes.

## Related Issues
Fixes #123
Closes #456

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

## Testing
- [ ] Added new tests
- [ ] All tests pass
- [ ] Manual testing performed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

Release Process

Version Numbering

We follow Semantic Versioning:

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes (backward compatible)

Creating a Release

Update version in pyproject.toml
Update CHANGELOG.md
Create a pull request with version changes
Merge to main after review
Create a GitHub release with tag
CI/CD pipeline handles publishing

Code Style

Python Style Guide

Follow PEP 8 guidelines
Use Black for code formatting
Use isort for import sorting
Maximum line length: 88 characters
Use type hints for all functions

Documentation Style

Use Google-style docstrings
Include parameter types and descriptions
Add usage examples where helpful
Use Markdown for README files

Example Code Style

from typing import Optional, Dict, Any

def generate_project(
    output_dir: Optional[str] = None,
    config: Optional[Dict[str, Any]] = None,
    verbose: bool = False
) -> str:
    """Generate a new MCP server project.
    
    Args:
        output_dir: Directory to create the project in
        config: Configuration overrides
        verbose: Enable verbose output
        
    Returns:
        Path to the generated project
        
    Raises:
        ProjectGenerationError: If generation fails
        
    Example:
        >>> project_path = generate_project(
        ...     output_dir="/tmp",
        ...     config={"server_type": "tools"}
        ... )
        >>> print(f"Project created at: {project_path}")
    """
    # Implementation here
    pass

Getting Help

GitHub Issues: For bugs and feature requests
GitHub Discussions: For questions and general discussion
Email: jpoullet2000@gmail.com for direct contact

Recognition

Contributors are recognized in:

CHANGELOG.md: For significant contributions
GitHub contributors page: Automatic recognition
Documentation: For major contributions

Thank you for contributing to egile-mcp-starter! 🎉