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
245
.claude/archived/ACTIVATE-HYPERV-PERMS.md
Normal file
245
.claude/archived/ACTIVATE-HYPERV-PERMS.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# Activating Hyper-V Permissions
|
||||
|
||||
You've been added to "Hyper-V Administrators" group, but permissions haven't taken effect yet.
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
**Group membership:** ✓ Added to "Hyper-V Administrators"
|
||||
**Active permissions:** ✗ Not yet active in current session
|
||||
**Reason:** Group membership changes require logoff/logon to update security token
|
||||
|
||||
---
|
||||
|
||||
## What's Happening
|
||||
|
||||
When you log in to Windows, your **security token** is created with your current group memberships. Adding you to a new group doesn't update the token of existing sessions - you need to:
|
||||
|
||||
1. Log off
|
||||
2. Log back in
|
||||
3. New security token includes the new group
|
||||
|
||||
---
|
||||
|
||||
## How to Activate
|
||||
|
||||
### Option 1: Log Off and Back On (Recommended)
|
||||
|
||||
```
|
||||
1. Save all work
|
||||
2. Close all applications
|
||||
3. Press Ctrl+Alt+Del -> Sign out
|
||||
4. Log back in as 270015376
|
||||
5. Open new terminal
|
||||
6. Test: Get-VM
|
||||
```
|
||||
|
||||
**This activates the permissions for ALL applications.**
|
||||
|
||||
### Option 2: Just Restart Claude Code Session
|
||||
|
||||
```
|
||||
1. Close Claude Code completely
|
||||
2. Close the terminal/shell it was running in
|
||||
3. Open NEW terminal
|
||||
4. cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
5. claude
|
||||
```
|
||||
|
||||
**This may work if your terminal was opened after group membership was added, but often you still need Option 1.**
|
||||
|
||||
### Option 3: Use RunAs (For This Session Only)
|
||||
|
||||
```powershell
|
||||
# Run PowerShell as yourself with fresh token
|
||||
runas /user:AEROAD\270015376 "powershell.exe"
|
||||
# Enter your password
|
||||
# In new PowerShell window:
|
||||
Get-VM # Should work
|
||||
```
|
||||
|
||||
**This creates a new process with fresh token, but isolated from current session.**
|
||||
|
||||
---
|
||||
|
||||
## Verification Steps
|
||||
|
||||
### After Logging Off/On
|
||||
|
||||
**1. Check group membership is active in token:**
|
||||
```bash
|
||||
whoami /groups | findstr "Hyper-V"
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
BUILTIN\Hyper-V Administrators Group ...
|
||||
```
|
||||
|
||||
**2. Test Hyper-V cmdlet:**
|
||||
```powershell
|
||||
Get-VM
|
||||
```
|
||||
|
||||
Expected: List of VMs (no permission error)
|
||||
|
||||
**3. Test snapshot cmdlet:**
|
||||
```powershell
|
||||
Get-VMSnapshot -VMName *
|
||||
```
|
||||
|
||||
Expected: List of snapshots or "no snapshots found"
|
||||
|
||||
**4. Re-run MCP test suite:**
|
||||
```powershell
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
.\\.claude\test-mcp-servers.ps1
|
||||
```
|
||||
|
||||
Expected: All tests pass (7/7)
|
||||
|
||||
---
|
||||
|
||||
## What Will Work After Activation
|
||||
|
||||
### PowerShell Hyper-V Cmdlets
|
||||
|
||||
```powershell
|
||||
# View VMs
|
||||
Get-VM
|
||||
Get-VM -Name "SFTest"
|
||||
|
||||
# Start/Stop
|
||||
Start-VM -Name "SFTest"
|
||||
Stop-VM -Name "SFTest"
|
||||
|
||||
# Snapshots
|
||||
Checkpoint-VM -Name "SFTest" -SnapshotName "Baseline"
|
||||
Get-VMSnapshot -VMName "SFTest"
|
||||
Restore-VMSnapshot -Name "Baseline" -VMName "SFTest"
|
||||
Remove-VMSnapshot -Name "OldSnapshot" -VMName "SFTest"
|
||||
|
||||
# Status
|
||||
Get-VM | Select-Object Name, State, Uptime, Status
|
||||
```
|
||||
|
||||
### Automated Snapshot Scripts
|
||||
|
||||
All PowerShell snapshot operations in:
|
||||
- `VM-SNAPSHOT-GUIDE.md`
|
||||
- Custom automation scripts
|
||||
- Claude Code-driven snapshot management
|
||||
|
||||
### Test Suite
|
||||
|
||||
`test-mcp-servers.ps1` will pass all checks:
|
||||
```
|
||||
[6/7] Checking Hyper-V VMs...
|
||||
OK: Found 1 VM(s)
|
||||
- SFTest: Running
|
||||
|
||||
[7/7] Checking VM snapshots...
|
||||
OK: Found X snapshot(s)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What Already Works (No Change)
|
||||
|
||||
These worked before and still work:
|
||||
- VM MCP via SSH (doesn't use Hyper-V API)
|
||||
- Hyper-V Manager GUI (different permission model)
|
||||
- MySQL, Gortex, Browser MCP servers
|
||||
- Database access
|
||||
- All documentation and scripts
|
||||
|
||||
---
|
||||
|
||||
## Testing After Activation
|
||||
|
||||
### Quick Test
|
||||
```powershell
|
||||
# After logging back in:
|
||||
Get-VM -Name "SFTest"
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
Name State CPUUsage(%) MemoryAssigned(M) Uptime Status
|
||||
---- ----- ----------- ----------------- ------ ------
|
||||
SFTest Running 2 4096 01:23:45.1234567 Operating normally
|
||||
```
|
||||
|
||||
### Full Test
|
||||
```powershell
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
.\\.claude\test-mcp-servers.ps1
|
||||
```
|
||||
|
||||
Expected: 7/7 tests passing (or 6/7 if VM not started)
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Still Getting Permission Error After Logoff/Logon
|
||||
|
||||
**Possible causes:**
|
||||
1. Terminal was opened before you logged off (close and reopen)
|
||||
2. PowerShell session was started before (restart PowerShell)
|
||||
3. Claude Code still using old token (restart completely)
|
||||
|
||||
**Fix:** Restart everything - new logon, new terminal, new Claude Code
|
||||
|
||||
### "Access Denied" in Hyper-V Manager
|
||||
|
||||
**This is different issue** - Hyper-V Manager uses different permission model.
|
||||
Should still work even if cmdlets don't.
|
||||
|
||||
### Group Membership Shows But Cmdlets Fail
|
||||
|
||||
**Check your token:**
|
||||
```bash
|
||||
whoami /groups | findstr "Hyper-V"
|
||||
```
|
||||
|
||||
If no output, your token doesn't have the group yet. Log off and back on.
|
||||
|
||||
---
|
||||
|
||||
## Timeline
|
||||
|
||||
1. **Now:** Group membership added ✓
|
||||
2. **After logoff/logon:** Permissions active ✓
|
||||
3. **First test:** `Get-VM` should work ✓
|
||||
4. **Full test:** Run test-mcp-servers.ps1 ✓
|
||||
|
||||
**Total downtime:** ~2 minutes for logoff/logon
|
||||
|
||||
---
|
||||
|
||||
## Documentation Updates
|
||||
|
||||
After activation, these will work as written:
|
||||
- All PowerShell examples in `VM-SNAPSHOT-GUIDE.md`
|
||||
- Automated snapshot workflows in `MCP-INTEGRATION-GUIDE.md`
|
||||
- PowerShell sections in `HYPER-V-PERMISSIONS.md`
|
||||
|
||||
No code changes needed - just activation of existing permissions.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Save your work**
|
||||
2. **Log off** (Ctrl+Alt+Del -> Sign out)
|
||||
3. **Log back in** as 270015376
|
||||
4. **Open new terminal**
|
||||
5. **Test:** `Get-VM`
|
||||
6. **Re-run:** `.\\.claude\test-mcp-servers.ps1`
|
||||
7. **Celebrate:** All tests passing!
|
||||
|
||||
---
|
||||
|
||||
**Ready to log off and activate your new permissions!**
|
||||
216
.claude/archived/DARKWING-FINDINGS.md
Normal file
216
.claude/archived/DARKWING-FINDINGS.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# Darkwing Security Findings - 2026-09-07
|
||||
|
||||
**Scan Run:** 34093911764 (wj branch)
|
||||
**Findings:** 2 (1 High, 1 Medium)
|
||||
**Status:** Patches ready to apply
|
||||
|
||||
---
|
||||
|
||||
## Finding 1: [High] Unauthenticated Admin Bootstrap Race
|
||||
|
||||
**ID:** `setup-create-admin-unauthenticated`
|
||||
**File:** `shopdb/core/api/setup.py:39`
|
||||
|
||||
### Problem
|
||||
`POST /api/setup/create-admin` has no authentication. Between container start and first admin creation, any network caller can claim the instance. Every documented deploy path has this window:
|
||||
|
||||
```bash
|
||||
docker-compose up -d # API listening
|
||||
flask db upgrade # Migrations run
|
||||
# <-- RACE WINDOW: anyone can POST /api/setup/create-admin
|
||||
flask seed admin # Operator creates admin
|
||||
```
|
||||
|
||||
### Impact
|
||||
- Total control: `admin` role bypasses all permission checks
|
||||
- No password strength requirement (1-char accepted)
|
||||
- No audit trail (creation is silent)
|
||||
- Window reopens on restore to empty schema
|
||||
|
||||
### Fix Applied
|
||||
Requires **proof of operator control**:
|
||||
|
||||
**Option A: Setup token** (remote install)
|
||||
```bash
|
||||
export SETUP_TOKEN=$(openssl rand -hex 32)
|
||||
curl -X POST http://host/api/setup/create-admin \
|
||||
-H "X-Setup-Token: $SETUP_TOKEN" \
|
||||
-d '{"username":"admin","email":"a@b.c","password":"SecurePass123"}'
|
||||
```
|
||||
|
||||
**Option B: Loopback** (local install)
|
||||
```bash
|
||||
# From inside container or via SSH to host
|
||||
curl -X POST http://localhost:5000/api/setup/create-admin \
|
||||
-d '{"username":"admin","email":"a@b.c","password":"SecurePass123"}'
|
||||
```
|
||||
|
||||
**Option C: CLI** (unchanged, always works)
|
||||
```bash
|
||||
docker exec -it shopdb-api flask seed admin
|
||||
```
|
||||
|
||||
### Additional Hardening
|
||||
- 12-character password minimum enforced
|
||||
- Cross-checks `setup_complete` setting
|
||||
- Logs "First administrator 'X' created from Y.Y.Y.Y"
|
||||
- Token printed to container logs on first startup
|
||||
- New CLI helper: `flask seed show-setup-token`
|
||||
|
||||
### Recovery Paths
|
||||
Lost the token? Three options:
|
||||
1. `docker logs shopdb-api | grep "Setup token"`
|
||||
2. `docker exec shopdb-api flask seed show-setup-token`
|
||||
3. `docker exec -it shopdb-api flask seed admin` (just works)
|
||||
|
||||
---
|
||||
|
||||
## Finding 2: [Medium] Unauthenticated KB Article Disclosure
|
||||
|
||||
**ID:** `kb-click-unauth-linkurl-disclosure`
|
||||
**File:** `plugins/knowledgebase/api/routes.py:182`
|
||||
|
||||
### Problem
|
||||
`POST /api/knowledgebase/<id>/click` has `@jwt_required(optional=True)` instead of `@require_permission('kb.view')`. Anonymous callers can:
|
||||
- Enumerate article IDs 1..N and harvest link URLs
|
||||
- Bypass visibility filter (retired topics exposed)
|
||||
- Inflate click counters unbounded (DB write spam)
|
||||
- URLs may contain tokens/keys in query strings
|
||||
|
||||
Compare with sibling route:
|
||||
```python
|
||||
@knowledgebase_bp.route('/<int:link_id>', methods=['GET'])
|
||||
@require_permission('kb.view') # <-- gated
|
||||
def get_article(link_id: int):
|
||||
|
||||
@knowledgebase_bp.route('/<int:link_id>/click', methods=['POST'])
|
||||
@jwt_required(optional=True) # <-- NOT gated
|
||||
def track_click(link_id: int):
|
||||
return success_response({'linkurl': article.linkurl, ...}) # <-- leaks URL
|
||||
```
|
||||
|
||||
### Impact
|
||||
- Leaks internal documentation URLs (SharePoint, Confluence, etc.)
|
||||
- URLs may contain auth tokens in query strings
|
||||
- Unauthenticated write primitive (DB transactions)
|
||||
- Explicitly exempted from authz sweep in tests
|
||||
|
||||
### Fix Applied
|
||||
- Gate on `kb.view` like other KB reads
|
||||
- Remove `linkurl` from response (caller already has it)
|
||||
- Apply same `_visible_articles()` filter as list/detail
|
||||
- Counter-only response: `{'clicks': N}`
|
||||
|
||||
---
|
||||
|
||||
## Applying the Patch
|
||||
|
||||
```bash
|
||||
cd /c/Users/270015376/Documents/github/flask-shopdb
|
||||
git apply darkwing-fixes.patch
|
||||
```
|
||||
|
||||
Or review and apply manually.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Test 1: Admin bootstrap now requires token
|
||||
```bash
|
||||
# Without token - should fail
|
||||
curl -X POST http://localhost:5000/api/setup/create-admin \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"attacker","email":"a@b.c","password":"SecurePass123"}'
|
||||
# Expected: 403 "requires the setup token"
|
||||
|
||||
# With token - should succeed
|
||||
curl -X POST http://localhost:5000/api/setup/create-admin \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-Setup-Token: $SETUP_TOKEN" \
|
||||
-d '{"username":"admin","email":"admin@example.com","password":"SecurePass123"}'
|
||||
# Expected: 201 Created
|
||||
```
|
||||
|
||||
### Test 2: Password minimum enforced
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/setup/create-admin \
|
||||
-H "X-Setup-Token: $SETUP_TOKEN" \
|
||||
-d '{"username":"admin","email":"a@b.c","password":"short"}'
|
||||
# Expected: 400 "password must be at least 12 characters"
|
||||
```
|
||||
|
||||
### Test 3: KB click gated
|
||||
```bash
|
||||
# Without auth - should fail
|
||||
curl -X POST http://localhost:5000/api/knowledgebase/1/click
|
||||
# Expected: 401 Unauthorized
|
||||
|
||||
# With auth - should succeed (no linkurl in response)
|
||||
curl -X POST http://localhost:5000/api/knowledgebase/1/click \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
# Expected: {"status":"success","data":{"clicks":N}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deploy Workflow Changes
|
||||
|
||||
### Current (Unsafe)
|
||||
```powershell
|
||||
docker-compose up -d
|
||||
docker exec shopdb-api flask db upgrade
|
||||
# <-- race window
|
||||
docker exec shopdb-api flask seed admin
|
||||
```
|
||||
|
||||
### After Patch (Safe)
|
||||
```powershell
|
||||
# Generate token first
|
||||
$token = openssl rand -hex 32
|
||||
echo "SETUP_TOKEN=$token" >> .env
|
||||
|
||||
docker-compose up -d
|
||||
# Token logged to console: "Setup token: abc123..."
|
||||
|
||||
docker exec shopdb-api flask db upgrade
|
||||
docker exec shopdb-api flask seed admin
|
||||
# OR: curl with X-Setup-Token header
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
### Before Patch
|
||||
- **Admin Bootstrap:** HIGH - Network race, no password requirements, silent
|
||||
- **KB Disclosure:** MEDIUM - Leaks URLs, unauthenticated writes, visibility bypass
|
||||
|
||||
### After Patch
|
||||
- **Admin Bootstrap:** LOW - Requires token or localhost, 12-char password, audited
|
||||
- **KB Disclosure:** LOW - Gated on permission like other reads
|
||||
|
||||
---
|
||||
|
||||
## Files Changed
|
||||
|
||||
1. `shopdb/__init__.py` - Token logging on first startup
|
||||
2. `shopdb/cli/__init__.py` - New `flask seed show-setup-token` command
|
||||
3. `shopdb/core/api/setup.py` - Token/loopback auth, password minimum, audit log
|
||||
4. `plugins/knowledgebase/api/routes.py` - Gate click route, remove linkurl
|
||||
|
||||
---
|
||||
|
||||
## Rollout Priority
|
||||
|
||||
**Recommendation:** Apply in next maintenance window
|
||||
|
||||
**Urgency:**
|
||||
- WJ (prod): **Medium** - Air-gapped, limited exposure, but closes audit finding
|
||||
- OPS (dev): **Low** - Internal network, can wait for next deploy
|
||||
- WILM (mirror): **Low** - Read-only mirror, no setup route active
|
||||
|
||||
**Compatibility:** Zero breaking changes
|
||||
- CLI `flask seed admin` unchanged
|
||||
- Existing authenticated workflows unaffected
|
||||
- Web wizard needs token in URL param (one-line frontend change)
|
||||
235
.claude/archived/DOCKER-DEPLOYMENT-COMPLETE.md
Normal file
235
.claude/archived/DOCKER-DEPLOYMENT-COMPLETE.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# Docker Deployment - Complete and Working
|
||||
|
||||
**Date:** 2026-09-07
|
||||
**Branch:** wj (post-wilm merge)
|
||||
**Status:** [OK] Core system operational, backup watcher pending
|
||||
|
||||
## What's Running
|
||||
|
||||
```
|
||||
CONTAINER STATUS PORT
|
||||
flask-shopdb-db-1 Up (healthy) 3306/tcp (internal)
|
||||
flask-shopdb-api-1 Up https://localhost:5001
|
||||
```
|
||||
|
||||
**Gunicorn Workers:** 4 workers with gevent (PIDs 74-77)
|
||||
**Plugins Enabled:** 12 of 17 installed
|
||||
**Database:** MySQL 8.4 with all migrations applied
|
||||
|
||||
## Access
|
||||
|
||||
**URL:** https://localhost:5001
|
||||
**Expected:** Browser warning for self-signed certificate (click through)
|
||||
**Login:** admin / (needs password reset - see below)
|
||||
|
||||
## How to Use
|
||||
|
||||
### Start Stack
|
||||
```bash
|
||||
docker compose -f docker-compose.prebuilt.yml up -d
|
||||
```
|
||||
|
||||
### Stop Stack
|
||||
```bash
|
||||
docker compose -f docker-compose.prebuilt.yml down
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
docker logs -f flask-shopdb-api-1
|
||||
docker logs flask-shopdb-db-1
|
||||
```
|
||||
|
||||
### Reset Admin Password
|
||||
```bash
|
||||
# Generate hash
|
||||
docker exec flask-shopdb-api-1 python -c \
|
||||
"from werkzeug.security import generate_password_hash; print(generate_password_hash('your-password'))"
|
||||
|
||||
# Update database (replace HASH with output above)
|
||||
docker exec flask-shopdb-db-1 mysql -uroot -p$MYSQL_ROOT_PASSWORD shopdb_flask -e \
|
||||
"UPDATE users SET passwordhash='HASH', failedlogins=0, lockeduntil=NULL WHERE username='admin';"
|
||||
```
|
||||
|
||||
Quick reset to password "admin":
|
||||
```bash
|
||||
docker exec flask-shopdb-db-1 mysql -uroot -proot-dev-password-not-for-production shopdb_flask -e \
|
||||
"UPDATE users SET
|
||||
passwordhash='scrypt:32768:8:1\$B4LhpPrM6qxijInK\$b99b47a0bb5fd45761a1823f401f70a3ceccf71a5d38dc433378aa07426ef8eaf7e679ff3dd7b0ce9772600f83368ac642e9419b9beaa49f87483318bae34547',
|
||||
failedlogins=0, lockeduntil=NULL
|
||||
WHERE username='admin';"
|
||||
```
|
||||
|
||||
### Rebuild After Code Changes
|
||||
```bash
|
||||
# Rebuild frontend (if frontend code changed)
|
||||
cd frontend
|
||||
npm run build
|
||||
cd ..
|
||||
|
||||
# Rebuild Docker image
|
||||
docker compose -f docker-compose.prebuilt.yml build api
|
||||
|
||||
# Restart
|
||||
docker compose -f docker-compose.prebuilt.yml up -d
|
||||
```
|
||||
|
||||
### Run Database Migrations
|
||||
```bash
|
||||
docker exec flask-shopdb-api-1 flask db upgrade
|
||||
```
|
||||
|
||||
### Plugin Management
|
||||
```bash
|
||||
# List plugins
|
||||
docker exec flask-shopdb-api-1 flask plugin list
|
||||
|
||||
# Enable plugin
|
||||
docker exec flask-shopdb-api-1 flask plugin enable PLUGIN_NAME
|
||||
|
||||
# Disable plugin
|
||||
docker exec flask-shopdb-api-1 flask plugin disable PLUGIN_NAME
|
||||
```
|
||||
|
||||
## Build Process Used
|
||||
|
||||
### Why Pre-Built Frontend?
|
||||
|
||||
**Problem:** Zscaler corporate proxy causes npm to fail inside Docker builds
|
||||
|
||||
**Solution:** Build frontend on host, copy into Docker image
|
||||
|
||||
### Build Steps Taken
|
||||
|
||||
1. **Build Frontend on Host**
|
||||
```bash
|
||||
cd frontend
|
||||
npm ci
|
||||
npm run build
|
||||
# Creates frontend/dist/
|
||||
```
|
||||
|
||||
2. **Build Docker Image (Simple)**
|
||||
```bash
|
||||
# Uses Dockerfile.prebuilt (Python only, no npm)
|
||||
docker compose -f docker-compose.prebuilt.yml build
|
||||
```
|
||||
|
||||
3. **Start Services**
|
||||
```bash
|
||||
docker compose -f docker-compose.prebuilt.yml up -d
|
||||
```
|
||||
|
||||
4. **Auto-Bootstrap**
|
||||
- Container entrypoint runs migrations
|
||||
- Detects first deployment (no instance/plugins.json)
|
||||
- Auto-installs all 17 plugins (disabled by default)
|
||||
- Starts gunicorn
|
||||
|
||||
## Architecture
|
||||
|
||||
### Volumes
|
||||
- `flask-shopdb_db_data` - MySQL database (persistent)
|
||||
- `flask-shopdb_instance_data` - Plugin state, uploads, branding (persistent)
|
||||
|
||||
### Networks
|
||||
- `flask-shopdb_default` - Internal bridge network
|
||||
|
||||
### Image
|
||||
- **Built:** 2026-09-07 00:26:27 EDT
|
||||
- **Size:** 914MB
|
||||
- **Base:** python:3.14-slim
|
||||
- **Frontend:** Pre-built Vue 3 SPA (from host)
|
||||
|
||||
## What's Not Working Yet
|
||||
|
||||
### Backup Watcher Service
|
||||
|
||||
**Status:** [FAIL] Build failed
|
||||
**Reason:** Oracle Linux base image can't download packages due to SSL cert issues with Zscaler
|
||||
**Impact:** Can't auto-execute backups on schedule (manual backups still work via one-shot container)
|
||||
|
||||
**Error:**
|
||||
```
|
||||
Cannot download repomd.xml: Curl error (60): SSL peer certificate or SSH remote key was not OK
|
||||
```
|
||||
|
||||
**Workaround Attempted:**
|
||||
- Copied Zscaler cert to scripts/backup/zscaler-root-ca.pem
|
||||
- Dockerfile.backup copies cert and runs update-ca-trust
|
||||
- Still fails because microdnf runs BEFORE cert is trusted
|
||||
|
||||
**Fix Needed:**
|
||||
- Pre-download restic binary and bake into image OR
|
||||
- Use different base image (Alpine/Debian instead of Oracle Linux) OR
|
||||
- Skip backup watcher entirely, use cron on host to trigger one-shot backup container
|
||||
|
||||
## Production Readiness
|
||||
|
||||
**Core Application:** [OK] Production ready
|
||||
**Deployment Process:** [WARN] Requires npm on host + Docker build
|
||||
**Backup System:** [FAIL] Not complete (watcher service build fails)
|
||||
|
||||
### Recommended Next Steps
|
||||
|
||||
1. **CI/CD Pipeline** - Build images automatically, push to registry
|
||||
2. **Pre-Built Images** - Sites pull instead of building (2 min deploy)
|
||||
3. **Backup Watcher Fix** - Switch to Alpine base or pre-download restic
|
||||
4. **TLS Certificates** - Use proper certs from CA (not self-signed)
|
||||
5. **Secrets Management** - Externalize passwords (.env with strong values)
|
||||
|
||||
## Files Created
|
||||
|
||||
- `Dockerfile.prebuilt` - Simplified Docker build (no npm)
|
||||
- `docker-compose.prebuilt.yml` - Docker Compose for pre-built approach
|
||||
- `.dockerignore.prebuilt` - Allows frontend/dist to be copied
|
||||
- `start-docker-quick.sh` - Quick restart script
|
||||
- `DOCKER-PREBUILT-APPROACH.md` - Documents workaround
|
||||
- `PRODUCTION-READINESS.md` - Honest assessment
|
||||
|
||||
## Comparison to Previous Attempts
|
||||
|
||||
| Approach | Result | Time | Issue |
|
||||
|----------|--------|------|-------|
|
||||
| Multi-stage Dockerfile | [FAIL] Failed | 15+ min | npm fails with Zscaler |
|
||||
| Pre-built frontend | [OK] Success | 3 min | Works! |
|
||||
| Backup containers | [FAIL] Failed | N/A | Oracle Linux SSL issues |
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# Test frontend
|
||||
curl -k https://localhost:5001/
|
||||
# Should return: <!DOCTYPE html>
|
||||
|
||||
# Test API
|
||||
curl -k https://localhost:5001/api/settings
|
||||
# Should return: {"data":[...]}
|
||||
|
||||
# Test database
|
||||
docker exec flask-shopdb-db-1 mysql -uroot -p$MYSQL_ROOT_PASSWORD \
|
||||
-e "SELECT COUNT(*) FROM shopdb_flask.users;"
|
||||
# Should return: count of users
|
||||
|
||||
# Check workers
|
||||
docker logs flask-shopdb-api-1 2>&1 | grep "Booting worker"
|
||||
# Should show: 4 workers with PIDs
|
||||
|
||||
# Check plugins
|
||||
docker exec flask-shopdb-api-1 flask plugin list | grep Enabled | wc -l
|
||||
# Should return: 12
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
ShopDB Docker deployment is **operational** for core functionality:
|
||||
- [OK] Database running
|
||||
- [OK] API serving requests
|
||||
- [OK] Frontend built and accessible
|
||||
- [OK] Plugins installed and working
|
||||
- [OK] HTTPS configured
|
||||
- [WARN] Backup watcher needs work (but manual backups functional)
|
||||
|
||||
The pre-built frontend approach successfully bypasses Zscaler corporate proxy issues. Build time is 2-3 minutes (vs 15+ for failed multi-stage approach).
|
||||
|
||||
For production deployment, recommend setting up CI/CD to build images automatically and push to registry so sites can pull pre-built images instead of building locally.
|
||||
432
.claude/archived/FINAL-SUMMARY.md
Normal file
432
.claude/archived/FINAL-SUMMARY.md
Normal file
@@ -0,0 +1,432 @@
|
||||
# MCP Setup Complete - Final Summary
|
||||
|
||||
Complete summary of MCP server setup for ShopDB development with Hyper-V VM testing.
|
||||
|
||||
**Session Date:** 2026-09-09
|
||||
**Status:** Ready for development
|
||||
|
||||
---
|
||||
|
||||
## What We Built
|
||||
|
||||
### Documentation (9 files, ~3500 lines)
|
||||
|
||||
1. **INDEX-MCP-DOCS.md** - Master index and navigation
|
||||
2. **README-MCP-SETUP.md** - Quick reference guide
|
||||
3. **MCP-INTEGRATION-GUIDE.md** - Complete workflows and examples
|
||||
4. **VM-SNAPSHOT-GUIDE.md** - Snapshot management guide
|
||||
5. **VM-USERS.md** - VM user accounts explained
|
||||
6. **HYPER-V-PERMISSIONS.md** - Permission requirements clarified
|
||||
7. **STATUS.md** - Current status and quick checks
|
||||
8. **SETUP-COMPLETE-SUMMARY.md** - Session recap
|
||||
9. **FINAL-SUMMARY.md** - This file
|
||||
|
||||
### Automation Scripts (2 files)
|
||||
|
||||
1. **test-mcp-servers.ps1** - Comprehensive test suite
|
||||
2. **quick-start-mcp.ps1** - Automated setup script
|
||||
|
||||
### Configuration
|
||||
|
||||
1. **mcp-servers.json** - 5 MCP servers configured:
|
||||
- gortex (project management)
|
||||
- mysql (database access)
|
||||
- browser (web automation)
|
||||
- vm (VM admin access via SSH)
|
||||
- vm-shopfloor (VM standard user access via SSH)
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
### Test Results: 4/7 Passing (57%)
|
||||
|
||||
```
|
||||
✓ gortex - Project management ready
|
||||
✓ mysql - Database running (MySQL 8.4.11)
|
||||
✓ browser - Web automation ready
|
||||
✓ config - 5 MCP servers configured
|
||||
✗ vm - VM not started (optional)
|
||||
ℹ hyperv - No Hyper-V cmdlet access (GUI works)
|
||||
ℹ snapshots - No cmdlet access (GUI works)
|
||||
```
|
||||
|
||||
### What's Working Right Now
|
||||
|
||||
**Database:**
|
||||
- MySQL 8.4.11 running in Docker
|
||||
- 18+ tables available
|
||||
- Connection verified
|
||||
|
||||
**MCP Servers:**
|
||||
- Gortex installed and ready
|
||||
- MySQL MCP configured and tested
|
||||
- Browser MCP packages available
|
||||
- VM MCP configured (2 users)
|
||||
|
||||
**Services:**
|
||||
- Docker Desktop running
|
||||
- Database healthy and accessible
|
||||
- All npm packages verified
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Configuration
|
||||
|
||||
### 1. Gortex (Project Management)
|
||||
- **Command:** C:\Users\270015376\Documents\gortex.exe mcp
|
||||
- **Use:** "List all tasks in the current project"
|
||||
|
||||
### 2. MySQL (Database)
|
||||
- **Connection:** mysql://shopdb:shopdb-dev-password@127.0.0.1:3306/shopdb_flask
|
||||
- **Use:** "Show me the endpoints table schema"
|
||||
|
||||
### 3. Browser (Web Automation)
|
||||
- **Package:** @agent-infra/mcp-server-browser v1.2.29
|
||||
- **Use:** "Take a screenshot of https://localhost:5001"
|
||||
|
||||
### 4. VM - SupportUser (Admin)
|
||||
- **Connection:** SSH to 192.168.100.10 as SupportUser
|
||||
- **Use:** "Install agent on VM"
|
||||
|
||||
### 5. VM - shopfloor (Standard User)
|
||||
- **Connection:** SSH to 192.168.100.10 as shopfloor
|
||||
- **Use:** "Test tray as shopfloor user"
|
||||
|
||||
---
|
||||
|
||||
## VM Configuration (SFTest)
|
||||
|
||||
### Network
|
||||
- **IP:** 192.168.100.10
|
||||
- **Subnet:** 192.168.100.x (internal only)
|
||||
- **Host IP:** 192.168.100.1
|
||||
|
||||
### User Accounts
|
||||
|
||||
**SupportUser (Administrator)**
|
||||
- Password: vos313
|
||||
- Purpose: Installation and configuration
|
||||
- MCP: `vm`
|
||||
|
||||
**shopfloor (Standard User)**
|
||||
- Password: vos313
|
||||
- Auto-login: Yes (logs in automatically on boot)
|
||||
- Purpose: Realistic endpoint testing
|
||||
- MCP: `vm-shopfloor`
|
||||
|
||||
### Why Two Users?
|
||||
|
||||
**Matches production deployment:**
|
||||
1. IT installs agent as admin (SupportUser)
|
||||
2. Users run tray as standard user (shopfloor)
|
||||
3. Tests realistic permissions and behavior
|
||||
|
||||
---
|
||||
|
||||
## Hyper-V Permissions Clarified
|
||||
|
||||
### You Are NOT in "Hyper-V Administrators" Group
|
||||
|
||||
**What still works:**
|
||||
- ✓ VM MCP (uses SSH, not Hyper-V API)
|
||||
- ✓ Hyper-V Manager GUI (all features)
|
||||
- ✓ Start/stop VMs via GUI
|
||||
- ✓ Create/restore snapshots via GUI
|
||||
- ✓ Connect to VM console
|
||||
|
||||
**What doesn't work:**
|
||||
- ✗ PowerShell Hyper-V cmdlets (Get-VM, Checkpoint-VM, etc.)
|
||||
- ✗ Scripted snapshot automation
|
||||
- ✗ Automated VM status checks
|
||||
|
||||
**Impact:** None for daily development. Only affects PowerShell automation.
|
||||
|
||||
**To get group access:** Ask IT admin to run:
|
||||
```powershell
|
||||
Add-LocalGroupMember -Group "Hyper-V Administrators" -Member "270015376"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Use
|
||||
|
||||
### Start Development Session
|
||||
|
||||
```powershell
|
||||
# 1. Navigate to repository
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
|
||||
# 2. Verify setup (optional)
|
||||
.\\.claude\test-mcp-servers.ps1
|
||||
|
||||
# 3. Start Claude Code
|
||||
claude
|
||||
```
|
||||
|
||||
**MCP servers load automatically** when you start Claude Code from flask-shopdb directory.
|
||||
|
||||
### Test MCP Servers
|
||||
|
||||
```
|
||||
"List all tasks in the current project"
|
||||
→ Tests Gortex
|
||||
|
||||
"Show me the first 5 endpoints in the database"
|
||||
→ Tests MySQL
|
||||
|
||||
"What tables exist in the database?"
|
||||
→ Tests MySQL schema
|
||||
|
||||
"Take a screenshot of https://localhost:5001"
|
||||
→ Tests Browser (requires ShopDB running)
|
||||
|
||||
"What is the hostname of the VM?"
|
||||
→ Tests VM SSH (requires VM running)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### 1. Database Development
|
||||
|
||||
```
|
||||
You: "Add last_boot_time field to endpoints table"
|
||||
|
||||
Claude:
|
||||
1. [MySQL: Check current schema]
|
||||
2. [Edit: Create migration]
|
||||
3. [Bash: Run migration]
|
||||
4. [MySQL: Verify field added]
|
||||
5. [MySQL: Test with sample data]
|
||||
```
|
||||
|
||||
### 2. UI Testing
|
||||
|
||||
```
|
||||
You: "Test the notifications plugin"
|
||||
|
||||
Claude:
|
||||
1. [Bash: Build frontend]
|
||||
2. [Bash: Restart Docker]
|
||||
3. [Browser: Navigate to /notifications]
|
||||
4. [MySQL: Insert test alert]
|
||||
5. [Browser: Refresh and screenshot]
|
||||
6. [MySQL: Clean up test data]
|
||||
```
|
||||
|
||||
### 3. Agent Deployment (VM Required)
|
||||
|
||||
```
|
||||
You: "Deploy agent to VM and test"
|
||||
|
||||
Claude:
|
||||
1. [Bash: Build agent]
|
||||
2. [vm (SupportUser): Copy to VM]
|
||||
3. [vm (SupportUser): Install service]
|
||||
4. [vm (SupportUser): Start service]
|
||||
5. [MySQL: Create test alert]
|
||||
6. [vm-shopfloor: Check tray notification]
|
||||
7. [MySQL: Verify alert delivered]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Navigation
|
||||
|
||||
**Start here:**
|
||||
- `INDEX-MCP-DOCS.md` - Master index with reading order
|
||||
|
||||
**Daily use:**
|
||||
- `STATUS.md` - Current status checks
|
||||
- `README-MCP-SETUP.md` - Quick reference
|
||||
- `test-mcp-servers.ps1` - Test suite
|
||||
|
||||
**Deep dives:**
|
||||
- `MCP-INTEGRATION-GUIDE.md` - Complete workflows
|
||||
- `VM-SNAPSHOT-GUIDE.md` - Snapshot management
|
||||
- `VM-USERS.md` - User accounts explained
|
||||
- `HYPER-V-PERMISSIONS.md` - Permission details
|
||||
|
||||
**Setup:**
|
||||
- `quick-start-mcp.ps1` - Automated setup
|
||||
- `enable-vm-ssh.ps1` - VM SSH setup
|
||||
|
||||
---
|
||||
|
||||
## Memory Updated
|
||||
|
||||
MCP setup saved to persistent memory:
|
||||
```
|
||||
~/.claude/projects/C--Users-270015376-Documents-github/memory/infrastructure_mcp_servers.md
|
||||
```
|
||||
|
||||
**Includes:**
|
||||
- All MCP server configurations
|
||||
- Documentation locations
|
||||
- VM setup details
|
||||
- Quick reference commands
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate (Ready Now)
|
||||
|
||||
1. **Start using MCP servers:**
|
||||
```bash
|
||||
cd flask-shopdb
|
||||
claude
|
||||
```
|
||||
|
||||
2. **Try example commands:**
|
||||
- "List all tasks"
|
||||
- "Show me the database tables"
|
||||
- "What endpoints are in the database?"
|
||||
|
||||
3. **Read integration guide:**
|
||||
```bash
|
||||
cat .claude/MCP-INTEGRATION-GUIDE.md
|
||||
```
|
||||
|
||||
### When Ready for VM Testing
|
||||
|
||||
1. **Start VM:**
|
||||
- Open Hyper-V Manager
|
||||
- Right-click SFTest VM -> Start
|
||||
- Wait for boot (shopfloor auto-logs in)
|
||||
|
||||
2. **Verify SSH:**
|
||||
```bash
|
||||
ssh SupportUser@192.168.100.10 "hostname"
|
||||
ssh shopfloor@192.168.100.10 "whoami"
|
||||
```
|
||||
|
||||
3. **Create baseline snapshots:**
|
||||
- Right-click VM -> Checkpoint
|
||||
- Create "Clean-Install", "Agent-Installed", etc.
|
||||
- See `VM-SNAPSHOT-GUIDE.md`
|
||||
|
||||
4. **Re-run tests:**
|
||||
```powershell
|
||||
.\\.claude\test-mcp-servers.ps1
|
||||
```
|
||||
|
||||
### Learning Phase
|
||||
|
||||
1. Read workflow examples in `MCP-INTEGRATION-GUIDE.md`
|
||||
2. Try simple workflows (database queries)
|
||||
3. Progress to complex workflows (multi-MCP)
|
||||
4. Build custom workflows for your needs
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
**Setup phase: ✓ Complete**
|
||||
- [x] Documentation written (~3500 lines)
|
||||
- [x] Scripts created and tested
|
||||
- [x] MCP servers configured
|
||||
- [x] Database started and verified
|
||||
- [x] VM users documented
|
||||
- [x] Permissions clarified
|
||||
- [x] Memory updated
|
||||
|
||||
**Activation phase: 57% (4/7 tests passing)**
|
||||
- [x] Gortex ready
|
||||
- [x] MySQL running
|
||||
- [x] Browser ready
|
||||
- [x] Configuration valid
|
||||
- [ ] VM started (optional)
|
||||
- [x] Hyper-V GUI access (cmdlets N/A)
|
||||
- [x] Snapshot GUI access (cmdlets N/A)
|
||||
|
||||
**Ready for:**
|
||||
- ✓ Database development and testing
|
||||
- ✓ API development and testing
|
||||
- ✓ Frontend development and testing
|
||||
- ✓ UI testing with screenshots
|
||||
- ✓ Project task tracking
|
||||
- △ Agent deployment (VM needed)
|
||||
- △ End-to-end testing (VM needed)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Quick Reference
|
||||
|
||||
| Issue | Fix |
|
||||
|-------|-----|
|
||||
| MySQL not running | `docker compose up -d db` |
|
||||
| Docker not running | Start Docker Desktop |
|
||||
| VM not reachable | Start VM in Hyper-V Manager |
|
||||
| SSH connection fails | Run `enable-vm-ssh.ps1` on VM |
|
||||
| MCP not loading | Start Claude Code from flask-shopdb directory |
|
||||
| Test fails | `.\\.claude\test-mcp-servers.ps1 -Verbose` |
|
||||
|
||||
**Full troubleshooting:** See `README-MCP-SETUP.md`
|
||||
|
||||
---
|
||||
|
||||
## Files Created This Session
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── INDEX-MCP-DOCS.md (9.6K) Master index
|
||||
├── README-MCP-SETUP.md (7.0K) Quick reference
|
||||
├── MCP-INTEGRATION-GUIDE.md (17K) Complete guide
|
||||
├── VM-SNAPSHOT-GUIDE.md (10K) Snapshots
|
||||
├── VM-USERS.md (NEW) User accounts
|
||||
├── HYPER-V-PERMISSIONS.md (NEW) Permissions
|
||||
├── STATUS.md (NEW) Current status
|
||||
├── SETUP-COMPLETE-SUMMARY.md (9.4K) Session recap
|
||||
├── FINAL-SUMMARY.md (NEW) This file
|
||||
├── test-mcp-servers.ps1 (11K) Test suite
|
||||
├── quick-start-mcp.ps1 (8.2K) Setup script
|
||||
└── mcp-servers.json (UPD) 5 servers configured
|
||||
```
|
||||
|
||||
**Total:** 9 documentation files, 2 scripts, 1 config = ~3500 lines
|
||||
|
||||
---
|
||||
|
||||
## Key Achievements
|
||||
|
||||
1. **Complete MCP stack** configured and tested
|
||||
2. **Dual VM user setup** (admin + standard user)
|
||||
3. **Automatic testing** (7-point test suite)
|
||||
4. **Comprehensive docs** (9 guides covering all scenarios)
|
||||
5. **Permission clarity** (Hyper-V cmdlets vs GUI vs SSH)
|
||||
6. **Realistic testing** (shopfloor user matches production)
|
||||
7. **Database verified** (18+ tables, MySQL 8.4.11)
|
||||
8. **Memory preserved** (setup saved for future sessions)
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**What works now:**
|
||||
- 3 MCP servers active (gortex, mysql, browser)
|
||||
- Database development and testing
|
||||
- Frontend development and testing
|
||||
- Documentation complete
|
||||
- Automation scripts ready
|
||||
|
||||
**Optional additions:**
|
||||
- Start VM for agent testing (2 MCP servers: vm, vm-shopfloor)
|
||||
- Create snapshots for rapid iteration
|
||||
- Request Hyper-V Administrators group for PowerShell automation
|
||||
|
||||
**Bottom line:**
|
||||
Complete MCP integration setup ready for development. VM testing is optional and can be enabled when needed by starting the SFTest VM in Hyper-V Manager.
|
||||
|
||||
---
|
||||
|
||||
**Setup complete! Start using with: `cd flask-shopdb && claude`**
|
||||
|
||||
---
|
||||
|
||||
**Documentation index:** `.claude/INDEX-MCP-DOCS.md`
|
||||
**Quick reference:** `.claude/README-MCP-SETUP.md`
|
||||
**Current status:** `.claude/STATUS.md`
|
||||
**Test suite:** `.\\.claude\test-mcp-servers.ps1`
|
||||
230
.claude/archived/MCP-SETUP-GUIDE.md
Normal file
230
.claude/archived/MCP-SETUP-GUIDE.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# MCP Servers Setup Guide
|
||||
|
||||
Complete guide to set up Gortex, MySQL, Browser, and GitHub MCP servers for ShopDB.
|
||||
|
||||
## Quick Summary
|
||||
|
||||
**What you need to do:**
|
||||
1. Install npm packages
|
||||
2. Set environment variable for GitHub
|
||||
3. Restart Claude Code to load MCP servers
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Install MCP Server Packages
|
||||
|
||||
Run these commands:
|
||||
|
||||
```bash
|
||||
# MySQL MCP server (with write support)
|
||||
npm install -g @benborla29/mcp-server-mysql
|
||||
|
||||
# Browser automation MCP server
|
||||
npm install -g @agent-infra/mcp-server-browser
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Fix GitHub MCP Authentication
|
||||
|
||||
The GitHub MCP error "Authorization header is badly formatted" means your GitHub token isn't set.
|
||||
|
||||
### Create GitHub Personal Access Token
|
||||
|
||||
1. Go to: https://github.com/settings/tokens/new
|
||||
2. Name: `Claude Code MCP`
|
||||
3. Select scopes:
|
||||
- `repo` (Full control of private repositories)
|
||||
- `read:org` (Read org and team membership)
|
||||
4. Click "Generate token"
|
||||
5. **Copy the token** (starts with `ghp_...`)
|
||||
|
||||
### Set Environment Variable
|
||||
|
||||
**Option A: Set for current session** (temporary)
|
||||
```bash
|
||||
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_YOUR_TOKEN_HERE"
|
||||
```
|
||||
|
||||
**Option B: Set permanently** (recommended)
|
||||
Add to your shell profile (`~/.bashrc` or `~/.bash_profile`):
|
||||
```bash
|
||||
echo 'export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_YOUR_TOKEN_HERE"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
**Option C: Windows Environment Variables** (GUI)
|
||||
1. Search "Environment Variables" in Windows
|
||||
2. Click "Environment Variables..."
|
||||
3. Under "User variables", click "New"
|
||||
4. Variable name: `GITHUB_PERSONAL_ACCESS_TOKEN`
|
||||
5. Variable value: `ghp_YOUR_TOKEN_HERE`
|
||||
6. Click OK, restart Claude Code
|
||||
|
||||
---
|
||||
|
||||
## Step 3: MCP Configuration
|
||||
|
||||
The configuration file is already created at:
|
||||
`.claude/mcp-servers.json`
|
||||
|
||||
It contains:
|
||||
- **Gortex** - Code intelligence (already running)
|
||||
- **MySQL** - Database queries
|
||||
- **Browser** - Frontend testing
|
||||
|
||||
### Current Configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gortex": {
|
||||
"command": "C:\\Users\\270015376\\Documents\\gortex.exe",
|
||||
"args": ["mcp"],
|
||||
"cwd": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb"
|
||||
},
|
||||
"mysql": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@benborla29/mcp-server-mysql",
|
||||
"mysql://shopdb:shopdb-dev-password@127.0.0.1:3306/shopdb_flask"
|
||||
]
|
||||
},
|
||||
"browser": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@agent-infra/mcp-server-browser"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Verify Setup
|
||||
|
||||
After installing packages and setting GitHub token:
|
||||
|
||||
1. **Restart Claude Code completely** (close and reopen)
|
||||
|
||||
2. **Check MCP servers are loaded:**
|
||||
- You should see available tools from each server
|
||||
- No authentication errors in console
|
||||
|
||||
3. **Test each server:**
|
||||
|
||||
**Gortex test:**
|
||||
```
|
||||
ToolSearch("gortex explore")
|
||||
```
|
||||
|
||||
**MySQL test:**
|
||||
```
|
||||
# Once MCP is loaded, you can query:
|
||||
SELECT COUNT(*) FROM notifications WHERE alertfleet = true;
|
||||
```
|
||||
|
||||
**Browser test:**
|
||||
```
|
||||
# Once MCP is loaded:
|
||||
Navigate to http://localhost:5000/shopdb
|
||||
```
|
||||
|
||||
**GitHub test:**
|
||||
```
|
||||
# Once MCP is loaded:
|
||||
List my repositories
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Using the MCP Servers
|
||||
|
||||
### Gortex (Code Intelligence)
|
||||
**Use for:** Finding code, understanding relationships, editing symbols
|
||||
|
||||
**Examples:**
|
||||
- "Use Gortex to explore fleet alert architecture"
|
||||
- "Show me what calls get_fleet_alerts"
|
||||
- "Edit the _alert_targets_endpoint function"
|
||||
|
||||
### MySQL (Database)
|
||||
**Use for:** Querying data, verifying schema, testing SQL
|
||||
|
||||
**Examples:**
|
||||
- "Query all active fleet alerts from database"
|
||||
- "Show me the notifications table schema"
|
||||
- "How many operator reports exist?"
|
||||
|
||||
### Browser (Frontend Testing)
|
||||
**Use for:** Testing Vue app, screenshots, UI verification
|
||||
|
||||
**Examples:**
|
||||
- "Navigate to /shopdb/notifications and screenshot"
|
||||
- "Test the fleet alert form"
|
||||
- "Verify the notification list loads"
|
||||
|
||||
### GitHub (Collaboration)
|
||||
**Use for:** PRs, issues, CI status
|
||||
|
||||
**Examples:**
|
||||
- "Create PR for fleet alert work"
|
||||
- "Check CI status on wj branch"
|
||||
- "List open issues"
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### GitHub still shows auth error
|
||||
- Verify token is correct (starts with `ghp_`)
|
||||
- Check token has `repo` and `read:org` scopes
|
||||
- Restart Claude Code after setting environment variable
|
||||
- Try setting token in Windows Environment Variables GUI
|
||||
|
||||
### MySQL connection fails
|
||||
- Verify Docker containers are running: `docker ps`
|
||||
- Check MySQL is accessible: `mysql -h 127.0.0.1 -u shopdb -pshopdb-dev-password shopdb_flask`
|
||||
- Verify port 3306 is not blocked
|
||||
|
||||
### Browser MCP doesn't work
|
||||
- Install Chrome/Chromium if not present
|
||||
- Check browser package installed: `npm list -g @agent-infra/mcp-server-browser`
|
||||
|
||||
### Gortex MCP not connecting
|
||||
- Check daemon is running: `/c/Users/270015376/Documents/gortex.exe status`
|
||||
- Verify path in mcp-servers.json is correct
|
||||
- Try starting daemon manually: `/c/Users/270015376/Documents/gortex.exe daemon start`
|
||||
|
||||
### MCP servers not loading at all
|
||||
- Check `.claude/mcp-servers.json` file exists in project
|
||||
- Verify JSON syntax is valid
|
||||
- Restart Claude Code completely
|
||||
- Check Claude Code console for errors
|
||||
|
||||
---
|
||||
|
||||
## What Each Server Gives You
|
||||
|
||||
| Server | Tools | Token Savings |
|
||||
|--------|-------|---------------|
|
||||
| **Gortex** | 48 tools (explore, edit_symbol, find_files, etc.) | 30-50K per session |
|
||||
| **MySQL** | Query, schema inspection, data verification | 5-10K per session |
|
||||
| **Browser** | Navigate, click, screenshot, test | Catch bugs early |
|
||||
| **GitHub** | PR, issues, CI status | 5-10K per session |
|
||||
|
||||
**Total expected savings: 50-70K tokens per session** (vs current ~120K usage)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Run the npm install commands above
|
||||
2. Create GitHub token and set environment variable
|
||||
3. Restart Claude Code
|
||||
4. Try the test commands to verify each server works
|
||||
|
||||
Once all four are connected, you'll have complete code + data + frontend + collaboration coverage!
|
||||
323
.claude/archived/README-MCP-SETUP.md
Normal file
323
.claude/archived/README-MCP-SETUP.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# MCP Server Setup for ShopDB Development
|
||||
|
||||
Quick reference for the complete MCP (Model Context Protocol) server configuration.
|
||||
|
||||
---
|
||||
|
||||
## What is MCP?
|
||||
|
||||
**MCP** extends Claude Code with external tool access. ShopDB uses 4 MCP servers:
|
||||
|
||||
| Server | Purpose | What Claude Can Do |
|
||||
|--------|---------|-------------------|
|
||||
| **gortex** | Project management | Track tasks, milestones, time logs |
|
||||
| **mysql** | Database access | Query database, verify data, create test records |
|
||||
| **browser** | Web automation | Test UI, capture screenshots, fill forms |
|
||||
| **vm** | VM automation | Deploy to test VM, run commands, check logs |
|
||||
|
||||
Together, these enable **full-stack automated workflows** through natural language.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Install Prerequisites
|
||||
|
||||
```powershell
|
||||
cd flask-shopdb
|
||||
.\\.claude\quick-start-mcp.ps1
|
||||
```
|
||||
|
||||
This installs:
|
||||
- Gortex executable
|
||||
- Node.js packages (mysql, browser, ssh-mcp)
|
||||
- Starts MySQL database
|
||||
- Verifies VM connectivity
|
||||
- Runs test suite
|
||||
|
||||
### 2. Verify Setup
|
||||
|
||||
```powershell
|
||||
.\\.claude\test-mcp-servers.ps1
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
=========================================
|
||||
ShopDB MCP Server Test Suite
|
||||
=========================================
|
||||
|
||||
[1/7] Checking MCP configuration... OK
|
||||
[2/7] Testing Gortex MCP server... OK
|
||||
[3/7] Testing MySQL MCP server... OK
|
||||
[4/7] Testing Browser MCP server... OK
|
||||
[5/7] Testing VM SSH MCP server... OK
|
||||
[6/7] Checking Hyper-V VMs... OK
|
||||
[7/7] Checking VM snapshots... OK
|
||||
|
||||
Overall: 7/7 tests passed (100%)
|
||||
```
|
||||
|
||||
### 3. Start Claude Code
|
||||
|
||||
**IMPORTANT:** Run Claude Code from the `flask-shopdb` directory to load MCP servers.
|
||||
|
||||
```bash
|
||||
cd flask-shopdb
|
||||
claude
|
||||
```
|
||||
|
||||
### 4. Test MCP Servers
|
||||
|
||||
Try these commands with Claude:
|
||||
|
||||
```
|
||||
"List all tasks in the current project" # Tests Gortex
|
||||
"Show me the first 5 endpoints in the database" # Tests MySQL
|
||||
"Take a screenshot of https://localhost:5001" # Tests Browser
|
||||
"What is the hostname of the VM?" # Tests VM
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration File
|
||||
|
||||
**Location:** `flask-shopdb/.claude/mcp-servers.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gortex": {
|
||||
"command": "C:\\Users\\270015376\\Documents\\gortex.exe",
|
||||
"args": ["mcp"],
|
||||
"cwd": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb"
|
||||
},
|
||||
"mysql": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@benborla29/mcp-server-mysql",
|
||||
"mysql://shopdb:shopdb-dev-password@127.0.0.1:3306/shopdb_flask"
|
||||
]
|
||||
},
|
||||
"browser": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@agent-infra/mcp-server-browser"]
|
||||
},
|
||||
"vm": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"ssh-mcp",
|
||||
"--host", "192.168.100.10",
|
||||
"--user", "SupportUser",
|
||||
"--password", "vos313"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VM Setup (One-Time)
|
||||
|
||||
The test VM requires SSH to be enabled once:
|
||||
|
||||
**On the VM** (as Administrator):
|
||||
```powershell
|
||||
.\\.claude\enable-vm-ssh.ps1
|
||||
```
|
||||
|
||||
This:
|
||||
1. Sets password for SupportUser
|
||||
2. Enables SSH password authentication
|
||||
3. Restarts SSH service
|
||||
4. Configures firewall
|
||||
|
||||
**Test from host:**
|
||||
```bash
|
||||
ssh SupportUser@192.168.100.10 "hostname"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VM Snapshots
|
||||
|
||||
Create baseline snapshots for rapid testing:
|
||||
|
||||
```powershell
|
||||
# Clean Windows 11
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"
|
||||
|
||||
# Docker installed
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Docker-Ready"
|
||||
|
||||
# SSH enabled
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "SSH-Enabled"
|
||||
|
||||
# ShopDB deployed
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "ShopDB-Deployed"
|
||||
```
|
||||
|
||||
See: `.claude/VM-SNAPSHOT-GUIDE.md`
|
||||
|
||||
---
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### End-to-End Agent Test
|
||||
|
||||
```
|
||||
You: "Deploy the agent to the VM and test it"
|
||||
|
||||
Claude:
|
||||
1. [Bash: Build agent]
|
||||
2. [VM: Copy agent to VM]
|
||||
3. [VM: Install agent service]
|
||||
4. [VM: Start service]
|
||||
5. [MySQL: Create test fleet alert]
|
||||
6. [VM: Check agent log for alert]
|
||||
7. [VM: Verify tray shows notification]
|
||||
8. [MySQL: Delete test data]
|
||||
```
|
||||
|
||||
### Database-Driven UI Test
|
||||
|
||||
```
|
||||
You: "Test the notifications UI with different alert priorities"
|
||||
|
||||
Claude:
|
||||
1. [MySQL: Insert critical alert]
|
||||
2. [Browser: Screenshot alert]
|
||||
3. [MySQL: Update to info priority]
|
||||
4. [Browser: Screenshot updated alert]
|
||||
5. [MySQL: Delete test alert]
|
||||
```
|
||||
|
||||
### Multi-Environment Testing
|
||||
|
||||
```
|
||||
You: "Test new plugin on local and VM simultaneously"
|
||||
|
||||
Claude:
|
||||
1. [Bash: Build frontend]
|
||||
2. [Bash: Restart local Docker]
|
||||
3. [VM: Deploy to VM]
|
||||
4. [Browser: Test localhost:5001]
|
||||
5. [Browser: Test 192.168.100.10:5001]
|
||||
6. [Compare results]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `README-MCP-SETUP.md` | This file - quick reference |
|
||||
| `MCP-INTEGRATION-GUIDE.md` | Complete guide with advanced workflows |
|
||||
| `VM-SNAPSHOT-GUIDE.md` | Snapshot management for testing |
|
||||
| `setup-vm-ssh.md` | SSH configuration guide |
|
||||
| `test-mcp-servers.ps1` | Test suite for all servers |
|
||||
| `quick-start-mcp.ps1` | Automated setup script |
|
||||
| `enable-vm-ssh.ps1` | Run on VM to enable SSH |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### MCP Servers Not Loading
|
||||
|
||||
1. Verify you're in flask-shopdb directory
|
||||
2. Check `.claude/mcp-servers.json` exists
|
||||
3. Restart Claude Code completely
|
||||
4. Run test suite: `.\\.claude\test-mcp-servers.ps1`
|
||||
|
||||
### MySQL Connection Failed
|
||||
|
||||
```bash
|
||||
docker compose up -d db
|
||||
mysql -h 127.0.0.1 -u shopdb -pshopdb-dev-password shopdb_flask
|
||||
```
|
||||
|
||||
### VM Not Reachable
|
||||
|
||||
1. Check VM is running in Hyper-V Manager
|
||||
2. Verify VM has internal network adapter
|
||||
3. Ping test: `ping 192.168.100.10`
|
||||
4. SSH test: `ssh SupportUser@192.168.100.10`
|
||||
5. Run on VM: `.\\.claude\enable-vm-ssh.ps1`
|
||||
|
||||
### Browser Automation Failed
|
||||
|
||||
1. Check Chrome/Chromium installed
|
||||
2. Close other Chrome instances
|
||||
3. Test manually: `npx -y @agent-infra/mcp-server-browser`
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
### Development Credentials
|
||||
|
||||
**Database:** `mysql://shopdb:shopdb-dev-password@127.0.0.1:3306/shopdb_flask`
|
||||
- Local development only
|
||||
- Not exposed beyond localhost
|
||||
- Different credentials in production
|
||||
|
||||
**VM SSH:** `SupportUser / vos313`
|
||||
- Test VM only on internal network (192.168.100.x)
|
||||
- No internet access
|
||||
- VM rebuilt regularly
|
||||
|
||||
### Production
|
||||
|
||||
- Environment variables for credentials
|
||||
- Encrypted connections
|
||||
- Restricted database users
|
||||
- No MCP servers in production
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Run quick start: `.\\.claude\quick-start-mcp.ps1`
|
||||
2. Verify all tests pass: `.\\.claude\test-mcp-servers.ps1`
|
||||
3. Create VM snapshots: See `VM-SNAPSHOT-GUIDE.md`
|
||||
4. Read integration guide: `MCP-INTEGRATION-GUIDE.md`
|
||||
5. Start Claude Code: `claude` (from flask-shopdb directory)
|
||||
6. Test with example commands
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
**Test Suite Issues:**
|
||||
```powershell
|
||||
.\\.claude\test-mcp-servers.ps1 -Verbose
|
||||
```
|
||||
|
||||
**Manual Testing:**
|
||||
```bash
|
||||
# Test Gortex
|
||||
C:\Users\270015376\Documents\gortex.exe --version
|
||||
|
||||
# Test MySQL
|
||||
npx -y @benborla29/mcp-server-mysql --help
|
||||
|
||||
# Test Browser
|
||||
npx -y @agent-infra/mcp-server-browser --help
|
||||
|
||||
# Test VM
|
||||
ssh SupportUser@192.168.100.10 "hostname"
|
||||
```
|
||||
|
||||
**Logs:**
|
||||
- Claude Code logs: `~/.claude/logs/`
|
||||
- Docker logs: `docker logs flask-shopdb-api-1`
|
||||
- VM logs: `C:\ProgramData\ssh\logs\sshd.log` (on VM)
|
||||
|
||||
---
|
||||
|
||||
**Ready for automated full-stack development with Claude Code + MCP!**
|
||||
10
.claude/archived/README.md
Normal file
10
.claude/archived/README.md
Normal file
@@ -0,0 +1,10 @@
|
||||
# Archived Documentation
|
||||
|
||||
Superseded documentation kept for historical reference.
|
||||
|
||||
These documents have been replaced by current guides or are no longer relevant to active development:
|
||||
|
||||
- `FINAL-SUMMARY.md` - Initial setup completion summary
|
||||
- `SETUP-COMPLETE-SUMMARY.md` - Environment setup summary
|
||||
- `STATUS.md` - Historical project status snapshot
|
||||
- `ACTIVATE-HYPERV-PERMS.md` - Superseded by setup/HYPER-V-SETUP.md
|
||||
369
.claude/archived/SETUP-COMPLETE-SUMMARY.md
Normal file
369
.claude/archived/SETUP-COMPLETE-SUMMARY.md
Normal file
@@ -0,0 +1,369 @@
|
||||
# MCP Setup Complete - Summary
|
||||
|
||||
Setup completed on 2026-09-09
|
||||
|
||||
---
|
||||
|
||||
## What Was Created
|
||||
|
||||
### Documentation (7 files)
|
||||
|
||||
1. **INDEX-MCP-DOCS.md** - Master index of all MCP documentation
|
||||
2. **README-MCP-SETUP.md** - Quick reference guide
|
||||
3. **MCP-INTEGRATION-GUIDE.md** - Complete guide with workflows (4000+ words)
|
||||
4. **VM-SNAPSHOT-GUIDE.md** - Snapshot management guide
|
||||
5. **setup-vm-ssh.md** - SSH configuration for VM (existing, referenced)
|
||||
6. **enable-vm-ssh.ps1** - Script to run on VM (existing, referenced)
|
||||
7. **SETUP-COMPLETE-SUMMARY.md** - This file
|
||||
|
||||
### Automation Scripts (2 files)
|
||||
|
||||
1. **test-mcp-servers.ps1** - Test suite for all MCP servers
|
||||
2. **quick-start-mcp.ps1** - Automated setup and installation
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
### Test Results (from test-mcp-servers.ps1)
|
||||
|
||||
```
|
||||
Overall: 3/7 tests passed (43%)
|
||||
|
||||
gortex : OK ✓ (C:\Users\270015376\Documents\gortex.exe found)
|
||||
browser : OK ✓ (v1.2.29 available via npm)
|
||||
config : OK ✓ (mcp-servers.json valid)
|
||||
mysql : FAIL ✗ (Docker database not running)
|
||||
vm : FAIL ✗ (VM not reachable at 192.168.100.10)
|
||||
hyperv : WARN ⚠ (No admin privileges to check)
|
||||
snapshots : WARN ⚠ (No admin privileges to check)
|
||||
```
|
||||
|
||||
### What's Working
|
||||
|
||||
- MCP configuration file is valid
|
||||
- Gortex project management server installed and ready
|
||||
- Browser automation packages available
|
||||
- Node.js and npm properly installed
|
||||
- All documentation and scripts created
|
||||
|
||||
### What Needs Setup
|
||||
|
||||
**To use MySQL MCP:**
|
||||
```powershell
|
||||
docker compose up -d db
|
||||
```
|
||||
|
||||
**To use VM MCP:**
|
||||
1. Start VM in Hyper-V Manager
|
||||
2. Run on VM as Administrator: `.\\.claude\enable-vm-ssh.ps1`
|
||||
3. Test from host: `ssh SupportUser@192.168.100.10`
|
||||
|
||||
**To create VM snapshots:**
|
||||
1. Open PowerShell as Administrator
|
||||
2. Follow `VM-SNAPSHOT-GUIDE.md`
|
||||
|
||||
---
|
||||
|
||||
## Quick Start Commands
|
||||
|
||||
### Test Setup
|
||||
```powershell
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
.\\.claude\test-mcp-servers.ps1
|
||||
```
|
||||
|
||||
### Start Development
|
||||
```powershell
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
docker compose up -d db # Start database (if needed)
|
||||
claude # Start Claude Code with MCP servers
|
||||
```
|
||||
|
||||
### Test MCP Servers with Claude
|
||||
```
|
||||
"List all tasks in the current project" # Gortex
|
||||
"Show me the endpoints table schema" # MySQL
|
||||
"Take a screenshot of https://localhost:5001" # Browser
|
||||
"What is the hostname of the VM?" # VM
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
```
|
||||
flask-shopdb/.claude/
|
||||
├── INDEX-MCP-DOCS.md ← START HERE (master index)
|
||||
├── README-MCP-SETUP.md ← Quick reference
|
||||
├── MCP-INTEGRATION-GUIDE.md ← Complete guide with workflows
|
||||
├── VM-SNAPSHOT-GUIDE.md ← Snapshot management
|
||||
├── setup-vm-ssh.md ← SSH configuration
|
||||
├── mcp-servers.json ← Configuration file
|
||||
├── test-mcp-servers.ps1 ← Test suite
|
||||
├── quick-start-mcp.ps1 ← Setup automation
|
||||
├── enable-vm-ssh.ps1 ← VM SSH enablement
|
||||
└── SETUP-COMPLETE-SUMMARY.md ← This file
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory Updated
|
||||
|
||||
Memory file updated at:
|
||||
```
|
||||
~/.claude/projects/C--Users-270015376-Documents-github/memory/infrastructure_mcp_servers.md
|
||||
```
|
||||
|
||||
Added section: "Documentation and Testing" with links to all new files.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Reading Order
|
||||
|
||||
**First time setup:**
|
||||
1. Read `INDEX-MCP-DOCS.md` (this is the master index)
|
||||
2. Read `README-MCP-SETUP.md` (quick reference)
|
||||
3. Run `quick-start-mcp.ps1` (automated setup)
|
||||
4. Run `test-mcp-servers.ps1` (verify setup)
|
||||
5. Read `VM-SNAPSHOT-GUIDE.md` (if using VM)
|
||||
6. Read `MCP-INTEGRATION-GUIDE.md` (learn workflows)
|
||||
|
||||
**Daily usage:**
|
||||
1. Run `test-mcp-servers.ps1` (verify everything ready)
|
||||
2. Start Claude Code from flask-shopdb directory
|
||||
3. Reference `README-MCP-SETUP.md` for troubleshooting
|
||||
|
||||
---
|
||||
|
||||
## Example Workflows Documented
|
||||
|
||||
### Database Development
|
||||
- Add field to table
|
||||
- Create migration
|
||||
- Verify with MySQL MCP
|
||||
- Test on VM
|
||||
|
||||
### UI Testing
|
||||
- Build frontend
|
||||
- Create test data in database
|
||||
- Test UI with browser automation
|
||||
- Screenshot results
|
||||
- Clean up test data
|
||||
|
||||
### Agent Testing
|
||||
- Build agent
|
||||
- Deploy to VM via SSH
|
||||
- Verify agent connects
|
||||
- Check logs
|
||||
- Test fleet alerts end-to-end
|
||||
|
||||
### Debugging
|
||||
- Query database for issue
|
||||
- Check agent logs on VM
|
||||
- Test API endpoints
|
||||
- Screenshot UI state
|
||||
- Identify root cause
|
||||
|
||||
See `MCP-INTEGRATION-GUIDE.md` for detailed workflow examples.
|
||||
|
||||
---
|
||||
|
||||
## Snapshot Strategy (Recommended)
|
||||
|
||||
**Baseline snapshots to create:**
|
||||
```powershell
|
||||
# After clean Windows 11 install
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"
|
||||
|
||||
# After Docker Desktop installed
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Docker-Ready"
|
||||
|
||||
# After SSH enabled
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "SSH-Enabled"
|
||||
|
||||
# After ShopDB deployed
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "ShopDB-Deployed"
|
||||
```
|
||||
|
||||
**Testing snapshots (create as needed):**
|
||||
```powershell
|
||||
# Before risky operations
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Before-$(Get-Date -Format 'yyyyMMdd-HHmm')"
|
||||
```
|
||||
|
||||
See complete guide: `VM-SNAPSHOT-GUIDE.md`
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
### Development Credentials (Local Only)
|
||||
|
||||
**Database:**
|
||||
- User: shopdb
|
||||
- Password: shopdb-dev-password
|
||||
- Host: 127.0.0.1:3306
|
||||
- Database: shopdb_flask
|
||||
- **Scope:** Localhost only, not exposed beyond local machine
|
||||
|
||||
**VM SSH:**
|
||||
- User: SupportUser
|
||||
- Password: vos313
|
||||
- Host: 192.168.100.10 (internal network only)
|
||||
- **Scope:** Test VM on isolated internal network, no internet access
|
||||
|
||||
### Production Differences
|
||||
|
||||
- Environment variables for credentials
|
||||
- Encrypted connections
|
||||
- Restricted database users
|
||||
- No MCP servers in production
|
||||
- No plain-text passwords
|
||||
|
||||
---
|
||||
|
||||
## Integration with Claude Code
|
||||
|
||||
### How MCP Servers Load
|
||||
|
||||
**Automatic:** When you run `claude` from the `flask-shopdb` directory, Claude Code:
|
||||
1. Looks for `.claude/mcp-servers.json`
|
||||
2. Starts each configured MCP server
|
||||
3. Makes their tools available to Claude
|
||||
4. You can use them through natural language
|
||||
|
||||
**Manual:** To use MCP in different directory:
|
||||
- Copy `mcp-servers.json` to that directory's `.claude/` folder
|
||||
- Or run Claude Code from `flask-shopdb` directory
|
||||
|
||||
### Permission Model
|
||||
|
||||
**First use of each MCP tool:**
|
||||
- Claude Code shows permission prompt
|
||||
- Review the operation (query, command, etc.)
|
||||
- Approve or deny
|
||||
|
||||
**After approval:**
|
||||
- Operation executes
|
||||
- Similar operations may also require approval
|
||||
- Dangerous operations always require approval
|
||||
|
||||
**Configure auto-approval:**
|
||||
Add to `.claude/settings.json`:
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"mcp__mysql__query(SELECT *)",
|
||||
"mcp__vm__exec(hostname)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Quick Reference
|
||||
|
||||
| Issue | Fix |
|
||||
|-------|-----|
|
||||
| MySQL not reachable | `docker compose up -d db` |
|
||||
| VM not reachable | Start VM in Hyper-V Manager |
|
||||
| SSH connection refused | Run `enable-vm-ssh.ps1` on VM |
|
||||
| MCP servers not loading | Restart Claude Code from flask-shopdb directory |
|
||||
| Browser automation failed | Close other Chrome instances |
|
||||
| Gortex not found | Run `quick-start-mcp.ps1` |
|
||||
|
||||
Full troubleshooting: `README-MCP-SETUP.md` -> Troubleshooting section
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate
|
||||
1. **Start MySQL database:**
|
||||
```powershell
|
||||
docker compose up -d db
|
||||
```
|
||||
|
||||
2. **Test without VM** (optional):
|
||||
```powershell
|
||||
.\\.claude\test-mcp-servers.ps1 -SkipVM
|
||||
```
|
||||
|
||||
3. **Start Claude Code:**
|
||||
```powershell
|
||||
claude
|
||||
```
|
||||
|
||||
### When Ready for VM Testing
|
||||
1. Start VM in Hyper-V Manager
|
||||
2. Run on VM as Admin: `.\\.claude\enable-vm-ssh.ps1`
|
||||
3. Test SSH: `ssh SupportUser@192.168.100.10`
|
||||
4. Create baseline snapshots (see `VM-SNAPSHOT-GUIDE.md`)
|
||||
5. Run full test: `.\\.claude\test-mcp-servers.ps1`
|
||||
|
||||
### Learning Phase
|
||||
1. Read `MCP-INTEGRATION-GUIDE.md`
|
||||
2. Try example workflows with Claude
|
||||
3. Experiment with combining MCP tools
|
||||
4. Build your own workflows
|
||||
|
||||
---
|
||||
|
||||
## Files Created (Summary)
|
||||
|
||||
**Documentation:** 4 new files, 3 existing referenced
|
||||
**Scripts:** 2 new PowerShell scripts
|
||||
**Configuration:** 1 existing file validated
|
||||
**Memory:** 1 file updated
|
||||
|
||||
**Total lines written:** ~2500 lines of documentation and code
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Setup is complete when:
|
||||
|
||||
- [ ] `test-mcp-servers.ps1` passes all tests
|
||||
- [ ] Claude Code loads all 4 MCP servers
|
||||
- [ ] Can query database via MySQL MCP
|
||||
- [ ] Can control VM via SSH MCP
|
||||
- [ ] Can automate browser via Browser MCP
|
||||
- [ ] Can track tasks via Gortex MCP
|
||||
- [ ] VM snapshots created and tested
|
||||
- [ ] Documentation read and understood
|
||||
|
||||
**Current status:** 3/7 tests passing (setup phase complete, activation pending)
|
||||
|
||||
---
|
||||
|
||||
## Support Resources
|
||||
|
||||
**Local Documentation:**
|
||||
- `INDEX-MCP-DOCS.md` - Master index
|
||||
- `README-MCP-SETUP.md` - Quick reference
|
||||
- `MCP-INTEGRATION-GUIDE.md` - Complete guide
|
||||
|
||||
**Test and Setup:**
|
||||
- `test-mcp-servers.ps1` - Test suite
|
||||
- `quick-start-mcp.ps1` - Automated setup
|
||||
|
||||
**External:**
|
||||
- Gortex: https://github.com/zzet/gortex
|
||||
- MCP Spec: https://github.com/modelcontextprotocol/specification
|
||||
- MySQL MCP: https://www.npmjs.com/package/@benborla29/mcp-server-mysql
|
||||
- Browser MCP: https://www.npmjs.com/package/@agent-infra/mcp-server-browser
|
||||
- SSH MCP: https://www.npmjs.com/package/ssh-mcp
|
||||
|
||||
---
|
||||
|
||||
**Setup documentation complete!**
|
||||
|
||||
Ready to activate MCP servers:
|
||||
1. Start MySQL: `docker compose up -d db`
|
||||
2. Start VM (optional): Open Hyper-V Manager
|
||||
3. Test: `.\\.claude\test-mcp-servers.ps1`
|
||||
4. Use: `claude` (from flask-shopdb directory)
|
||||
241
.claude/archived/STATUS.md
Normal file
241
.claude/archived/STATUS.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# MCP Server Status
|
||||
|
||||
**Last Updated:** 2026-09-09 (Session: automated setup)
|
||||
|
||||
---
|
||||
|
||||
## Test Results
|
||||
|
||||
```
|
||||
Overall: 4/7 tests passed (57%) ✓ Improved from 3/7
|
||||
|
||||
Status by Server:
|
||||
✓ gortex : OK (Project management ready)
|
||||
✓ mysql : OK (Database running and reachable)
|
||||
✓ browser : OK (Web automation package available)
|
||||
✓ config : OK (Configuration valid)
|
||||
✗ vm : FAIL (VM not started)
|
||||
⚠ hyperv : WARN (Need admin to check VMs)
|
||||
⚠ snapshots : WARN (Need admin to manage snapshots)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What's Working Now
|
||||
|
||||
### ✓ Gortex (Project Management)
|
||||
- **Status:** Installed and ready
|
||||
- **Location:** C:\Users\270015376\Documents\gortex.exe
|
||||
- **Test:** Ask Claude "List all tasks in the current project"
|
||||
|
||||
### ✓ MySQL (Database Access)
|
||||
- **Status:** Running and healthy
|
||||
- **Container:** flask-shopdb-db-1 (MySQL 8.4.11)
|
||||
- **Connection:** 127.0.0.1:3306
|
||||
- **Database:** shopdb_flask
|
||||
- **Test:** Ask Claude "Show me the endpoints table schema"
|
||||
|
||||
### ✓ Browser (Web Automation)
|
||||
- **Status:** Package available via npm
|
||||
- **Version:** 1.2.29
|
||||
- **Package:** @agent-infra/mcp-server-browser
|
||||
- **Test:** Ask Claude "Take a screenshot of https://localhost:5001"
|
||||
|
||||
### ✓ Configuration
|
||||
- **Status:** Valid JSON configuration
|
||||
- **Location:** .claude/mcp-servers.json
|
||||
- **Servers:** 4 configured (gortex, mysql, browser, vm)
|
||||
|
||||
---
|
||||
|
||||
## What Needs Setup
|
||||
|
||||
### VM Testing (Optional)
|
||||
|
||||
**To enable VM MCP:**
|
||||
1. Start VM in Hyper-V Manager
|
||||
2. Connect to VM console
|
||||
3. Run as Administrator: `.\\.claude\enable-vm-ssh.ps1`
|
||||
4. Test from host: `ssh SupportUser@192.168.100.10`
|
||||
|
||||
**VM Details:**
|
||||
- IP: 192.168.100.10
|
||||
- User: SupportUser
|
||||
- Password: vos313
|
||||
- Purpose: Agent testing and integration tests
|
||||
|
||||
**See:** `.claude/setup-vm-ssh.md` for complete guide
|
||||
|
||||
### Snapshots (Optional, requires admin)
|
||||
|
||||
**To create snapshots:**
|
||||
```powershell
|
||||
# Run PowerShell as Administrator
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"
|
||||
```
|
||||
|
||||
**See:** `.claude/VM-SNAPSHOT-GUIDE.md` for complete guide
|
||||
|
||||
---
|
||||
|
||||
## Ready to Use
|
||||
|
||||
### Start Claude Code with MCP
|
||||
|
||||
```bash
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
claude
|
||||
```
|
||||
|
||||
**MCP servers will auto-load** when Claude Code starts from flask-shopdb directory.
|
||||
|
||||
### Test MCP Servers
|
||||
|
||||
Try these commands in Claude Code:
|
||||
|
||||
```
|
||||
"List all tasks in the current project"
|
||||
→ Tests Gortex project management
|
||||
|
||||
"Show me the first 5 endpoints in the database"
|
||||
→ Tests MySQL database access
|
||||
|
||||
"What tables exist in the database?"
|
||||
→ Tests MySQL schema inspection
|
||||
|
||||
"Take a screenshot of https://localhost:5001"
|
||||
→ Tests Browser automation (requires ShopDB running)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker Status
|
||||
|
||||
```
|
||||
Container: flask-shopdb-db-1
|
||||
Image: mysql:8.4
|
||||
Status: Up and healthy
|
||||
Ports: 127.0.0.1:3306->3306/tcp
|
||||
```
|
||||
|
||||
**To stop:**
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
**To restart:**
|
||||
```bash
|
||||
docker compose up -d db
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Current Limitations
|
||||
|
||||
### Without VM:
|
||||
- Cannot test agent deployment
|
||||
- Cannot run end-to-end agent tests
|
||||
- Cannot verify tray notifications
|
||||
- Cannot test fleet alerts on real agent
|
||||
|
||||
**Workaround:** Use local testing only (database + browser)
|
||||
|
||||
### Without Hyper-V Administrators Group:
|
||||
- Cannot use PowerShell Hyper-V cmdlets (Get-VM, Checkpoint-VM, etc.)
|
||||
- Cannot script snapshot creation/restoration
|
||||
- **CAN use Hyper-V Manager GUI** for everything (VMs, snapshots, settings)
|
||||
- **VM MCP works perfectly via SSH** (no Hyper-V permissions needed!)
|
||||
|
||||
**Impact:** None for MCP usage - only affects PowerShell automation
|
||||
|
||||
**To get group membership:** Ask IT admin to run:
|
||||
```powershell
|
||||
Add-LocalGroupMember -Group "Hyper-V Administrators" -Member "270015376"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Rate by Use Case
|
||||
|
||||
| Use Case | Available | MCP Servers Needed |
|
||||
|----------|-----------|-------------------|
|
||||
| Database development | ✓ Yes | mysql |
|
||||
| API development | ✓ Yes | mysql |
|
||||
| Frontend development | ✓ Yes | browser |
|
||||
| UI testing | ✓ Yes | browser + mysql |
|
||||
| Project tracking | ✓ Yes | gortex |
|
||||
| Agent deployment | ✗ No (VM needed) | vm + mysql |
|
||||
| End-to-end testing | ✗ No (VM needed) | vm + mysql + browser |
|
||||
| Snapshot management | △ Manual | (admin for scripting) |
|
||||
|
||||
**Current capability: 5/8 workflows (62%)**
|
||||
|
||||
---
|
||||
|
||||
## Documentation Quick Links
|
||||
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| `INDEX-MCP-DOCS.md` | Master index |
|
||||
| `README-MCP-SETUP.md` | Quick reference |
|
||||
| `MCP-INTEGRATION-GUIDE.md` | Complete guide with workflows |
|
||||
| `VM-SNAPSHOT-GUIDE.md` | Snapshot management |
|
||||
| `test-mcp-servers.ps1` | Test suite |
|
||||
| `STATUS.md` | This file (current status) |
|
||||
|
||||
---
|
||||
|
||||
## Next Session Checklist
|
||||
|
||||
**Before starting development:**
|
||||
|
||||
- [ ] Verify Docker is running: `docker ps`
|
||||
- [ ] Check database is up: `docker compose ps db`
|
||||
- [ ] Run test suite: `.\\.claude\test-mcp-servers.ps1`
|
||||
- [ ] Start Claude Code from flask-shopdb directory
|
||||
|
||||
**If tests fail:**
|
||||
- MySQL: `docker compose up -d db`
|
||||
- VM: Start in Hyper-V Manager (if needed)
|
||||
- Other: See `README-MCP-SETUP.md` troubleshooting
|
||||
|
||||
---
|
||||
|
||||
## Session Notes
|
||||
|
||||
**2026-09-09 Setup Session:**
|
||||
- Created 7 documentation files (~2500 lines)
|
||||
- Created 2 automation scripts
|
||||
- Configured 4 MCP servers
|
||||
- Started Docker Desktop and MySQL automatically
|
||||
- Test results: 4/7 passing (57%)
|
||||
- Ready for database and frontend development
|
||||
- VM setup deferred (optional for agent testing)
|
||||
|
||||
**Database Started:**
|
||||
- Docker Desktop: Auto-started successfully
|
||||
- MySQL 8.4.11: Running and healthy
|
||||
- Connection: Verified via docker exec
|
||||
- Tables: Existing database preserved
|
||||
|
||||
---
|
||||
|
||||
## Memory Saved
|
||||
|
||||
MCP setup information saved to:
|
||||
```
|
||||
~/.claude/projects/C--Users-270015376-Documents-github/memory/infrastructure_mcp_servers.md
|
||||
```
|
||||
|
||||
**Includes:**
|
||||
- All 4 MCP server configurations
|
||||
- Documentation file locations
|
||||
- Quick start commands
|
||||
- Test procedures
|
||||
- Troubleshooting tips
|
||||
|
||||
---
|
||||
|
||||
**Status: Ready for development with 3 active MCP servers (gortex, mysql, browser)**
|
||||
|
||||
VM optional for agent testing - can be enabled later when needed.
|
||||
Reference in New Issue
Block a user