# 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)

## RPC Node Health, Testing, and Remediation (Chain 138)

This repo includes scripts to **test all RPC nodes**, **audit Proxmox storage restrictions**, and **enforce safe Besu heap sizing** to prevent swap/IO thrash.

### Run the full health suite (recommended)

```bash
PROXMOX_HOST=192.168.11.10 ./scripts/run-rpc-node-suite.sh
```

- Writes RPC test reports under `reports/` (JSON + Markdown).
- Runs remediation in **dry-run** mode by default.

### Apply remediation (only if you intend to change Proxmox / containers)

```bash
PROXMOX_HOST=192.168.11.10 ./scripts/run-rpc-node-suite.sh --apply --restart-besu
```

### Individual tools

```bash
# Full RPC matrix test (no Proxmox access required)
python3 ./scripts/test-all-rpc-nodes.py

# Proxmox audits
PROXMOX_HOST=192.168.11.10 ./scripts/audit-proxmox-rpc-storage.sh
PROXMOX_HOST=192.168.11.10 ./scripts/audit-proxmox-rpc-besu-heap.sh

# Idempotent remediation (dry-run by default)
PROXMOX_HOST=192.168.11.10 ./scripts/remediate-proxmox-rpc-stability.sh
```

## 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](docs/01-getting-started/README.md) for detailed documentation.

**Configuration:**
See [docs/MCP_SETUP.md](docs/04-configuration/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](docs/01-getting-started/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/04-configuration/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/04-configuration/MCP_SETUP.md) - MCP Server configuration guide
- [docs/PREREQUISITES.md](docs/01-getting-started/PREREQUISITES.md) - Prerequisites and requirements
- [docs/ENV_STANDARDIZATION.md](docs/04-configuration/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/01-getting-started/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](docs/01-getting-started/README.md) - MCP Server detailed documentation
- [ProxmoxVE/README.md](docs/01-getting-started/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.