# Contributing to MCP Server Templates

Thank you for your interest in contributing to the MCP Server Templates project! This guide will help you get started.

## 🚀 Quick Start for Contributors

1. **Fork** this repository
2. **Clone** your fork locally
3. **Create** a new branch for your feature/fix
4. **Make** your changes
5. **Test** locally using our scripts
6. **Submit** a pull request

## 📋 Types of Contributions

### 🏗️ New Templates
- Implement new MCP server functionality
- Follow our template structure and conventions
- Include comprehensive documentation and examples

### 🐛 Bug Fixes
- Fix issues in existing templates
- Improve error handling and edge cases
- Update documentation as needed

### 📚 Documentation
- Improve READMEs and guides
- Add usage examples
- Fix typos and clarity issues

### 🔧 Infrastructure
- Improve build scripts and CI/CD
- Enhance Docker configurations
- Optimize performance

## 🏗️ Creating a New Template

### 1. Template Structure

```
templates/your-template/
├── README.md              # Template documentation
├── template.json          # Configuration schema
├── Dockerfile            # Container definition
├── docker-compose.yml    # Local testing setup
├── requirements.txt      # Python dependencies (if applicable)
├── package.json          # Node.js dependencies (if applicable)
├── src/                  # Source code
│   ├── server.py        # Main MCP server (Python)
│   ├── server.js        # Main MCP server (JavaScript)
│   └── platform-wrapper.js  # Platform integration layer
└── config/               # Configuration examples
    └── config.yaml.example
```

### 2. Template Configuration Schema

Your `template.json` must include:

```json
{
  "name": "Your Template Name",
  "description": "Brief description of what this template does",
  "version": "1.0.0",
  "author": "Your Name <your.email@domain.com>",
  "docker_image": "data-everything/mcp-your-template",
  "categories": ["category1", "category2"],
  "config_schema": {
    "type": "object",
    "properties": {
      "your_setting": {
        "type": "string",
        "title": "Setting Display Name",
        "description": "What this setting controls",
        "env_mapping": "MCP_YOUR_SETTING",
        "default": "default_value"
      }
    },
    "required": ["your_setting"]
  },
  "health_check": {
    "path": "/health",
    "interval": "30s",
    "timeout": "10s"
  }
}
```

### 3. Environment Variable Mapping

All configuration options should support environment variables:

- **Naming Convention**: `MCP_` prefix, uppercase, underscores for separators
- **Arrays**: Use comma-separated values (`MCP_ALLOWED_DIRS=/path1,/path2`)
- **Booleans**: Use `true`/`false` strings
- **Objects**: Use `env_separator` in template.json for nested configs

Example:
```json
{
  "database_config": {
    "type": "object",
    "env_mapping": "MCP_DATABASE",
    "env_separator": "__",
    "properties": {
      "host": {"env_mapping": "MCP_DATABASE__HOST"},
      "port": {"env_mapping": "MCP_DATABASE__PORT"}
    }
  }
}
```

### 4. Platform Integration

Include a `platform-wrapper.js` for environment variable parsing:

```javascript
async function loadConfiguration() {
  const config = {};
  
  // Parse environment variables
  for (const [key, value] of Object.entries(process.env)) {
    if (key.startsWith('MCP_')) {
      // Parse based on your template's schema
      parseEnvironmentVariable(config, key, value);
    }
  }
  
  // Merge with config file if present
  if (fs.existsSync('/app/config/config.yaml')) {
    const fileConfig = yaml.load(fs.readFileSync('/app/config/config.yaml', 'utf8'));
    Object.assign(config, fileConfig);
  }
  
  return config;
}
```

## 🧪 Testing Your Template

### Local Testing Script

```bash
# Build your template
./scripts/build-template.sh your-template

# Test with environment variables
docker run --rm \
  --env=MCP_YOUR_SETTING=test_value \
  --env=MCP_LOG_LEVEL=debug \
  -p 8000:8000 \
  data-everything/mcp-your-template:latest

# Test with config file
docker run --rm \
  --volume=$(pwd)/templates/your-template/config:/app/config \
  -p 8000:8000 \
  data-everything/mcp-your-template:latest
```

### Integration Testing

Create test scripts in the `tests/` directory:

```python
# tests/test_your_template.py
import pytest
import requests
from test_utils import build_and_run_template

def test_your_template_health():
    with build_and_run_template('your-template') as container:
        response = requests.get(f"http://localhost:{container.port}/health")
        assert response.status_code == 200

def test_your_template_mcp_protocol():
    with build_and_run_template('your-template') as container:
        # Test MCP protocol endpoints
        pass
```

## 📚 Documentation Requirements

### Template README

Each template must include:

```markdown
# Template Name

Brief description of what this template does.

## Features
- Feature 1
- Feature 2
- Feature 3

## Configuration

### Environment Variables
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `MCP_SETTING` | What it does | `default` | Yes |

### Config File (Optional)
```yaml
setting: value
nested:
  option: value
```

## Usage Examples

### Docker
```bash
docker run -d \
  --env=MCP_SETTING=value \
  -p 8000:8000 \
  data-everything/mcp-template-name:latest
```

### Docker Compose
```yaml
version: '3.8'
services:
  template:
    image: data-everything/mcp-template-name:latest
    environment:
      - MCP_SETTING=value
    ports:
      - "8000:8000"
```

## Troubleshooting
Common issues and solutions.
```

## 🔍 Code Review Guidelines

### Checklist for Reviewers

- [ ] Template follows directory structure conventions
- [ ] `template.json` schema is complete and valid
- [ ] Environment variable mapping is consistent
- [ ] Docker image builds successfully
- [ ] Health check endpoint works
- [ ] Documentation is comprehensive
- [ ] Tests are included and pass
- [ ] No hardcoded secrets or credentials

### Code Quality Standards

- Use clear, descriptive variable names
- Include error handling and logging
- Follow language-specific best practices
- Add comments for complex logic
- Validate all inputs
- Use secure coding practices

## 🚀 Pull Request Process

1. **Create Issue**: Describe what you're building/fixing
2. **Fork & Branch**: Create a feature branch from main
3. **Develop**: Follow our guidelines and test thoroughly
4. **Document**: Update READMEs and add examples
5. **Test**: Ensure all tests pass locally
6. **Submit PR**: Include clear description and link to issue
7. **Review**: Address feedback from maintainers
8. **Merge**: We'll merge once approved

### PR Template

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] New template
- [ ] Bug fix
- [ ] Documentation update
- [ ] Infrastructure improvement

## Testing
- [ ] Built template locally
- [ ] Tested with environment variables
- [ ] Tested with config file
- [ ] Added automated tests
- [ ] Updated documentation

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

## 🛠️ Development Environment

### Prerequisites

- Docker and Docker Compose
- Git
- Your preferred language runtime (Python, Node.js, etc.)

### Setup

```bash
# Clone the repository
git clone https://github.com/your-username/mcp-server-templates.git
cd mcp-server-templates

# Make scripts executable
chmod +x scripts/*.sh

# Build and test a template
./scripts/build-template.sh file-server
```

## 🎯 Coding Standards

### Python Templates
- Use `black` for formatting
- Follow PEP 8 guidelines
- Include type hints
- Use `pytest` for testing

### JavaScript/Node.js Templates
- Use `prettier` for formatting
- Follow ESLint recommended rules
- Use modern async/await syntax
- Use `jest` for testing

### Docker Best Practices
- Use multi-stage builds
- Minimize image size
- Run as non-root user
- Include health checks
- Pin base image versions

## 🤝 Community Guidelines

- Be respectful and inclusive
- Help newcomers get started
- Provide constructive feedback
- Share knowledge and best practices
- Follow our Code of Conduct

## 📞 Getting Help

- **Issues**: Use GitHub Issues for bugs and feature requests
- **Discussions**: Use GitHub Discussions for questions
- **Documentation**: Check our docs/ directory
- **Examples**: Look at existing templates for reference

## 🏆 Recognition

Contributors will be:
- Listed in our CONTRIBUTORS.md file
- Credited in template documentation
- Invited to join our contributor community
- Featured in release notes for significant contributions

Thank you for contributing to the MCP Server Templates project! 🎉
