Skip to content

Latest commit

 

History

History
441 lines (295 loc) · 8.78 KB

deployment.rst

File metadata and controls

441 lines (295 loc) · 8.78 KB

Deployment Guide

This guide covers deploying PyWellen MCP Server to production environments.

Prerequisites

System Requirements

  • Python: 3.10 or later
  • Operating System: Linux, macOS, or Windows
  • Memory: Minimum 512MB RAM, recommended 2GB+ for large waveforms
  • Disk Space: 100MB for installation, additional space for waveform files

Dependencies

Core dependencies (automatically installed):

  • mcp - MCP protocol implementation
  • pydantic - Data validation and settings management

Optional dependencies:

  • pyyaml - YAML configuration file support
  • wellen - Waveform file parsing (when using real waveforms)

Installation

From PyPI

Once published, install via pip:

pip install pywellen-mcp

From Source

For development or latest features:

git clone https://github.com/fvutils/pywellen-mcp.git
cd pywellen-mcp
pip install -e ".[dev]"

Using IVPM

For integrated project environments:

# Add to ivpm.yaml
packages:
  - pywellen-mcp

# Update packages
ivpm update

Configuration

Environment Variables

  • PYWELLEN_MAX_SESSIONS - Maximum concurrent sessions (default: 10)
  • PYWELLEN_SESSION_TIMEOUT - Session timeout in seconds (default: 3600)
  • PYWELLEN_LOG_LEVEL - Logging level (default: INFO)

Configuration File

Create config.json in your project directory:

{
  "max_sessions": 10,
  "session_timeout": 3600,
  "signal_cache_size": 100,
  "log_level": "INFO",
  "enable_file_validation": true
}

Running the Server

Standalone Mode

Run the MCP server directly:

pywellen-mcp

The server listens on stdin/stdout for MCP protocol messages.

With MCP Client

Configure in your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "pywellen": {
      "command": "pywellen-mcp",
      "args": []
    }
  }
}

Docker Deployment

Create a Dockerfile:

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY pyproject.toml .
RUN pip install .

# Copy application
COPY src/ src/

# Run server
CMD ["pywellen-mcp"]

Build and run:

docker build -t pywellen-mcp .
docker run -i pywellen-mcp

Production Considerations

Performance Tuning

Session Management:

  • Adjust max_sessions based on available memory
  • Rule of thumb: 200MB RAM per active session
  • Monitor session count and cleanup expired sessions

Signal Caching:

  • Increase signal_cache_size for frequently accessed signals
  • Cache size of 100-500 typical for production
  • Monitor cache hit rates

File Handling:

  • Use local storage for waveform files (not network mounts)
  • Implement file rotation for temporary exports
  • Set up disk space monitoring

Memory Management

Large Waveform Files:

  • Files >1GB may require significant memory
  • Consider splitting large analyses into chunks
  • Use time range filtering to limit data loaded

Session Cleanup:

  • Automatic cleanup runs every hour
  • Manually trigger with session management tools
  • Monitor memory usage and adjust timeouts

Export Operations:

  • CSV exports load all time points in memory
  • Use time range filtering for large exports
  • Consider streaming exports for huge datasets

Security

File Access Control

Path Validation:

  • All file paths are validated and resolved to absolute paths
  • Directory existence and write permissions checked before operations
  • Path traversal attempts are blocked

Recommended Practice:

  • Run server with dedicated user account (not root)
  • Limit file system access to specific directories
  • Use read-only mounts for waveform file directories

Command Injection Protection

Viewer Launch:

  • Commands use list form (not shell strings)
  • No shell=True in subprocess calls
  • Viewer executables validated before launch

File Monitoring:

  • File paths sanitized before operations
  • No user-controlled command execution

Network Security

MCP Protocol:

  • Communication via stdin/stdout (not network sockets)
  • No network exposure by default
  • Client authentication handled by MCP client

Deployment:

  • If exposing via network proxy, use TLS/SSL
  • Implement authentication at proxy level
  • Rate limiting recommended

Monitoring

Logging

Configure logging levels:

import logging
logging.basicConfig(level=logging.INFO)

Log important events:

  • Session creation and cleanup
  • File operations (open, export, monitor)
  • Error conditions
  • Performance metrics

Health Checks

Implement health check endpoint (custom integration):

{
  "status": "healthy",
  "active_sessions": 3,
  "uptime_seconds": 86400,
  "memory_usage_mb": 512
}

Metrics to Monitor

  • Session Count: Current active sessions
  • Memory Usage: RAM consumption per session
  • Response Times: Tool call latency
  • Error Rates: Failed operations per hour
  • Disk Space: Available space for exports

Troubleshooting

Common Issues

Server Won't Start:

  • Check Python version (3.10+ required)
  • Verify dependencies installed: pip list | grep mcp
  • Check for conflicting packages

Session Timeout Errors:

  • Increase session_timeout in configuration
  • Check for long-running operations
  • Verify session IDs are valid

File Access Errors:

  • Verify file paths are absolute
  • Check directory permissions
  • Ensure disk space available

Viewer Launch Failures:

  • Verify viewer installed: which gtkwave
  • Check viewer in PATH
  • Test viewer manually first

Memory Issues:

  • Reduce max_sessions
  • Close unused sessions
  • Limit signal cache size
  • Use time range filtering

Debug Mode

Enable detailed logging:

export PYWELLEN_LOG_LEVEL=DEBUG
pywellen-mcp

Check server status:

# List active sessions
waveform_list_sessions

# Check file permissions
ls -la /path/to/waveform/files

Performance Debugging

Run performance benchmarks:

python scripts/benchmark.py

Profile memory usage:

python -m memory_profiler your_script.py

Backup and Recovery

Session State

Sessions are transient (in-memory only):

  • No persistent state to backup
  • Sessions recreated by opening waveforms
  • Configuration files should be backed up

Configuration Backup

Backup these files:

  • config.json - Server configuration
  • Signal list configurations (.json, .yaml)
  • GTKWave save files (.gtkw)
  • Custom scripts and integrations

Disaster Recovery

  1. Server Failure: Restart server, sessions will be recreated
  2. File Loss: Restore waveform files from backup
  3. Configuration Loss: Restore config files from backup
  4. Data Corruption: Re-export from original waveforms

Upgrading

Version Compatibility

  • Minor versions (1.0 → 1.1): Backward compatible
  • Major versions (1.0 → 2.0): May have breaking changes
  • Review CHANGELOG before upgrading

Upgrade Process

  1. Backup Configuration:

    cp config.json config.json.backup

  2. Install New Version:

    pip install --upgrade pywellen-mcp

  3. Test in Development:

    pywellen-mcp --version
# Run integration tests

  4. Deploy to Production:

    # Stop old version
# Start new version
# Verify functionality

  5. Rollback if Needed:

    pip install pywellen-mcp==1.0.0

Best Practices

  1. Resource Management:
    • Set appropriate session limits
    • Monitor memory usage
    • Clean up exports regularly
  2. Security:
    • Run with minimal privileges
    • Validate all file paths
    • Keep dependencies updated
  3. Monitoring:
    • Log important events
    • Track performance metrics
    • Set up alerts for errors
  4. Maintenance:
    • Regular dependency updates
    • Periodic security audits
    • Performance benchmarking
  5. Documentation:
    • Document custom configurations
    • Maintain runbooks
    • Track known issues

Support

See Also