a03fd3de4f
- Replace all unicode (emojis, checkmarks, arrows, em-dashes) with ASCII in .claude/ docs - Comment out OperatingSystemsList route in core.js - breaks lean builds without computers plugin - Comment out Operating Systems tab in ModelCatalogHub - TODO: Plugins should dynamically register their settings routes Fixes #2 CI check failures on wj branch Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
385 lines
9.5 KiB
Markdown
385 lines
9.5 KiB
Markdown
# 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
|