shopdb-flask/.claude/archived/README-MCP-SETUP.md

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

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

.\\.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.

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

{
  "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):

.\\.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:

ssh SupportUser@192.168.100.10 "hostname"

---

VM Snapshots

Create baseline snapshots for rapid testing:

# 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

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:

.\\.claude\test-mcp-servers.ps1 -Verbose

Manual Testing:

# 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!