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

Server Failure: Restart server, sessions will be recreated
File Loss: Restore waveform files from backup
Configuration Loss: Restore config files from backup
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

Backup Configuration:
```
cp config.json config.json.backup
```
Install New Version:
```
pip install --upgrade pywellen-mcp
```

Test in Development:

pywellen-mcp --version
# Run integration tests

Deploy to Production:

# Stop old version
# Start new version
# Verify functionality

Rollback if Needed:
```
pip install pywellen-mcp==1.0.0
```

Best Practices

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

Support

Documentation: https://fvutils.github.io/pywellen-mcp
Issues: https://github.com/fvutils/pywellen-mcp/issues
Discussions: https://github.com/fvutils/pywellen-mcp/discussions