ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bd48814021ff2fcd4e9d78d93f37dcd03e1b3eec
shopdb-flask/.claude/setup/INDEX-MCP-DOCS.md
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

385 lines
9.5 KiB
Markdown
Raw Blame History

# MCP Documentation Index
Complete documentation for ShopDB MCP (Model Context Protocol) server setup and workflows.
---
## Getting Started
**Start here:**
1. `README-MCP-SETUP.md` - Quick reference and setup instructions
2. `quick-start-mcp.ps1` - Automated setup script (run this first)
3. `test-mcp-servers.ps1` - Test suite to verify everything works
**Quick start command:**
```powershell
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 |
### Related Files (in parent directory)
| 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
```powershell
# 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
```powershell
# Verify MCP servers
.\\.claude\test-mcp-servers.ps1
# Start Claude Code from flask-shopdb directory
claude
```
### Troubleshooting
```powershell
# 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
```powershell
# 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
```powershell
# Before each test run
Restore-VMSnapshot -Name "ShopDB-Deployed" -VMName "ShopDB-Test-VM" -Confirm:$false
```
### List Snapshots
```powershell
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:**
1. `README-MCP-SETUP.md` - Understand what MCP is and quick start
2. Run `quick-start-mcp.ps1` - Automated setup
3. `setup-vm-ssh.md` - Configure VM SSH (one-time)
4. `VM-SNAPSHOT-GUIDE.md` - Create baseline snapshots
5. Run `test-mcp-servers.ps1` - Verify everything works
6. `MCP-INTEGRATION-GUIDE.md` - Learn workflows
**For troubleshooting:**
1. Run `test-mcp-servers.ps1 -Verbose`
2. Check `README-MCP-SETUP.md` -> Troubleshooting section
3. Check individual server documentation in this index
**For learning workflows:**
1. `MCP-INTEGRATION-GUIDE.md` - Complete guide
2. Try example workflows with Claude
3. 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
```powershell
# 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
Reference in New Issue View Git Blame Copy Permalink