Server Versions

Understanding server versions and how to manage them in Pylee

Server Versions

Server versions allow you to track and manage different releases of your MCP servers over time. This enables you to maintain multiple versions of a server for different environments, rollback to previous versions, and coordinate deployments across your organization.

What are Server Versions?

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

• Version Control: Track changes and evolution of your servers
• Environment Management: Deploy different versions to different environments
• Rollback Capability: Quickly revert to previous working versions
• Team Coordination: Share specific versions across your organization
• Release Management: Organize and document server releases

Version Numbering

Pylee uses semantic versioning (semver) for server versions:

Semantic Versioning Format

MAJOR.MINOR.PATCH

• MAJOR: Incompatible API changes
• MINOR: Backwards-compatible functionality additions
• PATCH: Backwards-compatible bug fixes

Examples

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

Version Suggestions

When creating a new server version, Pylee automatically suggests the next logical version number based on your existing versions:

• If no versions exist: 1.0.0
• For patch updates: increment the patch number (e.g., 1.0.0 → 1.0.1)
• For minor updates: increment the minor number (e.g., 1.0.5 → 1.1.0)
• For major updates: increment the major number (e.g., 1.5.3 → 2.0.0)

Creating Server Versions

Prerequisites

Before creating a server version, ensure you have:

• A server registered in your organization
• Appropriate permissions to create versions
• Your server code ready for release

Version Creation Process

1. Navigate to Server: Go to your server’s page in the Pylee dashboard
2. Create New Version: Click “Create New Version” or navigate to the versions section
3. Select Organization: Choose which organization will own this version
4. Enter Version Number: Provide a semantic version number
5. Review and Create: Confirm the version details and create

Version Validation

Pylee validates version numbers to ensure:

• Unique Versions: No duplicate versions within the same organization
• Valid Format: Follows semantic versioning conventions
• Logical Progression: Versions make sense in sequence

Managing Server Versions

Version Listing

View all versions of a server with details including:

• Version number
• Release date
• Organization ownership
• Current deployment status

Version Comparison

Compare different versions to understand:

• Changes between versions
• Feature additions or removals
• Configuration differences
• Performance improvements

Version Metadata

Each version stores important metadata:

• Creation Date: When the version was created
• Creator: Who created the version
• Organization: Which organization owns it
• Release Notes: Documentation of changes
• Deployment Status: Where it’s currently deployed

Version Deployment

Environment-Specific Deployment

Deploy different versions to different environments:

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

Gradual Rollout

Implement gradual rollouts:

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

Quickly rollback to previous versions:

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

Version Organization

Multi-Organization Support

Server versions can be owned by different organizations:

• Shared Servers: Multiple organizations using the same server
• Organization-Specific Versions: Custom versions for specific organizations
• Version Inheritance: Base versions with organization-specific modifications

Organization Context

When creating versions, consider:

• Target Organization: Which organization will own the version
• Access Permissions: Who can deploy and manage the version
• Resource Allocation: Organization-specific resource limits

Best Practices

Version Naming

Follow consistent naming conventions:

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

Release Planning

Plan your releases effectively:

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

Documentation

Document your versions thoroughly:

• Release Notes: What changed in each version
• Migration Guides: How to upgrade between versions
• Breaking Changes: Incompatible changes and workarounds

Testing Strategy

Test versions comprehensively:

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

Version Lifecycle

Development Phase

• Create development versions
• Test new features and fixes
• Iterate based on feedback

Release Phase

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

Maintenance Phase

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

Deprecation Phase

• Announce deprecation timeline
• Provide migration path
• Remove deprecated versions

Advanced Features

Version Tagging

Use tags to mark special versions:

• latest - Most recent stable version
• lts - Long-term support version
• beta - Beta release version
• alpha - Alpha release version

Version Branching

Maintain multiple version branches:

• Master Branch: Latest development
• Release Branches: Stable releases
• Hotfix Branches: Critical fixes

Version Automation

Automate version management:

• CI/CD Integration: Automatic version creation
• Deployment Automation: Automated deployment pipelines
• Version Monitoring: Monitor version health

Troubleshooting

Version Creation Issues

Common problems and solutions:

• Duplicate Version: Choose a different version number
• Invalid Format: Use semantic versioning format
• Permission Denied: Ensure you have version creation permissions

Deployment Issues

Resolve deployment problems:

• Version Not Found: Verify version exists and is accessible
• Compatibility Issues: Check version compatibility
• Resource Conflicts: Resolve resource allocation conflicts

Performance Issues

Optimize version performance:

• Version Size: Keep versions lightweight
• Startup Time: Optimize server startup
• Memory Usage: Monitor memory consumption

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 }} \
            --organization=${{ env.ORG_ID }}

Deployment Automation

Automate version deployment:

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

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

Security Considerations

Version Access Control

Control access to versions:

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

Version Signing

Sign versions for integrity:

• Digital Signatures: Verify version authenticity
• Checksum Validation: Ensure version integrity
• Audit Trail: Track version changes

Sensitive Data

Protect sensitive information:

• Environment Variables: Secure configuration
• API Keys: Protect authentication credentials
• Database Connections: Secure database access

Migration and Upgrades

Version Migration

Migrate between versions safely:

1. Backup Current State: Save current configuration
2. Test Migration: Test in non-production environment
3. Execute Migration: Apply version changes
4. Verify Results: Confirm migration success

Upgrade Strategies

Choose appropriate upgrade strategies:

• Blue-Green Deployment: Zero-downtime upgrades
• Rolling Updates: Gradual version rollout
• Canary Deployment: Test with subset of traffic

Monitoring and Observability

Version Metrics

Monitor version performance:

• Deployment Success Rate: Track deployment success
• Error Rates: Monitor version-specific errors
• Performance Metrics: Track response times and throughput

Health Checks

Implement version health checks:

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

Next Steps

• Learn about Organizations to understand version ownership
• Explore Servers for server management basics
• Check Variables for version-specific configuration
• Review Troubleshooting for common issues