Refactor code for improved readability and performance

2025-12-21 22:32:09 -08:00
parent 79e3c02f50
commit b45c2006be
2259 changed files with 380318 additions and 2 deletions
--- a/docs/01-getting-started/PREREQUISITES.md
+++ b/docs/01-getting-started/PREREQUISITES.md
@@ -0,0 +1,233 @@
+# Prerequisites and Setup Requirements
+
+Complete list of prerequisites and setup steps for the Proxmox workspace.
+
+## System Prerequisites
+
+### Required Software
+
+1. **Node.js**
+   - Version: 16.0.0 or higher
+   - Check: `node --version`
+   - Install: Download from [nodejs.org](https://nodejs.org/) or use package manager
+
+2. **pnpm**
+   - Version: 8.0.0 or higher
+   - Check: `pnpm --version`
+   - Install: `npm install -g pnpm`
+
+3. **Git**
+   - Any recent version
+   - Check: `git --version`
+   - Install: Usually pre-installed on Linux/Mac
+
+### Optional but Recommended
+
+- **Proxmox VE** (if deploying containers)
+  - Version: 7.0+ or 8.4+/9.0+
+  - For local development, you can use the MCP server to connect to remote Proxmox
+
+## Workspace Prerequisites
+
+### 1. Repository Setup
+
+```bash
+# Clone repository (if applicable)
+git clone <repository-url>
+cd proxmox
+
+# Initialize submodules
+git submodule update --init --recursive
+```
+
+### 2. Workspace Structure
+
+Required structure:
+```
+proxmox/
+├── package.json              # Root workspace config
+├── pnpm-workspace.yaml       # Workspace definition
+├── mcp-proxmox/              # MCP server submodule
+│   ├── index.js
+│   └── package.json
+└── ProxmoxVE/                # Helper scripts submodule
+    └── frontend/
+        └── package.json
+```
+
+### 3. Dependencies Installation
+
+```bash
+# Install all workspace dependencies
+pnpm install
+```
+
+This installs dependencies for:
+- `mcp-proxmox-server` - MCP server packages
+- `proxmox-helper-scripts-website` - Frontend packages
+
+## Configuration Prerequisites
+
+### 1. Environment Variables (.env)
+
+Location: `/home/intlc/.env`
+
+Required variables:
+```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
+```
+
+Optional variables:
+```bash
+PROXMOX_PORT=8006  # Defaults to 8006
+```
+
+### 2. Claude Desktop Configuration
+
+Location: `~/.config/Claude/claude_desktop_config.json`
+
+Required configuration:
+```json
+{
+  "mcpServers": {
+    "proxmox": {
+      "command": "node",
+      "args": ["/home/intlc/projects/proxmox/mcp-proxmox/index.js"]
+    }
+  }
+}
+```
+
+## Proxmox Server Prerequisites (if deploying)
+
+### 1. Proxmox VE Installation
+
+- Version 7.0+ or 8.4+/9.0+
+- Access to Proxmox web interface
+- API access enabled
+
+### 2. API Token Creation
+
+Create API token via Proxmox UI:
+1. Log into Proxmox web interface
+2. Navigate to **Datacenter** → **Permissions** → **API Tokens**
+3. Click **Add** to create new token
+4. Save Token ID and Secret
+
+Or use the script:
+```bash
+./scripts/create-proxmox-token.sh <host> <user> <password> <token-name>
+```
+
+### 3. LXC Template (for container deployments)
+
+Download base template:
+```bash
+pveam download local debian-12-standard_12.2-1_amd64.tar.zst
+```
+
+Or use `all-templates.sh` script:
+```bash
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/tools/addon/all-templates.sh)"
+```
+
+## Verification Steps
+
+### 1. Run Complete Setup
+
+```bash
+./scripts/complete-setup.sh
+```
+
+This script verifies and completes:
+- ✅ Prerequisites check
+- ✅ Submodule initialization
+- ✅ Dependency installation
+- ✅ Configuration file creation
+- ✅ Final verification
+
+### 2. Run Verification Script
+
+```bash
+./scripts/verify-setup.sh
+```
+
+### 3. Test MCP Server
+
+```bash
+# Test basic functionality (requires .env configured)
+pnpm test:basic
+
+# Start MCP server
+pnpm mcp:start
+```
+
+## Quick Setup Checklist
+
+- [ ] Node.js 16+ installed
+- [ ] pnpm 8+ installed
+- [ ] Git installed
+- [ ] Repository cloned
+- [ ] Submodules initialized
+- [ ] Dependencies installed (`pnpm install`)
+- [ ] `.env` file created and configured
+- [ ] Claude Desktop config created
+- [ ] (Optional) Proxmox API token created
+- [ ] (Optional) LXC template downloaded
+- [ ] Verification script passes
+
+## Troubleshooting Prerequisites
+
+### Node.js Issues
+
+```bash
+# Check version
+node --version
+
+# Install/update via nvm (recommended)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 18
+nvm use 18
+```
+
+### pnpm Issues
+
+```bash
+# Install globally
+npm install -g pnpm
+
+# Or use corepack (Node.js 16.9+)
+corepack enable
+corepack prepare pnpm@latest --activate
+```
+
+### Submodule Issues
+
+```bash
+# Force update submodules
+git submodule update --init --recursive --force
+
+# If submodules are outdated
+git submodule update --remote
+```
+
+### Dependency Issues
+
+```bash
+# Clean install
+rm -rf node_modules */node_modules */*/node_modules
+rm -rf pnpm-lock.yaml */pnpm-lock.yaml
+pnpm install
+```
+
+## Next Steps After Prerequisites
+
+1. **Configure Proxmox credentials** in `.env`
+2. **Restart Claude Desktop** (if using MCP server)
+3. **Test connection** with `pnpm test:basic`
+4. **Start development** with `pnpm mcp:dev` or `pnpm frontend:dev`
+