proxmox/README.md

# 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
   # Recommended: run setup to create .env in repo root and ~/.env from .env.example
   ./scripts/setup.sh
   # Or manually: copy template to repo root and/or home
   cp .env.example .env
   # and/or: cp .env.example ~/.env
   # Edit with your Proxmox, Cloudflare, NPM credentials (see .env.example)
   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)

### UniFi Commands

- `pnpm unifi:build` - Build UniFi API and MCP server packages
- `pnpm unifi:start` - Start the UniFi MCP server
- `pnpm unifi:dev` - Start the UniFi MCP server in development mode
- `pnpm unifi:cli` - Run UniFi CLI tool

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

### unifi-api & mcp-unifi-server

UniFi API client library and MCP server for managing Ubiquiti UniFi/UDM Pro devices.

**Features:**
- Type-safe API client with full TypeScript support
- Dual API mode support (Official Local API and Private Controller API)
- MCP server for Claude Desktop integration
- CLI tool for common operations
- Utility scripts for monitoring and health checks

See [unifi-api/README.md](unifi-api/README.md) for API client documentation.
See [mcp-unifi/README.md](mcp-unifi/README.md) for MCP server documentation.

**Configuration:**
See [docs/04-configuration/UNIFI_API_SETUP.md](docs/04-configuration/UNIFI_API_SETUP.md) for setup instructions.

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

## How to Navigate This Repo

**New to this repository?** Start here:

- **[ROOT_INDEX.md](ROOT_INDEX.md)** - Quick navigation index for newcomers and auditors
- **[DIRECTORY_REFERENCE.md](DIRECTORY_REFERENCE.md)** - Complete directory structure and organization guide
- **[docs/MASTER_INDEX.md](docs/MASTER_INDEX.md)** - Documentation index (deployment, architecture, services)
- **[PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)** - Project and docs structure

**Organization principles:** This repository uses a **flat + indexed** structure. The three-layer separation (control plane / core systems / ops evidence) is a **mental model**, not an enforced structure. See [docs/MASTER_INDEX.md](docs/MASTER_INDEX.md) and [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) for structure and intent.

## 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/12-quick-reference/QUICK_REFERENCE.md](docs/12-quick-reference/QUICK_REFERENCE.md) - Quick reference for ProxmoxVE scripts
- [docs/12-quick-reference/QUICK_REFERENCE_CARDS.md](docs/12-quick-reference/QUICK_REFERENCE_CARDS.md) - Network, VMID, commands, troubleshooting cards
- [docs/01-getting-started/README_START_HERE.md](docs/01-getting-started/README_START_HERE.md) - Getting started guide

### Deployment
- [docs/03-deployment/DEPLOYMENT_STATUS_CONSOLIDATED.md](docs/03-deployment/DEPLOYMENT_STATUS_CONSOLIDATED.md) - Deployment status
- [docs/03-deployment/DEPLOYMENT_READINESS.md](docs/03-deployment/DEPLOYMENT_READINESS.md) - Deployment readiness checklist
- **Next steps (master list):** [docs/00-meta/NEXT_STEPS_MASTER.md](docs/00-meta/NEXT_STEPS_MASTER.md)
- **CCIP WETH9 Bridge (Chain 138):** `./scripts/deploy-and-configure-weth9-bridge-chain138.sh` (use `--dry-run` to simulate) then set `CCIPWETH9_BRIDGE_CHAIN138`; see [COMPREHENSIVE_STATUS_BRIDGE_READY.md](COMPREHENSIVE_STATUS_BRIDGE_READY.md), [docs/07-ccip/README.md](docs/07-ccip/README.md), [scripts/README.md](scripts/README.md)

### Project Documentation
- [mcp-proxmox/README.md](mcp-proxmox/README.md) - MCP Server detailed documentation
- [ProxmoxVE/README.md](ProxmoxVE/README.md) - ProxmoxVE scripts documentation

### Multi-Chain Integration
- [ALL Mainnet Integration](ALL_MAINNET_MASTER_DOCUMENTATION.md) - Complete ALL Mainnet (651940) integration guide
- [ALL Mainnet Master Documentation](ALL_MAINNET_MASTER_DOCUMENTATION.md) - Quick reference for ALL Mainnet configuration

## 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/03-deployment/DEPLOYMENT_READINESS.md](docs/03-deployment/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.