Skip to content

Latest commit

 

History

History
364 lines (287 loc) · 8.72 KB

CONTRIBUTING.md

File metadata and controls

364 lines (287 loc) · 8.72 KB

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:

{
  "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:

{
  "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:

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

# 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:

# 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:

# 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

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

Docker Compose

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

# 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! 🎉