Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Welcome to the comprehensive documentation for ProxmoxMCP - a Python-based Model Context Protocol (MCP) server for managing Proxmox hypervisors.
For installation and basic usage, see the main README.
- Development roadmap and feature planning
- How to contribute to the project
- Comprehensive code analysis and structure
- Automated development workflow setup
- Comprehensive testing guide and best practices
- Token encryption and security practices
This project uses modern Python development practices:
Python 3.10+ for MCP compatibility
FastMCP for the server framework
Pydantic for data validation
Docker for containerized deployment
The server requires proper configuration for Proxmox API access. See the
configuration examples in the proxmox-config/ directory.
This project includes Claude Code automation for issue resolution. When you
assign an issue with the claude-code label, it automatically:
Creates a branch
Implements the solution
Runs tests and quality checks
Creates a pull request
- You're reading this live on GitBook!
- Project overview and setup
- Bug reports and feature requests
- Code contributions
This documentation is built with GitBook and automatically synced with the repository. 📖 Live URL:
This repository is configured to work with Claude Code automation for issue resolution. When you assign an issue to Claude Code, it will automatically create a branch, implement the solution, and create a pull request.
Use the "Claude Code Task" issue template or manually:
Create a new issue
Add the claude-code label
Assign to claude-code-bot (or ensure the label is present)
Provide clear requirements and acceptance criteria
When an issue is assigned to Claude Code, the automation will:
Create Branch: Generate a new branch named claude/issue-{number}-{title}
Comment: Add a comment to the issue indicating work has started
Implement: Analyze requirements and implement the solution
Quality Checks
After Claude Code completes the work:
Review the generated pull request
Check that all requirements are met
Run additional tests if needed
Merge when satisfied or request changes
The following secrets must be configured in your repository:
ANTHROPIC_API_KEY: Your Anthropic API key for Claude Code
GITHUB_TOKEN: Automatically provided by GitHub Actions
The workflow requires the following permissions:
contents: write - To create branches and commits
issues: write - To comment on issues
pull-requests: write - To create pull requests
Python Version: The workflow uses Python 3.10+ (required for MCP SDK compatibility)
Package Manager: Uses uv for fast dependency installation
Development Tools: Includes pytest, ruff, and mypy for quality checks
The automation is configured in .github/workflows/claude-issue-assignment.yml with:
When creating issues for Claude Code, include:
Be specific about requirements
Provide examples of expected behavior
Include error cases to handle
Reference existing code patterns when applicable
Check that the solution follows project conventions
Verify tests are comprehensive
Ensure documentation is updated if needed
Test the implementation manually if possible
Workflow doesn't trigger:
Ensure the issue has the claude-code label
Check that the assignee is in the assignee_trigger list (basher83 or claude-code-bot)
Verify repository secrets are configured
Python dependency errors:
The workflow requires Python 3.10+ for MCP SDK compatibility
Check that pyproject.toml specifies requires-python = ">=3.10"
Verify MCP dependencies are compatible with the Python version
Implementation fails:
Check the workflow logs for detailed error messages
Ensure the task description is clear and actionable
Verify the requirements don't conflict with existing code
Check that the ANTHROPIC_API_KEY secret is properly configured
Quality checks fail:
The workflow runs: pytest && ruff format . && mypy . && ruff check .
Claude Code will attempt to fix issues automatically
Manual intervention may be needed for complex conflicts
Check individual tool logs for specific failures
Missing ASSIGNEE_TRIGGER error:
Ensure assignee_trigger parameter is set in the workflow
Add your GitHub username to the trigger list
Verify the workflow configuration matches the action requirements
Check workflow run logs: Go to Actions tab → failed run → view logs
Verify issue setup: Confirm labels, assignee, and issue description
Test locally: Run uv pip install -e ".[dev]" to check dependencies
Check secrets
If you encounter issues with the automation:
Check the GitHub Actions logs for detailed error information
Review the issue description for clarity and completeness
Ensure all required repository secrets are configured
Verify Python and dependency compatibility
When an issue is assigned to trigger the automation, the following steps occur:
Branch Creation
Environment Setup
Claude Code Implementation
Analyzes issue requirements and codebase
The workflow automatically runs these checks:
pytest: All test suites must pass
ruff: Code formatting and linting compliance
mypy: Type checking validation
Project patterns: Follows existing code conventions
Create Issue: Use the Claude Code Task template
Automatic Processing:
Workflow triggers on assignment
Creates branch claude/issue-123-add-vm-backup-scheduling-feature
This automation streamlines the development process while maintaining code quality and project standards.
Commit: Create meaningful commits with the changes
Pull Request: Create a PR linking back to the issue
id-token: write - For authenticationConfirm the workflow file is on the main branch
ANTHROPIC_API_KEYCreate a support issue if problems persist
Implements solution following project patterns
Runs quality checks: pytest && ruff format . && mypy . && ruff check .
Creates meaningful commits with proper messages
Pull Request Creation
Automatic PR with descriptive title
Links back to the original issue
Includes summary of changes made
Ready for review and testing
Adds comment to issue with progress updates
Implementation:
Code is analyzed, written, and tested
All quality checks must pass
Multiple commits with descriptive messages
Pull Request:
PR #124 created automatically
Links to issue #123 with "Closes #123"
Includes implementation summary
Review: You review and merge the PR
Completion: Issue #123 is automatically closed
assignee_trigger: "basher83,claude-code-bot" # Users who can trigger automation
allowed_tools: "bash,read,write,edit,glob,grep" # Tools Claude Code can use
timeout_minutes: "120" # Maximum execution time## Task Description
Add support for VM snapshot management in the Proxmox MCP server.## Requirements
- [ ] Add `create_vm_snapshot` tool
- [ ] Add `delete_vm_snapshot` tool
- [ ] Add `restore_vm_snapshot` tool
- [ ] Include proper error handling## Acceptance Criteria
- [ ] All tools follow existing patterns in tools/ directory
- [ ] Proper Pydantic models for validation
- [ ] Rich formatted output
- [ ] Tests included## Technical Details
- Use the existing ProxmoxManager pattern
- Follow the formatting standards in formatting/ module
- Add to tools/vm.py or create tools/snapshot.py# Creates branch name from issue number and title
BRANCH_NAME="claude/issue-${ISSUE_NUMBER}-${CLEAN_TITLE}"
git checkout -b "$BRANCH_NAME"
git push origin "$BRANCH_NAME"# Set up Python 3.10 environment
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"Title: [CLAUDE] Add VM backup scheduling feature
Description: Clear requirements and acceptance criteria
Labels: claude-code, automation
Assignee: basher83A Model Context Protocol (MCP) server that enables AI assistants like Claude to manage Proxmox virtual infrastructure through simple, secure commands.
Note: This is a maintained fork of canvrno/ProxmoxMCP with Docker support and active maintenance.
🖥️ Node Management - List nodes, check status, monitor resources
🚀 VM Control - List VMs, execute commands via QEMU Guest Agent
💾 Storage Monitoring - View storage pools and usage
🏢 Cluster Overview - Monitor overall cluster health
🔒 Secure by Default - Token-based authentication, SSL verification
🤖 AI-Powered Diagnostics - Get intelligent insights about your infrastructure
Python 3.10+ or Docker
Access to a Proxmox server
Proxmox API token ()
Install UV:
Create your Proxmox config (e.g., ~/proxmox-config.json):
Add to your MCP client settings:
Note: Environment variable configuration is planned for a future release. Currently, you'll need to use a custom Docker image with your config file.
Log into your Proxmox web interface
Navigate to Datacenter → Permissions → API Tokens
Click Add and create a new token:
User: Select user (e.g., root@pam
Note: Set
"verify_ssl": falsein your config if using self-signed certificates.
The server provides the following MCP tools for interacting with Proxmox:
Lists all nodes in the Proxmox cluster.
Parameters: None
Example Response:
Get detailed status of a specific node.
Parameters:
node (string, required): Name of the node
Example Response:
List all VMs across the cluster.
Parameters: None
Example Response:
List available storage.
Parameters: None
Example Response:
Get overall cluster status.
Parameters: None
Example Response:
Execute a command in a VM's console using QEMU Guest Agent.
Parameters:
node (string, required): Name of the node where VM is running
vmid (string, required): ID of the VM
- Full guides and tutorials
- Development setup and workflow
- How to contribute
MIT License - see file for details.
We welcome contributions! Please see our for details.
Original project by
Built with
Powered by
Token ID: Enter a name (e.g., mcp-token)
Privilege Separation: Uncheck for full access
Copy the displayed token value - you won't see it again!
command (string, required): Command to executeExample Response:
Requirements:
VM must be running
QEMU Guest Agent must be installed and running in the VM
Command execution permissions must be enabled in the Guest Agent
Error Handling:
Returns error if VM is not running
Returns error if VM is not found
Returns error if command execution fails
Includes command output even if command returns non-zero exit code
This roadmap outlines the planned development and improvement efforts for the ProxmoxMCP project, prioritized for production readiness. The phases are organized by urgency with specific implementation guidance and timelines.
These items address critical security vulnerabilities and must be implemented immediately:
curl -LsSf https://astral.sh/uv/install.sh | sh{
"host": "your-proxmox-host.com",
"user": "root@pam",
"token_name": "mcp-token",
"token_value": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"verify_ssl": true
}{
"mcpServers": {
"proxmox": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/basher83/ProxmoxMCP.git",
"proxmox-mcp"
],
"env": {
"PROXMOX_MCP_CONFIG": "/Users/yourname/proxmox-config.json"
}
}
}
}{
"mcpServers": {
"proxmox": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PROXMOX_HOST=your-proxmox-host.com",
"-e",
"PROXMOX_USER=root@pam",
"-e",
"PROXMOX_TOKEN_NAME=mcp-token",
"-e",
"PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"-e",
"PROXMOX_VERIFY_SSL=true",
"ghcr.io/basher83/proxmoxmcp:latest"
]
}
}
}Enhance Docker security and deployment:
Standardize error handling across the codebase:
Optimize performance for production workloads:
Add new functionality after core improvements:
These can be implemented alongside the phases:
Throughout all phases:
Phase 1: 1-2 days (Critical security fixes)
Phase 2: 1 day (Docker improvements)
Phase 3: 2-3 days (Error handling)
Phase 4: 1-2 weeks (Performance improvements)
Phase 5: 2-4 weeks (Feature additions)
Immediate Priority: Security fixes first, then Docker improvements and error handlingNext Priority: Performance optimizations and comprehensive testingFuture Priority: New features and extended functionality
This roadmap is a living document and will be updated as development progresses and new priorities emerge.
# Add cryptography.fernet for token encryption
import os
from cryptography.fernet import Fernet
def encrypt_token(token: str, key: bytes) -> str:
"""Encrypt sensitive tokens"""
f = Fernet(key)
return f.encrypt(token.encode()).decode()import shlex
def validate_command(command: str) -> str:
"""Validate and sanitize shell commands"""
# Implement whitelist of allowed commands
# Escape special characters
return shlex.quote(command){
"auth": {
"user": "mcp@pve",
"token_name": "mcp-token",
"token_value": "${PROXMOX_TOKEN}"
}
}# Enhanced Dockerfile with security best practices
FROM python:3.10-slim AS base
# Security: Run as non-root from the start
RUN groupadd -r mcp && useradd -r -g mcp mcpservices:
proxmox-mcp:
secrets:
- proxmox_token
environment:
PROXMOX_TOKEN_FILE: /run/secrets/proxmox_token
secrets:
proxmox_token:
external: truedeploy:
resources:
limits:
cpus: '1'
memory: 512M
restart: unless-stopped
healthcheck:
test: ["CMD", "python", "-m", "proxmox_mcp.health"]
interval: 30s
timeout: 10s
retries: 3class ProxmoxError(Exception):
"""Base exception for Proxmox operations"""
pass
class ProxmoxAuthError(ProxmoxError):
"""Authentication-related errors"""
pass
class ProxmoxResourceNotFoundError(ProxmoxError):
"""Resource not found errors"""
passdef _handle_error(self, operation: str, error: Exception) -> None:
if isinstance(error, proxmoxer.AuthenticationError):
raise ProxmoxAuthError(f"Authentication failed: {error}")
# ... more specific error handling@self.mcp.tool(description="Check MCP server and Proxmox connection health")
def health_check():
try:
version = self.proxmox.version.get()
return {"status": "healthy", "proxmox_version": version}
except Exception as e:
return {"status": "unhealthy", "error": str(e)}from functools import lru_cache
import asyncio
class ProxmoxManager:
def __init__(self, ...):
self._connection_pool = {}
self._cache = {}
@lru_cache(maxsize=100)
def get_cached_node_status(self, node: str):
"""Cache frequently accessed data"""
return self.api.nodes(node).status.get()# In proxmox_mcp/tools/container.py
class ContainerTools(ProxmoxTool):
def get_containers(self) -> List[Content]:
"""List LXC containers"""
# Implementation similar to VM toolsasync def batch_execute_commands(self, commands: List[VMCommand]):
"""Execute multiple commands concurrently"""
tasks = [self.execute_command(cmd) for cmd in commands]
return await asyncio.gather(*tasks){
"proxmox": {
"host": "your-proxmox-host",
"port": 8006,
"verify_ssl": true, // Changed from false
"service": "PVE"
},
"auth": {
"user": "mcp@pve", // Use dedicated user
"token_name": "mcp-token",
"token_value": "${PROXMOX_TOKEN}" // Environment variable
}
}Thank you for your interest in contributing to ProxmoxMCP! This document provides guidelines and instructions for contributing to the project.
📚 Complete Documentation - For detailed guides and API reference
By participating in this project, you agree to abide by our Code of Conduct. Please be respectful and considerate of others when contributing to the project.
Fork the repository on GitHub
Clone your fork locally
Set up the development environment
Create a new branch for your changes
Python 3.8 or higher
Docker (for containerized development)
Proxmox VE instance (for testing)
Clone the repository:
Set up git configuration for development:
The example.gitconfig includes development-friendly settings like:
Python/JSON/Dockerfile diff patterns
Check the for tasks to work on or create a new issue for your proposed change
Create a new branch from main:
Make your changes
Add tests for your changes
Follow style guidelines
Use type hints for function parameters and return values
Write docstrings for all functions, classes, and modules
Keep functions focused on a single responsibility
We use the following tools for code formatting and linting:
for code formatting and linting
for type checking
You can run these tools with:
Write unit tests for all new functionality
Ensure all tests pass before submitting a pull request
Aim for high test coverage of your code
Include both positive and negative test cases
To run tests:
For coverage report:
Update documentation for any changes to functionality
Document all public APIs
Include examples where appropriate
Keep the README up to date
Use the appropriate issue template
Provide clear and detailed information
Include steps to reproduce for bugs
Label issues appropriately
Reference the related issue in your pull request
Provide a clear description of the changes
Update documentation as needed
Ensure all tests pass
If you discover a security vulnerability, please do NOT open an issue. Instead, email with details. We take security issues seriously and will address them promptly.
Join our for questions and community support
Follow the project on GitHub to stay updated
Share your success stories and use cases
Thank you for contributing to ProxmoxMCP!
Submit a pull request
git lg, git st, git sync)Performance and security optimizations
Create a virtual environment:
Install development dependencies:
Install pre-commit hooks:
This sets up automatic code quality checks that run before each commit. The hooks include:
Ruff formatting and linting
Type checking with mypy
Security scanning with bandit and safety
Markdown formatting validation
Note: Pre-commit will automatically install required tools in isolated environments, so you don't need to install them globally.
Configure your Proxmox connection:
Run the tests to ensure they pass:
Update documentation as needed
Commit your changes with a descriptive commit message:
Push your branch to your fork:
Create a pull request against the main branch of the original repository
Use meaningful variable and function names
Add comments for complex logic
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activatepip install -e ".[dev]"pre-commit installcp proxmox-config/config.example.json proxmox-config/config.json
# Edit config.json with your Proxmox credentialspytestgit commit -m "Add feature: your feature description"git push origin feature/your-feature-namegit clone https://github.com/yourusername/ProxmoxMCP.git
cd ProxmoxMCP# Option 1: Copy project git configuration (recommended)
cp example.gitconfig .git/config
# Then update with your personal details
git config user.name "Your Name"
git config user.email "your.email@example.com"
# Option 2: Manual configuration
git config user.name "Your Name"
git config user.email "your.email@example.com"
git config core.editor "vscode"
git config init.defaultBranch "main"
git config pull.rebase true
git config push.autoSetupRemote truegit checkout -b feature/your-feature-nameruff format src tests
ruff check src tests
mypy src testspytestpytest --cov=srcThe ProxmoxMCP project uses a modern development workflow with automated code quality, dependency management, and AI-assisted development. All workflows are designed to maintain high code quality while reducing manual overhead for contributors.
Automated Quality: Code formatting and linting happen automatically
AI-Assisted Development: Claude Code helps with issue resolution and code reviews
Security First: All dependencies and code changes are automatically reviewed
Consistent Standards: Enforced through automated tooling and workflows
Purpose: Automatically fixes code formatting and quality issues in pull requests.
Triggers:
Pull request creation and updates
Pushes to the main branch
Tools Used:
ruff: Python code formatting and linting
mypy: Type checking
Process:
Sets up Python 3.10 environment
Installs UV package manager with caching
Creates virtual environment and installs dev dependencies
Runs ruff formatter with fallback to auto-fix mode
Runs ruff with --fix flag for linting and import organization
Runs mypy for type checking validation
Commits any fixes directly to the PR branch via autofix.ci
Key Features:
Uses --exit-zero flags to prevent workflow failures
Caches dependencies for faster execution
Follows project's established tooling standards
Automatically handles import organization (complements manual configuration)
Purpose: Provides AI-powered code review and quality checks for pull requests.
Triggers:
Pull request opened
Pull request synchronized (new commits)
Components:
Runtime: ubuntu-latest
Permissions: contents:read, pull-requests:write, id-token:write
AI Model: Uses Claude via Anthropic API
Focus Areas:
Code quality and best practices
Potential bugs or security issues
Performance considerations
Test coverage analysis
Documentation completeness
Runtime: ubuntu-latest
Python Version: 3.9 (note: should be updated to 3.10 for consistency)
Tools: pytest, ruff, mypy
Process: Runs full quality check suite
Integration: Uses mcp__github__add_pull_request_review_comment for inline feedback.
Purpose: Automatically implements solutions when Claude Code bot is assigned to GitHub issues.
Triggers:
Issue assignment to claude-code-bot or issues labeled with claude-code
Process:
Notification: Adds comment explaining that Claude Code will work on the issue
Environment Setup: Python 3.10, UV package manager, project dependencies
Implementation: Claude Code analyzes requirements and implements solution
Quality Assurance: Runs pytest, ruff format, mypy, and ruff check to ensure code quality
Branch Management: Creates new branch for the work
Pull Request: Automatically creates PR when implementation is complete
Key Features:
120-minute timeout for complex issues
Follows project guidelines from CLAUDE.md
Automatic PR creation with issue linking
Progress tracking through GitHub comments
Branch Naming: claude/issue-{number}-{description}
Purpose: Automated dependency updates across multiple ecosystems.
Schedule: Weekly updates on different days to distribute load:
Monday 09:00 UTC: Python dependencies
Tuesday 09:00 UTC: Docker dependencies
Wednesday 09:00 UTC: GitHub Actions
Ecosystem: pip
Grouping Strategy:
Production: proxmoxer, pydantic, fastmcp (minor/patch only)
Development: pytest*, ruff, mypy (minor/patch only)
Major Version Protection: Critical dependencies are protected from major updates
Labels: dependencies, python
Assignee: @basher83
Ecosystem: docker
Target: Root directory Dockerfile
Labels: dependencies, docker
Commit Prefix: docker:
Ecosystem: github-actions
Target: .github/workflows/ directory
Labels: dependencies, github-actions
Commit Prefix: ci:
Security Features:
Major version updates require manual review
Automatic assignment to maintainers
Consistent labeling for easy filtering
Version: 0.1.x
Configuration: Line length 88 characters (Python standard)
Formatting Usage: ruff format .
Linting Usage: ruff check . --fix
Integration: Automatic via autofix.ci workflow
Version: 0.1.x
Rules: E (errors), F (pyflakes), B (bugbear), I (import sorting)
Target: Python 3.10+
Usage: ruff check . --fix
Import Sorting: Configured for ProxmoxMCP with first-party package recognition
Version: 1.x
Configuration: Strict type checking enabled
Features:
Disallows untyped definitions
Warns on unused ignores and redundant casts
Checks untyped definitions
Usage: mypy .
Version: 7.x
Mode: Strict asyncio mode
Extensions: pytest-asyncio for async test support
Usage: pytest
Purpose: Fast Python package installation and environment management
Features: Caching, lock files, virtual environment management
Integration: Used in all CI workflows for consistent dependency management
All pull requests must pass:
autofix.ci: Automatic code formatting and linting
Claude Auto Review: AI-powered code review
Quality Checks: Full test suite and type checking
While not enforced, developers can optionally use:
Create Feature Branch: git checkout -b feature/description
Make Changes: Implement your feature or fix
Local Testing: Run quality checks locally
Push Changes: git push origin feature/description
Create PR: GitHub will trigger autofix.ci and Claude review
Address Feedback: Respond to AI and human reviewer comments
Merge: Once approved and checks pass
Create Issue: Use GitHub issue templates
Label for Claude: Add claude-code label or assign to claude-code-bot
Automatic Implementation: Claude Code will work on the issue
Review PR: Review the automatically created pull request
Merge: Approve and merge when satisfied
Python Version: 3.10+
Code Style: Ruff formatting (88 character line length)
Import Organization: Automated via ruff isort
Type Hints: Required for all functions and methods
Testing: Pytest with async support
Documentation: Docstrings for all public functions
Follow the established commit template (.gitmessage):
Commit Types:
feat: New features
fix: Bug fixes
security: Security improvements
config: Configuration changes
docker: Container/deployment changes
refactor: Code refactoring
test: Test additions/updates
docs: Documentation updates
ci: CI/CD changes
deps: Dependency updates
Check that the workflow file is named exactly autofix.yml
Verify the autofix.ci app is installed on the repository
Ensure branch protection rules allow autofix commits
Verify the claude-code label exists in the repository
Check that ANTHROPIC_API_KEY secret is configured
Ensure issue templates are being used correctly
Run checks locally first: pytest && ruff format . && mypy . && ruff check .
Check for Python version mismatch (should be 3.10+)
Verify all dev dependencies are installed
Check Dependabot configuration syntax
Verify repository permissions for Dependabot
Review ignored dependencies list
Documentation: Check this file and CLAUDE.md
Issues: Create GitHub issue with question label
Discussions: Use GitHub Discussions for broader topics
Security: Use GitHub Security tab for security-related issues
Release Automation: Automated semantic versioning and releases
Security Scanning: CodeQL and dependency vulnerability scanning
Performance Testing: Automated performance regression testing
Documentation: Automated API documentation generation
Integration Testing: End-to-end testing with mock Proxmox environments
.github/workflows/autofix.yml: autofix.ci configuration
.github/workflows/claude-auto-review.yml: AI code review
.github/workflows/claude-issue-assignment.yml: Automated issue resolution
.github/dependabot.yml: Dependency update configuration
pyproject.toml: Python project configuration and tool settings
CLAUDE.md: Development commands and project guidelines
.gitmessage: Commit message template
This workflow documentation is maintained alongside the codebase. When adding new workflows or modifying existing ones, please update this document accordingly.
# Create and activate virtual environment
uv venv
source .venv/bin/activate # Linux/macOS
.\.venv\Scripts\Activate.ps1 # Windows
# Install with development dependencies
uv pip install -e ".[dev]"# Run individual tools
pytest # Run tests
ruff format . # Format code
mypy . # Type checking
ruff check . # Linting
ruff check . --fix # Fix linting issues
# Combined quality check (recommended)
pytest && ruff format . && mypy . && ruff check .# Install pre-commit hooks (optional)
pip install pre-commit
pre-commit installtype: brief description (max 50 chars)
Detailed explanation of what and why (not how).
Include impact on ProxmoxMCP components.
Wrap at 72 characters.
Fixes #issue-number
Co-authored-by: Name <email@example.com>This document describes the comprehensive testing capabilities available in ProxmoxMCP through the enhanced Taskfile.yml configuration.
ProxmoxMCP provides a sophisticated testing workflow that supports different testing scenarios, intelligent dependency management, and developer-friendly output. The testing system is designed to accommodate both rapid development cycles and comprehensive validation.
task testDescription: Run all tests with enhanced validation and informative output.
Features:
Comprehensive test suite execution (71 tests)
Enhanced output with progress indicators
Improved error reporting with --tb=short
Clear completion summary
Use Cases:
Pre-commit validation
Full codebase testing
CI/CD pipeline execution
task test:unitDescription: Run unit tests only with focused output.
Features:
Explicit unit test execution
Focused on tests/ directory
Short traceback format for faster debugging
Use Cases:
Development workflow testing
Quick validation during coding
Focused debugging sessions
task test:coverageDescription: Run tests with coverage reporting (intelligent dependency handling).
Features:
Automatic pytest-cov detection
Graceful fallback when coverage tools unavailable
HTML and terminal coverage reports
80% coverage threshold enforcement
Dependencies:
Use Cases:
Code coverage analysis
Quality assurance validation
Identifying untested code paths
task test:watchDescription: Run tests in watch mode for continuous development.
Features:
Automatic pytest-watch detection
Graceful fallback to single test run
Installation guidance for watch mode
Continuous testing during development
Dependencies:
Use Cases:
Test-driven development (TDD)
Continuous validation during coding
Rapid feedback loops
task test:securityDescription: Run security-focused test subset.
Features:
Filters tests with security keywords (encrypt, security, auth)
Focuses on authentication and encryption functionality
Faster execution for security validation
Use Cases:
Security-focused development
Encryption feature validation
Authentication flow testing
task test:toolsDescription: Run MCP tools tests.
Features:
Tests MCP server functionality
Validates VM console operations
Focuses on tool implementations
Quick validation of MCP protocol compliance
Use Cases:
MCP tool development
API integration validation
Tool functionality verification
task test:configDescription: Run configuration and encryption tests.
Features:
Tests configuration loading and validation
Validates encryption/decryption functionality
Focuses on config management
Covers 42 configuration-related tests
Use Cases:
Configuration system development
Encryption feature development
Config validation testing
task test:integrationDescription: Placeholder for integration tests (future implementation).
Features:
Guidance for integration test setup
Proxmox connection requirements
Future implementation roadmap
Clear setup instructions
Use Cases:
End-to-end testing (when implemented)
Real Proxmox API validation
Integration verification
Located in pyproject.toml:
Test Directory: tests/
Test Files: test_*.py
Test Functions: test_*
✅ Configuration loading and validation
✅ Encryption and security functionality
✅ MCP server implementation
✅ VM console operations
❌ AI diagnostic tools (tools/ai_diagnostics.py)
❌ Formatting modules (formatting/)
❌ Core Proxmox functionality (core/proxmox.py)
The testing system automatically detects optional dependencies and provides helpful fallbacks:
When dependencies are missing, the system provides exact installation commands:
The testing workflow integrates seamlessly with VS Code:
Test discovery works automatically
Debugging support for individual tests
Coverage highlighting with coverage extensions
Testing is integrated into git workflows:
Pre-commit hooks run quality checks
Push hooks can run full test suite
CI/CD integration validates all changes
Testing works in Docker environments:
Full test suite: ~6-8 seconds (71 tests)
Security subset: ~2-3 seconds (42 tests)
Tools subset: ~1-2 seconds (focused tests)
Config subset: ~3-4 seconds (42 tests)
Use focused test subsets during development
Leverage watch mode for continuous testing
Run full suite only for pre-commit/CI
Use coverage analysis periodically, not continuously
The Taskfile automatically configures PYTHONPATH:
Ensure you're using the correct environment:
Integration test implementation
Performance benchmarking
Load testing capabilities
Enhanced security testing
Testing improvements align with project roadmap:
Phase 1: Core component coverage expansion
Phase 2: Integration testing implementation
Phase 3: Performance and load testing
Phase 4: Advanced security testing
For detailed future improvements, see .
Use task test:watch during active development
Run focused subsets (test:security, test:tools) for quick feedback
Use task test:coverage periodically to identify coverage gaps
Use task ci for comprehensive local validation
Ensure all dependencies are properly locked in uv.lock
Test in clean environments to catch dependency issues
Monitor test execution times and optimize as needed
Share testing patterns and workflows with team members
Document any new test categories or patterns
Keep testing dependencies up to date
Contribute to test coverage improvements
This comprehensive testing workflow ensures high code quality, rapid development feedback, and reliable validation of ProxmoxMCP functionality across all components.
Async Support: Full async/await support enabled
tools/node.py, tools/storage.py, etc.)Run task pre-commit before committing changes
task testtask test:unittask test:coverageuv add pytest-cov --group devtask test:watchuv add pytest-watch --group devtask test:securitytask test:toolstask test:configtask test:integration# 1. Start watch mode for continuous testing
task test:watch
# 2. Make code changes
# 3. Tests run automatically
# 4. Run focused tests for specific areas
task test:security # For security features
task test:tools # For MCP tools
task test:config # For configuration# 1. Run comprehensive pre-commit checks
task pre-commit
# This includes:
# - Code formatting (black)
# - Linting with auto-fix (ruff)
# - Type checking (mypy)
# - Development YAML linting
# - All tests pass validation# 1. Install coverage dependencies
uv add pytest-cov --group dev
# 2. Run coverage analysis
task test:coverage
# 3. Review HTML coverage report
open htmlcov/index.html # macOS/Linux
start htmlcov/index.html # Windows# Simulate full CI pipeline locally
task ci
# This runs:
# - All code quality checks (task check)
# - Complete test suite (task test)
# - Comprehensive validation# Test specific components during development
task test:security # Security features
task test:tools # MCP tools
task test:config # Configuration system[tool.pytest.ini_options]
asyncio_mode = "strict"
testpaths = ["tests"]
python_files = ["test_*.py"]
addopts = "-v"# Automatic detection and fallback
if uv run python -c "import pytest_cov" 2>/dev/null; then
# Run with coverage
uv run pytest --cov=src --cov-report=html
else
# Fallback with installation hint
echo "💡 Install with: uv add pytest-cov --group dev"
uv run pytest -v
fi# Automatic detection and fallback
if uv run python -c "import pytest_watch" 2>/dev/null; then
# Run in watch mode
uv run pytest-watch
else
# Fallback with guidance
echo "🔄 Running tests once instead..."
uv run pytest -v
fi# Coverage tools
uv add pytest-cov --group dev
# Watch mode tools
uv add pytest-watch --group dev
# Future performance testing
uv add pytest-benchmark --group dev# Build and test in Docker
docker compose up --build
docker compose exec app task test# Ensure you're in the project root
cd /path/to/ProxmoxMCP
task test# Install all development dependencies
uv sync --extra dev
# Install specific testing dependencies
uv add pytest-cov pytest-watch --group dev# Manually install coverage tools
uv add pytest-cov --group dev
# Verify installation
uv run python -c "import pytest_cov; print('Coverage tools installed')"# Ensure asyncio mode is configured in pyproject.toml
[tool.pytest.ini_options]
asyncio_mode = "strict"env:
PYTHONPATH: "src:{{.PYTHONPATH}}"# Activate UV environment
source .venv/bin/activate # Linux/macOS
.\.venv\Scripts\Activate.ps1 # Windows
# Or use UV directly
uv run task testThis document tracks the implementation of Claude Code SDK integration into ProxmoxMCP to create intelligent, AI-powered infrastructure management capabilities. The integration will transform ProxmoxMCP from a basic management tool into an intelligent infrastructure advisor.
Add AI-powered diagnostic capabilities to ProxmoxMCP
Provide intelligent cluster health analysis and recommendations
Enable automated VM issue diagnosis and troubleshooting
Implement resource optimization suggestions
Integration of Claude Code SDK for AI analysis
Four new MCP tools for intelligent diagnostics
Comprehensive data collection from Proxmox APIs
Rich formatted output using existing ProxmoxTemplates
Target: Establish project structure and dependencies Completed: 2025-06-17
Acceptance Criteria: ✅ All met
Project dependencies properly configured
Development environment supports Claude Code SDK
Basic integration patterns validated
Target: Implement AI diagnostic tools Completed: 2025-06-17
Acceptance Criteria: ✅ All met
All four AI diagnostic tools implemented with graceful fallback
Data collection methods working with real Proxmox APIs
Claude Code SDK properly integrated with error handling
Rich formatted output consistent with existing tools
Target: Register tools with MCP server Completed: 2025-06-17
Acceptance Criteria: ✅ All met
All tools properly registered with MCP server
Tool descriptions follow existing patterns
Comprehensive error handling implemented
Logging consistent with existing tools
Target: Comprehensive testing and quality assurance Completed: 2025-06-17
Acceptance Criteria: ✅ Core criteria met
All quality checks pass ✅
Type safety enforced ✅
Code formatting standardized ✅
Integration tested ✅
Target: Complete documentation and prepare for release
Acceptance Criteria:
Complete user documentation
Usage examples for all AI tools
Configuration guide for Claude Code SDK
Troubleshooting documentation
Target: Extend AI capabilities to VM console operationsPriority: Medium - Builds on successful Phase 1-4 implementation
Integration Strategy: Enhance existing architecture rather than create new classes
Acceptance Criteria:
Integration maintains existing architecture patterns
Only safe, read-only diagnostic commands executed automatically
User retains control over command execution and analysis
Graceful fallback when Claude SDK unavailable
Safety Principles:
User Control: Suggest commands rather than auto-execute
Safety First: Only execute read-only, safe diagnostic commands
Transparency: Clear indication of AI vs system-generated recommendations
Fallback: Maintain functionality when AI unavailable
Target: Extend AI capabilities to configuration management and optimizationPriority: High Value - Enterprise focused capabilities
Scope: Selective integration of configuration management features
Configuration validation against best practices
VM optimization recommendations with specific parameters
Security configuration auditing with compliance frameworks
Template generation for standardized deployments
Integration Strategy: Extend existing AIProxmoxDiagnostics classTimeline: Post Phase 6 completion, based on user demand and enterprise requirements
Data Collection: Gather comprehensive metrics from Proxmox APIs
AI Analysis: Send structured data to Claude Code SDK with specialized prompts
Response Processing: Stream and format AI-generated insights
Output Formatting: Use ProxmoxTemplates for consistent presentation
Base Class: Inherits from ProxmoxTool
Dependencies: Claude Code SDK, existing ProxmoxAPI patterns
Methods: Four main diagnostic tools plus data collection helpers
Configuration
Cluster Metrics: Nodes, VMs, storage, network status
VM Diagnostics: Configuration, performance, logs, statistics
Resource Metrics: Utilization, capacity, optimization opportunities
Security Metrics: Authentication, access controls, network security
System Prompts: Specialized for Proxmox infrastructure analysis
Streaming: Async response processing for real-time analysis
Error Handling: Fallback mechanisms for SDK unavailability
Rate Limiting: Proper handling of API limits and retries
Inheritance: ProxmoxTool base class for consistency
Claude SDK Integration: ClaudeCodeOptions with Proxmox-specific system prompts
Graceful Fallback: CLAUDE_SDK_AVAILABLE flag with basic analysis methods
Comprehensive Data Collection: 400+ lines of Proxmox API data gathering
_collect_cluster_metrics(): Node status, VM lists, storage pools, cluster status
_collect_vm_diagnostics(): VM config, performance metrics, guest agent data, snapshots
_collect_resource_metrics(): Utilization calculations, capacity analysis
Async Streaming: async for message in query() pattern
System Prompts: Expert Proxmox administrator persona with actionable focus
Error Handling: Try/catch with detailed logging and RuntimeError propagation
Data Collection: Mock Proxmox API responses
AI Integration: Mock Claude Code SDK responses
Error Handling: Test various failure scenarios
Output Formatting: Validate template rendering
End-to-End: Full diagnostic workflows
Performance: Large cluster simulation
Security: Sensitive data handling
Compatibility: Different Proxmox versions
Code Quality: Black formatting, mypy type checking
Test Coverage: Minimum 80% coverage requirement
Documentation: Comprehensive docstrings and examples
Security: Secret handling and input validation
CLAUDE_CODE_API_KEY: Authentication for Claude Code SDK
PROXMOX_MCP_AI_ENABLED: Enable/disable AI features
PROXMOX_MCP_AI_TIMEOUT: Analysis timeout setting
No Sensitive Data: Avoid sending credentials or secrets to AI
Data Sanitization: Clean sensitive information from analysis data
Local Processing: Option for on-premises AI analysis
Permission Validation: Ensure user has proper Proxmox permissions
Audit Logging: Log all AI analysis requests and responses
Rate Limiting: Prevent abuse of AI analysis features
Graceful Degradation: Function without AI when SDK unavailable
Fallback Modes: Basic analysis when AI fails
Comprehensive Logging: Detailed error tracking and debugging
Graceful Fallback: CLAUDE_SDK_AVAILABLE pattern works excellently
Type Safety: Mypy compliance required careful data structure typing
Architecture: ProxmoxTool inheritance maintained consistency
Error Handling: Comprehensive try/catch with specific error messages
Based on the AI-Enhanced VM Console evaluation, these features provide significant value:
Intelligent Command Suggestion: AI recommends diagnostic commands based on issue descriptions
Output Analysis: AI interprets command results and suggests follow-up actions
Troubleshooting Workflows: Automated diagnostic sequences with AI guidance
VM Performance Profiling: AI analysis of resource utilization patterns
Optimization Recommendations: Specific configuration changes with impact analysis
Bottleneck Identification: Intelligent identification of performance constraints
Enhance Existing Classes: Extend AIProxmoxDiagnostics rather than create new classes
Safety-First Approach: User-controlled command execution with read-only defaults
Consistent Architecture: Maintain ProxmoxTool patterns and MCP integration
Based on configuration management analysis, these capabilities provide significant enterprise value:
Cluster Configuration Validation: Automated validation against Proxmox best practices
VM Configuration Optimization: Individual VM tuning recommendations with specific parameters
Security Configuration Auditing: Comprehensive security posture analysis with compliance frameworks
Performance Configuration Analysis: Optimization recommendations for storage, network, and compute
Configuration Template Generator: AI-generated templates for specific use cases and requirements
Best Practice Implementation: Automated application of industry-standard configurations
Compliance Templates: Pre-built templates for security frameworks (CIS, NIST, SOC2)
Scaling Configuration Guidance: Multi-node and enterprise deployment recommendations
Comprehensive Config Harvesting: Datacenter, user permissions, storage, firewall, HA, backup policies
Node-Level Security Configs: DNS, certificates, time synchronization, security settings
Cross-Component Analysis: Configuration interdependency analysis and optimization
Historical Configuration Tracking: Change analysis and configuration drift detection
Risk Assessment: CVSS-style scoring for configuration vulnerabilities
Change Impact Analysis: Predict effects of configuration modifications
Compliance Reporting: Automated compliance status against security frameworks
Configuration Backup Recommendations: Backup and disaster recovery configuration validation
Extend AIProxmoxDiagnostics: Add configuration methods rather than separate class
Security-First Data Handling: Careful sanitization of sensitive configuration data
Gradual Feature Implementation: Prioritize highest-impact configuration validations
Enterprise Focus: Target enterprise use cases with compliance and security priorities
Value Justification: Configuration management represents the natural evolution from reactive diagnostics to proactive infrastructure optimization, providing substantial enterprise value through automated best practices, security compliance, and performance optimization.
Predictive Analysis: Forecast resource needs and potential issues
Automated Remediation: AI-suggested fix implementations
Trend Analysis: Historical data analysis and pattern recognition
Custom Analysis: User-defined diagnostic queries
Multi-Cluster: Analysis across multiple Proxmox clusters
External Data: Integration with monitoring systems
Reporting: Automated report generation and scheduling
Alerts: AI-powered alerting and notification system
Performance: Analysis completion time < 30 seconds
Accuracy: AI recommendations validated by experts
Reliability: 99%+ uptime for AI diagnostic features
Coverage: Support for all major Proxmox configurations
Adoption: Usage of AI diagnostic tools
Satisfaction: User feedback on AI recommendations
Effectiveness: Problems solved using AI insights
Time Savings: Reduction in manual diagnostic time
This Claude Code SDK integration will transform ProxmoxMCP into an intelligent infrastructure management platform, providing AI-powered insights that help administrators optimize, secure, and maintain their Proxmox environments more effectively. The phased implementation approach ensures quality and maintainability while delivering value at each milestone.
Document Version: 2.0 Last Updated: 2025-06-17 (Updated with Phase 1-4 completion + Phase 6-7 planning) Next Review: Upon completion of Phase 5 (Documentation) and start of Phase 6 (Enhanced VM Console Features)
Extended Vision: Evolve into comprehensive AI-powered configuration management platform
Full test coverage and documentation
analyze_cluster_health - Comprehensive cluster analysisPerformance analysis provides actionable optimization insights
Error Handling: Graceful degradation and comprehensive logging
Rich Output Formatting: Emoji-enhanced, structured analysis reports
Type Safety: Full mypy compliance with proper type annotations
_collect_security_metrics(): User accounts, firewall config, datacenter settings
Project planning and documentation structure
Data Collection: Robust API failure handling for partial data scenarios
User-Controlled Analysis: Allow users to specify scope and depth of configuration analysis
ProxmoxMCP Server
├── Existing Tools (nodes, VMs, storage, cluster)
├── AI Diagnostic Tools ✅ IMPLEMENTED
│ ├── AIProxmoxDiagnostics (base class) - 736 lines
│ ├── Data Collection Layer ✅
│ │ ├── _collect_cluster_metrics() - Nodes, VMs, storage, cluster status
│ │ ├── _collect_vm_diagnostics() - VM config, performance, agent data
│ │ ├── _collect_resource_metrics() - Resource utilization calculations
│ │ └── _collect_security_metrics() - Users, firewall, datacenter config
│ ├── Claude Code SDK Integration ✅
│ │ ├── Query Processing - Async streaming with ClaudeCodeOptions
│ │ ├── Response Streaming - Real-time AI analysis delivery
│ │ ├── Error Handling - Graceful fallback when SDK unavailable
│ │ └── System Prompts - Proxmox expertise specialization
│ └── Output Formatting ✅
│ ├── AI Analysis Templates - Rich formatted responses with emojis
│ ├── ProxmoxTemplates Integration - Consistent with existing tools
│ └── Fallback Analysis - Basic insights when AI unavailable
└── Enhanced VM Console Features 🔄 PLANNED (Phase 6)
├── Command Analysis Integration
├── Performance Diagnostics Extension
└── Intelligent Troubleshooting Workflowssrc/proxmox_mcp/
├── tools/
│ ├── ai_diagnostics.py # ✅ NEW: 736 lines, AI diagnostic tools
│ ├── definitions.py # ✅ MODIFIED: Added 4 AI tool descriptions
│ ├── base.py # ✅ MODIFIED: Fixed type annotations for template mapping
│ └── __init__.py # ✅ MODIFIED: Export AIProxmoxDiagnostics class
├── server.py # ✅ MODIFIED: Registered 4 AI tools with async handlers
└── config/
└── settings.py # Future: AI configuration options
docs/
└── claude-code-sdk-integration.md # ✅ NEW: This tracking document (updated)
pyproject.toml # ✅ MODIFIED: Added claude-code-sdk>=1.0.0,<2.0.0
tests/ # Future: AI diagnostic testsdependencies = [
# Existing dependencies...
"claude-code-sdk>=1.0.0,<2.0.0", # NEW: AI analysis capability
]# New tools to register in server.py
@self.mcp.tool(description=ANALYZE_CLUSTER_HEALTH_DESC)
async def analyze_cluster_health() -> List[TextContent]:
return await self.ai_diagnostics.analyze_cluster_health()
@self.mcp.tool(description=DIAGNOSE_VM_ISSUES_DESC)
async def diagnose_vm_issues(
node: str, vmid: str
) -> List[TextContent]:
return await self.ai_diagnostics.diagnose_vm_issues(node, vmid)
@self.mcp.tool(description=SUGGEST_RESOURCE_OPTIMIZATION_DESC)
async def suggest_resource_optimization() -> List[TextContent]:
return await self.ai_diagnostics.suggest_resource_optimization()
@self.mcp.tool(description=ANALYZE_SECURITY_POSTURE_DESC)
async def analyze_security_posture() -> List[TextContent]:
return await self.ai_diagnostics.analyze_security_posture()# Optional configuration in settings.py
class AISettings(BaseModel):
claude_sdk_enabled: bool = True
max_analysis_timeout: int = 60 # seconds
system_prompt_template: str = "default"
max_response_tokens: int = 4000
stream_responses: bool = TrueBased on Codacy analysis, this document outlines the comprehensive improvements made to our pre-commit hooks system.
We've enhanced your existing task-based workflow with proper pre-commit hooks that automatically catch and fix the issues identified by Codacy analysis.
✅ Formal pre-commit hooks (.pre-commit-config.yaml)
✅ Security scanning (bandit, safety)
✅ Dependency vulnerability checks (trivy-style scanning)
✅ Dockerfile linting (hadolint)
✅ Shell script linting (shellcheck)
✅ Custom security checks (shell=True detection)
✅ Complexity analysis (radon)
✅ Enhanced task commands (security, complexity, hooks management)
Addresses: Issues #61 (shell=True), #64 (hardcoded credentials)
Addresses: Issue #65 (dependency CVEs)
Addresses: Issue #61 (prevents future shell=True usage)
Addresses: Issue #62 (method complexity)
Addresses: Issue #66 (Dockerfile security)
black - Code formatting
ruff - Linting and import sorting
mypy - Type checking
bandit - Security scanning
safety - Dependency vulnerabilities
complexity-check - Code complexity analysis
check-test-credentials - Test credential validation
hadolint - Dockerfile linting
shellcheck - Shell script linting
yamllint - YAML formatting
.pre-commit-config.yamlMain configuration with all hooks and settings.
pyproject.toml (Enhanced)Taskfile.yml (Enhanced)Added security, complexity, and hooks management tasks.
Run setup: ./scripts/setup-precommit.sh
Address critical issues: Focus on GitHub issues #61 and #65
Test workflow: Make a test commit to verify hooks work
Weekly: task hooks:update to update hook versions
Monthly: pre-commit run safety --hook-stage manual for dependency checks
Before releases: task complexity to check code quality trends
Your existing autofix workflow will work seamlessly with these changes:
Consider adding:
Automatic detection of shell=True vulnerabilities
Dependency scanning for known CVEs
Credential leak prevention in test files
Complexity monitoring to prevent technical debt
Consistent formatting across all files
Type safety enforcement
Faster feedback - catch issues before CI
Automatic fixes for many issues
Clear error messages with fix suggestions
Standardized workflow across all developers
Automated enforcement of coding standards
Reduced code review overhead
🎉 Your pre-commit setup now addresses all Codacy issues while maintaining your existing workflow!
For questions or issues, refer to:
(Codacy issues)
Comprehensive milestone planning documentation including current milestones, management guidelines, and best practices.
Last Updated: January 6, 2025
This section outlines the release milestones for ProxmoxMCP, including goals, success criteria, timelines, and risk assessments for each phase of development.
MCP Protocol Support
Current Target: MCP Protocol v0.1.0
Future Compatibility: MCP Protocol v1.0.0 (planned for v1.2.0)
Proxmox VE Compatibility
Primary Support: Proxmox VE 8.x
Secondary Support: Proxmox VE 7.4+ (limited features)
API Requirements: Proxmox API v2.0+
Due by August 15, 2025 | Current Progress: 0%
🔧 Stabilization and hardening phase preparing for first stable release
Goals
Establish a solid foundation for the v1.0.0 release through comprehensive testing, security improvements, and documentation completion. Focus on core functionality stability and production readiness preparation.
Success Criteria
✅ Security Foundation: Token encryption implemented with 100% coverage
✅ Core Stability: 95%+ test coverage for all core tools (node, VM, storage, cluster)
✅ Documentation: Complete API documentation with examples for all tools
✅ Docker Security: Non-root container execution with security scanning passed
Focus Areas
Security Hardening: Input validation, token encryption, SSL enforcement
Testing Infrastructure: Automated testing with mocked Proxmox environments
Documentation: User guides, API documentation, deployment examples
Performance Optimization: Response time improvements and resource usage optimization
Dependencies
Proxmox VE: 7.4+ compatibility testing
Python: 3.10+ support with async/await patterns
MCP Protocol: v0.1.0 compliance verification
Release Planning
Feature Freeze: July 15, 2025
Beta Release: July 30, 2025
Release Candidate: August 10, 2025
Final Release: August 15, 2025
Risk Assessment
Technical Risks: Proxmox API changes, MCP protocol updates
Mitigation: Version pinning, compatibility testing, fallback implementations
Resource Risk: Documentation completion timeline
Mitigation: Automated documentation generation, community contributions
Target Users
Home lab enthusiasts, small business IT administrators, automation developers seeking stable ProxmoxMCP foundation
Due by October 31, 2025 | Current Progress: 0%
🎯 First stable release of ProxmoxMCP with production-ready security and functionality
Goals
Deliver a production-ready MCP server for Proxmox VE management with enterprise-grade security, comprehensive tool coverage, and complete documentation suitable for production deployments.
Success Criteria
✅ Security Compliance: OWASP security guidelines compliance with penetration testing passed
✅ Token Encryption: AES-256 encryption for all stored credentials with key rotation support
✅ SSL Security: SSL verification enabled by default with certificate validation
✅ Command Security: VM command validation and sanitization with allowlist enforcement
Focus Areas
Production Security: Comprehensive security audit and vulnerability assessment
Tool Completeness: Full coverage of essential Proxmox VE management operations
Operational Excellence: Monitoring, logging, health checks, graceful degradation
User Experience: Intuitive tool usage with clear error messages and examples
Dependencies
v0.9.0 Completion: All stabilization goals met
Security Audit: Third-party security assessment completed
MCP Protocol: Stable v0.1.0 implementation
Release Planning
Feature Freeze: September 15, 2025
Security Audit: September 30, 2025
Beta Release: October 10, 2025
Release Candidate: October 25, 2025
Risk Assessment
Security Risk: Vulnerability discovery during audit
Mitigation: Early security testing, regular vulnerability scans, security-first development
Performance Risk: Latency issues under load
Mitigation: Performance testing, caching strategies, connection pooling
Target Users
Home lab enthusiasts, small business IT, automation developers, early enterprise adopters
Due by January 31, 2026 | Current Progress: 0%
🚀 Enhanced features and user experience improvements for power users
Goals
Expand tool coverage with advanced Proxmox features, enhance user experience through improved formatting and error handling, and establish community integration examples for broader adoption.
Success Criteria
✅ Extended Tool Coverage: Backup management, cluster operations, and networking tools (30+ tools total)
✅ Advanced Theming: Customizable output themes with color schemes and emoji controls
✅ Error Intelligence: Context-aware error messages with suggested resolutions (80% error self-help)
✅ Performance Optimization
Focus Areas
Tool Expansion: Cluster management, backup operations, network configuration, user management
User Experience: Rich formatting, intelligent error handling, progress indicators
Performance: Caching strategies, connection pooling, async optimizations
Integrations: MCP client examples, automation workflows, third-party tool integration
Dependencies
v1.0.0 Stability: Proven production reliability
Proxmox VE: 8.x feature compatibility
Community Feedback: User experience insights from v1.0.0 adoption
Release Planning
Feature Freeze: December 15, 2025
Beta Release: January 10, 2026
Release Candidate: January 25, 2026
Final Release: January 31, 2026
Risk Assessment
Feature Scope Risk: Over-ambitious feature set affecting quality
Mitigation: Phased feature delivery, MVP approach, continuous testing
Performance Risk: Feature additions impacting response times
Mitigation: Performance budgets, benchmarking, optimization sprints
Target Users
Power users, automation specialists, enterprise evaluators, DevOps teams
Due by April 30, 2026 | Current Progress: 0%
🏢 Enterprise-grade features and production readiness for large-scale deployments
Goals
Transform ProxmoxMCP into an enterprise-ready solution with comprehensive monitoring, scalability features, and advanced deployment options suitable for production enterprise environments.
Success Criteria
✅ Metrics Integration: Prometheus metrics with Grafana dashboards and 50+ monitored metrics
✅ Container Orchestration: Kubernetes deployment with Helm charts and operators
✅ Multi-Cluster Support: Management of 10+ Proxmox clusters with centralized control
✅ Rate Limiting: Configurable throttling with 99.99% availability under load
Focus Areas
Enterprise Monitoring: Metrics collection, alerting, dashboards, SLA monitoring
Scalability: Multi-cluster support, load balancing, horizontal scaling
Security: Advanced authentication, authorization, audit logging, compliance
Operations: Kubernetes deployment, CI/CD integration, automated scaling
Dependencies
v1.1.0 Features: Enhanced tool coverage and performance optimizations
Kubernetes: Production-ready Kubernetes cluster for testing
Enterprise Features: LDAP/SAML integration requirements
Release Planning
Feature Freeze: March 15, 2026
Enterprise Testing: March 30, 2026
Beta Release: April 10, 2026
Release Candidate: April 25, 2026
Risk Assessment
Complexity Risk: Enterprise features increasing system complexity
Mitigation: Modular architecture, feature flags, gradual rollout
Scalability Risk: Performance degradation with large-scale deployments
Mitigation: Load testing, performance monitoring, auto-scaling
Target Users
Enterprise IT departments, DevOps teams, MSPs, large-scale production deployments
Major Versions: Breaking changes allowed with 6-month deprecation notice
Minor Versions: Backwards compatible with deprecated feature warnings
Patch Versions: No breaking changes, security fixes prioritized
Vulnerability Response: 24-hour acknowledgment, 7-day resolution for critical issues
Security Audits: Quarterly security reviews starting with v1.0.0
Dependency Management: Automated dependency scanning and updates
Feedback Cycles: Monthly community calls during development phases
Beta Testing: Open beta programs for each major release
Documentation: Community-contributed examples and tutorials encouraged
Code Quality: Maintain >90% test coverage across all releases
Refactoring: Dedicated 20% time allocation for technical debt reduction
Performance: Continuous benchmarking and optimization efforts
Milestones should be:
Release-focused: Tied to specific software releases (v1.0, v1.1, etc.)
Time-bound: Have clear due dates
Goal-oriented: Represent meaningful project achievements
User-facing: Deliver value to end users
Examples for ProxmoxMCP:
v1.0.0 - Stable Release
v1.1.0 - Enhanced Security
v2.0.0 - Breaking Changes
1. Use Semantic Versioning
2. Set Realistic Due Dates
Based on team capacity and complexity
Allow buffer time for testing and documentation
Review and adjust dates as needed
3. Scope Appropriately
Small milestones (2-4 weeks): 5-15 issues
Medium milestones (1-2 months): 15-30 issues
Large milestones (quarterly): 30+ issues
4. Balance Issue Types
Current State Assessment:
You're at an early stage (pre-v1.0)
Focus should be on stability and core features
Recommended Milestones:
1. v0.9.0 - Pre-Release Stabilization (Due: July 15, 2025)
Security improvements (#41 type issues)
Core functionality testing
Documentation completion
Docker optimization
2. v1.0.0 - First Stable Release (Due: August 30, 2025)
All critical security issues resolved
Comprehensive documentation
Production-ready Docker setup
Basic monitoring/health checks
3. v1.1.0 - Enhanced Features (Due: October 31, 2025)
Additional Proxmox tools
Improved error handling
Performance optimizations
Community-requested features
1. Creation Process
2. Issue Assignment
Assign issues during sprint planning
Use labels to categorize: priority:high, effort:medium
Review assignments weekly
3. Progress Tracking
Monitor completion percentage
Identify blockers early
Adjust scope if needed
4. Release Preparation
90% complete: Feature freeze
95% complete: Code freeze
100% complete: Release and close milestone
Key Metrics to Monitor
Burn-down rate: Issues closed over time
Scope creep: Issues added after milestone start
Velocity: Average issues completed per week
Quality: Bug rate in releases
GitHub Insights
Use milestone progress bar
Filter issues by milestone
Generate release notes from closed issues
Immediate Actions
Create your first milestone: v1.0.0 - Stable Release
Set realistic timeline: 2-3 months from now
Assign existing issues: Start with security and core features
Document milestone goals: Clear success criteria
Sample Milestone Description
Weekly Reviews
Check milestone progress
Identify blocked issues
Adjust priorities if needed
Monthly Reviews
Assess timeline feasibility
Consider scope adjustments
Plan next milestone
Post-Release Reviews
Analyze what worked/didn't work
Improve estimation accuracy
Update process based on learnings
This document consolidates all milestone planning information for ProxmoxMCP, providing both current milestone details and comprehensive management guidelines.
🎨 Trailing whitespace
trailing-whitespace
✅ Active
Low
🎨 Dead code
ruff
✅ Active
Low
📦 Dependency CVEs
safety
✅ Active
Critical
🐳 Dockerfile issues
hadolint
✅ Active
Medium
📝 YAML formatting
yamllint
✅ Enhanced
Low
check-subprocess-shell - Prevent shell=True
trailing-whitespace - Fix style issues
🚨 shell=True vulnerabilities
bandit, custom hook
✅ Active
Critical
🔒 Hardcoded credentials
bandit
✅ Active
Medium
📐 Code complexity
radon
✅ Active
Medium
✅ Performance Baseline: Sub-200ms response time for standard operations
✅ Error Handling: Comprehensive error handling with user-friendly messages
✅ Configuration Validation: Pydantic models for all configuration with validation
Docker Improvements: Security hardening, health checks, multi-arch support
✅ Documentation Coverage: 100% API documentation with practical examples and tutorials
✅ Container Security: Docker security hardening with vulnerability scanning < 5 medium issues
✅ Health Monitoring: Health check endpoints with 99.9% availability SLA
✅ Tool Coverage: 90%+ of core Proxmox operations supported (nodes, VMs, storage, basic cluster)
✅ Performance: Sub-100ms response time for 95% of operations
✅ Reliability: 99.9% uptime with automatic recovery mechanisms
Deployment Options: Multiple deployment methods (pip, Docker, source)
Final Release: October 31, 2025
Compatibility Risk: Proxmox VE version compatibility issues
Mitigation: Multi-version testing, backwards compatibility maintenance
✅ Integration Examples: Working examples for Cline, VSCode, and 3+ other MCP clients
✅ Configuration Flexibility: Advanced configuration options with environment variable support
✅ API Coverage: 95% of Proxmox VE API endpoints supported for common operations
✅ Async Operations: Full async support for long-running operations with progress tracking
Advanced Features: Batch operations, filtering, advanced querying capabilities
Integration Risk: MCP client compatibility issues
Mitigation: Multi-client testing, compatibility matrix, fallback modes
✅ Enterprise Auth: LDAP/SAML integration with role-based access control (RBAC)
✅ Audit Logging: Comprehensive audit trails with compliance reporting (SOX, GDPR ready)
✅ High Availability: Multi-instance deployment with automatic failover (99.99% uptime)
✅ Scalability: Support for 1000+ VMs across multiple clusters with sub-500ms response times
Reliability: High availability, disaster recovery, backup/restore procedures
Final Release: April 30, 2026
Security Risk: Enterprise authentication integration vulnerabilities
Mitigation: Security audits, penetration testing, compliance validation
Q3 2025 - Performance ImprovementsMilestones
Release planning
v1.0.0, v1.1.0
Projects
Workflow tracking
"Development Roadmap"
Labels
Categorization
bug, enhancement, priority:high
# Run the setup script
./scripts/setup-precommit.sh
# Or manual setup:
uv sync --extra dev
task hooks:setup- repo: https://github.com/PyCQA/bandit
hooks:
- id: bandit
args: [
"-r",
".",
"--skip",
"B101,B601", # Skip assert and shell=True in tests
"--exclude",
"tests/,mem0-mcp/",
]- repo: https://github.com/pyupio/safety
hooks:
- id: safety
stages: [manual] # Run: pre-commit run safety --hook-stage manual- repo: local
hooks:
- id: check-subprocess-shell
entry: bash -c 'if grep -r "shell=True" src/ --include="*.py"; then echo
"❌ Found shell=True in source code!"; exit 1; fi'- id: complexity-check
entry: bash -c 'radon cc src/ --min B --show-complexity'
stages: [manual]- repo: https://github.com/hadolint/hadolint
hooks:
- id: hadolint-docker
args: [--ignore, DL3008, --ignore, SC2028]# Your existing workflow still works
task pre-commit
# New security-focused commands
task security # Run security analysis
task security:deps # Check dependency vulnerabilities
task complexity # Analyze code complexity
# Pre-commit hook management
task hooks:setup # Install hooks
task hooks:run # Run all hooks manually
task hooks:update # Update hook versions# Hooks run automatically on commit
git add .
git commit -m "feat: add new feature"
# ↑ Automatically runs: format, lint, security, complexity checks
# Manual hook execution
pre-commit run --all-files
# Run specific hook
pre-commit run bandit
pre-commit run trailing-whitespace# Check for shell=True vulnerabilities (addresses issue #61)
pre-commit run check-subprocess-shell
# Full security scan
task security
# Dependency vulnerability check (addresses issue #65)
pre-commit run safety --hook-stage manual
# Check test credentials (addresses issue #64)
pre-commit run check-test-credentials --hook-stage manual[project.optional-dependencies]
dev = [
# ... existing tools ...
# New security tools
"bandit>=1.7.0,<2.0.0",
"safety>=3.0.0,<4.0.0",
# Code quality
"radon>=6.0.0,<7.0.0",
"pre-commit>=3.0.0,<4.0.0",
]# To allow shell=True in specific files:
- id: bandit
args: ["--skip", "B101,B601,B602"] # Add B602 to skip more shell issues# Adjust complexity limits:
- id: complexity-check
entry: bash -c 'radon cc src/ --min A --show-complexity' # Stricter (A vs B)- repo: local
hooks:
- id: custom-check
name: Custom security check
entry: ./scripts/custom-security-check.sh
language: system# .github/workflows/autofix.yml already includes:
- name: Run ruff linting with auto-fix
run: uv run ruff check . --fix-only --exit-zero
- name: Run ruff formatting
run: uv run ruff format .- name: Run security checks
run: uv run bandit -r src/ --format custom --skip B101,B601# Skip hooks temporarily (NOT recommended for production)
git commit --no-verify -m "emergency fix"
# Fix specific hook failure
pre-commit run <hook-name> --all-files
# Update hooks if outdated
pre-commit autoupdate# Run only fast hooks
pre-commit run --hook-stage commit
# Skip slow hooks in CI
# (already configured in .pre-commit-config.yaml)v1.0.0 - Major release
v1.1.0 - Minor features
v1.0.1 - Bug fixesTypical milestone composition:
- 60% Features/Enhancements
- 25% Bug fixes
- 10% Documentation
- 5% Technical debt# Using GitHub CLI
# Install the milestones extension
gh extension install valeriobelli/gh-milestone
# Create v1.0.0 milestone
gh milestone create \
--title "v1.0.0 - First Stable Release" \
--due-date "2025-08-15" \
--description "🎯 First stable release of ProxmoxMCP
Goals: Production-ready security, core functionality stability, complete documentation
Success Criteria:
✅ All critical security issues resolved
✅ Token encryption implemented
✅ SSL verification enabled by default
✅ VM command validation and sanitization
✅ Complete documentation with examples
✅ Docker security hardening
✅ Health check endpoints
✅ 90%+ of core tools functional
Target Users: Home lab enthusiasts, small business IT, automation developers"
# Create v1.1.0 milestone
gh milestone create \
--title "v1.1.0 - Enhanced Features" \
--due-date "2025-10-31" \
--description "🚀 Enhanced features and user experience improvements
Goals: Enhanced tool coverage, performance optimizations, community features
Focus Areas:
✅ Additional Proxmox tools (cluster, backup management)
✅ Enhanced formatting and theming
✅ Better error messages and debugging
✅ Performance improvements
✅ Integration examples (Cline, other MCP clients)
✅ Advanced configuration options
Target Users: Power users, automation specialists, enterprise evaluators"
# Create v1.2.0 milestone
gh milestone create \
--title "v1.2.0 - Production Hardening" \
--due-date "2025-12-31" \
--description "🏢 Enterprise-grade features and production readiness
Goals: Enterprise features, monitoring, scalability, deployment options
Focus Areas:
✅ Metrics and monitoring integration
✅ Kubernetes deployment options
✅ Multi-node Proxmox cluster support
✅ Rate limiting and throttling
✅ Advanced authentication options
✅ Logging and audit capabilities
Target Users: Enterprise IT, DevOps teams, production deployments"## v1.0.0 - Stable Release
**Goals:**
- Production-ready security (token encryption, SSL verification)
- Comprehensive tool coverage (VM, node, storage management)
- Complete documentation and examples
- Docker deployment optimization
**Success Criteria:**
- All critical security issues resolved
- 90%+ test coverage
- Documentation complete
- Performance benchmarks met
**Target Users:**
- Home lab enthusiasts
- Small business IT administrators
- Proxmox automation developersOpen Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Type "Tasks: Run Task"
Choose from:
Lint YAML Files
Fix YAML Issues
Check YAML (Strict)
The repository includes a customized yamllint configuration that:
Sets line length to 120 characters (flexible for GitHub Actions)
Uses 2-space indentation
Allows common GitHub Actions truthy values (yes, no, on, off)
Ignores lock files and template directories
Provides warnings instead of errors for line length
The linting automatically finds and checks:
*.yml files
*.yaml files
Excludes: pnpm-lock.yaml, yarn.lock, package-lock.json
Ignores: node_modules, .git, venv, __pycache__
YAML linting is integrated into:
Autofix Workflow (.github/workflows/autofix.yml) - Runs on every PR/push
Dedicated YAML Lint Workflow (.github/workflows/yaml-lint.yml) - Triggered by YAML changes
Add to your development workflow:
Edit .yamllint.yml to customize rules for your needs. See yamllint
documentation for
all available options.
Run task --list to see all available commands:
# On macOS
brew install go-task/tap/go-task
# On Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
# Or download from https://github.com/go-task/task/releases# Install dependencies (including yamllint)
task setup# Lint all YAML files
task yaml:lint
# Show detailed issues
task yaml:fix
# Strict check (exits with error if issues found)
task yaml:check
# Auto-fix all code issues (Python + YAML)
task fix
# Run all quality checks
task check
# Pre-commit style workflow
task pre-commit# Lint all YAML files
./scripts/yaml-lint.sh
# Show detailed issues
./scripts/yaml-lint.sh --fix
# Strict check
./scripts/yaml-lint.sh --check
# Auto-fix spacing issues
./scripts/yaml-autofix.sh# Run before committing
task pre-commit
# Or run full CI simulation
task ci# ❌ Too long
- name: This is a very long line that exceeds the maximum line length limit and should be broken down
# ✅ Fixed
- name: >
This is a very long line that exceeds the maximum line length limit
and should be broken down# ❌ Wrong indentation
steps:
- name: Step 1
run: echo "hello"
# ✅ Correct indentation
steps:
- name: Step 1
run: echo "hello"# ❌ Inconsistent
enabled: True
debug: false
cache: yes
# ✅ Consistent
enabled: true
debug: false
cache: true# Reinstall dependencies
task setup
# or
uv sync --extra dev# Make script executable
chmod +x scripts/yaml-lint.sh
chmod +x scripts/yaml-autofix.shtask: Available tasks for this project:
* default: Show available tasks
* check: Run all code quality checks
* ci: Run CI checks locally
* fix: Auto-fix all fixable issues
* pre-commit: Run pre-commit checks
* quick: Quick development check
* setup: Set up development environment
* yaml:autofix: Auto-fix YAML spacing issues
* yaml:check: Check YAML files (strict mode)
* yaml:fix: Show detailed YAML linting issues
* yaml:lint: Lint all YAML filesEnvironment-based Keys: Master keys stored separately from encrypted data
Backward Compatibility: Existing plain-text configurations continue to work
CLI Tools: Easy-to-use command-line utilities for encryption management
Security Note: The key generation process now includes enhanced security measures that prevent the key from being exposed in terminal history or log files during automatic generation.
ProxmoxMCP supports secure master key rotation for enhanced security compliance and incident response.
Schedule Regular Rotations: Rotate master keys annually or after security incidents
Test Before Production: Always test rotated configurations before deploying
Coordinate Updates: Ensure all systems using the configuration are updated with the new key
Secure Backup Storage: Store configuration backups securely and separately from the new key
Monitor Rotation: Keep audit logs of key rotation activities
PROXMOX_MCP_MASTER_KEY
Master encryption key
Yes (for encrypted configs)
PROXMOX_MCP_CONFIG
Path to config file
Yes
Store Keys Separately: Never store the master key in the same location as encrypted data
Use Environment Variables: Avoid hardcoding keys in scripts or configuration files
Rotate Keys Regularly: Generate new master keys periodically and re-encrypt configurations
Secure Key Storage: Use secure key management systems in production environments
Backup Safely: Ensure encrypted backups include both data and key recovery procedures
Clear Terminal History: After key generation, consider clearing terminal history to prevent exposure
Use CLI Tool: Always use the provided CLI tool for key generation rather than manual methods
Test After Rotation: Always verify configurations work after key rotation before production use
Coordinate Key Updates: Ensure all systems are updated with new keys during rotation
Audit Key Operations: Maintain logs of key generation, rotation, and usage activities
Existing configurations work without changes. To migrate:
Backup Current Config: Always backup your working configuration
Generate Master Key: Create and securely store a master key
Encrypt Configuration: Use the CLI tool to encrypt sensitive values
Update Environment: Set the master key environment variable
Test Thoroughly: Verify the server starts and connects successfully
Clean Up: Securely delete plain text configuration files
"Token decryption failed"
Verify PROXMOX_MCP_MASTER_KEY environment variable is set correctly
Ensure the master key matches the one used for encryption
"Config file not found"
Check PROXMOX_MCP_CONFIG environment variable points to correct file
Verify file permissions and path accessibility
"Invalid encrypted token format"
Encrypted tokens must start with enc: prefix
Verify file wasn't corrupted during transfer or storage
Enable debug logging to troubleshoot encryption issues:
Key rotation is essential for maintaining long-term security. ProxmoxMCP provides comprehensive tools and procedures for safely rotating encryption keys.
Regular Schedule: Annually or as per your organization's security policy
Security Incidents: When compromise is suspected or confirmed
Personnel Changes: After team member departures or role changes
Major Deployments: Before critical releases or infrastructure changes
Compliance Requirements: As mandated by security frameworks (SOC2, ISO27001, etc.)
Before starting key rotation, ensure you have:
Current Access: Ability to decrypt existing configurations
Backup Strategy: Secure backup procedures for configuration files
Testing Environment: Non-production environment for validation
Downtime Window: Planned maintenance window for service restarts
Rollback Plan: Procedures to revert if rotation fails
Team Coordination: All team members aware of the rotation schedule
Prepare Green Environment: Deploy with new keys
Validate Green: Test all functionality
Switch Traffic: Update load balancer/proxy
Monitor: Ensure no errors
Cleanup Blue: Remove old environment after validation
Rotate Keys: Generate new keys for configuration
Update Environment: Set new master key
Restart Service: Restart with new configuration
Validate: Confirm service operational
Update Monitoring: Ensure alerts still function
If key rotation fails, follow these steps:
Document Issue: Record what went wrong
Preserve Evidence: Keep failed configuration for analysis
Review Logs: Check server and application logs
Plan Fix: Address root cause before retry
Schedule Retry: Plan next rotation attempt
Use CLI Tool: Always use the provided encryption utility
Secure Generation: Use cryptographically secure random generation
Document Creation: Log key generation events (not the keys themselves)
Immediate Storage: Store keys in secure key management systems
Separate Storage: Never store keys with encrypted data
Access Control: Implement strict access controls
Encryption at Rest: Encrypt keys in storage systems
Backup Keys: Maintain secure, encrypted backups
Secure Channels: Use encrypted communication for key distribution
Just-in-Time: Provide keys only when needed
Audit Trail: Log key access and distribution
Temporary Access: Use short-lived keys where possible
Secure Deletion: Use cryptographic erasure techniques
Audit Cleanup: Remove keys from all systems
Documentation: Update key management records
Compliance: Follow data retention policies
If you lose access to your master key:
Check Backups: Look for securely stored key backups
Emergency Access: Use disaster recovery key procedures
Re-encrypt Data: Use available plain-text configurations to re-encrypt
Update Systems: Deploy new configurations with new keys
Post-Incident: Review and improve key backup procedures
If configuration files become corrupted:
Stop Service: Prevent further issues
Restore Backup: Use most recent valid backup
Validate Restoration: Test with current master key
Resume Service: Restart with restored configuration
Investigate: Determine corruption cause
If key compromise is suspected:
Immediate Rotation: Start emergency key rotation
Revoke Access: Disable compromised keys
Audit Usage: Review key usage logs
Notify Stakeholders: Inform relevant parties
Update Procedures: Strengthen key protection
Symptoms: Rotation fails during verification phase
Causes:
Wrong PROXMOX_MCP_MASTER_KEY environment variable
Configuration file corrupted
Key truncated or modified
Solutions:
Symptoms: Backup creation fails during rotation
Causes:
Insufficient disk space
Permission issues
File system errors
Solutions:
Symptoms: Server won't start after key rotation
Causes:
Environment variable not updated
Configuration cache issues
Service configuration problems
Solutions:
Enable detailed logging during rotation:
Environment file (/etc/proxmox-mcp/environment):
For more information, see the main README.md or security documentation.
# Generate a new master key securely
python -m proxmox_mcp.utils.encrypt_config --generate-key
# Follow the prompts to securely save the generated key
# Then set it as an environment variable:
export PROXMOX_MCP_MASTER_KEY="your-generated-key"# Encrypt existing config
python -m proxmox_mcp.utils.encrypt_config proxmox-config/config.json
# This creates config.encrypted.json with encrypted token values# Set environment variables
export PROXMOX_MCP_CONFIG="proxmox-config/config.encrypted.json"
export PROXMOX_MCP_MASTER_KEY="your-master-key"
# Run the server
python -m proxmox_mcp.server# Basic encryption
python -m proxmox_mcp.utils.encrypt_config config.json
# Specify output file
python -m proxmox_mcp.utils.encrypt_config config.json -o encrypted.jsonpython -m proxmox_mcp.utils.encrypt_config config.json --status# Generate a new master key with security prompts
python -m proxmox_mcp.utils.encrypt_config --generate-key
# The tool will display the key once and prompt you to save it securely
# No key exposure in logs or terminal history during automatic generation# Rotate master key for a specific configuration file
python -m proxmox_mcp.utils.encrypt_config --rotate-key config.encrypted.json
# The tool will:
# 1. Verify current master key can decrypt the configuration
# 2. Create a timestamped backup of the original file
# 3. Generate a new master key
# 4. Re-encrypt all tokens with the new key
# 5. Provide instructions for updating environment variables# Rotate master key for all configuration files in a directory
python -m proxmox_mcp.utils.encrypt_config --rotate-key-all proxmox-config/
# Bulk rotation will:
# - Process all *.json files in the directory (except examples)
# - Skip files without encrypted content
# - Use the same new master key for all files
# - Create individual backups for each rotated file
# - Provide summary of successful and failed rotations{
"auth": {
"user": "root@pam",
"token_name": "my-token",
"token_value": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}
}{
"auth": {
"user": "root@pam",
"token_name": "my-token",
"token_value": "enc:Z0FBQUFBQm9QYjUz..."
}
}# Add to your config.json
{
"logging": {
"level": "DEBUG"
}
}# Verify current configuration works
export PROXMOX_MCP_CONFIG="proxmox-config/config.encrypted.json"
export PROXMOX_MCP_MASTER_KEY="your-current-key"
python -m proxmox_mcp.server --test
# Create secure backup
cp proxmox-config/config.encrypted.json proxmox-config/config.encrypted.json.backup.$(date +%Y%m%d_%H%M%S)# Rotate key for one configuration file
python -m proxmox_mcp.utils.encrypt_config --rotate-key proxmox-config/config.encrypted.json
# The tool will:
# - Verify current key can decrypt the file
# - Create timestamped backup automatically
# - Generate new master key
# - Re-encrypt all sensitive values
# - Display new key for environment update# Rotate all configurations in a directory
python -m proxmox_mcp.utils.encrypt_config --rotate-key-all proxmox-config/
# This will:
# - Process all .json files (excluding examples)
# - Use same new key for all files
# - Skip files without encrypted content
# - Create individual backups
# - Provide rotation summary# Update environment with new key (provided by rotation tool)
export PROXMOX_MCP_MASTER_KEY="new-generated-key"
# Test with new key
python -m proxmox_mcp.server --test# Verify all functionality works
python -m proxmox_mcp.server --test
# Test actual Proxmox connectivity
# (Start server and test MCP tools)# Stop any running services
sudo systemctl stop proxmox-mcp # or docker stop container
# Restore from backup
cp proxmox-config/config.encrypted.json.backup.TIMESTAMP proxmox-config/config.encrypted.json
# Restore old environment variable
export PROXMOX_MCP_MASTER_KEY="old-master-key"
# Test configuration
python -m proxmox_mcp.server --test
# Restart service
sudo systemctl start proxmox-mcp# Use separate keys for dev
export PROXMOX_MCP_MASTER_KEY_DEV="dev-specific-key"
export PROXMOX_MCP_CONFIG="dev-config/config.encrypted.json"# Staging mirrors production procedures
export PROXMOX_MCP_MASTER_KEY_STAGING="staging-specific-key"
export PROXMOX_MCP_CONFIG="staging-config/config.encrypted.json"# Production uses highest security standards
export PROXMOX_MCP_MASTER_KEY="production-master-key"
export PROXMOX_MCP_CONFIG="prod-config/config.encrypted.json"# Verify environment variable is set correctly
echo $PROXMOX_MCP_MASTER_KEY | wc -c # Should be 45 characters
# Test decryption manually
python -c "
from proxmox_mcp.utils.encryption import TokenEncryption
import os
enc = TokenEncryption(os.getenv('PROXMOX_MCP_MASTER_KEY'))
print('Key works!' if enc else 'Key invalid')
"
# Check configuration file integrity
python -m proxmox_mcp.utils.encrypt_config config.encrypted.json --status# Check disk space
df -h
# Check permissions
ls -la proxmox-config/
# Create backup manually
cp config.encrypted.json config.encrypted.json.manual.backup# Verify new environment variable
echo $PROXMOX_MCP_MASTER_KEY
# Clear any cache
rm -rf ~/.proxmox_mcp_cache
# Test configuration directly
python -m proxmox_mcp.server --test
# Check service logs
journalctl -u proxmox-mcp -f# Enable debug logging
export PROXMOX_MCP_DEBUG=true
# Run rotation with verbose output
python -m proxmox_mcp.utils.encrypt_config --rotate-key config.encrypted.json
# Check detailed logs
tail -f /var/log/proxmox-mcp/rotation.log# Test server startup
python -m proxmox_mcp.server --test
# Verify MCP tools work
python -c "
import asyncio
from proxmox_mcp.core.proxmox import ProxmoxManager
# Test basic connectivity
"# Start server in test mode
python -m proxmox_mcp.server --test-mode
# Run MCP client tests
mcp test localhost:8000
# Verify all tools respond correctlyname: Key Rotation
on:
schedule:
- cron: '0 2 1 */3 *' # Quarterly at 2 AM
workflow_dispatch:
jobs:
rotate-keys:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.10'
- name: Install dependencies
run: |
pip install -e .
- name: Rotate staging keys
env:
PROXMOX_MCP_MASTER_KEY: ${{ secrets.STAGING_MASTER_KEY }}
run: |
python -m proxmox_mcp.utils.encrypt_config --rotate-key staging-config/config.encrypted.json
- name: Test rotated configuration
env:
PROXMOX_MCP_MASTER_KEY: ${{ secrets.NEW_STAGING_KEY }}
run: |
python -m proxmox_mcp.server --test
- name: Update secrets
run: |
# Update GitHub secrets with new key
gh secret set STAGING_MASTER_KEY --body "$NEW_KEY"stages:
- rotate
- test
- deploy
rotate-keys:
stage: rotate
script:
- python -m proxmox_mcp.utils.encrypt_config --rotate-key-all config/
- echo "NEW_KEY=$NEW_MASTER_KEY" >> rotation.env
artifacts:
reports:
dotenv: rotation.env
only:
- schedules
test-rotation:
stage: test
needs: [rotate-keys]
script:
- export PROXMOX_MCP_MASTER_KEY=$NEW_KEY
- python -m proxmox_mcp.server --test
dependencies:
- rotate-keys
deploy-production:
stage: deploy
needs: [test-rotation]
script:
- kubectl create secret generic proxmox-master-key --from-literal=key=$NEW_KEY
- kubectl rollout restart deployment/proxmox-mcp
only:
- schedules# Create monitoring script for key rotation
cat > monitor-key-rotation.sh << 'EOF'
#!/bin/bash
# Monitor key age and trigger rotation
KEY_FILE="/etc/proxmox-mcp/key-metadata.json"
MAX_AGE_DAYS=365
if [ -f "$KEY_FILE" ]; then
LAST_ROTATION=$(jq -r '.last_rotation' "$KEY_FILE")
CURRENT_DATE=$(date +%s)
DAYS_SINCE_ROTATION=$(( (CURRENT_DATE - LAST_ROTATION) / 86400 ))
if [ $DAYS_SINCE_ROTATION -gt $MAX_AGE_DAYS ]; then
echo "Key rotation required: $DAYS_SINCE_ROTATION days since last rotation"
# Trigger automated rotation
python -m proxmox_mcp.utils.encrypt_config --rotate-key-all /etc/proxmox-mcp/
fi
fi
EOF
# Schedule with cron
echo "0 2 * * 0 /usr/local/bin/monitor-key-rotation.sh" | sudo crontab -services:
proxmox-mcp:
environment:
- PROXMOX_MCP_CONFIG=/app/config/config.encrypted.json
- PROXMOX_MCP_MASTER_KEY=${MASTER_KEY}
volumes:
- ./config:/app/config
healthcheck:
test: ["CMD", "python", "-m", "proxmox_mcp.server", "--test"]
interval: 30s
timeout: 10s
retries: 3version: '3.8'
services:
proxmox-mcp:
image: proxmox-mcp:latest
environment:
- PROXMOX_MCP_CONFIG=/app/config/config.encrypted.json
secrets:
- master_key
volumes:
- ./config:/app/config
deploy:
replicas: 2
update_config:
parallelism: 1
delay: 10s
secrets:
master_key:
external: trueapiVersion: apps/v1
kind: Deployment
metadata:
name: proxmox-mcp
spec:
replicas: 2
selector:
matchLabels:
app: proxmox-mcp
template:
metadata:
labels:
app: proxmox-mcp
spec:
containers:
- name: proxmox-mcp
image: proxmox-mcp:latest
env:
- name: PROXMOX_MCP_CONFIG
value: "/app/config/config.encrypted.json"
- name: PROXMOX_MCP_MASTER_KEY
valueFrom:
secretKeyRef:
name: proxmox-master-key
key: key
volumeMounts:
- name: config
mountPath: /app/config
readinessProbe:
exec:
command:
- python
- -m
- proxmox_mcp.server
- --test
initialDelaySeconds: 5
periodSeconds: 10
volumes:
- name: config
configMap:
name: proxmox-config
---
apiVersion: v1
kind: Secret
metadata:
name: proxmox-master-key
type: Opaque
data:
key: <base64-encoded-master-key>[Unit]
Description=Proxmox MCP Server
After=network.target
[Service]
Type=simple
User=proxmox-mcp
Group=proxmox-mcp
Environment=PROXMOX_MCP_CONFIG=/etc/proxmox-mcp/config.encrypted.json
EnvironmentFile=/etc/proxmox-mcp/environment
ExecStart=/usr/bin/python -m proxmox_mcp.server
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=10
# Security hardening
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/log/proxmox-mcp
[Install]
WantedBy=multi-user.targetPROXMOX_MCP_MASTER_KEY=your-master-keytask branch
Interactive branch creation
task branch
task branch:feature
Create feature branch
task branch:feature -- "desc" [issue]
task branch:fix
Create fix branch
task branch:fix -- "description" [issue]
task branch:security
Create security branch
task branch:security -- "description"
task branch:validate
Validate current branch
task branch:validate
task branch:validate:all
Validate all branches
task branch:validate:all
task branch:check
Check specific branch
task branch:check -- "branch-name"
task branch:status
Show branch status
task branch:status
task work:start
Start new work
task work:start
task work:save
Save current work
task work:save
task work:finish
Finish and prepare PR
task work:finish
task branch:ready
Check PR readiness
task branch:ready
The new branch tasks work seamlessly with your existing workflow:
You can customize the branch tasks by editing the Taskfile.yml:
The tasks respect your existing environment:
The new tasks are organized in the task list:
Shows organized sections:
Branch Management: All branch-related tasks
Development Setup: Existing setup tasks
Code Quality: Existing quality tasks
Testing: Existing test tasks
etc.
All your existing tasks remain unchanged:
✅ task setup - Still works exactly the same
✅ task quick - No changes to existing workflow
✅ task check - All quality checks unchanged
✅ task ci - CI simulation unchanged
The branch tasks only require:
Git (already required for your project)
Bash (standard on macOS/Linux)
The branch template scripts (included)
No additional dependencies needed!
Task not found:
Branch script not executable:
Git errors:
This integration makes branch management a natural part of your existing Task workflow while maintaining all the power and flexibility of your current setup!
This document outlines the security scanning process for ProxmoxMCP dependencies.
✅ All dependencies updated as of commit b9fb0da:
setuptools 80.9.0 (≥78.1.1 required for CVE-2025-47273)
requests 2.32.4 (≥2.32.4 required for CVE-2024-47081)
h11 0.16.0 (≥0.16.0 required for CVE-2025-43859)
Run dependency scans before each release
Monitor security advisories for core dependencies
Update vulnerable dependencies immediately for critical issues
Consider implementing:
GitHub Dependabot for automated dependency updates
Pre-commit hooks for security scanning
CI/CD integration with security scanning tools
Assess Impact: Determine if vulnerability affects ProxmoxMCP functionality
Update Dependencies: Use uv add "package>=secure_version"
Test Functionality: Run full test suite and quality checks
Commit Changes: Follow security commit message format
For critical security vulnerabilities, follow responsible disclosure practices and escalate to project maintainers immediately.
# Run the integration script
./scripts/branch-templates/integrate-taskfile.sh
# Or manually copy from the integrated version
cp Taskfile-integrated.yml Taskfile.yml# Start working on a new feature
task work:start
# This will:
# 1. Guide you through branch creation
# 2. Set up development environment
# 3. Show next steps
# Or create specific branch types directly
task branch:feature -- "add-vm-monitoring-tools" 123
task branch:fix -- "memory-leak-connection-pool" 58
task branch:security -- "fix-shell-injection"# Save your work (quality checks + commit guidance)
task work:save
# Check if your branch is ready for PR
task branch:ready
# Validate your branch name
task branch:validate
# See all your branches
task branch:list# Complete your work and get PR guidance
task work:finish
# Check branch status
task branch:status
# Sync with main if needed
task branch:sync# The branch:ready task combines:
task branch:ready
# - Branch name validation
# - All code quality checks (format, lint, type)
# - Test execution
# - YAML validation# Combined workflow example
task work:start # Create branch + setup
# ... make your changes ...
task quick # Format + lint + test (existing task)
task work:save # Quality check + commit helper
task work:finish # Final checks + PR guidance
# Or step by step
task branch:feature -- "new-api" 123
task setup # Existing setup task
# ... development work ...
task check # Existing quality checks
task branch:ready # New: combines validation + checks# Feature branches with issue numbers
task branch:feature -- "add-monitoring" 123
task branch:feature -- "improve-performance"
# Fix branches
task branch:fix -- "connection-timeout" 58
task branch:fix -- "null-pointer-exception"
# Security branches
task branch:security -- "cve-2025-47273-fix"
task branch:security -- "input-validation"
# Release branches
task branch:release -- "v1.0.0"
task branch:release -- "v1.1.0-beta"
# Branch validation
task branch:check -- "feature/123-my-branch"
task branch:check -- "invalid-branch-name"# Guided experience for beginners
task branch
# This opens the interactive branch creator with:
# - Branch type selection
# - Description input
# - Issue number linking
# - Confirmation and guidance# Show current branch and git status
task branch:status
# List all branches with commit info
task branch:list
# Show project information including branch
task info# Create your own workflow combinations
task branch:feature -- "new-tool" 123 && task setup && task dev
# Check everything before creating PR
task branch:ready && echo "Ready for PR!"
# Quick branch creation and immediate development
task work:start && code .# The tasks handle git operations automatically:
# - Update main branch before creating new branches
# - Push branches with upstream tracking
# - Provide git commands for manual operations
# Branch cleanup (shows commands to run)
task branch:clean
# Output: Commands to delete merged branches# Local CI simulation with branch validation
task ci && task branch:validate
# Pre-commit workflow
task pre-commit && task branch:ready# Example: Add your own branch workflow
custom:workflow:
desc: My custom workflow
cmds:
- task: branch:feature
- task: setup
- task: test
- echo "Custom workflow complete!"env:
PYTHONPATH: "src:{{.PYTHONPATH}}" # Existing
# Branch scripts use git configuration automaticallytask --list# Make sure integration completed
task --list | grep branch
# If not found, re-run integration
./scripts/branch-templates/integrate-taskfile.shchmod +x scripts/branch-templates/*.sh# Make sure you're in the git repository
git status
# Check if main branch exists
git branch -a# Show all available tasks
task --list
# Show task description
task --summary branch:feature
# Show project info including current branch
task info
# Validate current setup
task branch:validate# Essential commands for daily use
task branch # Create new branch (interactive)
task work:start # Start new work (create + setup)
task work:save # Save work (check + commit help)
task work:finish # Finish work (ready + PR guide)
# Quick branch creation
task branch:feature -- "desc" 123 # Feature with issue
task branch:fix -- "desc" 58 # Fix with issue
task branch:hotfix -- "desc" # Emergency fix
# Quality and validation
task branch:ready # Check if ready for PR
task quick # Fast quality check (existing)
task check # Full quality check (existing)
# Status and management
task branch:status # Current branch info
task branch:list # All branches overview
task info # Project + branch infoencrypt_config.py:47 to use shell=FalseStatus: COMPLETED
The current implementation in src/proxmox_mcp/utils/encrypt_config.py uses
secure ANSI escape sequences
No subprocess calls with shell=True exist in the codebase
Terminal clearing is implemented usingprint("\033[2J\033[H", end="", flush=True)
Status: COMPLETED
Windows: Uses ANSI escape sequences with ctypes fallback
Linux/macOS: Uses ANSI escape sequences directly
No platform-specific subprocess calls with shell=True
Status: COMPLETED
Test comments confirm "Our implementation no longer uses subprocess"
Tests verify ANSI escape sequence usage instead of subprocess calls
All terminal clearing tests updated for secure implementation
Status: VERIFIED
Comprehensive search of src/ directory found no shell=True usage
Comprehensive search of tests/ directory found no shell=True usage
Only references are in documentation and pre-commit configuration
Status: COMPLETED
Custom hook exists in .pre-commit-config.yaml
Hook command: grep -r "shell=True" src/ --include="*.py"
Prevents future introduction of shell=True vulnerabilities
The clear_terminal_if_requested() function now uses:
ANSI escape sequences: \033[2J\033[H
Cross-platform compatibility without subprocess
Proper error handling and fallbacks
Eliminates command injection vulnerabilities
No shell interpretation of user input
Maintains functionality across platforms
Follows security best practices
find_filecontent searches for shell=True in src/ and tests/
Pre-commit hook testing
Code formatting and linting verification
All action items from issue #61 have been completed. The security vulnerability has been resolved through a secure implementation that eliminates subprocess shell=True usage while maintaining the required terminal clearing functionality.
task branch:chore
Create chore branch
task branch:chore -- "description"
task branch:hotfix
Create hotfix branch
task branch:hotfix -- "description"
task branch:release
Create release branch
task branch:release -- "v1.0.0"
task branch:sync
Sync with main
task branch:sync
task branch:clean
Show cleanup commands
task branch:clean
task branch:list
List all branches
task branch:list
task branch:workflow
Complete workflow
task branch:workflow
Document Resolution: Update this file with resolution details
# Install pip-audit if not available
uv add --dev pip-audit
# Scan current dependencies
uv run pip-audit
# Scan with detailed output
uv run pip-audit --format=json --output=security-report.json# Install safety scanner
uv add --dev safety
# Export dependencies and scan
uv export --format=requirements-txt | uv run safety check --stdinComprehensive guide to automated markdown formatting and quality assurance
This guide covers the automated markdown linting system implemented to maintain consistent documentation quality across ProxmoxMCP. The system automatically detects, reports, and fixes common markdown formatting issues.
Purpose: Modern, fast markdown linting tool
Auto-fix: Automatically resolves 70%+ of formatting issues
Integration: Works with pre-commit, CI/CD, and local development
.markdownlint.jsonc)Customized Rules: Tailored for technical documentation
120-character line limit: Balances readability and display
Flexible HTML: Allows badges, details, and common HTML elements
Automatic: Runs on every commit
Auto-fix: Applies fixes before commit
Fast: Only processes changed markdown files
PR Analysis: Automatic markdown quality checking
Auto-fix Commits: Pushes fixes directly to PR branches
Quality Reports: Detailed summaries and artifacts
Pre-commit: Automatic fixing on commit
Manual fixes: task markdown:fix
Quality check: task markdown:summary
Automatic analysis: GitHub Action runs on PR
Auto-fix commits: Fixes pushed to PR branch
Quality reports: Detailed analysis in artifacts
500+ formatting issues across documentation
Manual fixing: Time-intensive and inconsistent
Review overhead: Significant PR review time
149 remaining issues (70% reduction)
Auto-fixing: Most issues resolved automatically
Consistent quality: Enforced formatting standards
Custom rule development: Project-specific linting rules
Integration with documentation generators: Hugo, GitBook, etc.
AI-powered suggestions: Automated content improvements
Performance optimization: Faster linting for large documentation sets
Scheduled quality reports: Weekly documentation health checks
Integration with project management: Link quality metrics to milestones
Multi-language support: Extend to other markup formats
: See markdown tasks
: Hook setup
💡 Tip: Run
task markdown:summaryregularly to monitor documentation quality and catch issues early in development.
MD009
Trailing spaces
✅ Removes spaces
MD010
Hard tabs
✅ Converts to spaces
MD012
Multiple consecutive blank lines
✅ Removes extras
MD032
Lists not surrounded by blank lines
✅ Adds blank lines
MD022
Headers not surrounded by blank lines
✅ Adds blank lines
MD031
Code blocks not surrounded by blank lines
✅ Adds blank lines
MD047
Files not ending with newline
✅ Adds newline
MD013
Line too long (>120 chars)
Break lines, shorter URLs
MD025
Multiple H1 headers
Restructure document
MD041
First line not H1
Add title or disable for snippets
MD029
Inconsistent list numbering
Manually renumber lists
task markdown:lint # Check all markdown files
task markdown:fix # Auto-fix formatting issues
task markdown:check # Strict checking (CI mode)
task markdown:summary # Overview of all issues# Install markdownlint-cli2 globally
npm install -g markdownlint-cli2
# Or use the project's Taskfile
task setup # Already includes markdown tooling# Check all markdown files
task markdown:lint
# Auto-fix issues (recommended)
task markdown:fix
# Check what would be fixed (preview)
markdownlint-cli2 "**/*.md" --fix --output-fixes"MD013": {
"line_length": 120, // Increased from default 80
"headers": false, // Don't count header lines
"code_blocks": false, // Don't count code blocks
"tables": false // Don't count table lines
}"MD033": {
"allowed_elements": [
"details", "summary", // Collapsible sections
"br", "img", "a", // Basic HTML
"kbd", "sub", "sup" // Typography
]
}"MD046": {
"style": "fenced" // Prefer ``` over indented blocks
}# In .github/workflows/markdown-lint.yml
- Markdown quality checking
- Auto-fix generation
- Quality report artifacts
- Integration with existing workflows# Ignore certain directories
markdownlint-cli2 "**/*.md" "!node_modules/**" "!.venv/**"{
"MD024": {
// Allow duplicate headers in different sections
"allow_different_nesting": true
},
"MD040": false // Disable requirement for code block languages
}{
"markdownlint.config": {
"extends": ".markdownlint.jsonc"
}
}-- With coc.nvim or nvim-lsp
require'lspconfig'.marksman.setup{}# Install globally
npm install -g markdownlint-cli2
# Or use npx
npx markdownlint-cli2 "**/*.md"# Fix issues in batches
markdownlint-cli2 --fix "docs/*.md"
markdownlint-cli2 --fix "*.md"# Run manually to see details
pre-commit run markdownlint-cli2 --all-files
# Update pre-commit
pre-commit autoupdateThis report analyzes the ProxmoxMCP codebase for efficiency improvements and identifies several significant performance bottlenecks. The primary issues center around N+1 query problems in API calls, missing caching mechanisms, and inefficient error handling patterns.
File: src/proxmox_mcp/tools/vm.py
Lines: 79-120
Impact: High - VMs are typically the most numerous resources
Issue: The get_vms() method makes individual API calls for each VM's configuration:
Performance Impact:
For a cluster with 100 VMs across 3 nodes: 103 API calls (3 for nodes + 100 for VM configs)
Each API call adds network latency and server processing overhead
Scales poorly as VM count increases
Recommended Fix: Batch VM config retrieval and implement better error isolation per node.
File: src/proxmox_mcp/tools/node.py
Lines: 69-85
Impact: Medium - Fewer nodes than VMs typically
Issue: Similar pattern where each node requires a separate detailed status call:
Performance Impact:
For a 5-node cluster: 6 API calls (1 for node list + 5 for detailed status)
Less severe than VM issue but still inefficient
File: src/proxmox_mcp/tools/storage.py
Lines: 70-90
Impact: Medium - Storage pools are typically fewer but still inefficient
Issue: Each storage pool requires individual status API call:
Files: All tool classes Impact: Medium - Repeated calls fetch same data
Issue: No caching mechanism for frequently accessed data such as:
Node lists (rarely change)
VM configurations (change infrequently)
Storage pool information
Recommended Fix: Implement a simple TTL-based cache for relatively static data.
Files: Multiple tool files Impact: Low - Code maintainability issue
Issue: Repetitive try-catch blocks that could be consolidated:
Each tool implements similar error handling patterns
Could be abstracted into base class methods
Some error handling stops entire operations when partial failures could be tolerated
Files: VM and Node tools Impact: Low-Medium - Could benefit from parallelization
Issue: Operations that could be parallelized are running sequentially:
Multiple node queries could run in parallel
VM config retrieval could be parallelized per node
API Call Explosion: O(n) API calls where n = number of VMs
Failure Propagation: Single VM config failure can impact entire operation
No Batching: Each VM processed individually instead of in batches
Batch Processing: Group operations by node to reduce API round trips
Error Isolation: Node-level failures don't break entire operation
Graceful Degradation: Use available data when detailed config unavailable
Before: 103 API calls for 100 VMs across 3 nodes
After: ~6 API calls (3 for node VM lists + 3 for batch config attempts)
Improvement: ~94% reduction in API calls
Fix N+1 query problem in get_vms() method
Implement better error isolation
Maintain backward compatibility
Apply similar optimizations to node and storage tools
Consider implementing parallel API calls
Implement TTL-based caching for static data
Add cache invalidation mechanisms
Consider memory usage implications
Abstract common error handling patterns
Implement retry mechanisms where appropriate
Improve error reporting granularity
Measure API call reduction in test environments
Benchmark response times with varying cluster sizes
Monitor memory usage with optimizations
Ensure response format remains unchanged
Verify error handling still works correctly
Test fallback mechanisms
Confirm existing functionality preserved
Validate error scenarios still handled properly
Check edge cases (empty clusters, offline nodes)
The ProxmoxMCP codebase has several efficiency opportunities, with the VM tools N+1 query problem being the most impactful. The proposed optimizations will significantly improve performance for larger Proxmox clusters while maintaining backward compatibility and improving error resilience.
The fixes are low-risk as they maintain the same interfaces and response formats while optimizing the underlying implementation. The modular nature of the codebase makes these optimizations straightforward to implement and test.
for vm in vms:
vmid = vm["vmid"]
try:
config = self.proxmox.nodes(node_name).qemu(vmid).config.get() # Individual API call per VMfor node in result:
node_name = node["node"]
status = self.proxmox.nodes(node_name).status.get() # Individual API call per nodefor store in result:
status = self.proxmox.nodes(store.get("node", "localhost")).storage(store["storage"]).status.get()This document contains the findings from a thorough review of the ProxmoxMCP repository, focusing on potential issues, bugs, security vulnerabilities, and enhancement opportunities.
ProxmoxMCP is a Model Context Protocol (MCP) server implementation that provides tools and resources for interacting with Proxmox Virtual Environment (PVE) clusters. The repository contains code for connecting to Proxmox instances, managing virtual machines, and exposing these capabilities through the MCP protocol.
Key components of the repository include:
Core Proxmox API integration (proxmox_mcp/core/proxmox.py)
MCP server implementation (proxmox_mcp/server.py)
Configuration management (proxmox_mcp/config/)
Tool implementations for various Proxmox operations (proxmox_mcp/tools/)
Docker deployment configuration (Dockerfile, compose.yaml)
This review examines the codebase across multiple dimensions including code quality, Docker implementation, architecture, security, and documentation.
Token Handling: API tokens are stored in plaintext in configuration
files (proxmox-config/config.json), creating a potential security risk
SSL Verification: SSL verification is disabled by default in examples
(verify_ssl: false in configuration examples), which could lead to
man-in-the-middle attacks
Input Validation: Limited input validation for VM commands inproxmox_mcp/tools/vm.py, potentially allowing injection attacks
Inconsistent Practices: Error handling varies across the codebase, with some functions using specific exceptions and others using generic try/except blocks
Missing Error Propagation: Some errors are caught and logged but not properly propagated to the caller
Configuration Errors: Limited error handling for configuration loading
in proxmox_mcp/config/loader.py
Race Conditions: Potential race conditions in command execution,
particularly in the console manager (proxmox_mcp/tools/console/manager.py)
Resource Leaks: Some resources may not be properly closed in error cases
Edge Cases: Several edge cases not properly handled, such as network timeouts and API rate limiting
Structure: Generally well-structured with clear separation of concerns
Maintainability: Some modules have high complexity and could benefit from refactoring
Logging: Inconsistent logging practices across the codebase
Type Annotations: Limited use of type annotations, which could improve code reliability
Non-root User: Properly uses a non-root user in the Dockerfile, which is a security best practice
Multi-stage Builds: Effectively uses multi-stage builds to reduce the attack surface
Base Image: Uses Python base image but could specify a more minimal alternative
Missing Limits: No resource limits defined in compose.yaml, which could lead to resource exhaustion
No Health Checks: Missing health check configuration in Docker Compose file
Volume Mounts: Appropriate use of volume mounts for configuration, but could benefit from read-only mounts where possible
Environment Variables: Limited use of environment variables for configuration
Secrets Management: No use of Docker secrets for sensitive information
Default Configuration: Example configuration includes potentially insecure defaults
Layer Caching: Could improve Dockerfile to better leverage layer caching
Dependencies: Installs all dependencies at once, which could be optimized
Image Size: Final image could be further optimized for size
Organization: Well-organized with clear separation between core functionality, tools, and utilities
Modularity: Good modularity with distinct components for different aspects of functionality
Naming Conventions: Consistent and clear naming conventions throughout the project
Single Connection Model: Current implementation uses a single connection to Proxmox, which could be a bottleneck
Synchronous Operations: Many operations are synchronous, which could limit throughput
No Caching: Limited caching of frequently accessed data, which could impact performance
Tool Framework: Good foundation for adding new tools through the base tool classes
Missing Plugin System: No formal plugin system for extending functionality
Configuration Extensibility: Configuration system is flexible but lacks schema validation
Proxmox API: Solid integration with Proxmox API through the proxmoxer library
MCP Protocol: Good implementation of the MCP protocol for tool and resource exposure
Missing Integrations: Limited integration with other systems (e.g., monitoring, alerting)
Plaintext Storage: API tokens stored in plaintext in configuration files (proxmox-config/config.json)
No Token Rotation: No mechanism for token rotation or expiration
Limited Authentication Options: Only supports API token authentication, not other methods
Verification Disabled: SSL verification disabled by default in examples
No Certificate Pinning: No implementation of certificate pinning for added security
Missing TLS Configuration: No explicit TLS version or cipher configuration
Limited Sanitization: Limited input sanitization, especially for VM commands
Command Injection Risk: Potential for command injection in VM operations
Parameter Validation: Inconsistent parameter validation across tools
No User-level Controls: No user-level access control or permission checking
All-or-Nothing Access: Anyone with access to the MCP server has full access to all tools
No Audit Logging: Limited logging of security-relevant actions
Inadequate Protection: Inadequate protection of sensitive credentials in Docker configuration
No Encryption: No encryption of sensitive data at rest
Hardcoded Credentials: Some examples include hardcoded credentials
Overview: Good high-level overview of the project
Inconsistencies: Some inconsistencies between documentation and actual code
Missing Sections: Limited information on security best practices and troubleshooting
Basic Coverage: Basic installation instructions provided
Platform Gaps: Missing details for some platforms
Prerequisites: Unclear prerequisites for installation
Basic Setup: Basic Docker setup instructions provided
Advanced Configuration: Missing documentation on advanced Docker configuration
Security Considerations: Limited coverage of Docker security considerations
Examples: Good examples for basic tool usage
Error Handling: Missing information on error handling
Advanced Usage: Limited documentation on advanced usage patterns
Quick Start: Missing a comprehensive quick start guide
Visual Documentation: No diagrams or visual aids
Troubleshooting: Limited troubleshooting information
Fix Security Vulnerabilities:
Implement token encryption at rest in proxmox_mcp/config/loader.py
Enable SSL verification by default in configuration examples
Add input validation for VM commands in
Enhance Docker Configuration:
Add resource limits in compose.yaml
Implement read-only filesystem where possible
Use specific version tags for base images in Dockerfile
Enhance Extensibility:
Implement a formal plugin system
Add dynamic tool discovery
Create better documentation for extending the tool set
Feature Additions:
Add support for LXC containers (currently missing)
Implement batch operations for better performance
Add support for Proxmox Backup Server
Exception Handling: Overly broad exception catching in multiple files, which could mask security issues
proxmox_mcp/tools/vm.pyImplement Docker secrets for sensitive credentials in compose.yaml
Improve Error Handling:
Standardize error handling across the codebase
Catch specific exceptions instead of generic ones
Add comprehensive error handling for configuration loading in proxmox_mcp/config/loader.py
Implement proper error propagation to clients
Add health checks for container monitoring
Improve Scalability:
Implement connection pooling in proxmox_mcp/core/proxmox.py
Add caching for frequently accessed data
Convert more operations to async, particularly in proxmox_mcp/tools/
Implement request throttling to prevent API rate limiting
Strengthen Documentation:
Add a comprehensive quick start guide
Create a troubleshooting FAQ
Standardize environment variable names
Improve Docker deployment documentation
Add security best practices section
Implement configuration schema validation
Improve Code Quality:
Make logging practices consistent across the codebase
Add comprehensive type annotations
Implement proper resource cleanup in all tools
Refactor complex modules for better maintainability
Add Testing:
Expand test coverage beyond the current limited tests
Add security-focused tests
Implement container testing
Add integration tests with a mock Proxmox API
Implement resource monitoring and alerting
Integration Improvements:
Enhance Cline integration examples
Add support for other MCP clients
Implement API versioning
Add integration with monitoring systems
Implement webhook support for events
Comprehensive branch management documentation including implementation details, strategy, and workflow guidelines.
This document provides complete guidance on branch management for the ProxmoxMCP project, covering both the implemented tools and strategic workflow processes. The branch management system ensures consistent naming conventions, quality gates, and efficient development workflows.
Successfully implemented a comprehensive branch management system for the ProxmoxMCP project that addresses all shell script issues and provides robust branch naming validation and management tools.
Shell Script Issues (~30 issues)
File: scripts/branch-templates/config.sh
✅ Missing shebang (SC2148): Added proper #!/usr/bin/env bash shebang
✅ Multiple unused variables (SC2034): All variables are now properly exported for external use
✅ Error handling: Added set -euo pipefail for robust error handling
File: scripts/branch-templates/validate.sh
✅ Use ${variable//search/replace} instead of sed (SC2001): Replaced all sed usage with bash parameter expansion
✅ Unused variable suggestions: All variables are properly used throughout the script
✅ Proper shebang and error handling: Consistent with best practices
Additional Improvements
✅ Shellcheck compliance: All scripts pass shellcheck validation
✅ Consistent coding standards: Follow existing project patterns
✅ Proper documentation: Comprehensive inline comments and help text
Core Scripts
scripts/branch-templates/config.sh (108 lines)
Central configuration for branch management system
Exported variables for external script usage
Shared functions for validation logic
Supporting Files
BRANCH_MANAGEMENT_SUMMARY.md (This file's source)
Implementation summary and testing results
Branch Naming Convention Enforcement
Format: <type>/<component>-<description>
Valid Types: feature, fix, security, docker, config, docs, ci, perf
Valid Components: vm, container, storage, network, backup, auth, encryption, config, api, mcp, core, tools, formatting, docker, proxmox, console, management
Interactive Tools
Branch Creation: Guided prompts for type, component, and description selection
Validation: Current branch or specific name validation with detailed feedback
Branch Listing: Visual status indicators (✅ valid, ❌ invalid, 🛡️ protected)
Cleanup: Safe removal of merged branches with dry-run option
Configuration System
Default Settings: Sensible defaults for immediate use
User Customization: Optional .branch-config file for overrides
Protected Branches: Automatic recognition of main, develop, staging
Component Extensibility
Validation Testing
Help System Testing
Script Quality Verification
✅ All scripts are executable (chmod +x applied)
✅ Proper error handling with set -euo pipefail
✅ No shellcheck warnings or errors
✅ Consistent with existing project shell script patterns
Quick Start
Advanced Usage
Git Hooks Integration
The system can be integrated with Git hooks for automatic enforcement:
Pre-push validation to prevent invalid branch names
Pre-commit validation for branch name compliance
Examples provided in documentation
CI/CD Integration
Scripts can be incorporated into CI/CD pipelines for branch name validation during pull request creation.
Code Quality Improvements
Shell Script Standards: All scripts follow best practices and are shellcheck compliant
Error Handling: Robust error handling with proper exit codes
Documentation: Comprehensive documentation for maintainability
User Experience: Intuitive interface with helpful error messages and suggestions
Development Workflow Enhancement
Consistency: Enforces consistent branch naming across the project
Guidance: Interactive tools help developers create properly named branches
Maintenance: Automated cleanup of merged branches
Validation: Early detection of naming convention violations
Maintainability
Modular Design: Separate configuration, validation, and management components
Extensibility: Easy to add new branch types and components
Configuration: User-customizable settings without code changes
Testing: All functionality tested and verified
Status: COMPLETE ✨
All shell script issues have been resolved and the comprehensive branch management system has been successfully implemented with:
✅ 30+ shell script issues addressed
✅ 4 new files created with 989 total lines of code
✅ Complete documentation and usage examples
✅ Full testing and validation
The branch management system is ready for immediate use and provides a solid foundation for maintaining consistent branch naming conventions across the ProxmoxMCP project.
This section outlines the branching strategy and workflow for the ProxmoxMCP repository to ensure consistent, high-quality development practices.
1. main Branch
Purpose: Production-ready code, always deployable
Protection: Fully protected, no direct pushes
Merge Requirements: PR review + CI checks passing
2. Feature Branches
3. Fix Branches
4. Security Branches
5. Maintenance Branches
6. Release Branches (Optional)
7. Hotfix Branches
Use PR template checklist
Link related issues
Add appropriate labels
Request relevant reviewers
Address review feedback
Keep commits clean and logical
Squash commits if necessary before merge
✅ Require pull request reviews before merging (minimum: 1)
✅ Require status checks to pass before merging
Codacy quality checks
CI/CD workflows (autofix, yaml-lint)
All PRs must pass:
Automated Checks
Codacy quality assessment
Security vulnerability scans
Linting (ruff, black, mypy)
Security Changes
Code Changes
Documentation Changes
Before Creating PR
PR Description Template
All PRs must pass Codacy quality gates
Security issues must be addressed before merge
Code complexity limits enforced
Automated dependency PRs get dependencies label
Security updates get expedited review
Breaking changes require manual testing
autofix.yml: Automated formatting fixes
claude-auto-review.yml: AI-assisted code review
yaml-lint.yml: YAML file validation
Update branch protection rules
Create PR and issue templates
Document new workflow (this guide)
Train team on new process
Apply new workflow to all new PRs
Migrate any existing feature work to proper branches
Update CI/CD to enforce new rules
Monitor adoption and address issues
Refine review process based on experience
Add additional automation as needed
Create release process documentation
Q: What if I accidentally committed to main? A: Create a revert commit, then properly implement the change in a feature branch.
Q: How do I handle conflicts during rebase? A:
Q: What if CI checks fail? A: Fix the issues locally, commit the fixes, and push to update the PR.
Q: Emergency fix needed in production? A: Use hotfix workflow with fast-track review process.
Quality Assurance: All changes reviewed and tested
Security Focus: Mandatory security reviews for sensitive changes
Automation Integration: Leverages existing Codacy/CI infrastructure
Flexibility: Supports different types of changes appropriately
Implement branch protection rules
Create PR/issue templates
Update CI/CD workflows if needed
Begin using new workflow for all changes
This document provides comprehensive branch management guidance for ProxmoxMCP, combining implementation details with strategic workflow processes.
User-configurable settings support
scripts/branch-templates/validate.sh (386 lines)
Comprehensive branch name validation
Multiple validation layers (length, prefix, component, description, characters)
Helpful error messages and suggestions
Support for current branch and specific name validation
scripts/branch-templates/branch-manager.sh (330 lines)
Main interface for branch management operations
Interactive branch creation with guided prompts
Branch listing with validation status indicators
Merged branch cleanup functionality
Comprehensive help system
scripts/branch-templates/README.md (165 lines)
Complete documentation and usage guide
Quick start examples
Configuration options
Git hooks integration examples
Troubleshooting guide
Character Validation: Only alphanumeric, hyphens, and forward slashes
Description Requirements: Meaningful descriptive suffix after component
✅ No unused variables (all exported for external use)
✅ Parameter expansion used instead of sed (addresses SC2001)
Security scans
✅ Require branches to be up to date before merging
✅ Restrict pushes to matching branches
✅ Do not allow bypassing the above settings
✅ Allow force pushes: disabled
✅ Allow deletions: disabled
Test suite (pytest)
Manual Review
Code quality review
Security review (for security changes)
Documentation review (for docs changes)
Traceability: Clear history and relationship to issues
Collaboration: Encourages code review and knowledge sharing
# Valid branch name
$ ./scripts/branch-templates/validate.sh --name "feature/vm-console-management"
[SUCCESS] Branch name is valid! ✨
# Invalid branch name
$ ./scripts/branch-templates/validate.sh --name "invalid-branch-name"
[ERROR] Branch name validation failed
[INFO] Suggestions for improvement:
Example: feature/core-update
Format: <type>/<component>-<description># Both scripts provide comprehensive help
$ ./scripts/branch-templates/validate.sh --help
$ ./scripts/branch-templates/branch-manager.sh help# Validate current branch
./scripts/branch-templates/validate.sh --current
# Create new branch interactively
./scripts/branch-templates/branch-manager.sh create
# List all branches with status
./scripts/branch-templates/branch-manager.sh list# Validate specific branch name
./scripts/branch-templates/validate.sh --name "feature/api-enhancement"
# List including remote branches
./scripts/branch-templates/branch-manager.sh list --all
# Clean up merged branches (dry run)
./scripts/branch-templates/branch-manager.sh cleanup --dry-runfeature/issue-number-short-description
# Examples:
feature/61-fix-subprocess-shell-vulnerabilities
feature/65-update-security-dependencies
feature/new-vm-management-toolsfix/issue-number-short-description
# Examples:
fix/58-autofix-workflow-warnings
fix/memory-leak-in-connection-poolsecurity/vulnerability-description
# Examples:
security/cve-2025-47273-setuptools
security/bandit-shell-injection-fixeschore/maintenance-task
# Examples:
chore/update-documentation
chore/dependency-updates
chore/ci-workflow-improvementsrelease/version-number
# Examples:
release/v1.0.0
release/v1.1.0-betahotfix/critical-issue-description
# Examples:
hotfix/security-patch-immediate
hotfix/production-down-fix# Ensure main is current
git checkout main
git pull origin main
# Create feature branch
git checkout -b feature/123-add-new-tool
# Work and commit
git add .
git commit -m "feat: implement new VM monitoring tool
- Add VM metrics collection
- Implement memory usage tracking
- Add CPU utilization monitoring
Closes #123"
# Push branch
git push -u origin feature/123-add-new-tool# After PR approval and merge
git checkout main
git pull origin main
git branch -d feature/123-add-new-tool
git push origin --delete feature/123-add-new-tool# Critical production issue
git checkout main
git pull origin main
git checkout -b hotfix/critical-security-patch
# Make minimal fix
git add .
git commit -m "hotfix: patch critical security vulnerability
- Fix shell injection in subprocess calls
- Update affected methods to use shell=False
- Add input validation
Addresses CVE-2025-XXXX"
# Push and create emergency PR
git push -u origin hotfix/critical-security-patch
# Create PR with "hotfix" label for fast-track review# Prepare release
git checkout main
git pull origin main
git checkout -b release/v1.0.0
# Update version numbers, finalize docs
git add .
git commit -m "release: prepare v1.0.0
- Update version to 1.0.0
- Finalize release notes
- Update documentation"
# Create release PR
git push -u origin release/v1.0.0
# After merge, tag the release
git tag v1.0.0
git push origin v1.0.0## Summary
Brief description of changes
## Changes Made
- Bullet point list of changes
- Link to related issues: Closes #123
## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
## Documentation
- [ ] Documentation updated
- [ ] README updated if needed
- [ ] API docs updated if needed
## Breaking Changes
- [ ] No breaking changes
- [ ] Breaking changes documented and versionedgit rebase main
# Fix conflicts in files
git add .
git rebase --continue
