CONTRIBUTING.md

# 🤝 Contributing to MissionControlMCP

Thank you for considering contributing to MissionControlMCP! This document provides guidelines for contributing to the project.

---

## 📋 Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [How to Contribute](#how-to-contribute)
- [Coding Standards](#coding-standards)
- [Testing Guidelines](#testing-guidelines)
- [Pull Request Process](#pull-request-process)
- [Reporting Bugs](#reporting-bugs)
- [Suggesting Features](#suggesting-features)

---

## 📜 Code of Conduct

This project adheres to a code of conduct. By participating, you are expected to uphold this code:

- **Be Respectful:** Treat everyone with respect and consideration
- **Be Constructive:** Provide helpful feedback and suggestions
- **Be Collaborative:** Work together towards common goals
- **Be Professional:** Maintain professionalism in all interactions

---

## 🚀 Getting Started

### Prerequisites

- Python 3.11 or higher
- Git
- Basic knowledge of Python and MCP protocol

### Fork and Clone

1. Fork the repository on GitHub
2. Clone your fork locally:
```bash
git clone https://github.com/YOUR_USERNAME/CleanEye-Hackathon.git
cd CleanEye-Hackathon/mission_control_mcp
```

3. Add upstream remote:
```bash
git remote add upstream https://github.com/AlBaraa-1/CleanEye-Hackathon.git
```

---

## 💻 Development Setup

### 1. Create Virtual Environment

```bash
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate
```

### 2. Install Dependencies

```bash
pip install -r requirements.txt
```

### 3. Install Development Dependencies

```bash
pip install pytest black flake8 mypy
```

### 4. Run Tests

```bash
python demo.py
```

---

## 🛠️ How to Contribute

### Types of Contributions

We welcome:

1. **Bug Fixes** - Fix issues in existing tools
2. **New Tools** - Add new MCP tools
3. **Documentation** - Improve docs and examples
4. **Tests** - Add or improve test coverage
5. **Performance** - Optimize existing code
6. **Examples** - Add real-world use cases

---

## 📝 Coding Standards

### Python Style Guide

We follow [PEP 8](https://pep8.org/) with these specifics:

**Formatting:**
```python
# Good
def function_name(param1: str, param2: int) -> Dict[str, Any]:
    """
    Function description.
    
    Args:
        param1: Parameter description
        param2: Parameter description
        
    Returns:
        Dictionary with results
    """
    result = {"key": "value"}
    return result

# Bad
def functionName(param1,param2):
    result={"key":"value"}
    return result
```

**Use Black for Formatting:**
```bash
black tools/your_tool.py
```

**Type Hints:**
```python
from typing import Dict, Any, List, Optional

def process_data(data: List[str], limit: Optional[int] = None) -> Dict[str, Any]:
    ...
```

**Docstrings:**
```python
def my_function(param: str) -> Dict[str, Any]:
    """
    Brief description (one line).
    
    Longer description if needed explaining the function's
    purpose, behavior, and any important details.
    
    Args:
        param: Description of parameter
        
    Returns:
        Description of return value
        
    Raises:
        ValueError: When invalid input
        FileNotFoundError: When file not found
        
    Example:
        >>> result = my_function("example")
        >>> print(result['key'])
        'value'
    """
    ...
```

---

## ✅ Testing Guidelines

### Writing Tests

All new tools must include tests:

**1. Create Test File:**
```python
# tests/test_your_tool.py
import pytest
from tools.your_tool import your_function

def test_your_function_success():
    """Test successful operation"""
    result = your_function("valid_input")
    assert result['success'] == True
    assert 'data' in result

def test_your_function_error():
    """Test error handling"""
    with pytest.raises(ValueError):
        your_function("invalid_input")
```

**2. Run Tests:**
```bash
pytest tests/test_your_tool.py -v
```

### Test Coverage

Aim for 90%+ coverage:
```bash
pytest --cov=tools tests/
```

### Test Categories

- **Unit Tests** - Test individual functions
- **Integration Tests** - Test tool combinations
- **MCP Tests** - Test MCP protocol integration

---

## 🔄 Pull Request Process

### 1. Create Feature Branch

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description
```

### 2. Make Changes

- Write code following style guide
- Add tests for new functionality
- Update documentation
- Run tests locally

### 3. Commit Changes

Use clear commit messages:
```bash
git add .
git commit -m "Add: New email sentiment analysis tool"
# or
git commit -m "Fix: PDF reader handling encrypted files"
# or
git commit -m "Docs: Update API reference for web fetcher"
```

**Commit Message Format:**
- `Add:` - New features
- `Fix:` - Bug fixes
- `Docs:` - Documentation changes
- `Test:` - Test additions/changes
- `Refactor:` - Code refactoring
- `Perf:` - Performance improvements

### 4. Push to Fork

```bash
git push origin feature/your-feature-name
```

### 5. Create Pull Request

1. Go to GitHub repository
2. Click "New Pull Request"
3. Select your branch
4. Fill in PR template:

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement

## Testing
- [ ] All tests pass
- [ ] New tests added
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guide
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] No breaking changes
```

### 6. Code Review

- Address reviewer feedback
- Make requested changes
- Push updates to same branch

### 7. Merge

Once approved, maintainers will merge your PR.

---

## 🐛 Reporting Bugs

### Before Submitting

1. Check existing issues
2. Verify bug in latest version
3. Gather reproduction steps

### Bug Report Template

```markdown
**Bug Description**
Clear description of the bug

**To Reproduce**
Steps to reproduce:
1. Run command '...'
2. Call function '...'
3. See error

**Expected Behavior**
What should happen

**Actual Behavior**
What actually happens

**Environment**
- OS: Windows 11
- Python: 3.12
- MCP Version: 1.0.0

**Error Messages**
```
Paste error messages here
```

**Additional Context**
Any other relevant information
```

---

## 💡 Suggesting Features

### Feature Request Template

```markdown
**Feature Description**
What feature would you like to see?

**Use Case**
Why is this feature needed? How will it be used?

**Proposed Solution**
How should this feature work?

**Alternatives Considered**
What other approaches did you consider?

**Additional Context**
Any mockups, examples, or references
```

---

## 🏗️ Adding New Tools

### Tool Structure

```python
# tools/my_new_tool.py
"""
Tool Name - Brief description
"""
import logging
from typing import Dict, Any

logger = logging.getLogger(__name__)

def my_tool_function(param: str) -> Dict[str, Any]:
    """
    Tool description.
    
    Args:
        param: Parameter description
        
    Returns:
        Dictionary with results
    """
    try:
        # Implementation
        result = process_data(param)
        
        return {
            "success": True,
            "data": result,
            "metadata": {}
        }
        
    except Exception as e:
        logger.error(f"Error in my_tool: {e}")
        raise
```

### Register Tool in MCP Server

```python
# mcp_server.py
from tools.my_new_tool import my_tool_function

# In tool registration section:
server.register_tool(
    name="my_tool",
    description="What this tool does",
    input_schema={
        "type": "object",
        "properties": {
            "param": {"type": "string", "description": "Param description"}
        },
        "required": ["param"]
    }
)
```

### Add Tests

```python
# tests/test_my_tool.py
def test_my_tool():
    result = my_tool_function("test_input")
    assert result['success'] == True
```

### Update Documentation

1. Add to README.md tool list
2. Add to API.md reference
3. Add to EXAMPLES.md with use case
4. Add sample files to examples/

---

## 📚 Documentation Guidelines

### What to Document

- **README.md** - Overview, setup, quick start
- **API.md** - Complete function signatures
- **EXAMPLES.md** - Real-world use cases
- **TESTING.md** - How to test
- **Code Comments** - Complex logic explanation

### Documentation Style

```python
# Good - Clear and concise
def calculate_total(items: List[float]) -> float:
    """Calculate the sum of item prices."""
    return sum(items)

# Bad - Over-documented
def calculate_total(items: List[float]) -> float:
    """
    This function takes a list of items and calculates the total
    by iterating through each item and adding them together using
    the built-in sum function and then returns the result.
    """
    return sum(items)
```

---

## 🎯 Development Workflow

### Typical Workflow

1. **Check Issues** - Find or create issue
2. **Discuss** - Comment on issue before starting
3. **Branch** - Create feature branch
4. **Develop** - Write code + tests
5. **Test** - Run all tests locally
6. **Document** - Update docs
7. **Commit** - Clear commit messages
8. **Push** - Push to your fork
9. **PR** - Create pull request
10. **Review** - Address feedback
11. **Merge** - Maintainer merges

### Stay in Sync

```bash
# Pull latest changes from upstream
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
```

---

## 🏆 Recognition

Contributors will be:
- Listed in README.md contributors section
- Mentioned in release notes
- Credited in commit history

---

## 📞 Getting Help

- **Questions:** Open a GitHub Discussion
- **Chat:** Join our Discord (link in README)
- **Issues:** GitHub Issues for bugs/features

---

## 📄 License

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

---

**Thank you for contributing to MissionControlMCP!** 🚀

Every contribution, no matter how small, helps make this project better for everyone.