Versions

Understanding versions in Pylee and how they enable version control for your MCP servers

Versions

Versions are fundamental to managing your MCP servers in Pylee. They provide a structured way to track, deploy, and manage different releases of your servers across environments.

What are Versions?

Versions in Pylee represent specific releases or iterations of your MCP servers. They enable:

• Change Tracking: Monitor evolution of your servers over time
• Environment Management: Deploy different versions to different environments
• Rollback Capability: Quickly revert to previous working versions
• Team Collaboration: Share specific versions across your organization
• Release Management: Organize and document server releases

Version Types

Server Versions

Server versions are numbered releases of your MCP servers that contain:

• Source Code: The actual server implementation
• Configuration: Server-specific settings and parameters
• Dependencies: Required packages and remotes
• Environment: Variables and secrets needed for operation

Learn more about Server Versions →

Registry Versions

Registry versions track different releases of packages and servers in your organization’s registry:

• Package Versions: Different releases of reusable packages
• Server Templates: Versioned server configurations
• Shared Resources: Common utilities and libraries

Version Lifecycle

1. Development Phase

• Create development versions for testing
• Iterate on features and fixes
• Validate changes in development environment

2. Release Phase

• Create release candidate versions
• Perform comprehensive testing
• Create stable release version

3. Deployment Phase

• Deploy to staging environment
• Validate in production-like conditions
• Roll out to production

4. Maintenance Phase

• Monitor version performance
• Apply security patches
• Plan deprecation timeline

Version Numbering

Pylee uses semantic versioning (semver) for consistent version management:

Format

MAJOR.MINOR.PATCH

Examples

• 1.0.0 - Initial release
• 1.0.1 - Bug fix release
• 1.1.0 - New feature release
• 2.0.0 - Breaking changes release

Pre-release Versions

• 1.0.0-alpha.1 - Alpha release
• 1.0.0-beta.1 - Beta release
• 1.0.0-rc.1 - Release candidate

Creating Your First Version

Prerequisites

Before creating a version, ensure you have:

1. Server Registered: Your server must be registered in Pylee
2. Proper Permissions: You need version creation permissions
3. Code Ready: Your server code is ready for release

Step-by-Step Guide

1. Navigate to Server: Go to your server’s page in Pylee
2. Create Version: Click “Create New Version”
3. Enter Details: Provide version number and release notes
4. Configure: Set up remotes, packages, and environment
5. Deploy: Create deployment to make version available

Version Management Best Practices

Naming Conventions

• Use semantic versioning consistently
• Include pre-release identifiers when appropriate
• Consider branch-based versioning for development

Release Planning

• Feature Branches: Develop features separately
• Version Branches: Maintain stable version branches
• Hotfix Branches: Quick fixes for production issues

Documentation

• Release Notes: Document what changed in each version
• Migration Guides: Provide upgrade instructions
• Breaking Changes: Clearly identify incompatible changes

Testing Strategy

• Unit Tests: Test individual components
• Integration Tests: Test server integration
• Performance Tests: Validate performance characteristics
• Compatibility Tests: Ensure backwards compatibility

Version Deployment Strategies

Environment-Specific Deployment

Deploy different versions to different environments:

{
  "environments": {
    "development": "1.2.0-beta.1",
    "staging": "1.1.5",
    "production": "1.1.4"
  }
}

Gradual Rollout

1. Development: Deploy and test new version
2. Staging: Validate in staging environment
3. Canary: Deploy to small subset of production
4. Production: Full production deployment

Rollback Strategy

• Immediate Rollback: Revert to last known good version
• Selective Rollback: Rollback specific environments
• Staged Rollback: Gradually rollback across environments

Version Configuration

Server Configuration

Each version can have its own configuration:

• Remotes: HTTP endpoints for server communication
• Packages: Dependencies from npm, PyPI, Docker, Homebrew
• Variables: Environment-specific configuration
• Secrets: Secure storage of sensitive data

Environment Variables

Configure environment-specific settings:

{
  "variables": {
    "API_BASE_URL": "https://api.example.com",
    "LOG_LEVEL": "info",
    "TIMEOUT": "30000"
  }
}

Secrets Management

Securely store sensitive information:

{
  "secrets": {
    "API_KEY": "your-api-key",
    "DATABASE_URL": "your-database-connection-string",
    "JWT_SECRET": "your-jwt-secret"
  }
}

Version Monitoring

Performance Metrics

Monitor version performance:

• Response Times: Track API response times
• Error Rates: Monitor version-specific errors
• Throughput: Measure request handling capacity
• Resource Usage: Monitor CPU and memory usage

Health Checks

Implement comprehensive health checks:

• Startup Checks: Verify version starts correctly
• Runtime Checks: Monitor ongoing health
• Dependency Checks: Verify external dependencies

Alerting

Set up alerts for version issues:

• Error Rate Thresholds: Alert on high error rates
• Performance Degradation: Alert on slow response times
• Dependency Failures: Alert on external service failures

Version Security

Access Control

Control who can manage versions:

• Read Permissions: Who can view versions
• Write Permissions: Who can create versions
• Deploy Permissions: Who can deploy versions

Vulnerability Management

Keep versions secure:

• Dependency Scanning: Scan for vulnerable dependencies
• Security Patches: Apply security updates promptly
• Audit Trail: Track all version changes

Compliance

Ensure versions meet compliance requirements:

• Data Protection: Implement data protection measures
• Access Logging: Log all version access
• Retention Policies: Manage version retention

Integration with CI/CD

Automated Version Creation

Integrate with your CI/CD pipeline:

name: Create Version
on:
  push:
    tags:
      - 'v*'

jobs:
  create-version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Create Pylee Version
        run: |
          pylee server version create \
            --server=${{ env.SERVER_NAME }} \
            --version=${{ github.ref_name }}

Deployment Automation

Automate version deployment:

name: Deploy Version
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to deploy'
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy Version
        run: |
          pylee server deploy \
            --version=${{ inputs.version }}

Troubleshooting

Common Issues

Version Creation Fails

• Verify version number format
• Check permissions
• Ensure server exists

Deployment Issues

• Verify version exists
• Check environment configuration
• Validate dependencies

Performance Problems

• Monitor resource usage
• Check dependency health
• Optimize configuration

Getting Help

• Check Troubleshooting Guide
• Review Server Documentation
• Contact support for assistance

Next Steps

• Learn about Server Versions for detailed server versioning
• Explore Deployments to deploy your versions
• Check Variables for environment configuration
• Review Secrets for secure data management