Build Automation Documentation

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:

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:

# 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

# 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

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

# Re-run hooks manually
pre-commit run --all-files

# Update hook repositories
pre-commit autoupdate

Version inconsistency:

# Check current versions
python scripts/check_versions.py

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

Build failures:

# 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