This document contains the findings from a thorough review of the ProxmoxMCP
repository, focusing on potential issues, bugs, security vulnerabilities, and
enhancement opportunities.
1. Introduction and Overview
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/)
This review examines the codebase across multiple dimensions including code
quality, Docker implementation, architecture, security, and documentation.
2. Code Quality and Reliability Findings
Security Vulnerabilities
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
Error Handling
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
Potential Bugs
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
Code Quality
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
3. Docker Implementation Findings
Security Practices
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
Resource Management
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
Configuration
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
Build Optimization
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
4. Architecture Findings
Project Structure
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
Scalability
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
Extensibility
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
Integration
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)
5. Security Findings
Authentication
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
SSL/TLS
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
Input Validation
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
Access Control
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
Secrets Management
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
6. Documentation Findings
README Clarity
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
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.
Getting Started
Fork the repository on GitHub
Clone your fork locally
Set up the development environment
Create a new branch for your changes
Development Environment
Prerequisites
Python 3.8 or higher
Docker (for containerized development)
Proxmox VE instance (for testing)
Setup
Clone the repository:
Set up git configuration for development:
The example.gitconfig includes development-friendly settings like:
Python/JSON/Dockerfile diff patterns
Contribution Workflow
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
Coding Standards
Follow style guidelines
Use type hints for function parameters and return values
Write docstrings for all functions, classes, and modules
Code Formatting
We use the following tools for code formatting and linting:
for code formatting and linting
for type checking
You can run these tools with:
Testing
Write unit tests for all new functionality
Ensure all tests pass before submitting a pull request
Aim for high test coverage of your code
To run tests:
For coverage report:
Documentation
Update documentation for any changes to functionality
Document all public APIs
Include examples where appropriate
Issue and Pull Request Process
Issues
Use the appropriate issue template
Provide clear and detailed information
Include steps to reproduce for bugs
Pull Requests
Reference the related issue in your pull request
Provide a clear description of the changes
Update documentation as needed
Security Vulnerabilities
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.
Community
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!
Project Roadmap
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:
Secure Token Storage
SSL Security
Input Validation
Configuration Security
Phase 2: Docker Improvements (1 day)
Enhance Docker security and deployment:
Docker Security
Docker Secrets
Resource Management
Phase 3: Enhanced Error Handling (2-3 days)
Standardize error handling across the codebase:
Exception Hierarchy
Error Handling Implementation
Health Check Endpoint
Phase 4: Performance Improvements
Optimize performance for production workloads:
Connection Management
Async Operations
Phase 5: Feature Additions
Add new functionality after core improvements:
LXC Support
Batch Operations
Extended Functionality
Quick Wins for Immediate Impact
These can be implemented alongside the phases:
Testing & Quality Assurance
Throughout all phases:
Timeline
Phase 1: 1-2 days (Critical security fixes)
Phase 2: 1 day (Docker improvements)
Phase 3: 2-3 days (Error handling)
Focus Areas
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.
Pre-commit Setup
Based on Codacy analysis, this document outlines the comprehensive improvements made to our pre-commit hooks system.
🎯 Overview
We've enhanced your existing task-based workflow with proper pre-commit hooks that
automatically catch and fix the issues identified by Codacy analysis.
check-test-credentials - Test credential validation
🟢 Informational
hadolint - Dockerfile linting
shellcheck - Shell script linting
yamllint - YAML formatting
🎛️ Configuration Files
.pre-commit-config.yaml
Main configuration with all hooks and settings.
pyproject.toml (Enhanced)
Taskfile.yml (Enhanced)
Added security, complexity, and hooks management tasks.
🔧 Customization
Adjusting Security Rules
Complexity Thresholds
Adding Custom Hooks
🎯 Next Steps
Immediate Actions
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
Ongoing Maintenance
Weekly: task hooks:update to update hook versions
Monthly: pre-commit run safety --hook-stage manual for dependency checks
Before releases: task complexity
Integration with CI/CD
Your existing autofix workflow will work seamlessly with these changes:
Consider adding:
🤔 Troubleshooting
Hook Failures
Performance Issues
📈 Benefits
Security
Automatic detection of shell=True vulnerabilities
Dependency scanning for known CVEs
Credential leak prevention in test files
Code Quality
Complexity monitoring to prevent technical debt
Consistent formatting across all files
Type safety enforcement
Developer Experience
Faster feedback - catch issues before CI
Automatic fixes for many issues
Clear error messages with fix suggestions
Team Consistency
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)
Claude Code Automation
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.
How It Works
1. Creating an Issue for Claude Code
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)
2. Automatic Process
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
3. Review Process
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
Configuration Requirements
Repository Secrets
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
Permissions
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
Environment Requirements
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
Workflow Configuration
The automation is configured in .github/workflows/claude-issue-assignment.yml with:
Issue Template Guidelines
When creating issues for Claude Code, include:
Clear Task Description
Specific Requirements
Acceptance Criteria
Technical Details
Best Practices
For Issue Creation
Be specific about requirements
Provide examples of expected behavior
Include error cases to handle
For Review
Check that the solution follows project conventions
Verify tests are comprehensive
Ensure documentation is updated if needed
Troubleshooting
Common Issues
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)
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
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
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
Debugging Steps
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
Getting Help
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
Workflow Execution Details
Step-by-Step Process
When an issue is assigned to trigger the automation, the following steps occur:
Branch Creation
Environment Setup
Claude Code Implementation
Quality Assurance
The workflow automatically runs these checks:
pytest: All test suites must pass
ruff: Code formatting and linting compliance
mypy: Type checking validation
Example Workflow
Create Issue: Use the Claude Code Task template
Automatic Processing:
Workflow triggers on assignment
This automation streamlines the development process while maintaining code quality and project standards.
Taskfile Integration
🚀 Quick Integration
To integrate branch management tasks into your existing Taskfile.yml:
# 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 mcp
class ProxmoxError(Exception):
"""Base exception for Proxmox operations"""
pass
class ProxmoxAuthError(ProxmoxError):
"""Authentication-related errors"""
pass
class ProxmoxResourceNotFoundError(ProxmoxError):
"""Resource not found errors"""
pass
def _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)}
# In proxmox_mcp/tools/container.py
class ContainerTools(ProxmoxTool):
def get_containers(self) -> List[Content]:
"""List LXC containers"""
# Implementation similar to VM tools
async 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)
# 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
# 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)
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.
## 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: basher83
Branch Creation Tasks
Task
Description
Usage
task 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"
Branch Management Tasks
Task
Description
Usage
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
Workflow Tasks
Task
Description
Usage
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
🎯 Usage Examples
Starting New Work
During Development
Finishing Work
Quality Assurance Integration
🔄 Integration with Existing Tasks
The new branch tasks work seamlessly with your existing workflow:
🎨 Task Features
Command Line Arguments
Interactive Mode
Status and Information
🔧 Advanced Usage
Custom Workflows
Git Integration
CI/CD Integration
🛠️ Customization
Modifying Tasks
You can customize the branch tasks by editing the Taskfile.yml:
Environment Variables
The tasks respect your existing environment:
📊 Task List Integration
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.
🔄 Migration and Compatibility
Backward Compatibility
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
New Dependencies
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!
🚨 Troubleshooting
Common Issues
Task not found:
Branch script not executable:
Git errors:
Getting Help
🎉 Quick Start Cheat Sheet
This integration makes branch management a natural part of your existing Task workflow while
maintaining all the power and flexibility of your current setup!
Claude SDK Integration
Project Overview
This 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.
Goals
Add AI-powered diagnostic capabilities to ProxmoxMCP
Provide intelligent cluster health analysis and recommendations
Enable automated VM issue diagnosis and troubleshooting
Scope
Integration of Claude Code SDK for AI analysis
Four new MCP tools for intelligent diagnostics
Comprehensive data collection from Proxmox APIs
Milestone Tracking
Phase 1: Foundation Setup ✅ COMPLETED
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
Phase 2: Core Implementation ✅ COMPLETED
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
Phase 3: Integration & Registration ✅ COMPLETED
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
Phase 4: Testing & Validation ✅ COMPLETED
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 ✅
Phase 5: Documentation & Finalization 🔄 IN PROGRESS
Target: Complete documentation and prepare for release
Acceptance Criteria:
Complete user documentation
Usage examples for all AI tools
Configuration guide for Claude Code SDK
Phase 6: Enhanced VM Console Features 🔄 PLANNED
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
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.
Advanced AI Features (Future)
Predictive Analysis: Forecast resource needs and potential issues
Trend Analysis: Historical data analysis and pattern recognition
Integration Expansions (Future)
Multi-Cluster: Analysis across multiple Proxmox clusters
External Data: Integration with monitoring systems
Reporting: Automated report generation and scheduling
Success Metrics
Technical Metrics
Performance: Analysis completion time < 30 seconds
Accuracy: AI recommendations validated by experts
Reliability: 99%+ uptime for AI diagnostic features
User Experience Metrics
Adoption: Usage of AI diagnostic tools
Satisfaction: User feedback on AI recommendations
Effectiveness: Problems solved using AI insights
Conclusion
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)
Introduction
A 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 with Docker support and active maintenance.
Testing Guide
This document describes the comprehensive testing capabilities available in ProxmoxMCP through the
enhanced Taskfile.yml configuration.
Overview
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.
Development Workflows
This document provides comprehensive documentation for all automated workflows, CI/CD processes, and development practices in the ProxmoxMCP project.
Table of Contents
Security Fix Verification
Summary
This document verifies that all action items from GitHub issue #61 regarding
critical subprocess shell=True vulnerabilities have been completed.
Issue #61 Action Items Status
Branch Management
Comprehensive branch management documentation including implementation details, strategy, and workflow guidelines.
Table of Contents
Dependency Scanning
This document outlines the security scanning process for ProxmoxMCP dependencies.
Current Security Status
✅ All dependencies updated as of commit b9fb0da:
# 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
# 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!"
# Make sure integration completed
task --list | grep branch
# If not found, re-run integration
./scripts/branch-templates/integrate-taskfile.sh
chmod +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 info
✅ Fix encrypt_config.py:47 to use shell=False
Status: 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)
✅ Update platform-specific command handling
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
✅ Fix test assertions in test_encrypt_config.py
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
✅ Verify no other shell=True instances exist
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
✅ Add pre-commit hook to prevent future shell=True usage
Prevents future introduction of shell=True vulnerabilities
Security Implementation Details
Current Secure Implementation
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
Security Benefits
Eliminates command injection vulnerabilities
No shell interpretation of user input
Maintains functionality across platforms
Follows security best practices
Verification Commands Run
find_filecontent searches for shell=True in src/ and tests/
Pre-commit hook testing
Code formatting and linting verification
Conclusion
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
License
Python Configuration
Encrypted Config
MCP Settings Example
Config Examples
Standard Config
Docker Configuration
Implement resource optimization suggestions
Add comprehensive security posture analysis
Extended Vision: Evolve into comprehensive AI-powered configuration management platform
Rich formatted output using existing ProxmoxTemplates
Full test coverage and documentation
Rich formatted output consistent with existing tools
Run focused subsets (test:security, test:tools) for quick feedback
Use task test:coverage periodically to identify coverage gaps
Run task pre-commit before committing changes
CI/CD Testing
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
Team Collaboration
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.
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)
Manual Scanning Commands
Using uv with pip-audit
Using safety (alternative)
Monitoring and Prevention
Regular Security Reviews
Run dependency scans before each release
Monitor security advisories for core dependencies
Update vulnerable dependencies immediately for critical issues
Automated Prevention (Future Enhancement)
Consider implementing:
GitHub Dependabot for automated dependency updates
Pre-commit hooks for security scanning
CI/CD integration with security scanning tools
Response Process for Vulnerabilities
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
Document Resolution: Update this file with resolution details
Contact and Escalation
For critical security vulnerabilities, follow responsible disclosure practices and escalate to
project maintainers immediately.
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 Workflows
src/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 tests
# 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 = True
task test
task test:unit
task test:coverage
uv add pytest-cov --group dev
task test:watch
uv add pytest-watch --group dev
task test:security
task test:tools
task test:config
task 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
# 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
# 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 test
# 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
The 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.
Key Principles
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
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.
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.
Implementation Summary (PR #67)
Comprehensive Branch Management System Implementation
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.
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: Easy addition of new valid components
🧪 Testing Results
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
✅ No unused variables (all exported for external use)
✅ Parameter expansion used instead of sed (addresses SC2001)
🚀 Usage Examples
Quick Start
Advanced Usage
🔧 Integration Options
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.
📊 Impact Assessment
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
✅ Completion Status
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
✅ Integration-ready with Git hooks and CI/CD systems
The branch management system is ready for immediate use and provides a solid foundation for maintaining consistent branch naming conventions across the ProxmoxMCP project.
Branching Strategy
Enhanced GitHub Flow
This section outlines the branching strategy and workflow for the ProxmoxMCP repository to ensure consistent, high-quality development practices.
Branch Types
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
Workflow Processes
Standard Development Workflow
1. Start New Work
2. Create Pull Request
Use PR template checklist
Link related issues
Add appropriate labels
Request relevant reviewers
Ensure all CI checks pass
3. Review Process
Address review feedback
Keep commits clean and logical
Squash commits if necessary before merge
4. Merge and Cleanup
Emergency Hotfix Workflow
Release Workflow
Branch Protection Rules
Main Branch Protection
✅ Require pull request reviews before merging (minimum: 1)
✅ Require status checks to pass before merging
Codacy quality checks
CI/CD workflows (autofix, yaml-lint)
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
Quality Gates
All PRs must pass:
Automated Checks
Codacy quality assessment
Security vulnerability scans
Linting (ruff, black, mypy)
Test suite (pytest)
Manual Review
Code quality review
Security review (for security changes)
Best Practices
PR Review Guidelines
For Reviewers
Security Changes
Code Changes
Documentation Changes
For Contributors
Before Creating PR
PR Description Template
Integration with Existing Tools
Codacy Integration
All PRs must pass Codacy quality gates
Security issues must be addressed before merge
Code complexity limits enforced
Dependabot Integration
Automated dependency PRs get dependencies label
Security updates get expedited review
Breaking changes require manual testing
CI/CD Workflows
autofix.yml: Automated formatting fixes
claude-auto-review.yml: AI-assisted code review
yaml-lint.yml: YAML file validation
All workflows must pass for PR merge
Migration Plan
Phase 1: Foundation (Week 1)
Update branch protection rules
Create PR and issue templates
Document new workflow (this guide)
Train team on new process
Phase 2: Process Rollout (Week 2)
Apply new workflow to all new PRs
Migrate any existing feature work to proper branches
Update CI/CD to enforce new rules
Phase 3: Optimization (Week 3-4)
Monitor adoption and address issues
Refine review process based on experience
Add additional automation as needed
Create release process documentation
Troubleshooting
Common Issues
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.
Benefits of This Strategy
Quality Assurance: All changes reviewed and tested
Security Focus: Mandatory security reviews for sensitive changes
This 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.
Major Efficiency Issues Identified
1. N+1 Query Problem in VM Tools (HIGH PRIORITY)
File:src/proxmox_mcp/tools/vm.pyLines: 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.
2. N+1 Query Problem in Node Tools (MEDIUM PRIORITY)
File:src/proxmox_mcp/tools/node.pyLines: 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
3. N+1 Query Problem in Storage Tools (MEDIUM PRIORITY)
File:src/proxmox_mcp/tools/storage.pyLines: 70-90
Impact: Medium - Storage pools are typically fewer but still inefficient
Issue: Each storage pool requires individual status API call:
4. Missing Caching Layer (MEDIUM PRIORITY)
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.
Graceful Degradation: Use available data when detailed config unavailable
Expected Performance Improvement
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
Implementation Priority
Phase 1: VM Tools Optimization (Immediate)
Fix N+1 query problem in get_vms() method
Implement better error isolation
Maintain backward compatibility
Phase 2: Node and Storage Tools (Future)
Apply similar optimizations to node and storage tools
Consider implementing parallel API calls
Phase 3: Caching Layer (Future)
Implement TTL-based caching for static data
Add cache invalidation mechanisms
Consider memory usage implications
Phase 4: Error Handling Consolidation (Future)
Abstract common error handling patterns
Implement retry mechanisms where appropriate
Improve error reporting granularity
Testing Considerations
Performance Testing
Measure API call reduction in test environments
Benchmark response times with varying cluster sizes
Monitor memory usage with optimizations
Functional Testing
Ensure response format remains unchanged
Verify error handling still works correctly
Test fallback mechanisms
Regression Testing
Confirm existing functionality preserved
Validate error scenarios still handled properly
Check edge cases (empty clusters, offline nodes)
Conclusion
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.
Milestone Planning
ProxmoxMCP Milestone Planning Guide
Comprehensive milestone planning documentation including current milestones, management guidelines, and best practices.
Table of Contents
Current Milestones
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.
Compatibility Matrix
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+
4 v1.0.0 - First Stable Release https://github.com/basher83/ProxmoxMCP/milestone/4
5 v1.1.0 - Enhanced Features https://github.com/basher83/ProxmoxMCP/milestone/5
6 v1.2.0 - Production Hardening https://github.com/basher83/ProxmoxMCP/milestone/6
🔧 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
Testing Infrastructure: Automated testing with mocked Proxmox environments
Documentation: User guides, API documentation, deployment examples
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
Risk Assessment
Technical Risks: Proxmox API changes, MCP protocol updates
Mitigation: Version pinning, compatibility testing, fallback implementations
Resource Risk: Documentation completion timeline
Target Users
Home lab enthusiasts, small business IT administrators, automation developers seeking stable ProxmoxMCP foundation
v1.0.0 - First Stable Release
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.
Security Risk: Vulnerability discovery during audit
Mitigation: Early security testing, regular vulnerability scans, security-first development
Performance Risk: Latency issues under load
Target Users
Home lab enthusiasts, small business IT, automation developers, early enterprise adopters
v1.1.0 - Enhanced Features
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.
Performance Risk: Feature additions impacting response times
Target Users
Power users, automation specialists, enterprise evaluators, DevOps teams
v1.2.0 - Production Hardening
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
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
Workflow and Commands
Milestone Management Workflow
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
Milestone vs. Projects vs. Labels
Feature
Use For
Example
Tracking and Metrics
Key Metrics to Monitor
Burn-down rate: Issues closed over time
Scope creep: Issues added after milestone start
Velocity: Average issues completed per week
GitHub Insights
Use milestone progress bar
Filter issues by milestone
Generate release notes from closed issues
ProxmoxMCP Specific Recommendations
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
Sample Milestone Description
Regular Review Process
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.
Markdown Automation
Comprehensive guide to automated markdown formatting and quality assurance
🎯 Overview
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.
🛠️ Components
1. markdownlint-cli2
Purpose: Modern, fast markdown linting tool
Auto-fix: Automatically resolves 70%+ of formatting issues
Integration: Works with pre-commit, CI/CD, and local development
2. Configuration (.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
3. Taskfile Integration
4. Pre-commit Hook
Automatic: Runs on every commit
Auto-fix: Applies fixes before commit
Fast: Only processes changed markdown files
5. GitHub Actions Workflow
PR Analysis: Automatic markdown quality checking
Auto-fix Commits: Pushes fixes directly to PR branches
Scheduled quality reports: Weekly documentation health checks
Integration with project management: Link quality metrics to milestones
Multi-language support: Extend to other markup formats
📚 Additional Resources
: See markdown tasks
💡 Tip: Run task markdown:summary regularly to monitor documentation
quality and catch issues early in development.
Security & Encryption
ProxmoxMCP now supports secure encryption of API tokens and other sensitive configuration values at rest.
Features
Fernet Encryption: Industry-standard AES 128 in CBC mode with HMAC SHA256 authentication
Secure Key Derivation: PBKDF2 with salt to prevent rainbow table attacks
Environment-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
Quick Start
1. Generate a Master Key
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.
2. Encrypt Your Configuration
3. Use Encrypted Configuration
CLI Reference
Encrypt Configuration File
Check Encryption Status
Generate Master Key
Master Key Rotation
ProxmoxMCP supports secure master key rotation for enhanced security compliance and incident response.
Rotate Key for Single Configuration
Rotate Key for All Configurations
Key Rotation Best Practices
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
Configuration Format
Before Encryption
After Encryption
Environment Variables
Variable
Description
Required
Security Best Practices
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
Migration from Plain Text
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
Troubleshooting
Common Issues
"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
Debug Mode
Enable debug logging to troubleshoot encryption issues:
Key Rotation Procedures
Key rotation is essential for maintaining long-term security. ProxmoxMCP provides comprehensive
tools and procedures for safely rotating encryption keys.
When to Rotate 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
Pre-Rotation Checklist
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
Step-by-Step Rotation Procedure
1. Preparation Phase
2. Single Configuration Rotation
3. Bulk Configuration Rotation
4. Environment Update
5. Validation Phase
Zero-Downtime Rotation Strategies
Blue-Green Deployment
Prepare Green Environment: Deploy with new keys
Validate Green: Test all functionality
Switch Traffic: Update load balancer/proxy
Rolling Update
Rotate Keys: Generate new keys for configuration
Update Environment: Set new master key
Restart Service: Restart with new configuration
Rollback Procedures
If key rotation fails, follow these steps:
Immediate Rollback
Post-Rollback Analysis
Document Issue: Record what went wrong
Preserve Evidence: Keep failed configuration for analysis
Review Logs: Check server and application logs
Advanced Key Management
Multi-Environment Key Management
Development Environment
Staging Environment
Production Environment
Key Management Lifecycle
Key Generation
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)
Key Storage
Separate Storage: Never store keys with encrypted data
Access Control: Implement strict access controls
Encryption at Rest: Encrypt keys in storage systems
Key Distribution
Secure Channels: Use encrypted communication for key distribution
Just-in-Time: Provide keys only when needed
Audit Trail: Log key access and distribution
Key Retirement
Secure Deletion: Use cryptographic erasure techniques
Audit Cleanup: Remove keys from all systems
Documentation: Update key management records
Disaster Recovery Scenarios
Lost Master Key
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
Corrupted Configuration
If configuration files become corrupted:
Stop Service: Prevent further issues
Restore Backup: Use most recent valid backup
Validate Restoration: Test with current master key
Compromised Keys
If key compromise is suspected:
Immediate Rotation: Start emergency key rotation
Revoke Access: Disable compromised keys
Audit Usage: Review key usage logs
Troubleshooting Key Rotation
Common Rotation Issues
"Current master key cannot decrypt configuration"
Symptoms: Rotation fails during verification phase
Causes:
Wrong PROXMOX_MCP_MASTER_KEY environment variable
Configuration file corrupted
Key truncated or modified
Solutions:
"Failed to create backup"
Symptoms: Backup creation fails during rotation
Causes:
Insufficient disk space
Permission issues
File system errors
Solutions:
"Service fails to start with new key"
Symptoms: Server won't start after key rotation
Causes:
Environment variable not updated
Configuration cache issues
Service configuration problems
Solutions:
Debug Mode for Rotation
Enable detailed logging during rotation:
Validation Procedures After Rotation
Basic Connectivity Test
Full Integration Test
CI/CD Integration
GitHub Actions
GitLab CI
Automated Monitoring
Integration Examples
Docker Compose
Docker Swarm with Secrets
Kubernetes
Systemd Service
Environment file (/etc/proxmox-mcp/environment):
For more information, see the main or .
YAML Linting
This repository includes comprehensive YAML linting and auto-fixing capabilities using yamllint and task automation.
type: 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>
# 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-run
# Run manually to see details
pre-commit run markdownlint-cli2 --all-files
# Update pre-commit
pre-commit autoupdate
# 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
# 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
# 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
# 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 correctly
# 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
# 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
# Reinstall dependencies
task setup
# or
uv sync --extra dev
# Make script executable
chmod +x scripts/yaml-lint.sh
chmod +x scripts/yaml-autofix.sh
task: 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 files
Command execution permissions must be enabled in the Guest Agent
Returns error if command execution fails
Includes command output even if command returns non-zero exit code
