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
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!**
|
||||
Reference in New Issue
Block a user