Reorganize repository structure and clean up documentation
Clean up and organize the flask-shopdb repository for better maintainability and discoverability: ## Changes - Update .gitignore for build artifacts (publish/, data/, 122M total) - Reorganize .claude/ into 6 subdirectories with README navigation - Consolidate overlapping MCP setup guides into MCP-QUICK-START.md - Move deployment docs from root to docs/deployment/ - Archive dated status reports to .claude/archived/ - Delete temporary files (logs, backups, empty reports, ~50K) ## New Structure .claude/ organized into: - setup/ - MCP, VM, Hyper-V, GitHub setup guides + scripts (17 files) - plans/ - Feature plans and protocols (5 files) - maintenance/ - Deployment checklists and reports (4 files) - archived/ - Historical documentation (9 files) - skills/ - Claude Code automation (5 files) - workflows/ - Security audit workflow (1 file) docs/deployment/ created with 6 deployment guides: - LOCAL-DEV-SETUP.md, DOCKER-SETUP.md, DOCKER-PREBUILT-APPROACH.md - PRODUCTION-READINESS.md, DEPLOY-TO-VM.md, README.md Root directory cleaned to essential docs only: - CLAUDE.md, README.md, CONTRIBUTING.md, CHANGELOG.md Benefits: - Clear navigation via README.md in each subdirectory - No duplicate/overlapping documentation - Large artifacts properly gitignored (won't bloat repository) - Historical context preserved in archived/ See .claude/CLEANUP-SUMMARY.md for complete details. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Proudlock
249
.claude/setup/HYPER-V-SETUP.md
Normal file
249
.claude/setup/HYPER-V-SETUP.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# Hyper-V Permissions Explained
|
||||
|
||||
Quick guide to understanding Hyper-V permissions and why they don't matter for MCP usage.
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
**Your account:** 270015376
|
||||
**Hyper-V Administrators group:** Empty (you're not a member)
|
||||
**Result:** Cannot use PowerShell Hyper-V cmdlets
|
||||
|
||||
---
|
||||
|
||||
## What This Affects
|
||||
|
||||
### ✓ Still Works (No Admin Needed)
|
||||
|
||||
| Feature | How to Use | Notes |
|
||||
|---------|-----------|-------|
|
||||
| VM MCP Server | SSH to VM | Uses network, not Hyper-V API |
|
||||
| Start/Stop VMs | Hyper-V Manager GUI | Right-click VM |
|
||||
| View VM status | Hyper-V Manager GUI | Shows all VMs |
|
||||
| Create snapshots | Hyper-V Manager GUI | Right-click VM -> Checkpoint |
|
||||
| Restore snapshots | Hyper-V Manager GUI | Right-click snapshot -> Apply |
|
||||
| Connect to VM | Hyper-V Manager GUI | Double-click VM |
|
||||
| VM settings | Hyper-V Manager GUI | Right-click VM -> Settings |
|
||||
|
||||
**Bottom line:** Everything you need works via GUI or SSH.
|
||||
|
||||
### ✗ Doesn't Work (Need Group Membership)
|
||||
|
||||
| Feature | Why It Fails | Workaround |
|
||||
|---------|-------------|-----------|
|
||||
| `Get-VM` cmdlet | No Hyper-V perms | Use Hyper-V Manager GUI |
|
||||
| `Checkpoint-VM` cmdlet | No Hyper-V perms | Right-click VM -> Checkpoint |
|
||||
| `Restore-VMSnapshot` cmdlet | No Hyper-V perms | Right-click snapshot -> Apply |
|
||||
| Scripted snapshot automation | No cmdlet access | Manual via GUI |
|
||||
| Test script Hyper-V checks | No cmdlet access | Warnings are harmless |
|
||||
|
||||
**Bottom line:** Only PowerShell automation is blocked.
|
||||
|
||||
---
|
||||
|
||||
## Why VM MCP Works Without Admin
|
||||
|
||||
**VM MCP uses SSH, not Hyper-V API:**
|
||||
|
||||
```
|
||||
Traditional approach (needs Hyper-V perms):
|
||||
Claude -> PowerShell -> Hyper-V API -> VM
|
||||
|
||||
VM MCP approach (no perms needed):
|
||||
Claude -> ssh-mcp -> Network -> SSH Server on VM -> Commands
|
||||
```
|
||||
|
||||
**Key difference:** VM MCP treats the VM like any remote Windows machine. It doesn't care about Hyper-V at all.
|
||||
|
||||
---
|
||||
|
||||
## Test Results Explained
|
||||
|
||||
When you run `test-mcp-servers.ps1`:
|
||||
|
||||
```
|
||||
[6/7] Checking Hyper-V VMs...
|
||||
INFO: Cannot use PowerShell Hyper-V cmdlets
|
||||
NOTE: VM MCP works via SSH - no admin needed for that!
|
||||
|
||||
[7/7] Checking VM snapshots...
|
||||
INFO: Cannot use PowerShell snapshot cmdlets
|
||||
TIP: Use Hyper-V Manager GUI to create/restore snapshots
|
||||
```
|
||||
|
||||
**These are informational, not errors.** The test script is just explaining what you can't do via PowerShell.
|
||||
|
||||
---
|
||||
|
||||
## Getting Admin/Group Access
|
||||
|
||||
### Option 1: Request Group Membership (Recommended)
|
||||
|
||||
Ask your IT admin to add you to "Hyper-V Administrators" group:
|
||||
|
||||
```powershell
|
||||
# Admin runs:
|
||||
Add-LocalGroupMember -Group "Hyper-V Administrators" -Member "270015376"
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Can use PowerShell cmdlets
|
||||
- Can script VM operations
|
||||
- Test script shows all green
|
||||
|
||||
**Drawbacks:**
|
||||
- Need to request from IT
|
||||
- May have approval process
|
||||
|
||||
### Option 2: Keep As-Is (Works Fine)
|
||||
|
||||
Use Hyper-V Manager GUI instead of PowerShell.
|
||||
|
||||
**Benefits:**
|
||||
- No need to request access
|
||||
- GUI is often easier than cmdlets
|
||||
- VM MCP works perfectly
|
||||
|
||||
**Drawbacks:**
|
||||
- Can't script snapshot management
|
||||
- Test script shows warnings
|
||||
|
||||
---
|
||||
|
||||
## GUI Equivalents
|
||||
|
||||
All PowerShell operations have GUI equivalents:
|
||||
|
||||
### Create Snapshot
|
||||
**PowerShell:**
|
||||
```powershell
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"
|
||||
```
|
||||
|
||||
**GUI:**
|
||||
1. Open Hyper-V Manager
|
||||
2. Right-click VM
|
||||
3. Select "Checkpoint"
|
||||
4. Enter name "Clean-Install"
|
||||
5. Click OK
|
||||
|
||||
### Restore Snapshot
|
||||
**PowerShell:**
|
||||
```powershell
|
||||
Restore-VMSnapshot -Name "Clean-Install" -VMName "ShopDB-Test-VM" -Confirm:$false
|
||||
```
|
||||
|
||||
**GUI:**
|
||||
1. Open Hyper-V Manager
|
||||
2. Select VM in left pane
|
||||
3. In "Checkpoints" pane (bottom), right-click "Clean-Install"
|
||||
4. Select "Apply"
|
||||
5. Choose "Apply" or "Apply and Create Checkpoint"
|
||||
|
||||
### List Snapshots
|
||||
**PowerShell:**
|
||||
```powershell
|
||||
Get-VMSnapshot -VMName "ShopDB-Test-VM"
|
||||
```
|
||||
|
||||
**GUI:**
|
||||
1. Open Hyper-V Manager
|
||||
2. Select VM
|
||||
3. View "Checkpoints" pane at bottom
|
||||
4. See all snapshots in tree view
|
||||
|
||||
### Check VM Status
|
||||
**PowerShell:**
|
||||
```powershell
|
||||
Get-VM | Select-Object Name, State, Uptime
|
||||
```
|
||||
|
||||
**GUI:**
|
||||
1. Open Hyper-V Manager
|
||||
2. View all VMs in center pane
|
||||
3. See Name, State, CPU Usage, etc.
|
||||
|
||||
---
|
||||
|
||||
## Documentation Updates
|
||||
|
||||
The following docs have been updated to clarify admin requirements:
|
||||
|
||||
- `test-mcp-servers.ps1` - Shows INFO instead of WARN for Hyper-V perms
|
||||
- `STATUS.md` - Explains impact (none for MCP)
|
||||
- `HYPER-V-PERMISSIONS.md` - This guide
|
||||
|
||||
**VM-SNAPSHOT-GUIDE.md** still shows PowerShell commands, but mentions GUI alternatives.
|
||||
|
||||
---
|
||||
|
||||
## When Would You Need Admin?
|
||||
|
||||
**You'd only need Hyper-V admin for:**
|
||||
|
||||
1. **Automated snapshot scripts** - Create/restore snapshots from command line
|
||||
2. **VM creation** - Creating new VMs via PowerShell
|
||||
3. **Advanced scripting** - Batch operations on multiple VMs
|
||||
4. **CI/CD integration** - Automated testing workflows that manage VMs
|
||||
|
||||
**For daily development:** GUI + VM MCP is perfectly fine.
|
||||
|
||||
---
|
||||
|
||||
## Claude Code Integration
|
||||
|
||||
**With VM MCP, Claude can:**
|
||||
```
|
||||
✓ Execute commands on VM
|
||||
✓ Copy files to/from VM
|
||||
✓ Read logs from VM
|
||||
✓ Check service status
|
||||
✓ Install/configure software
|
||||
✓ Test agent deployment
|
||||
✓ All via SSH - no Hyper-V perms needed!
|
||||
```
|
||||
|
||||
**Claude cannot (without Hyper-V perms):**
|
||||
```
|
||||
✗ Create snapshots via PowerShell
|
||||
✗ Restore snapshots via script
|
||||
✗ Query VM state via Get-VM
|
||||
|
||||
But you can do these manually in GUI!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Current situation:**
|
||||
- You're not in "Hyper-V Administrators" group
|
||||
- VM MCP works perfectly via SSH
|
||||
- Use Hyper-V Manager GUI for snapshot management
|
||||
- Test script shows warnings but everything is functional
|
||||
|
||||
**Recommendation:**
|
||||
Keep as-is unless you need automated snapshot scripting. For daily development, GUI + SSH is sufficient.
|
||||
|
||||
**If you want group membership:**
|
||||
Request from IT admin to add you to "Hyper-V Administrators" local group.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Without Group | With Group |
|
||||
|------|--------------|------------|
|
||||
| VM MCP (SSH) | ✓ Works | ✓ Works |
|
||||
| Start/stop VM | ✓ GUI | ✓ GUI or PowerShell |
|
||||
| Create snapshot | ✓ GUI | ✓ GUI or PowerShell |
|
||||
| Restore snapshot | ✓ GUI | ✓ GUI or PowerShell |
|
||||
| View VM status | ✓ GUI | ✓ GUI or PowerShell |
|
||||
| Script automation | ✗ Can't | ✓ Can |
|
||||
|
||||
**Bottom line: You can do everything, just not via PowerShell scripts.**
|
||||
|
||||
---
|
||||
|
||||
**No action required - setup is complete and functional!**
|
||||
Reference in New Issue
Block a user