267 Automation 3dfb4b4c

# Build Automation Documentation

## Overview

The MCP Context Provider now includes comprehensive build automation to ensure code quality, consistent releases, and streamlined development workflows.

## Automation Components

### 1. GitHub Actions

#### Release Workflow (`.github/workflows/release.yml`)
- **Trigger**: Git tag creation (e.g., `git tag v1.8.0`)
- **Actions**:
  - Validates all source files and JSON syntax
  - Builds DXT package with correct version
  - Tests package integrity
  - Creates GitHub release with package attached
  - Generates comprehensive release notes

#### CI Workflow (`.github/workflows/ci.yml`)
- **Trigger**: Pull requests and pushes to main/develop
- **Actions**:
  - Multi-platform testing (Ubuntu, macOS, Windows)
  - Multi-Python version testing (3.8, 3.9, 3.10, 3.11)
  - Context file validation
  - Build process testing
  - Security scanning
  - Code quality checks

### 2. Pre-commit Hooks (`.pre-commit-config.yaml`)

Automatically run before each commit to ensure code quality:
- JSON validation and formatting
- Python code formatting with Black
- Context file structure validation
- Build process testing
- Version consistency checking

**Setup**:
```bash
pip install pre-commit
pre-commit install
```

### 3. Validation Scripts

#### Context Validation (`scripts/validate_contexts.py`)
- Validates JSON syntax in all context files
- Checks required fields (tool_category, description)
- Validates optional section structure
- Ensures semantic versioning in metadata

#### Build Testing (`scripts/test_build.py`)
- Tests build process without creating full package
- Validates source file accessibility
- Tests DXT structure creation
- Verifies file copying operations

#### Version Consistency (`scripts/check_versions.py`)
- Checks version consistency across:
  - `package.json`
  - `scripts/build_dxt.py`
  - `CHANGELOG.md`
  - `scripts/install.sh`

### 4. Version Management (`scripts/bump_version.py`)

Automated version management across all project files:

```bash
# Show current version
python scripts/bump_version.py show

# Bump patch version (1.7.0 → 1.7.1)
python scripts/bump_version.py bump patch

# Bump minor version (1.7.0 → 1.8.0)
python scripts/bump_version.py bump minor

# Bump major version (1.7.0 → 2.0.0)
python scripts/bump_version.py bump major

# Set specific version
python scripts/bump_version.py set 1.8.5
```

## Development Workflow

### Making Changes
1. **Edit source files** in repository root
2. **Pre-commit hooks** automatically validate changes
3. **Push to branch** triggers CI validation
4. **Create PR** runs full test suite

### Releasing New Version

#### Option 1: Using Version Script
```bash
# Bump version and update all files
python scripts/bump_version.py bump minor

# Commit changes
git add .
git commit -m "chore: bump version to 1.8.0"

# Create and push tag
git tag v1.8.0
git push origin main --tags
```

#### Option 2: Manual Process
```bash
# Create tag directly
git tag v1.8.0
git push origin --tags
```

Both methods trigger the automated release workflow.

### Pre-commit Hook Validation

When you commit, the following validations run automatically:
- ✅ JSON syntax validation
- ✅ JSON formatting (auto-fixes)
- ✅ Context structure validation
- ✅ Build process testing
- ✅ Version consistency check
- ✅ Python code formatting

## CI/CD Pipeline Stages

### Pull Request Validation
1. **Validation Stage**:
   - Context file structure validation
   - Build process testing
   - Version consistency checking
   - JSON syntax validation

2. **Build Test Stage**:
   - Full DXT package build test
   - Package unpack verification
   - Context file count validation

3. **Compatibility Stage**:
   - Multi-OS testing (Ubuntu, macOS, Windows)
   - Multi-Python testing (3.8, 3.9, 3.10, 3.11)
   - Cross-platform build validation

4. **Security Stage**:
   - Secret scanning with TruffleHog
   - Sensitive file detection
   - Security policy compliance

### Release Pipeline
1. **Source Validation**:
   - All source files accessible
   - JSON syntax validation
   - Context file structure validation

2. **Package Building**:
   - DXT package creation with version extraction
   - Package integrity verification
   - Content validation

3. **Testing**:
   - Package unpack testing
   - Structure verification
   - Context file counting

4. **Release Creation**:
   - GitHub release with package attachment
   - Automated release notes generation
   - Package registry information

## Quality Assurance Features

### Automated Validation
- **JSON Schema Validation**: All context files validated against structure requirements
- **Build Process Testing**: Ensures build system works before commits
- **Version Synchronization**: Prevents version drift across files
- **Security Scanning**: Detects potential security issues

### Multi-Platform Support
- **Cross-Platform Testing**: Ensures compatibility across Windows, macOS, Linux
- **Python Version Support**: Tests against Python 3.8+ requirements
- **Build System Compatibility**: Validates DXT CLI across platforms

### Code Quality
- **Python Formatting**: Automatic code formatting with Black
- **JSON Formatting**: Consistent JSON structure and indentation
- **Documentation Consistency**: Ensures all automation is documented

## Troubleshooting

### Common Issues

**Pre-commit hook failures**:
```bash
# Re-run hooks manually
pre-commit run --all-files

# Update hook repositories
pre-commit autoupdate
```

**Version inconsistency**:
```bash
# Check current versions
python scripts/check_versions.py

# Fix with version script
python scripts/bump_version.py set 1.7.0
```

**Build failures**:
```bash
# Test build process
python scripts/test_build.py

# Validate context files
python scripts/validate_contexts.py contexts/*.json
```

**CI/CD failures**:
- Check GitHub Actions logs
- Ensure all required files are committed
- Validate that DXT CLI is accessible
- Check Python version compatibility

## Benefits

✅ **Automated Quality Assurance**: Prevents broken commits and releases
✅ **Consistent Versioning**: Eliminates version drift across files
✅ **Streamlined Releases**: One command creates complete releases
✅ **Multi-Platform Validation**: Ensures compatibility across environments
✅ **Security Integration**: Automatic security scanning and validation
✅ **Developer Experience**: Clear feedback and automated fixing where possible

## Future Enhancements

Potential automation improvements:
- **Automated Documentation**: Generate docs from context files
- **Performance Testing**: Automated performance benchmarks
- **Integration Testing**: Full Claude Desktop integration tests
- **Dependency Management**: Automated dependency updates
- **Release Notifications**: Automated notification systems