# 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