Files

Proudlock bd48814021 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>

2026-09-11 15:45:05 -04:00

9.5 KiB

Raw Blame History

MCP Documentation Index

Complete documentation for ShopDB MCP (Model Context Protocol) server setup and workflows.

Getting Started

Start here:

README-MCP-SETUP.md - Quick reference and setup instructions
quick-start-mcp.ps1 - Automated setup script (run this first)
test-mcp-servers.ps1 - Test suite to verify everything works

Quick start command:

cd flask-shopdb
.\\.claude\quick-start-mcp.ps1
.\\.claude\test-mcp-servers.ps1
claude

Documentation Files

Core Setup

File	Purpose	When to Use
`README-MCP-SETUP.md`	Quick reference	Starting point, troubleshooting
`MCP-INTEGRATION-GUIDE.md`	Complete guide	Learning workflows, advanced patterns
`mcp-servers.json`	Configuration	Modify server settings

VM Setup

File	Purpose	When to Use
`setup-vm-ssh.md`	SSH configuration guide	First-time VM setup
`enable-vm-ssh.ps1`	SSH setup script	Run on VM as Administrator
`VM-SNAPSHOT-GUIDE.md`	Snapshot management	Creating/restoring VM snapshots

Testing and Automation

File	Purpose	When to Use
`test-mcp-servers.ps1`	MCP test suite	Verify setup, diagnose issues
`quick-start-mcp.ps1`	Automated setup	Initial install, repair setup

File	Purpose	When to Use
`../deploy-to-vm.ps1`	VM deployment	Deploy ShopDB to VM
`../test-vm-connectivity.ps1`	VM network test	Debug VM connectivity
`../open-firewall-for-vm.ps1`	Firewall config	Allow VM to access host

MCP Server Overview

1. Gortex (Project Management)

Status: Installed at C:\Users\270015376\Documents\gortex.exe Configuration: .claude/mcp-servers.json -> "gortex" Test: Ask Claude "List all tasks in the current project"

Use cases:

Track development tasks
Log time spent on features
Manage sprint milestones
Generate progress reports

Documentation:

GitHub: https://github.com/zzet/gortex
Local: (none - use GitHub docs)

2. MySQL (Database Access)

Status: Installed via npx @benborla29/mcp-server-mysql Configuration: .claude/mcp-servers.json -> "mysql" Requires: Docker running with docker compose up -d db Test: Ask Claude "Show me the endpoints table schema"

Use cases:

Query database without reading models
Create test data (alerts, reports)
Verify migration results
Debug data issues
Analyze performance

Documentation:

npm: https://www.npmjs.com/package/@benborla29/mcp-server-mysql
Local: README-MCP-SETUP.md

3. Browser (Web Automation)

Status: Installed via npx @agent-infra/mcp-server-browser Configuration: .claude/mcp-servers.json -> "browser" Requires: Chrome/Chromium installed Test: Ask Claude "Take a screenshot of https://localhost:5001"

Use cases:

Automated UI testing
Screenshot capture for validation
Form submission testing
End-to-end workflow testing
Visual regression checks

Documentation:

npm: https://www.npmjs.com/package/@agent-infra/mcp-server-browser
Local: MCP-INTEGRATION-GUIDE.md

4. VM (SSH Remote Control)

Status: Installed via npx ssh-mcp Configuration: .claude/mcp-servers.json -> "vm" Requires: VM running with SSH enabled Connection: SupportUser@192.168.100.10 (password: vos313) Test: Ask Claude "What is the hostname of the VM?"

Use cases:

Deploy agent to test VM
Run PowerShell commands remotely
Transfer files to/from VM
Monitor agent logs
Check service status
Test agent integration

Documentation:

npm: https://www.npmjs.com/package/ssh-mcp
Local: setup-vm-ssh.md, VM-SNAPSHOT-GUIDE.md

Common Tasks

Initial Setup

# 1. Run automated setup
cd flask-shopdb
.\\.claude\quick-start-mcp.ps1

# 2. Enable SSH on VM (one-time, on VM as Admin)
.\\.claude\enable-vm-ssh.ps1

# 3. Create baseline snapshots
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Docker-Ready"
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "SSH-Enabled"
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "ShopDB-Deployed"

# 4. Test setup
.\\.claude\test-mcp-servers.ps1

# 5. Start Claude Code
claude

Daily Usage

# Verify MCP servers
.\\.claude\test-mcp-servers.ps1

# Start Claude Code from flask-shopdb directory
claude

Troubleshooting

# Test all servers with verbose output
.\\.claude\test-mcp-servers.ps1 -Verbose

# Test without VM
.\\.claude\test-mcp-servers.ps1 -SkipVM

# Reinstall prerequisites
.\\.claude\quick-start-mcp.ps1 -InstallOnly

# Test individual components
C:\Users\270015376\Documents\gortex.exe --version
docker compose ps
ssh SupportUser@192.168.100.10 "hostname"
npx -y @agent-infra/mcp-server-browser --help

Workflow Examples

Example 1: Add Database Field

You: "Add last_boot_time field to endpoints"

Claude uses:
- MySQL to check current schema
- Edit to create migration
- Bash to run migration
- MySQL to verify field added
- VM to test on test environment

See MCP-INTEGRATION-GUIDE.md section "Workflow 1" for details.

Example 2: UI Testing

You: "Test the notifications plugin UI"

Claude uses:
- Bash to build frontend
- Browser to navigate and test
- MySQL to create test data
- Browser to screenshot results
- MySQL to clean up test data

See MCP-INTEGRATION-GUIDE.md section "Workflow 2" for details.

Example 3: Agent Deployment

You: "Deploy agent to VM and verify it works"

Claude uses:
- Bash to build agent
- VM to stop/copy/start agent service
- VM to tail logs
- MySQL to verify heartbeat
- Browser to screenshot endpoint page

See MCP-INTEGRATION-GUIDE.md section "Workflow 3" for details.

Snapshot Workflows

Create Baseline Snapshots

# After each major setup stage
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Docker-Ready"
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "SSH-Enabled"
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "ShopDB-Deployed"

Restore to Clean State

# Before each test run
Restore-VMSnapshot -Name "ShopDB-Deployed" -VMName "ShopDB-Test-VM" -Confirm:$false

List Snapshots

Get-VMSnapshot -VMName "ShopDB-Test-VM" | 
  Select-Object Name, CreationTime, ParentSnapshotName | 
  Format-Table

See VM-SNAPSHOT-GUIDE.md for complete snapshot management guide.

File Organization

flask-shopdb/
└── .claude/
    ├── INDEX-MCP-DOCS.md              ← This file (documentation index)
    ├── README-MCP-SETUP.md            ← Quick reference
    ├── MCP-INTEGRATION-GUIDE.md       ← Complete guide
    ├── VM-SNAPSHOT-GUIDE.md           ← Snapshot management
    ├── setup-vm-ssh.md                ← SSH setup guide
    ├── mcp-servers.json               ← Configuration file
    ├── test-mcp-servers.ps1           ← Test suite
    ├── quick-start-mcp.ps1            ← Setup automation
    └── enable-vm-ssh.ps1              ← VM SSH enablement

Reading Order

For new setup:

README-MCP-SETUP.md - Understand what MCP is and quick start
Run quick-start-mcp.ps1 - Automated setup
setup-vm-ssh.md - Configure VM SSH (one-time)
VM-SNAPSHOT-GUIDE.md - Create baseline snapshots
Run test-mcp-servers.ps1 - Verify everything works
MCP-INTEGRATION-GUIDE.md - Learn workflows

For troubleshooting:

Run test-mcp-servers.ps1 -Verbose
Check README-MCP-SETUP.md -> Troubleshooting section
Check individual server documentation in this index

For learning workflows:

MCP-INTEGRATION-GUIDE.md - Complete guide
Try example workflows with Claude
Adapt patterns to your needs

Testing Checklist

Before starting development session:

Run .\\.claude\test-mcp-servers.ps1
All 7 tests pass (or 6 if skipping VM)
Docker database is running
VM is running (if testing agent)
VM has SSH enabled
Baseline snapshots exist
Start Claude Code from flask-shopdb directory

Support and Resources

GitHub Repositories:

Gortex: https://github.com/zzet/gortex
MCP Spec: https://github.com/modelcontextprotocol/specification

npm Packages:

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

Local Documentation:

This directory: All .md files
Parent: DEPLOY-TO-VM.md, test-vm-connectivity.ps1
Memory: ~/.claude/projects/.../memory/infrastructure_mcp_servers.md

Quick Commands Reference

# Setup
cd flask-shopdb
.\\.claude\quick-start-mcp.ps1

# Test
.\\.claude\test-mcp-servers.ps1

# Start
claude

# VM Snapshots
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "MySnapshot"
Restore-VMSnapshot -Name "MySnapshot" -VMName "ShopDB-Test-VM" -Confirm:$false
Get-VMSnapshot -VMName "ShopDB-Test-VM"

# VM SSH (from host)
ssh SupportUser@192.168.100.10 "hostname"

# Database
docker compose up -d db
mysql -h 127.0.0.1 -u shopdb -pshopdb-dev-password shopdb_flask

# Manual MCP Tests
C:\Users\270015376\Documents\gortex.exe --version
npx -y @benborla29/mcp-server-mysql --help
npx -y @agent-infra/mcp-server-browser --help
npx -y ssh-mcp --help

Updated: 2026-09-09 Version: 1.0

9.5 KiB Raw Blame History

MCP Documentation Index

Getting Started

Documentation Files

Core Setup

VM Setup

Testing and Automation

Related Files (in parent directory)

MCP Server Overview

1. Gortex (Project Management)

2. MySQL (Database Access)

3. Browser (Web Automation)

4. VM (SSH Remote Control)

Common Tasks

Initial Setup

Daily Usage

Troubleshooting

Workflow Examples

Example 1: Add Database Field

Example 2: UI Testing

Example 3: Agent Deployment

Snapshot Workflows

Create Baseline Snapshots

Restore to Clean State

List Snapshots

File Organization

Reading Order

Testing Checklist

Support and Resources

Quick Commands Reference

9.5 KiB

Raw Blame History