241 lines
6.4 KiB
Markdown
241 lines
6.4 KiB
Markdown
# Proxmox Project Workspace
|
|
|
|
This workspace contains multiple Proxmox-related projects managed as a monorepo using pnpm workspaces.
|
|
|
|
## Project Structure
|
|
|
|
- **`mcp-proxmox/`** - Proxmox MCP (Model Context Protocol) Server - Node.js-based server for interacting with Proxmox hypervisors
|
|
- **`ProxmoxVE/`** - ProxmoxVE Helper Scripts - Collection of scripts and frontend for managing Proxmox containers and VMs
|
|
- **`smom-dbis-138-proxmox/`** - Deployment scripts and configurations for specific use cases
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 16+
|
|
- pnpm 8+
|
|
- Git (for submodule management)
|
|
|
|
## Setup
|
|
|
|
### Quick Setup
|
|
|
|
Run the automated setup script:
|
|
|
|
```bash
|
|
./scripts/setup.sh
|
|
```
|
|
|
|
This will:
|
|
- Create `.env` file from template (if it doesn't exist)
|
|
- Create Claude Desktop configuration (if it doesn't exist)
|
|
- Install all workspace dependencies
|
|
|
|
### Manual Setup
|
|
|
|
1. **Clone the repository** (if not already done):
|
|
```bash
|
|
git clone <repository-url>
|
|
cd proxmox
|
|
```
|
|
|
|
2. **Initialize and update submodules**:
|
|
```bash
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
3. **Install dependencies**:
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
4. **Configure environment**:
|
|
```bash
|
|
# Copy .env template
|
|
cp .env.example ~/.env
|
|
# Edit with your Proxmox credentials
|
|
nano ~/.env
|
|
```
|
|
|
|
5. **Configure Claude Desktop**:
|
|
```bash
|
|
# Copy config template
|
|
mkdir -p ~/.config/Claude
|
|
cp claude_desktop_config.json.example ~/.config/Claude/claude_desktop_config.json
|
|
# Verify the path in the config file is correct
|
|
```
|
|
|
|
6. **Verify setup**:
|
|
```bash
|
|
./scripts/verify-setup.sh
|
|
```
|
|
|
|
This will install dependencies for all workspace packages and set up configuration files.
|
|
|
|
## Available Scripts
|
|
|
|
From the root directory, you can run:
|
|
|
|
### MCP Server Commands
|
|
|
|
- `pnpm mcp:start` - Start the Proxmox MCP server
|
|
- `pnpm mcp:dev` - Start the MCP server in development mode (with watch)
|
|
|
|
### Frontend Commands
|
|
|
|
- `pnpm frontend:dev` - Start the ProxmoxVE frontend development server
|
|
- `pnpm frontend:build` - Build the ProxmoxVE frontend for production
|
|
- `pnpm frontend:start` - Start the production frontend server
|
|
|
|
### Testing
|
|
|
|
- `pnpm test` - Run tests (if available)
|
|
- `pnpm test:basic` - Run basic MCP server tests (read-only operations)
|
|
- `pnpm test:workflows` - Run comprehensive workflow tests (requires elevated permissions)
|
|
|
|
## Workspace Packages
|
|
|
|
### mcp-proxmox-server
|
|
|
|
The Proxmox MCP server provides a Model Context Protocol interface for managing Proxmox hypervisors.
|
|
|
|
**Features:**
|
|
- 55+ MCP tools for Proxmox management
|
|
- Configurable permission levels (basic vs elevated)
|
|
- Secure token-based authentication
|
|
- Support for VMs, containers, storage, snapshots, backups, and more
|
|
|
|
See [mcp-proxmox/README.md](mcp-proxmox/README.md) for detailed documentation.
|
|
|
|
**Configuration:**
|
|
See [docs/MCP_SETUP.md](docs/MCP_SETUP.md) for instructions on configuring the MCP server with Claude Desktop.
|
|
|
|
### proxmox-helper-scripts-website
|
|
|
|
A Next.js frontend for browsing and managing Proxmox helper scripts.
|
|
|
|
**Features:**
|
|
- Browse available container and VM scripts
|
|
- View script details, requirements, and installation instructions
|
|
- JSON editor for script metadata
|
|
- Category and version management
|
|
|
|
See [ProxmoxVE/frontend/README.md](ProxmoxVE/frontend/README.md) for more information.
|
|
|
|
## Environment Configuration
|
|
|
|
### MCP Server Configuration
|
|
|
|
The MCP server loads configuration from `/home/intlc/.env` (one directory up from the project root). Create this file with:
|
|
|
|
```bash
|
|
PROXMOX_HOST=your-proxmox-ip-or-hostname
|
|
PROXMOX_USER=root@pam
|
|
PROXMOX_TOKEN_NAME=your-token-name
|
|
PROXMOX_TOKEN_VALUE=your-token-secret
|
|
PROXMOX_ALLOW_ELEVATED=false
|
|
PROXMOX_PORT=8006
|
|
```
|
|
|
|
See [docs/MCP_SETUP.md](docs/MCP_SETUP.md) for detailed configuration instructions.
|
|
|
|
## Development
|
|
|
|
### Working with Submodules
|
|
|
|
To update submodules to their latest versions:
|
|
|
|
```bash
|
|
git submodule update --remote
|
|
```
|
|
|
|
To update a specific submodule:
|
|
|
|
```bash
|
|
cd mcp-proxmox
|
|
git pull origin main
|
|
cd ..
|
|
git add mcp-proxmox
|
|
git commit -m "Update mcp-proxmox submodule"
|
|
```
|
|
|
|
### Adding New Dependencies
|
|
|
|
To add a dependency to a specific workspace package:
|
|
|
|
```bash
|
|
pnpm --filter mcp-proxmox-server add <package-name>
|
|
pnpm --filter proxmox-helper-scripts-website add <package-name>
|
|
```
|
|
|
|
To add a dev dependency:
|
|
|
|
```bash
|
|
pnpm --filter <package-name> add -D <package-name>
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
proxmox/
|
|
├── scripts/ # Project root utility scripts
|
|
├── docs/ # Project documentation
|
|
├── mcp-proxmox/ # MCP Server submodule
|
|
├── ProxmoxVE/ # ProxmoxVE Helper Scripts submodule
|
|
└── smom-dbis-138-proxmox/ # Deployment scripts submodule
|
|
```
|
|
|
|
See [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) for detailed structure documentation.
|
|
|
|
## Project Documentation
|
|
|
|
### Setup & Configuration
|
|
- [docs/MCP_SETUP.md](docs/MCP_SETUP.md) - MCP Server configuration guide
|
|
- [docs/PREREQUISITES.md](docs/PREREQUISITES.md) - Prerequisites and requirements
|
|
- [docs/ENV_STANDARDIZATION.md](docs/ENV_STANDARDIZATION.md) - Environment variable standardization
|
|
|
|
### Quick References
|
|
- [docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) - Quick reference for ProxmoxVE scripts
|
|
- [docs/README_START_HERE.md](docs/README_START_HERE.md) - Getting started guide
|
|
|
|
### Deployment
|
|
- [docs/DEPLOYMENT_VALIDATION_REPORT.md](docs/DEPLOYMENT_VALIDATION_REPORT.md) - Deployment validation for ml110-01
|
|
|
|
### Project Documentation
|
|
- [mcp-proxmox/README.md](mcp-proxmox/README.md) - MCP Server detailed documentation
|
|
- [ProxmoxVE/README.md](ProxmoxVE/README.md) - ProxmoxVE scripts documentation
|
|
|
|
## Deployment Status
|
|
|
|
### ✅ Ready for Deployment
|
|
|
|
**Current Status:** All validations passing (100%)
|
|
|
|
- ✅ Prerequisites: 33/33 (100%)
|
|
- ✅ Deployment Validation: 41/41 (100%)
|
|
- ✅ API Connection: Working (Proxmox 9.1.1)
|
|
- ✅ Target Node: ml110 (online)
|
|
|
|
**Quick Deploy:**
|
|
```bash
|
|
cd smom-dbis-138-proxmox
|
|
sudo ./scripts/deployment/deploy-all.sh
|
|
```
|
|
|
|
See [docs/DEPLOYMENT_READINESS.md](docs/DEPLOYMENT_READINESS.md) for complete deployment guide.
|
|
|
|
## Validation
|
|
|
|
Run comprehensive validation:
|
|
```bash
|
|
./scripts/complete-validation.sh
|
|
```
|
|
|
|
Individual checks:
|
|
- `./scripts/check-prerequisites.sh` - Prerequisites validation
|
|
- `./scripts/validate-ml110-deployment.sh` - Deployment validation
|
|
- `./scripts/test-connection.sh` - Connection testing
|
|
|
|
## License
|
|
|
|
This workspace contains multiple projects with different licenses. Please refer to individual project directories for license information.
|
|
|