​

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