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>
This commit is contained in:
Proudlock
71
.claude/setup/GITHUB-MCP-SETUP.md
Normal file
71
.claude/setup/GITHUB-MCP-SETUP.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# GitHub MCP Setup Guide
|
||||
|
||||
The GitHub MCP server failed to connect with error:
|
||||
```
|
||||
Authorization header is badly formatted
|
||||
```
|
||||
|
||||
## Fixing the GitHub MCP Connection
|
||||
|
||||
1. **Check MCP configuration** (likely in `.claude/mcp.json` or Claude app settings):
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "...",
|
||||
"args": [...],
|
||||
"env": {
|
||||
"GITHUB_TOKEN": "your-token-here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Verify GitHub token**:
|
||||
- Token should be a GitHub Personal Access Token (PAT)
|
||||
- Required scopes: `repo`, `read:org`
|
||||
- Generate at: https://github.com/settings/tokens
|
||||
|
||||
3. **Token format**:
|
||||
- Classic PAT: `ghp_...` (starts with ghp_)
|
||||
- Fine-grained PAT: `github_pat_...`
|
||||
- No extra quotes or whitespace
|
||||
|
||||
4. **Common issues**:
|
||||
- Token expired (regenerate on GitHub)
|
||||
- Wrong token format (not base64 encoded, just raw token)
|
||||
- Authorization header format (should be `Bearer <token>` or `token <token>`)
|
||||
|
||||
5. **Test token manually**:
|
||||
```bash
|
||||
curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user
|
||||
```
|
||||
|
||||
## What GitHub MCP Would Enable
|
||||
|
||||
Once connected, I could:
|
||||
- Create PRs directly from conversation
|
||||
- Check CI/CD status
|
||||
- Link commits to issues
|
||||
- Review PR comments
|
||||
- Update issue status
|
||||
|
||||
## Alternative: Manual Git + GitHub CLI
|
||||
|
||||
If MCP stays broken, you can use `gh` CLI:
|
||||
```bash
|
||||
# Install GitHub CLI if not present
|
||||
winget install --id GitHub.cli
|
||||
|
||||
# Authenticate
|
||||
gh auth login
|
||||
|
||||
# I can then use gh commands via Bash tool
|
||||
gh pr create --title "..." --body "..."
|
||||
gh pr status
|
||||
```
|
||||
|
||||
## To Diagnose
|
||||
|
||||
Check Claude Code settings or MCP config file for the github server configuration and verify the token is valid.
|
||||
164
.claude/setup/GORTEX-MCP-SETUP.md
Normal file
164
.claude/setup/GORTEX-MCP-SETUP.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# Gortex MCP Integration Guide
|
||||
|
||||
Gortex is successfully installed and has indexed your ShopDB repository (115K+ symbols, 412K edges).
|
||||
|
||||
Now we need to connect it as an MCP server so Claude Code can use its 48 tools directly.
|
||||
|
||||
## Current Status
|
||||
|
||||
**Installed:** ✅ Gortex v0.64.2 at `C:\Users\270015376\Documents\gortex.exe`
|
||||
|
||||
**Daemon Running:** ✅
|
||||
```bash
|
||||
/c/Users/270015376/Documents/gortex.exe status
|
||||
# Shows: daemon running, flask-shopdb tracked with 2467 files
|
||||
```
|
||||
|
||||
**Indexed Repository:** ✅ flask-shopdb at `C:\Users\270015376\Documents\github\flask-shopdb`
|
||||
|
||||
## How to Connect as MCP Server
|
||||
|
||||
### Option 1: Claude Desktop App
|
||||
|
||||
If using Claude Desktop app, add to your MCP config file (likely `~/Library/Application Support/Claude/claude_desktop_config.json` on Mac or equivalent on Windows):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gortex": {
|
||||
"command": "C:\\Users\\270015376\\Documents\\gortex.exe",
|
||||
"args": ["mcp"],
|
||||
"cwd": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 2: Claude Code CLI
|
||||
|
||||
Check if there's an `.claude/mcp.json` in your project:
|
||||
|
||||
```bash
|
||||
cat .claude/mcp.json
|
||||
```
|
||||
|
||||
If it exists, add Gortex server. If not, create it:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gortex": {
|
||||
"command": "C:\\Users\\270015376\\Documents\\gortex.exe",
|
||||
"args": ["mcp"],
|
||||
"cwd": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 3: Manual Start (Testing)
|
||||
|
||||
Test the MCP server manually:
|
||||
```bash
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
/c/Users/270015376/Documents/gortex.exe mcp
|
||||
```
|
||||
|
||||
This starts the MCP server in stdio mode. Press Ctrl+C to stop.
|
||||
|
||||
## Available Tools (48 total)
|
||||
|
||||
Once connected, Claude Code will have access to these tools:
|
||||
|
||||
### Navigation & Discovery
|
||||
- `explore` - Start here for any task (gets relevant symbols)
|
||||
- `find_files` - Find files by name
|
||||
- `batch_symbols` - Get multiple symbols + callers/callees
|
||||
- `find_implementations` - What implements this interface
|
||||
- `find_declaration` - Where is this symbol defined
|
||||
- `find_co_changing_symbols` - Files that change together
|
||||
|
||||
### Code Editing
|
||||
- `edit_symbol` - Edit code by symbol ID (no need to read whole file)
|
||||
- `edit_file` - Edit any file by exact replacement
|
||||
- `batch_edit` - Apply multiple edits atomically
|
||||
|
||||
### Analysis & Review
|
||||
- `detect_changes` - Map uncommitted changes to blast radius
|
||||
- `diff_context` - Graph context for git diffs (perfect for merges!)
|
||||
- `explain_change_impact` - What will break if I change this
|
||||
- `audit_health` - Code health grades (A-F)
|
||||
- `find_clones` - Duplicate code detection
|
||||
- `api_impact` - Impact report before modifying routes
|
||||
|
||||
### Memory & Session
|
||||
- `distill_session` - Summarize work session
|
||||
- Context buffering tools (`ctx_peek`, `ctx_slice`, `ctx_grep`)
|
||||
|
||||
## Expected Token Savings
|
||||
|
||||
Based on our typical workflow:
|
||||
|
||||
**Exploring fleet alerts:**
|
||||
- Current: 10-15K tokens (multiple grep + read cycles)
|
||||
- With Gortex: 2-3K tokens (explore tool)
|
||||
- **Savings: ~70-80%**
|
||||
|
||||
**Editing routes.py:**
|
||||
- Current: 5K tokens (read 3000-line file)
|
||||
- With Gortex: 1-2K tokens (edit_symbol)
|
||||
- **Savings: ~60-70%**
|
||||
|
||||
**Merging wilm → wj:**
|
||||
- Current: 8-12K tokens (read conflicts, understand context)
|
||||
- With Gortex: 3-5K tokens (diff_context tool)
|
||||
- **Savings: ~50-60%**
|
||||
|
||||
**Overall session savings: 30-50K tokens per session** (out of 200K budget)
|
||||
|
||||
## Testing Connection
|
||||
|
||||
After adding to MCP config, restart Claude Code and check:
|
||||
|
||||
```
|
||||
# In Claude Code conversation, look for system message about MCP servers
|
||||
# Or try using a tool:
|
||||
ToolSearch("gortex explore")
|
||||
```
|
||||
|
||||
If working, you'll see Gortex tools available via ToolSearch.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Daemon not running:**
|
||||
```bash
|
||||
/c/Users/270015376/Documents/gortex.exe daemon start
|
||||
```
|
||||
|
||||
**Check status:**
|
||||
```bash
|
||||
/c/Users/270015376/Documents/gortex.exe status
|
||||
```
|
||||
|
||||
**Stop daemon:**
|
||||
```bash
|
||||
/c/Users/270015376/Documents/gortex.exe daemon stop
|
||||
```
|
||||
|
||||
**Re-index after major changes:**
|
||||
```bash
|
||||
# Daemon auto-updates, but to force:
|
||||
/c/Users/270015376/Documents/gortex.exe untrack .
|
||||
/c/Users/270015376/Documents/gortex.exe track .
|
||||
```
|
||||
|
||||
## Why This Matters
|
||||
|
||||
Instead of me reading entire files to understand code, I can:
|
||||
1. Ask Gortex "explore fleet alerts" → get relevant symbols
|
||||
2. Query "what calls get_fleet_alerts" → see usage
|
||||
3. Edit symbols directly by ID → no file reading
|
||||
4. Analyze blast radius before changes → prevent bugs
|
||||
5. Get merge context → easier conflict resolution
|
||||
|
||||
This turns Gortex from a "nice to have" into a "fundamental workflow tool" that saves significant tokens and improves code understanding.
|
||||
249
.claude/setup/HYPER-V-SETUP.md
Normal file
249
.claude/setup/HYPER-V-SETUP.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# Hyper-V Permissions Explained
|
||||
|
||||
Quick guide to understanding Hyper-V permissions and why they don't matter for MCP usage.
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
**Your account:** 270015376
|
||||
**Hyper-V Administrators group:** Empty (you're not a member)
|
||||
**Result:** Cannot use PowerShell Hyper-V cmdlets
|
||||
|
||||
---
|
||||
|
||||
## What This Affects
|
||||
|
||||
### ✓ Still Works (No Admin Needed)
|
||||
|
||||
| Feature | How to Use | Notes |
|
||||
|---------|-----------|-------|
|
||||
| VM MCP Server | SSH to VM | Uses network, not Hyper-V API |
|
||||
| Start/Stop VMs | Hyper-V Manager GUI | Right-click VM |
|
||||
| View VM status | Hyper-V Manager GUI | Shows all VMs |
|
||||
| Create snapshots | Hyper-V Manager GUI | Right-click VM -> Checkpoint |
|
||||
| Restore snapshots | Hyper-V Manager GUI | Right-click snapshot -> Apply |
|
||||
| Connect to VM | Hyper-V Manager GUI | Double-click VM |
|
||||
| VM settings | Hyper-V Manager GUI | Right-click VM -> Settings |
|
||||
|
||||
**Bottom line:** Everything you need works via GUI or SSH.
|
||||
|
||||
### ✗ Doesn't Work (Need Group Membership)
|
||||
|
||||
| Feature | Why It Fails | Workaround |
|
||||
|---------|-------------|-----------|
|
||||
| `Get-VM` cmdlet | No Hyper-V perms | Use Hyper-V Manager GUI |
|
||||
| `Checkpoint-VM` cmdlet | No Hyper-V perms | Right-click VM -> Checkpoint |
|
||||
| `Restore-VMSnapshot` cmdlet | No Hyper-V perms | Right-click snapshot -> Apply |
|
||||
| Scripted snapshot automation | No cmdlet access | Manual via GUI |
|
||||
| Test script Hyper-V checks | No cmdlet access | Warnings are harmless |
|
||||
|
||||
**Bottom line:** Only PowerShell automation is blocked.
|
||||
|
||||
---
|
||||
|
||||
## Why VM MCP Works Without Admin
|
||||
|
||||
**VM MCP uses SSH, not Hyper-V API:**
|
||||
|
||||
```
|
||||
Traditional approach (needs Hyper-V perms):
|
||||
Claude -> PowerShell -> Hyper-V API -> VM
|
||||
|
||||
VM MCP approach (no perms needed):
|
||||
Claude -> ssh-mcp -> Network -> SSH Server on VM -> Commands
|
||||
```
|
||||
|
||||
**Key difference:** VM MCP treats the VM like any remote Windows machine. It doesn't care about Hyper-V at all.
|
||||
|
||||
---
|
||||
|
||||
## Test Results Explained
|
||||
|
||||
When you run `test-mcp-servers.ps1`:
|
||||
|
||||
```
|
||||
[6/7] Checking Hyper-V VMs...
|
||||
INFO: Cannot use PowerShell Hyper-V cmdlets
|
||||
NOTE: VM MCP works via SSH - no admin needed for that!
|
||||
|
||||
[7/7] Checking VM snapshots...
|
||||
INFO: Cannot use PowerShell snapshot cmdlets
|
||||
TIP: Use Hyper-V Manager GUI to create/restore snapshots
|
||||
```
|
||||
|
||||
**These are informational, not errors.** The test script is just explaining what you can't do via PowerShell.
|
||||
|
||||
---
|
||||
|
||||
## Getting Admin/Group Access
|
||||
|
||||
### Option 1: Request Group Membership (Recommended)
|
||||
|
||||
Ask your IT admin to add you to "Hyper-V Administrators" group:
|
||||
|
||||
```powershell
|
||||
# Admin runs:
|
||||
Add-LocalGroupMember -Group "Hyper-V Administrators" -Member "270015376"
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Can use PowerShell cmdlets
|
||||
- Can script VM operations
|
||||
- Test script shows all green
|
||||
|
||||
**Drawbacks:**
|
||||
- Need to request from IT
|
||||
- May have approval process
|
||||
|
||||
### Option 2: Keep As-Is (Works Fine)
|
||||
|
||||
Use Hyper-V Manager GUI instead of PowerShell.
|
||||
|
||||
**Benefits:**
|
||||
- No need to request access
|
||||
- GUI is often easier than cmdlets
|
||||
- VM MCP works perfectly
|
||||
|
||||
**Drawbacks:**
|
||||
- Can't script snapshot management
|
||||
- Test script shows warnings
|
||||
|
||||
---
|
||||
|
||||
## GUI Equivalents
|
||||
|
||||
All PowerShell operations have GUI equivalents:
|
||||
|
||||
### Create Snapshot
|
||||
**PowerShell:**
|
||||
```powershell
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"
|
||||
```
|
||||
|
||||
**GUI:**
|
||||
1. Open Hyper-V Manager
|
||||
2. Right-click VM
|
||||
3. Select "Checkpoint"
|
||||
4. Enter name "Clean-Install"
|
||||
5. Click OK
|
||||
|
||||
### Restore Snapshot
|
||||
**PowerShell:**
|
||||
```powershell
|
||||
Restore-VMSnapshot -Name "Clean-Install" -VMName "ShopDB-Test-VM" -Confirm:$false
|
||||
```
|
||||
|
||||
**GUI:**
|
||||
1. Open Hyper-V Manager
|
||||
2. Select VM in left pane
|
||||
3. In "Checkpoints" pane (bottom), right-click "Clean-Install"
|
||||
4. Select "Apply"
|
||||
5. Choose "Apply" or "Apply and Create Checkpoint"
|
||||
|
||||
### List Snapshots
|
||||
**PowerShell:**
|
||||
```powershell
|
||||
Get-VMSnapshot -VMName "ShopDB-Test-VM"
|
||||
```
|
||||
|
||||
**GUI:**
|
||||
1. Open Hyper-V Manager
|
||||
2. Select VM
|
||||
3. View "Checkpoints" pane at bottom
|
||||
4. See all snapshots in tree view
|
||||
|
||||
### Check VM Status
|
||||
**PowerShell:**
|
||||
```powershell
|
||||
Get-VM | Select-Object Name, State, Uptime
|
||||
```
|
||||
|
||||
**GUI:**
|
||||
1. Open Hyper-V Manager
|
||||
2. View all VMs in center pane
|
||||
3. See Name, State, CPU Usage, etc.
|
||||
|
||||
---
|
||||
|
||||
## Documentation Updates
|
||||
|
||||
The following docs have been updated to clarify admin requirements:
|
||||
|
||||
- `test-mcp-servers.ps1` - Shows INFO instead of WARN for Hyper-V perms
|
||||
- `STATUS.md` - Explains impact (none for MCP)
|
||||
- `HYPER-V-PERMISSIONS.md` - This guide
|
||||
|
||||
**VM-SNAPSHOT-GUIDE.md** still shows PowerShell commands, but mentions GUI alternatives.
|
||||
|
||||
---
|
||||
|
||||
## When Would You Need Admin?
|
||||
|
||||
**You'd only need Hyper-V admin for:**
|
||||
|
||||
1. **Automated snapshot scripts** - Create/restore snapshots from command line
|
||||
2. **VM creation** - Creating new VMs via PowerShell
|
||||
3. **Advanced scripting** - Batch operations on multiple VMs
|
||||
4. **CI/CD integration** - Automated testing workflows that manage VMs
|
||||
|
||||
**For daily development:** GUI + VM MCP is perfectly fine.
|
||||
|
||||
---
|
||||
|
||||
## Claude Code Integration
|
||||
|
||||
**With VM MCP, Claude can:**
|
||||
```
|
||||
✓ Execute commands on VM
|
||||
✓ Copy files to/from VM
|
||||
✓ Read logs from VM
|
||||
✓ Check service status
|
||||
✓ Install/configure software
|
||||
✓ Test agent deployment
|
||||
✓ All via SSH - no Hyper-V perms needed!
|
||||
```
|
||||
|
||||
**Claude cannot (without Hyper-V perms):**
|
||||
```
|
||||
✗ Create snapshots via PowerShell
|
||||
✗ Restore snapshots via script
|
||||
✗ Query VM state via Get-VM
|
||||
|
||||
But you can do these manually in GUI!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Current situation:**
|
||||
- You're not in "Hyper-V Administrators" group
|
||||
- VM MCP works perfectly via SSH
|
||||
- Use Hyper-V Manager GUI for snapshot management
|
||||
- Test script shows warnings but everything is functional
|
||||
|
||||
**Recommendation:**
|
||||
Keep as-is unless you need automated snapshot scripting. For daily development, GUI + SSH is sufficient.
|
||||
|
||||
**If you want group membership:**
|
||||
Request from IT admin to add you to "Hyper-V Administrators" local group.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Without Group | With Group |
|
||||
|------|--------------|------------|
|
||||
| VM MCP (SSH) | ✓ Works | ✓ Works |
|
||||
| Start/stop VM | ✓ GUI | ✓ GUI or PowerShell |
|
||||
| Create snapshot | ✓ GUI | ✓ GUI or PowerShell |
|
||||
| Restore snapshot | ✓ GUI | ✓ GUI or PowerShell |
|
||||
| View VM status | ✓ GUI | ✓ GUI or PowerShell |
|
||||
| Script automation | ✗ Can't | ✓ Can |
|
||||
|
||||
**Bottom line: You can do everything, just not via PowerShell scripts.**
|
||||
|
||||
---
|
||||
|
||||
**No action required - setup is complete and functional!**
|
||||
384
.claude/setup/INDEX-MCP-DOCS.md
Normal file
384
.claude/setup/INDEX-MCP-DOCS.md
Normal file
@@ -0,0 +1,384 @@
|
||||
# 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
|
||||
716
.claude/setup/MCP-COORDINATOR-CONNECTION-GUIDE.md
Normal file
716
.claude/setup/MCP-COORDINATOR-CONNECTION-GUIDE.md
Normal file
@@ -0,0 +1,716 @@
|
||||
# How to Connect to mcp-coordinator
|
||||
|
||||
Complete guide for connecting Claude Code (and other AI tools) to the mcp-coordinator daemon.
|
||||
|
||||
---
|
||||
|
||||
## Connection Methods
|
||||
|
||||
mcp-coordinator supports two connection methods:
|
||||
|
||||
| Method | How It Works | Best For |
|
||||
|--------|--------------|----------|
|
||||
| **HTTP/SSE** | Claude connects via HTTP to daemon at `http://localhost:3100` | Most reliable, recommended |
|
||||
| **stdio** | Claude spawns coordinator process, talks via stdin/stdout | Single session, no shared state |
|
||||
|
||||
**For ShopDB: Use HTTP/SSE** (allows multiple sessions to share one coordinator)
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Your PC │
|
||||
│ │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ Claude Code #1 │ │ Claude Code #2 │ │
|
||||
│ │ (Session 1) │ │ (Session 2) │ │
|
||||
│ └────────┬─────────┘ └────────┬─────────┘ │
|
||||
│ │ │ │
|
||||
│ │ MCP over HTTP │ MCP over HTTP│
|
||||
│ │ (localhost:3100) │ │
|
||||
│ └──────────────┬───────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────▼──────────┐ │
|
||||
│ │ mcp-coordinator │ │
|
||||
│ │ (daemon) │ │
|
||||
│ │ Port: 3100 │ │
|
||||
│ │ MQTT: 1883 │ │
|
||||
│ └───────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Both Claude sessions connect to the SAME daemon = shared state = coordination works!**
|
||||
|
||||
---
|
||||
|
||||
## Setup 1: Local Solo (Just You, Multiple Sessions)
|
||||
|
||||
### Step 1: Start the Coordinator Daemon
|
||||
|
||||
```bash
|
||||
# Install globally first
|
||||
npm install -g mcp-coordinator
|
||||
|
||||
# Initialize config
|
||||
mcp-coordinator init
|
||||
|
||||
# Start daemon (runs in background)
|
||||
mcp-coordinator server start --daemon
|
||||
|
||||
# Verify it's running
|
||||
mcp-coordinator server status
|
||||
# Output: "Server is running (PID: 12345) on http://127.0.0.1:3100"
|
||||
```
|
||||
|
||||
### Step 2: Configure Claude Code
|
||||
|
||||
Add to `.claude/mcp-servers.json`:
|
||||
|
||||
```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"]
|
||||
},
|
||||
"coordinator": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "mcp-coordinator", "mcp"],
|
||||
"env": {
|
||||
"COORDINATOR_URL": "http://127.0.0.1:3100",
|
||||
"COORDINATOR_AGENT_NAME": "session-main",
|
||||
"COORDINATOR_AGENT_ROLE": "developer"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key environment variables:**
|
||||
- `COORDINATOR_URL` - Where to connect (localhost for you)
|
||||
- `COORDINATOR_AGENT_NAME` - Unique name for this session (e.g., "session-main", "session-plugin-work")
|
||||
- `COORDINATOR_AGENT_ROLE` - What this session does (e.g., "developer", "reviewer", "refactor")
|
||||
|
||||
### Step 3: Launch Claude Code Sessions
|
||||
|
||||
**Session 1:**
|
||||
```bash
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
claude
|
||||
|
||||
# Inside Claude:
|
||||
You: "Check coordinator status"
|
||||
Claude: [Calls mcp__coordinator__coordinator_status]
|
||||
Claude: "Coordinator running at http://127.0.0.1:3100. 1 agent registered: session-main (you)."
|
||||
```
|
||||
|
||||
**Session 2 (different terminal):**
|
||||
```bash
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
claude
|
||||
|
||||
# Need different agent name! Edit .claude/mcp-servers.json first:
|
||||
# Change "COORDINATOR_AGENT_NAME": "session-main" to "session-plugin"
|
||||
# Or pass as env var:
|
||||
COORDINATOR_AGENT_NAME=session-plugin claude
|
||||
|
||||
# Inside Claude:
|
||||
You: "Check coordinator status"
|
||||
Claude: [Calls mcp__coordinator__coordinator_status]
|
||||
Claude: "Coordinator running. 2 agents registered: session-main, session-plugin (you)."
|
||||
```
|
||||
|
||||
**Both sessions now see each other!**
|
||||
|
||||
---
|
||||
|
||||
## Setup 2: Team Mode (Multiple Developers)
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────┐ ┌─────────────────────┐
|
||||
│ Dev PC #1 │ │ Dev PC #2 │
|
||||
│ (270015376) │ │ (coworker) │
|
||||
│ │ │ │
|
||||
│ Claude Code │ │ Cursor │
|
||||
│ │ │ │ │ │
|
||||
│ └─────────────┼────────┼───────┘ │
|
||||
│ │ │ │
|
||||
└─────────────────────┘ └─────────────────────┘
|
||||
│ │
|
||||
│ MCP over HTTP │
|
||||
│ (LAN: 192.168.1.100:3100) │
|
||||
└──────────────┬───────────────┘
|
||||
│
|
||||
┌─────────▼──────────┐
|
||||
│ Shared PC or │
|
||||
│ Dev Server │
|
||||
│ │
|
||||
│ mcp-coordinator │
|
||||
│ Host: 0.0.0.0 │
|
||||
│ Port: 3100 │
|
||||
└────────────────────┘
|
||||
```
|
||||
|
||||
### Step 1: Set Up Shared Coordinator
|
||||
|
||||
**On shared machine (or your PC if you're hosting):**
|
||||
|
||||
```bash
|
||||
# Install
|
||||
npm install -g mcp-coordinator
|
||||
|
||||
# Initialize
|
||||
mcp-coordinator init
|
||||
|
||||
# Edit config to allow LAN connections
|
||||
# File: ~/.mcp-coordinator/config.json
|
||||
```
|
||||
|
||||
Edit `~/.mcp-coordinator/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"port": 3100,
|
||||
"host": "0.0.0.0", // ← Changed from 127.0.0.1 to allow LAN
|
||||
"cors": {
|
||||
"enabled": true,
|
||||
"origins": ["*"] // Or specific IPs
|
||||
}
|
||||
},
|
||||
"auth": {
|
||||
"enabled": true, // Recommended for team mode
|
||||
"method": "basic",
|
||||
"users": [
|
||||
{"username": "270015376", "password": "your-password-here"},
|
||||
{"username": "coworker", "password": "their-password"}
|
||||
]
|
||||
},
|
||||
"repo": {
|
||||
"root": "/shared/path/to/shopdb-flask", // Or leave blank
|
||||
"git_cochange_enabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Start daemon:**
|
||||
|
||||
```bash
|
||||
mcp-coordinator server start --daemon
|
||||
|
||||
# Find the IP address
|
||||
# Windows:
|
||||
ipconfig | findstr IPv4
|
||||
# Output: IPv4 Address. . . . . . . . . . . : 192.168.1.100
|
||||
|
||||
# Verify externally accessible:
|
||||
mcp-coordinator server status
|
||||
# Or from another PC: curl http://192.168.1.100:3100/health
|
||||
```
|
||||
|
||||
### Step 2: Connect Each Developer
|
||||
|
||||
**Dev 1 (You) - .claude/mcp-servers.json:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"coordinator": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "mcp-coordinator", "mcp"],
|
||||
"env": {
|
||||
"COORDINATOR_URL": "http://192.168.1.100:3100",
|
||||
"COORDINATOR_AGENT_NAME": "270015376-claude",
|
||||
"COORDINATOR_AGENT_ROLE": "developer",
|
||||
"COORDINATOR_AUTH_USER": "270015376",
|
||||
"COORDINATOR_AUTH_PASS": "your-password-here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Dev 2 (Coworker) - their config:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"coordinator": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "mcp-coordinator", "mcp"],
|
||||
"env": {
|
||||
"COORDINATOR_URL": "http://192.168.1.100:3100",
|
||||
"COORDINATOR_AGENT_NAME": "coworker-cursor",
|
||||
"COORDINATOR_AGENT_ROLE": "developer",
|
||||
"COORDINATOR_AUTH_USER": "coworker",
|
||||
"COORDINATOR_AUTH_PASS": "their-password"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Now both devs' AI tools coordinate through the same daemon!**
|
||||
|
||||
---
|
||||
|
||||
## Connection Flow (Technical Details)
|
||||
|
||||
### What Happens When Claude Starts
|
||||
|
||||
1. **Claude reads** `.claude/mcp-servers.json`
|
||||
2. **Claude spawns** `npx mcp-coordinator mcp` with env vars
|
||||
3. **Coordinator MCP wrapper** connects to daemon at `COORDINATOR_URL`
|
||||
4. **Wrapper registers** agent via HTTP POST to `/api/register_agent`
|
||||
5. **MQTT subscription** opens for real-time events
|
||||
6. **Claude calls** MCP tools, wrapper forwards to daemon via HTTP
|
||||
7. **Daemon responds** via HTTP, wrapper returns to Claude
|
||||
8. **MQTT pushes** events (consultations, status) to wrapper
|
||||
9. **Wrapper surfaces** as MCP tool results to Claude
|
||||
|
||||
### Connection Verification
|
||||
|
||||
**Check if daemon is reachable:**
|
||||
|
||||
```bash
|
||||
# From same machine:
|
||||
curl http://127.0.0.1:3100/health
|
||||
# Expected: {"status":"ok","version":"2.3.0"}
|
||||
|
||||
# From other machine (team mode):
|
||||
curl http://192.168.1.100:3100/health
|
||||
|
||||
# Check MQTT broker:
|
||||
# Install MQTT client first: npm install -g mqtt
|
||||
mqtt sub -h 127.0.0.1 -p 1883 -t 'coordinator/#' -v
|
||||
# Should show: Connected to mqtt://127.0.0.1:1883
|
||||
```
|
||||
|
||||
**Check if Claude is connected:**
|
||||
|
||||
Inside Claude session:
|
||||
|
||||
```
|
||||
You: "Call coordinator_status"
|
||||
|
||||
Claude: [Calls mcp__coordinator__coordinator_status]
|
||||
Claude: "Connected. Daemon version 2.3.0. Agents registered: 1"
|
||||
```
|
||||
|
||||
**View in dashboard:**
|
||||
|
||||
```bash
|
||||
# Open browser
|
||||
mcp-coordinator dashboard
|
||||
# Or manually: http://127.0.0.1:3100/dashboard
|
||||
|
||||
# Should show:
|
||||
# - Active Agents: session-main (online)
|
||||
# - Connection count: 1
|
||||
# - MQTT clients: 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Naming Strategy
|
||||
|
||||
**Important:** Each Claude session needs a UNIQUE `COORDINATOR_AGENT_NAME`.
|
||||
|
||||
### Recommended Naming:
|
||||
|
||||
| Session Purpose | Agent Name | Role |
|
||||
|----------------|------------|------|
|
||||
| Main development | `270015376-main` | `developer` |
|
||||
| Plugin work | `270015376-plugins` | `developer` |
|
||||
| Code review | `270015376-review` | `reviewer` |
|
||||
| Refactoring | `270015376-refactor` | `refactor` |
|
||||
| Testing | `270015376-test` | `tester` |
|
||||
|
||||
### Dynamic Naming:
|
||||
|
||||
**Option 1: Per-project config**
|
||||
|
||||
Create `.claude/mcp-servers.json` in each project with unique names:
|
||||
|
||||
```bash
|
||||
# In flask-shopdb/.claude/mcp-servers.json
|
||||
"COORDINATOR_AGENT_NAME": "270015376-shopdb-main"
|
||||
|
||||
# In another-project/.claude/mcp-servers.json
|
||||
"COORDINATOR_AGENT_NAME": "270015376-otherproject-main"
|
||||
```
|
||||
|
||||
**Option 2: Environment variable override**
|
||||
|
||||
```bash
|
||||
# Launch with custom name
|
||||
COORDINATOR_AGENT_NAME=270015376-bugfix-session claude
|
||||
|
||||
# Or in Windows:
|
||||
set COORDINATOR_AGENT_NAME=270015376-bugfix-session
|
||||
claude
|
||||
```
|
||||
|
||||
**Option 3: Auto-generate from git branch**
|
||||
|
||||
Add to `.claude/mcp-servers.json`:
|
||||
|
||||
```json
|
||||
"coordinator": {
|
||||
"command": "bash",
|
||||
"args": [
|
||||
"-c",
|
||||
"export COORDINATOR_AGENT_NAME=\"270015376-$(git branch --show-current)\"; npx -y mcp-coordinator mcp"
|
||||
],
|
||||
"env": {
|
||||
"COORDINATOR_URL": "http://127.0.0.1:3100"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now agent name is: `270015376-wj` or `270015376-wilm` based on branch!
|
||||
|
||||
---
|
||||
|
||||
## Multiple Sessions Example
|
||||
|
||||
**Scenario:** You're working on two features simultaneously.
|
||||
|
||||
### Session 1: Main Work (Operator Reports)
|
||||
|
||||
```bash
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
COORDINATOR_AGENT_NAME=270015376-operator-reports claude
|
||||
|
||||
# Inside Claude:
|
||||
You: "Fix operator report email alerts"
|
||||
Claude: [register_agent as "270015376-operator-reports"]
|
||||
Claude: [announce_work for plugins/endpoints/api/routes.py]
|
||||
Claude: "Registered. No conflicts. Proceeding..."
|
||||
```
|
||||
|
||||
### Session 2: Plugin Work (Fleet Alerts)
|
||||
|
||||
```bash
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
COORDINATOR_AGENT_NAME=270015376-fleet-alerts claude
|
||||
|
||||
# Inside Claude:
|
||||
You: "Add scope filtering to fleet alerts"
|
||||
Claude: [register_agent as "270015376-fleet-alerts"]
|
||||
Claude: [announce_work for plugins/notifications/models/notification.py]
|
||||
Claude: "Registered. No conflicts. Proceeding..."
|
||||
```
|
||||
|
||||
### Dashboard View:
|
||||
|
||||
http://127.0.0.1:3100/dashboard shows:
|
||||
|
||||
```
|
||||
Active Agents (2)
|
||||
├─ 270015376-operator-reports
|
||||
│ └─ Files: plugins/endpoints/api/routes.py
|
||||
│ └─ Status: Working
|
||||
│ └─ Since: 2 minutes ago
|
||||
│
|
||||
└─ 270015376-fleet-alerts
|
||||
└─ Files: plugins/notifications/models/notification.py
|
||||
└─ Status: Working
|
||||
└─ Since: 1 minute ago
|
||||
|
||||
Consultations (0)
|
||||
No conflicts detected
|
||||
```
|
||||
|
||||
### If They Conflict:
|
||||
|
||||
**Session 2 tries to edit routes.py:**
|
||||
|
||||
```
|
||||
You: "Also update the route handler"
|
||||
Claude: [announce_work for plugins/endpoints/api/routes.py]
|
||||
Claude: "⚠️ Conflict detected!"
|
||||
Claude: "Agent '270015376-operator-reports' is currently modifying routes.py"
|
||||
Claude: [post_to_thread]
|
||||
Claude: "Consulting... Opening thread #1"
|
||||
|
||||
# Session 1 sees notification via MQTT
|
||||
Claude (Session 1): "📢 New consultation: Agent '270015376-fleet-alerts' also needs routes.py"
|
||||
Claude (Session 1): [Reads thread]
|
||||
Claude (Session 1): [post_to_thread] "I'm working on _send_operator_report_alert function. What do you need?"
|
||||
|
||||
# Session 2 sees response
|
||||
Claude (Session 2): [Reads thread]
|
||||
Claude (Session 2): [post_to_thread] "I need to update the route registration. Different concern. Can proceed in parallel."
|
||||
|
||||
# Both agree
|
||||
Claude (Session 1): [Approves in thread]
|
||||
Claude (Session 2): [Approves in thread]
|
||||
# Coordinator auto-closes thread as "resolved"
|
||||
|
||||
# Both proceed with edits
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Connection Troubleshooting
|
||||
|
||||
### Problem: "Connection refused"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
Error: connect ECONNREFUSED 127.0.0.1:3100
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Check daemon is running:
|
||||
```bash
|
||||
mcp-coordinator server status
|
||||
```
|
||||
|
||||
2. If not running, start it:
|
||||
```bash
|
||||
mcp-coordinator server start --daemon
|
||||
```
|
||||
|
||||
3. Check port:
|
||||
```bash
|
||||
# Windows:
|
||||
netstat -ano | findstr 3100
|
||||
# Should show: TCP 127.0.0.1:3100 ... LISTENING
|
||||
```
|
||||
|
||||
4. Check firewall (team mode):
|
||||
```bash
|
||||
# Windows: Allow port 3100 inbound
|
||||
netsh advfirewall firewall add rule name="mcp-coordinator" dir=in action=allow protocol=TCP localport=3100
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: "Agent already registered"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
Error: Agent name "270015376-main" is already registered
|
||||
```
|
||||
|
||||
**Cause:** You started two Claude sessions with the same name.
|
||||
|
||||
**Solution:** Use different names:
|
||||
|
||||
```bash
|
||||
# Session 1
|
||||
COORDINATOR_AGENT_NAME=270015376-main claude
|
||||
|
||||
# Session 2
|
||||
COORDINATOR_AGENT_NAME=270015376-secondary claude
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: "Unauthorized"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
Error: 401 Unauthorized
|
||||
```
|
||||
|
||||
**Cause:** Team mode has auth enabled, but you didn't provide credentials.
|
||||
|
||||
**Solution:** Add to env vars:
|
||||
|
||||
```json
|
||||
"env": {
|
||||
"COORDINATOR_URL": "http://192.168.1.100:3100",
|
||||
"COORDINATOR_AUTH_USER": "270015376",
|
||||
"COORDINATOR_AUTH_PASS": "your-password"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: "MCP tools not showing up"
|
||||
|
||||
**Symptoms:** Claude doesn't have coordinator tools available.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Restart Claude Code completely
|
||||
2. Check .mcp.json is in right location:
|
||||
```bash
|
||||
ls .claude/mcp-servers.json
|
||||
```
|
||||
|
||||
3. Verify JSON syntax:
|
||||
```bash
|
||||
cat .claude/mcp-servers.json | jq .
|
||||
# Should parse without error
|
||||
```
|
||||
|
||||
4. Check Claude Code MCP settings:
|
||||
```bash
|
||||
# In Claude Code settings (if GUI)
|
||||
# Or check logs: ~/.claude/logs/
|
||||
```
|
||||
|
||||
5. Test connection manually:
|
||||
```bash
|
||||
npx -y mcp-coordinator mcp
|
||||
# Should connect and show MCP server ready
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Connection Best Practices
|
||||
|
||||
### 1. Keep Daemon Running
|
||||
|
||||
**Start on boot (Windows):**
|
||||
|
||||
Create `startup-coordinator.bat`:
|
||||
|
||||
```bat
|
||||
@echo off
|
||||
mcp-coordinator server start --daemon
|
||||
```
|
||||
|
||||
Add to: `shell:startup`
|
||||
|
||||
**Or use Task Scheduler:**
|
||||
|
||||
```xml
|
||||
<Task version="1.2">
|
||||
<Actions>
|
||||
<Exec>
|
||||
<Command>mcp-coordinator</Command>
|
||||
<Arguments>server start --daemon</Arguments>
|
||||
</Exec>
|
||||
</Actions>
|
||||
<Triggers>
|
||||
<LogonTrigger />
|
||||
</Triggers>
|
||||
</Task>
|
||||
```
|
||||
|
||||
### 2. Monitor Daemon Health
|
||||
|
||||
**Check periodically:**
|
||||
|
||||
```bash
|
||||
# Status
|
||||
mcp-coordinator server status
|
||||
|
||||
# Logs
|
||||
mcp-coordinator server logs --tail 50
|
||||
|
||||
# Restart if crashed
|
||||
mcp-coordinator server restart
|
||||
```
|
||||
|
||||
**Set up health check (team mode):**
|
||||
|
||||
```bash
|
||||
# Cron job (Linux) or Task Scheduler (Windows)
|
||||
# Every 5 minutes:
|
||||
curl http://127.0.0.1:3100/health || mcp-coordinator server start --daemon
|
||||
```
|
||||
|
||||
### 3. Use Descriptive Agent Names
|
||||
|
||||
**Good:**
|
||||
- `270015376-operator-reports`
|
||||
- `270015376-plugin-refactor`
|
||||
- `jdoe-bugfix-auth`
|
||||
|
||||
**Bad:**
|
||||
- `agent1`
|
||||
- `claude`
|
||||
- `test`
|
||||
|
||||
**Why:** Dashboard shows names. You want to see "who's working on what" at a glance.
|
||||
|
||||
### 4. Set Agent Roles
|
||||
|
||||
```json
|
||||
"COORDINATOR_AGENT_ROLE": "developer" // or:
|
||||
"COORDINATOR_AGENT_ROLE": "reviewer" // Code review session
|
||||
"COORDINATOR_AGENT_ROLE": "refactor" // Refactoring session
|
||||
"COORDINATOR_AGENT_ROLE": "tester" // Test writing session
|
||||
"COORDINATOR_AGENT_ROLE": "debugger" // Bug hunting session
|
||||
```
|
||||
|
||||
**Why:** Dashboard can filter/group by role.
|
||||
|
||||
---
|
||||
|
||||
## Connection Summary
|
||||
|
||||
### Local Solo Mode:
|
||||
|
||||
1. Start daemon: `mcp-coordinator server start --daemon`
|
||||
2. Add to `.claude/mcp-servers.json` with `COORDINATOR_URL=http://127.0.0.1:3100`
|
||||
3. Launch Claude sessions with unique `COORDINATOR_AGENT_NAME`
|
||||
4. All sessions connect to same daemon = coordination works
|
||||
|
||||
### Team Mode:
|
||||
|
||||
1. Start daemon on shared machine with `host: "0.0.0.0"`
|
||||
2. Open firewall port 3100
|
||||
3. Each dev adds coordinator to their MCP config with `COORDINATOR_URL=http://SHARED_IP:3100`
|
||||
4. Each dev uses unique agent name (include username)
|
||||
5. Enable auth in coordinator config
|
||||
6. All devs' AIs coordinate through shared daemon
|
||||
|
||||
### Key Points:
|
||||
|
||||
- **One daemon, many sessions** = shared state
|
||||
- **Unique agent names** = identity tracking
|
||||
- **HTTP/SSE transport** = reliable, scalable
|
||||
- **MQTT for push** = real-time updates
|
||||
- **Dashboard** = visibility
|
||||
|
||||
---
|
||||
|
||||
## Next: Testing the Connection
|
||||
|
||||
Once connected, test with:
|
||||
|
||||
```
|
||||
You: "Check coordinator status"
|
||||
Claude: [Calls coordinator_status]
|
||||
|
||||
You: "List active agents"
|
||||
Claude: [Calls list_agents]
|
||||
|
||||
You: "Announce I'm working on routes.py"
|
||||
Claude: [Calls announce_work]
|
||||
|
||||
You: "Show any consultations"
|
||||
Claude: [Calls list_consultations]
|
||||
```
|
||||
|
||||
If all work, you're fully connected!
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Connection docs:** https://swoofer.github.io/mcp-coordinator/connection.html
|
||||
- **MCP config examples:** https://github.com/swoofer/mcp-coordinator/tree/main/examples
|
||||
- **Troubleshooting:** https://swoofer.github.io/mcp-coordinator/troubleshooting.html
|
||||
723
.claude/setup/MCP-COORDINATOR-EVALUATION.md
Normal file
723
.claude/setup/MCP-COORDINATOR-EVALUATION.md
Normal file
@@ -0,0 +1,723 @@
|
||||
# MCP Coordinator Tools for Multi-Agent Collaboration
|
||||
|
||||
Research findings for coordinating multiple AI agents working on ShopDB simultaneously.
|
||||
|
||||
---
|
||||
|
||||
## 🏆 Top Recommendation: mcp-coordinator
|
||||
|
||||
**By:** Maxime Gagnon (swoofer)
|
||||
**Status:** Production-ready (v2.3.0, 2500+ tests)
|
||||
**npm:** `mcp-coordinator`
|
||||
**GitHub:** https://github.com/swoofer/mcp-coordinator
|
||||
**Docs:** https://swoofer.github.io/mcp-coordinator
|
||||
|
||||
### What It Does
|
||||
|
||||
**Stop your AI coding agents from overwriting each other's work.**
|
||||
|
||||
One daemon. Every Claude Code / Cursor / Cline / Aider session on the same repo announces what it's about to touch, sees what the others are doing, and resolves conflicts BEFORE a line of code is written.
|
||||
|
||||
### Perfect For ShopDB Because:
|
||||
|
||||
1. **Works with Claude Code** - No need to switch tools
|
||||
2. **Zero config local mode** - Just for you (solo dev running 2-3 sessions)
|
||||
3. **Team mode ready** - When your coworkers start using AI
|
||||
4. **Air-gap compatible** - Runs locally, no internet needed (ADR-004)
|
||||
5. **File-level conflict detection** - Prevents two AIs editing same files
|
||||
|
||||
### How It Works
|
||||
|
||||
```
|
||||
Claude Session 1 Claude Session 2
|
||||
| |
|
||||
| announce_work | announce_work
|
||||
v v
|
||||
+--------------+ +--------------+
|
||||
| MCP client | <-- MQTT -->| MCP client |
|
||||
| (Claude) | push-based | (Claude) |
|
||||
+--------------+ +--------------+
|
||||
| MCP HTTP / SSE |
|
||||
+---------------+---------------+
|
||||
|
|
||||
+----------v----------+
|
||||
| mcp-coordinator |
|
||||
| 26 MCP tools |
|
||||
| SQLite registry |
|
||||
| MQTT broker |
|
||||
| Dashboard (3100) |
|
||||
+---------------------+
|
||||
```
|
||||
|
||||
### The Consultation Cycle
|
||||
|
||||
**Before any code is written:**
|
||||
|
||||
1. **Announce** - "I'm about to edit plugins/endpoints/api/routes.py"
|
||||
2. **Detect** - Coordinator checks: "Is anyone else working on this?"
|
||||
3. **Consult** - If conflict detected, opens consultation thread
|
||||
4. **Resolve** - AIs coordinate approach, then proceed
|
||||
|
||||
**Impact Scoring:**
|
||||
|
||||
| Score | Meaning | Action |
|
||||
|-------|---------|--------|
|
||||
| 100 | Direct conflict (same file) | Thread opened, consultation required |
|
||||
| 80 | Dependency conflict (you need their file) | Thread opened |
|
||||
| 30-89 | Gray zone (same module) | Auto-resolved, introspection recommended |
|
||||
| <30 | No conflict | Proceed immediately |
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# 1. Install globally
|
||||
npm install -g mcp-coordinator
|
||||
|
||||
# 2. Initialize (creates config, prints MCP snippet)
|
||||
mcp-coordinator init
|
||||
|
||||
# 3. Start daemon
|
||||
mcp-coordinator server start --daemon
|
||||
|
||||
# 4. Verify
|
||||
mcp-coordinator server status
|
||||
mcp-coordinator dashboard # http://localhost:3100/dashboard
|
||||
```
|
||||
|
||||
### Configuration (.mcp-coordinator/config.json)
|
||||
|
||||
Automatically created, but you can customize:
|
||||
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"port": 3100,
|
||||
"host": "127.0.0.1", // Local only (or "0.0.0.0" for LAN)
|
||||
"mqtt": {
|
||||
"enabled": true,
|
||||
"port": 1883
|
||||
}
|
||||
},
|
||||
"coordination": {
|
||||
"consultation_timeout_ms": 300000, // 5 min
|
||||
"auto_resolve_gray_zone": true
|
||||
},
|
||||
"repo": {
|
||||
"root": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb",
|
||||
"git_cochange_enabled": true // Uses git history for smarter detection
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Add to Claude Code (.claude/mcp-servers.json)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gortex": { ... },
|
||||
"mysql": { ... },
|
||||
"browser": { ... },
|
||||
"coordinator": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "mcp-coordinator", "mcp"],
|
||||
"env": {
|
||||
"COORDINATOR_URL": "http://127.0.0.1:3100"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### MCP Tools Exposed (26 total)
|
||||
|
||||
**Core coordination:**
|
||||
- `register_agent(name, role, files)` - Register your session
|
||||
- `announce_work(target_files, depends_on_files, target_modules)` - Before coding
|
||||
- `coordinator_status()` - See all active agents
|
||||
- `list_consultations()` - See open conflicts
|
||||
|
||||
**Consultation threads:**
|
||||
- `post_to_thread(consultation_id, message)` - Discuss approach
|
||||
- `close_consultation(consultation_id, resolution)` - Mark resolved
|
||||
- `claim_consultation(consultation_id)` - Take ownership
|
||||
|
||||
**Work tracking:**
|
||||
- `post_progress(task, status, details)` - Update what you're doing
|
||||
- `list_agent_progress()` - See what others are doing
|
||||
|
||||
**File tracking:**
|
||||
- `declare_file_intent(file, operation)` - "I'm about to modify X"
|
||||
- `release_file_intent(file)` - "I'm done with X"
|
||||
|
||||
Full list: https://swoofer.github.io/mcp-coordinator/tools.html
|
||||
|
||||
### Dashboard (http://localhost:3100/dashboard)
|
||||
|
||||
Real-time view of:
|
||||
- Active agents (who's connected)
|
||||
- Open consultations (current conflicts)
|
||||
- Recent announcements (what's being worked on)
|
||||
- Agent activity timeline
|
||||
- File conflict map
|
||||
|
||||
### Usage Example
|
||||
|
||||
**Your Claude session:**
|
||||
```
|
||||
You: "Fix the operator report email alerts"
|
||||
|
||||
Claude: [Calls register_agent]
|
||||
Claude: [Calls announce_work with target_files: ["plugins/endpoints/api/routes.py"]]
|
||||
Claude: "No conflicts detected. Proceeding..."
|
||||
Claude: [Makes changes]
|
||||
Claude: [Commits]
|
||||
```
|
||||
|
||||
**If conflict detected:**
|
||||
```
|
||||
You: "Fix the operator report email alerts"
|
||||
|
||||
Claude: [Calls register_agent]
|
||||
Claude: [Calls announce_work]
|
||||
Claude: "⚠️ Conflict detected! jdoe's AI is also editing routes.py."
|
||||
Claude: [Calls post_to_thread]
|
||||
Claude: "Consulting with other agent... They're adding fleet alerts, I'm fixing operator reports. Different functions."
|
||||
Claude: [Waits for response]
|
||||
Claude: "Agreed to work on different sections. Proceeding..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Alternative: essaim (Multi-Agent Orchestrator)
|
||||
|
||||
**By:** Same author (Maxime Gagnon / swoofer)
|
||||
**npm:** `essaim`
|
||||
**GitHub:** https://github.com/swoofer/essaim
|
||||
|
||||
### What It Does
|
||||
|
||||
Spawn N coordinated Claude Code agents with presets. Orchestrator manages them.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Launch 3 coordinated agents on bug hunt
|
||||
essaim run swarm --agents 3 -p ~/flask-shopdb
|
||||
|
||||
# They coordinate via mcp-coordinator automatically
|
||||
# Work-stealing: discover issues -> share pool -> agents claim tasks
|
||||
```
|
||||
|
||||
### When To Use essaim vs mcp-coordinator
|
||||
|
||||
| Use Case | Tool | Why |
|
||||
|----------|------|-----|
|
||||
| **You + 2-3 manual Claude sessions** | mcp-coordinator only | Simple, you control each session |
|
||||
| **Team (multiple devs with AIs)** | mcp-coordinator only | Each dev runs their own Claude, coordinator prevents conflicts |
|
||||
| **Automated multi-agent swarm** | essaim + mcp-coordinator | Orchestrator spawns/manages agents, coordinator prevents conflicts |
|
||||
|
||||
**For ShopDB:** Start with mcp-coordinator only. essaim is for when you want to spawn 5+ agents automatically.
|
||||
|
||||
---
|
||||
|
||||
## Other Options Found
|
||||
|
||||
### 1. momo-agentic
|
||||
**Purpose:** Agentic bot framework (Bun/Node.js)
|
||||
**Verdict:** Too generic, not focused on coordination
|
||||
|
||||
### 2. agent-install
|
||||
**Purpose:** Install SKILL.md and AGENTS.md files
|
||||
**Verdict:** Just documentation installer, not coordination
|
||||
|
||||
### 3. @langchain/mcp-adapters
|
||||
**Purpose:** LangChain.js adapters for MCP
|
||||
**Verdict:** Wrong use case (for building tools, not coordination)
|
||||
|
||||
### 4. @azure-devops/mcp
|
||||
**Purpose:** Azure DevOps MCP server
|
||||
**Verdict:** Different domain (CI/CD, not multi-agent)
|
||||
|
||||
**None of these solve the multi-AI coordination problem.**
|
||||
|
||||
---
|
||||
|
||||
## Recommendation for ShopDB
|
||||
|
||||
### Phase 1: Solo Developer (You) - NOW
|
||||
|
||||
**Install:** `mcp-coordinator` only
|
||||
|
||||
**Why:**
|
||||
- You run 2-3 Claude Code sessions sometimes
|
||||
- Prevents "wait, I already changed that file in the other session"
|
||||
- Zero overhead (local daemon, ~5 MB RAM)
|
||||
- Dashboard shows what each session is doing
|
||||
|
||||
**Setup time:** 5 minutes
|
||||
|
||||
**Expected benefit:**
|
||||
- No more conflicts between your own sessions
|
||||
- Clear visibility into "what is each AI working on"
|
||||
- File-level locking prevents overwrites
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Team Expansion - LATER
|
||||
|
||||
**When:** Your coworkers start using Claude Code / Cursor / Aider
|
||||
|
||||
**Add:**
|
||||
- Shared mcp-coordinator server on LAN
|
||||
- Each dev connects to same coordinator
|
||||
- Real-time conflict detection across team
|
||||
|
||||
**Config change:**
|
||||
```json
|
||||
// In coordinator config
|
||||
"server": {
|
||||
"host": "0.0.0.0", // Listen on LAN
|
||||
"port": 3100
|
||||
}
|
||||
|
||||
// In each dev's .claude/mcp-servers.json
|
||||
"coordinator": {
|
||||
"env": {
|
||||
"COORDINATOR_URL": "http://SHARED_SERVER_IP:3100"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected benefit:**
|
||||
- Team-wide visibility
|
||||
- Prevents two devs' AIs from conflicting
|
||||
- Dashboard shows all team activity
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Advanced Automation - FUTURE
|
||||
|
||||
**When:** You want automated multi-agent workflows
|
||||
|
||||
**Add:** `essaim` for orchestration
|
||||
|
||||
**Use cases:**
|
||||
- "Spawn 5 agents to refactor all plugins"
|
||||
- "Bug hunt: 3 agents discover, 2 agents fix"
|
||||
- "Security scan: agent per plugin, coordinated fixes"
|
||||
|
||||
---
|
||||
|
||||
## Comparison to Your Manual Solutions
|
||||
|
||||
| Feature | Manual (memory files) | mcp-coordinator | Benefit |
|
||||
|---------|----------------------|-----------------|---------|
|
||||
| **Conflict detection** | Manual check | Automatic before coding | Prevents overwrites |
|
||||
| **Real-time visibility** | Git branch list | Live dashboard | See activity now |
|
||||
| **File locking** | None | Automatic announce/claim | No simultaneous edits |
|
||||
| **Team coordination** | Slack messages | Built-in consultation | Structured discussion |
|
||||
| **Overhead** | Update files manually | Automatic via MCP | Zero friction |
|
||||
| **Audit trail** | Session notes | SQLite + dashboard | Complete history |
|
||||
|
||||
**mcp-coordinator automates everything you were planning to build manually.**
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### For Air-Gapped Environment (ADR-004)
|
||||
|
||||
✅ **Works perfectly:**
|
||||
- Runs entirely locally (no internet required)
|
||||
- SQLite database (no external DB)
|
||||
- MQTT broker embedded (no external service)
|
||||
- Dashboard is local HTTP (no cloud)
|
||||
|
||||
✅ **Team mode on LAN:**
|
||||
- Runs on internal network only
|
||||
- No external connections
|
||||
- All data stays in your environment
|
||||
|
||||
### Authentication
|
||||
|
||||
**Local mode:** None needed (only you)
|
||||
|
||||
**Team mode options:**
|
||||
- Basic auth (username/password)
|
||||
- OAuth 2.1 (GitHub, Google, Azure AD, Custom IdP)
|
||||
- JWT tokens
|
||||
- Per-org allowlists
|
||||
|
||||
For ShopDB: Basic auth is fine (internal network, trusted team).
|
||||
|
||||
---
|
||||
|
||||
## Installation Guide for ShopDB
|
||||
|
||||
### Step 1: Install mcp-coordinator
|
||||
|
||||
```bash
|
||||
# Global install (recommended)
|
||||
npm install -g mcp-coordinator
|
||||
|
||||
# Or via winget (Windows)
|
||||
# (Not available yet, use npm)
|
||||
```
|
||||
|
||||
### Step 2: Initialize
|
||||
|
||||
```bash
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
|
||||
# This creates ~/.mcp-coordinator/ with config
|
||||
mcp-coordinator init
|
||||
|
||||
# Optional: Auto-write to project .mcp.json
|
||||
mcp-coordinator init --write-mcp-config .
|
||||
```
|
||||
|
||||
### Step 3: Configure for ShopDB
|
||||
|
||||
Edit `~/.mcp-coordinator/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"port": 3100,
|
||||
"host": "127.0.0.1"
|
||||
},
|
||||
"repo": {
|
||||
"root": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb",
|
||||
"git_cochange_enabled": true
|
||||
},
|
||||
"coordination": {
|
||||
"consultation_timeout_ms": 300000,
|
||||
"auto_resolve_gray_zone": true,
|
||||
"file_patterns": {
|
||||
"critical": [
|
||||
"shopdb/core/**/*.py",
|
||||
"plugins/*/migrations/**/*.py"
|
||||
],
|
||||
"ignore": [
|
||||
"*.log",
|
||||
"*.pyc",
|
||||
"__pycache__/**",
|
||||
"frontend/dist/**"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Add to Claude Code MCP Config
|
||||
|
||||
Edit `.claude/mcp-servers.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gortex": { ... },
|
||||
"mysql": { ... },
|
||||
"browser": { ... },
|
||||
"coordinator": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "mcp-coordinator", "mcp"],
|
||||
"env": {
|
||||
"COORDINATOR_URL": "http://127.0.0.1:3100",
|
||||
"COORDINATOR_AGENT_NAME": "270015376-main",
|
||||
"COORDINATOR_AGENT_ROLE": "developer"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Start Coordinator
|
||||
|
||||
```bash
|
||||
# Start as daemon (background)
|
||||
mcp-coordinator server start --daemon
|
||||
|
||||
# Or run in foreground (for debugging)
|
||||
mcp-coordinator server start
|
||||
|
||||
# Check status
|
||||
mcp-coordinator server status
|
||||
|
||||
# View logs
|
||||
mcp-coordinator server logs
|
||||
|
||||
# Stop
|
||||
mcp-coordinator server stop
|
||||
```
|
||||
|
||||
### Step 6: Verify in Claude Code
|
||||
|
||||
Restart Claude Code, then:
|
||||
|
||||
```
|
||||
You: "Check coordinator status"
|
||||
|
||||
Claude: [Calls coordinator_status]
|
||||
Claude: "Coordinator running. 1 agent registered (you). No active consultations."
|
||||
```
|
||||
|
||||
### Step 7: Test Conflict Detection
|
||||
|
||||
**Open two Claude Code windows on same project:**
|
||||
|
||||
**Window 1:**
|
||||
```
|
||||
You: "Edit the operator report function in routes.py"
|
||||
|
||||
Claude: [Calls announce_work for plugins/endpoints/api/routes.py]
|
||||
Claude: "Registered intent to modify routes.py. No conflicts. Proceeding..."
|
||||
```
|
||||
|
||||
**Window 2 (while Window 1 is working):**
|
||||
```
|
||||
You: "Fix the fleet alert function in routes.py"
|
||||
|
||||
Claude: [Calls announce_work for plugins/endpoints/api/routes.py]
|
||||
Claude: "⚠️ Conflict detected! Another session (270015376-main) is editing routes.py."
|
||||
Claude: [Opens consultation thread]
|
||||
Claude: "Consulting... Other session is working on _send_operator_report_alert. I need _alert_targets_endpoint. Different functions, can proceed in parallel."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dashboard Usage
|
||||
|
||||
Open: http://localhost:3100/dashboard
|
||||
|
||||
**Panels:**
|
||||
- **Active Agents** - All connected Claude sessions
|
||||
- **Live Consultations** - Current conflicts being resolved
|
||||
- **Recent Announcements** - What's being worked on
|
||||
- **File Conflict Map** - Which files have contention
|
||||
- **Agent Timeline** - Activity history
|
||||
|
||||
**Perfect for:**
|
||||
- "What is my other Claude session doing?"
|
||||
- "Is anyone else touching this file?"
|
||||
- "What did we work on today?"
|
||||
|
||||
---
|
||||
|
||||
## Expected Token Savings
|
||||
|
||||
**Without coordinator:**
|
||||
- Manual conflict resolution: 5-10K tokens
|
||||
- Explaining what other session did: 3-5K tokens
|
||||
- Merge conflict resolution: 10-20K tokens
|
||||
|
||||
**With coordinator:**
|
||||
- Automatic announce: ~500 tokens
|
||||
- Consultation thread: 1-2K tokens (only when needed)
|
||||
- No merge conflicts: 0 tokens
|
||||
|
||||
**Net savings:** 10-30K tokens per conflict avoided
|
||||
|
||||
**Plus:** Time savings (no manual coordination)
|
||||
|
||||
---
|
||||
|
||||
## Integration with Existing Tools
|
||||
|
||||
### Works With:
|
||||
|
||||
| Tool | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| **Claude Code** | ✅ Perfect | Native MCP support |
|
||||
| **Gortex** | ✅ Compatible | Both are MCP servers, no conflict |
|
||||
| **MySQL MCP** | ✅ Compatible | Separate concern |
|
||||
| **Browser MCP** | ✅ Compatible | Separate concern |
|
||||
| **GitHub MCP** | ✅ Compatible | Can coordinate PR creation |
|
||||
|
||||
### Workflow Example:
|
||||
|
||||
```
|
||||
You: "Review all plugins for ADR compliance and create PRs for fixes"
|
||||
|
||||
Claude (Session 1): [Announces] "Reviewing plugins/notifications/"
|
||||
Claude (Session 2): [Announces] "Reviewing plugins/endpoints/"
|
||||
→ No conflict, both proceed
|
||||
|
||||
Claude (Session 1): [Gortex] Finds code patterns
|
||||
Claude (Session 1): [Coordinator] Announces intent to fix
|
||||
Claude (Session 1): [Edit] Makes changes
|
||||
Claude (Session 1): [GitHub MCP] Creates PR
|
||||
|
||||
Claude (Session 2): [Gortex] Finds code patterns
|
||||
Claude (Session 2): [Coordinator] Announces intent to fix
|
||||
Claude (Session 2): [Sees Session 1's PR via GitHub MCP]
|
||||
Claude (Session 2): "Coordinating with other PR to avoid conflicts..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cost Analysis
|
||||
|
||||
### mcp-coordinator
|
||||
|
||||
**License:** MIT (Free)
|
||||
**Hosting:** Self-hosted (your machine)
|
||||
**Resources:** ~5-10 MB RAM, negligible CPU
|
||||
**Maintenance:** None (daemon runs in background)
|
||||
|
||||
**Total cost:** $0
|
||||
|
||||
### Alternative: Building Your Own
|
||||
|
||||
Based on your `.claude/AI-COLLABORATION.md` proposal:
|
||||
|
||||
**Development time:**
|
||||
- Basic coordinator: 2-4 hours
|
||||
- Conflict detection: 4-8 hours
|
||||
- MQTT/real-time: 4-8 hours
|
||||
- Dashboard: 8-16 hours
|
||||
- Testing: 4-8 hours
|
||||
|
||||
**Total:** 22-44 hours
|
||||
|
||||
**At $100/hour equivalent:** $2,200-$4,400 in time
|
||||
|
||||
**mcp-coordinator saves you $2,200-$4,400 in development time.**
|
||||
|
||||
---
|
||||
|
||||
## Risks and Limitations
|
||||
|
||||
### Limitations:
|
||||
|
||||
1. **Requires Node.js 22+** - You have it
|
||||
2. **Local daemon must run** - One more process (but tiny)
|
||||
3. **Not magic** - AIs still need to cooperate (they do via MCP tools)
|
||||
4. **Learning curve** - ~30 min to understand consultation flow
|
||||
|
||||
### Risks:
|
||||
|
||||
1. **Daemon crashes** - Agents still work, just no coordination (graceful degradation)
|
||||
2. **Port conflict (3100)** - Configurable
|
||||
3. **Team adoption** - Need everyone to install (but worth it)
|
||||
|
||||
### Mitigations:
|
||||
|
||||
1. Daemon is stable (2500+ tests, production-ready)
|
||||
2. Configure different port if needed
|
||||
3. Show team the dashboard - adoption is easy when they see value
|
||||
|
||||
---
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
### Should You Install mcp-coordinator?
|
||||
|
||||
| Question | Answer | Points |
|
||||
|----------|--------|--------|
|
||||
| Do you run 2+ Claude sessions on same repo? | **Yes** | +3 |
|
||||
| Have you had conflicts between sessions? | **Likely** | +2 |
|
||||
| Will team use AI tools? | **Eventually** | +2 |
|
||||
| Want dashboard of AI activity? | **Yes** | +1 |
|
||||
| Have 5 minutes to set up? | **Yes** | +1 |
|
||||
| Willing to run background daemon? | **Yes** | +1 |
|
||||
|
||||
**Your score: 10/10**
|
||||
|
||||
**Recommendation:** Install it NOW.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate (Today):
|
||||
|
||||
1. ✅ Read this evaluation
|
||||
2. ⏳ Install mcp-coordinator: `npm install -g mcp-coordinator`
|
||||
3. ⏳ Run init: `mcp-coordinator init`
|
||||
4. ⏳ Start daemon: `mcp-coordinator server start --daemon`
|
||||
5. ⏳ Add to `.claude/mcp-servers.json`
|
||||
6. ⏳ Restart Claude Code
|
||||
7. ⏳ Test: `coordinator_status()` in Claude
|
||||
|
||||
**Time:** 5-10 minutes
|
||||
|
||||
### This Week:
|
||||
|
||||
8. Use it for a few days
|
||||
9. Check dashboard daily
|
||||
10. Note any conflicts it catches
|
||||
11. Share with team if they're using AI
|
||||
|
||||
### Next Sprint:
|
||||
|
||||
12. Team meeting: demo the dashboard
|
||||
13. Install on each dev's machine
|
||||
14. Set up shared coordinator (if team adopted AI)
|
||||
|
||||
---
|
||||
|
||||
## Questions Answered
|
||||
|
||||
**Q: Does this work with air-gap deployment?**
|
||||
A: Yes, fully local, no internet required.
|
||||
|
||||
**Q: Does this slow down Claude?**
|
||||
A: No, announce_work takes ~100ms. Consultation only on conflicts.
|
||||
|
||||
**Q: What if daemon is down?**
|
||||
A: Claude still works, just no coordination. Graceful degradation.
|
||||
|
||||
**Q: Can I use with my existing MCP servers?**
|
||||
A: Yes, coordinator is just another MCP server. No conflicts.
|
||||
|
||||
**Q: What about secrets in coordination?**
|
||||
A: All local, no external transmission. Team mode stays on your LAN.
|
||||
|
||||
**Q: How does this differ from git branches?**
|
||||
A: Prevents conflicts BEFORE committing. Git is after-the-fact.
|
||||
|
||||
**Q: Can I turn it off?**
|
||||
A: Yes, just stop daemon. Or remove from .mcp.json. No lock-in.
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
**mcp-coordinator is production-ready, actively maintained, and solves EXACTLY the problem you described.**
|
||||
|
||||
It automates everything you were planning to build manually in `.claude/AI-COLLABORATION.md`:
|
||||
|
||||
| Your Plan | mcp-coordinator | Savings |
|
||||
|-----------|-----------------|---------|
|
||||
| memory/active_work.md | Automatic agent registry | 100% |
|
||||
| Branch naming convention | Agent announces work | 100% |
|
||||
| Session notes | Consultation threads + audit log | 100% |
|
||||
| Pre-commit conflict check | Real-time detection BEFORE coding | 100% |
|
||||
| Custom MCP coordinator | Already built, tested, documented | 22-44 hours |
|
||||
|
||||
**Your manual Phase 1 (5 min): mcp-coordinator does automatically in real-time.**
|
||||
**Your manual Phase 2 (30 min): mcp-coordinator includes out of the box.**
|
||||
**Your manual Phase 3 (2-4 hours): mcp-coordinator is literally this.**
|
||||
|
||||
**Recommendation: Install mcp-coordinator instead of building your own. You get:**
|
||||
- 2500+ tests
|
||||
- Production-ready
|
||||
- Dashboard
|
||||
- Team support
|
||||
- OAuth/auth
|
||||
- Active maintenance
|
||||
- MIT license
|
||||
|
||||
**For free.**
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- **GitHub:** https://github.com/swoofer/mcp-coordinator
|
||||
- **Docs:** https://swoofer.github.io/mcp-coordinator
|
||||
- **npm:** https://www.npmjs.com/package/mcp-coordinator
|
||||
- **Issues:** https://github.com/swoofer/mcp-coordinator/issues
|
||||
- **Discussions:** https://github.com/swoofer/mcp-coordinator/discussions
|
||||
|
||||
**Want me to install and configure it now?**
|
||||
681
.claude/setup/MCP-INTEGRATION-GUIDE.md
Normal file
681
.claude/setup/MCP-INTEGRATION-GUIDE.md
Normal file
@@ -0,0 +1,681 @@
|
||||
# MCP Server Integration Guide for ShopDB Development
|
||||
|
||||
Complete guide to using all four MCP servers together with Claude Code for automated development, testing, and deployment workflows.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
**MCP (Model Context Protocol) Servers** extend Claude Code with external tool access:
|
||||
|
||||
| MCP Server | Purpose | Tools Provided |
|
||||
|------------|---------|----------------|
|
||||
| **gortex** | Project management | Task tracking, milestones, time tracking |
|
||||
| **mysql** | Database access | Query execution, schema inspection, data manipulation |
|
||||
| **browser** | Web automation | Page navigation, screenshots, form filling, testing |
|
||||
| **vm** | VM automation via SSH | Command execution, file transfer, process management |
|
||||
|
||||
Together, these enable **full-stack automated workflows**: from code changes to database migrations to VM deployment to browser testing, all through natural language conversation with Claude.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Location
|
||||
|
||||
All MCP servers are configured in:
|
||||
```
|
||||
flask-shopdb/.claude/mcp-servers.json
|
||||
```
|
||||
|
||||
**Important:** MCP servers only load when Claude Code runs from `flask-shopdb` directory.
|
||||
|
||||
### Current Configuration
|
||||
|
||||
```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"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### 1. Gortex MCP Server
|
||||
|
||||
**Install:**
|
||||
```bash
|
||||
curl -L -o gortex_windows_amd64.zip https://github.com/zzet/gortex/releases/latest/download/gortex_windows_amd64.zip
|
||||
unzip -o gortex_windows_amd64.zip -d C:\Users\270015376\Documents\
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
C:\Users\270015376\Documents\gortex.exe --version
|
||||
```
|
||||
|
||||
**What it enables:**
|
||||
- Track development tasks
|
||||
- Log time spent on features
|
||||
- Manage sprint milestones
|
||||
- Generate reports
|
||||
|
||||
### 2. MySQL MCP Server
|
||||
|
||||
**Install:** (handled by npx, no manual install needed)
|
||||
|
||||
**Requires:** MySQL/Docker running locally
|
||||
|
||||
**Start database:**
|
||||
```bash
|
||||
cd flask-shopdb
|
||||
docker compose up -d db
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
mysql -h 127.0.0.1 -u shopdb -pshopdb-dev-password shopdb_flask -e "SELECT 1"
|
||||
```
|
||||
|
||||
**What it enables:**
|
||||
- Query database directly
|
||||
- Inspect schema and indexes
|
||||
- Verify migration results
|
||||
- Create test data
|
||||
- Debug data issues
|
||||
|
||||
### 3. Browser MCP Server
|
||||
|
||||
**Install:** (handled by npx, no manual install needed)
|
||||
|
||||
**Requires:** Chrome/Chromium browser installed
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
npx -y @agent-infra/mcp-server-browser --help
|
||||
```
|
||||
|
||||
**What it enables:**
|
||||
- Automated UI testing
|
||||
- Screenshot capture
|
||||
- Form submission testing
|
||||
- Visual regression checks
|
||||
- End-to-end workflow testing
|
||||
|
||||
### 4. VM SSH MCP Server
|
||||
|
||||
**Install:** (handled by npx, no manual install needed)
|
||||
|
||||
**Requires:**
|
||||
- Hyper-V VM running at 192.168.100.10
|
||||
- OpenSSH server enabled on VM
|
||||
- User account: SupportUser (password: vos313)
|
||||
|
||||
**Setup VM SSH** (run on VM as Administrator):
|
||||
```powershell
|
||||
# On VM
|
||||
.\\.claude\enable-vm-ssh.ps1
|
||||
```
|
||||
|
||||
**Verify from host:**
|
||||
```bash
|
||||
ssh SupportUser@192.168.100.10 "hostname"
|
||||
```
|
||||
|
||||
**What it enables:**
|
||||
- Deploy agent to test VM
|
||||
- Run commands on VM
|
||||
- Transfer files to/from VM
|
||||
- Monitor agent logs
|
||||
- Test agent integration
|
||||
|
||||
---
|
||||
|
||||
## Testing MCP Servers
|
||||
|
||||
### Run Test Suite
|
||||
|
||||
```powershell
|
||||
cd flask-shopdb
|
||||
.\\.claude\test-mcp-servers.ps1
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
==========================================
|
||||
ShopDB MCP Server Test Suite
|
||||
==========================================
|
||||
|
||||
[1/7] Checking MCP configuration...
|
||||
OK: Config file exists
|
||||
[2/7] Testing Gortex MCP server...
|
||||
OK: Gortex found at C:\Users\270015376\Documents\gortex.exe
|
||||
[3/7] Testing MySQL MCP server...
|
||||
OK: MySQL server is reachable at 127.0.0.1:3306
|
||||
[4/7] Testing Browser MCP server...
|
||||
OK: Browser MCP package exists (version 1.2.3)
|
||||
[5/7] Testing VM SSH MCP server...
|
||||
OK: VM is reachable at 192.168.100.10
|
||||
OK: SSH port 22 is open on VM
|
||||
[6/7] Checking Hyper-V VMs...
|
||||
OK: Found 1 VM(s)
|
||||
- ShopDB-Test-VM: Running
|
||||
[7/7] Checking VM snapshots...
|
||||
OK: Found 4 snapshot(s)
|
||||
- ShopDB-Test-VM: Clean-Install (2024-09-08 10:30)
|
||||
- ShopDB-Test-VM: Docker-Ready (2024-09-08 11:45)
|
||||
- ShopDB-Test-VM: SSH-Enabled (2024-09-08 12:15)
|
||||
- ShopDB-Test-VM: ShopDB-Deployed (2024-09-09 09:00)
|
||||
|
||||
==========================================
|
||||
Summary
|
||||
==========================================
|
||||
|
||||
config : OK
|
||||
gortex : OK
|
||||
mysql : OK
|
||||
browser : OK
|
||||
vm : OK
|
||||
hyperv : OK
|
||||
snapshots : OK
|
||||
|
||||
Overall: 7/7 tests passed (100%)
|
||||
```
|
||||
|
||||
### Test Individual Servers with Claude
|
||||
|
||||
**Start Claude Code from flask-shopdb:**
|
||||
```bash
|
||||
cd flask-shopdb
|
||||
claude
|
||||
```
|
||||
|
||||
**Test Gortex:**
|
||||
```
|
||||
You: "List all tasks in the current project"
|
||||
Claude: [Uses mcp__gortex__list_tasks]
|
||||
```
|
||||
|
||||
**Test MySQL:**
|
||||
```
|
||||
You: "Show me the first 5 endpoints in the database"
|
||||
Claude: [Uses mcp__mysql__query]
|
||||
```
|
||||
|
||||
**Test Browser:**
|
||||
```
|
||||
You: "Take a screenshot of https://localhost:5001"
|
||||
Claude: [Uses mcp__browser__navigate and mcp__browser__screenshot]
|
||||
```
|
||||
|
||||
**Test VM:**
|
||||
```
|
||||
You: "What is the hostname of the VM?"
|
||||
Claude: [Uses mcp__vm__exec with command "hostname"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integrated Workflows
|
||||
|
||||
### Workflow 1: Feature Development with Database Changes
|
||||
|
||||
**Scenario:** Add new field to endpoints table, update API, test on VM
|
||||
|
||||
```
|
||||
You: "Add 'last_boot_time' timestamp field to endpoints"
|
||||
|
||||
Claude:
|
||||
1. [Gortex: Create task "Add last_boot_time field"]
|
||||
2. [MySQL: Check current endpoints schema]
|
||||
3. [Edit: Create Alembic migration]
|
||||
4. [Bash: Run migration locally]
|
||||
5. [MySQL: Verify column added]
|
||||
6. [Edit: Update endpoint model and API]
|
||||
7. [Bash: Run tests]
|
||||
8. [Gortex: Update task status to "testing"]
|
||||
9. [VM: Deploy to test VM]
|
||||
10. [VM: Restart agent]
|
||||
11. [MySQL: Check VM endpoint records include new field]
|
||||
12. [Gortex: Mark task complete]
|
||||
|
||||
Result: Feature developed, tested, and verified end-to-end
|
||||
```
|
||||
|
||||
### Workflow 2: UI Testing After Plugin Changes
|
||||
|
||||
**Scenario:** Modified plugins UI, verify it works in browser
|
||||
|
||||
```
|
||||
You: "Test the new notifications plugin UI"
|
||||
|
||||
Claude:
|
||||
1. [Bash: Build frontend]
|
||||
2. [Bash: Restart Docker stack]
|
||||
3. [Browser: Navigate to https://localhost:5001]
|
||||
4. [Browser: Login as admin]
|
||||
5. [Browser: Click "Notifications" in sidebar]
|
||||
6. [Browser: Screenshot current state]
|
||||
7. [MySQL: Insert test fleet alert]
|
||||
8. [Browser: Refresh page]
|
||||
9. [Browser: Verify alert appears]
|
||||
10. [Browser: Screenshot alert display]
|
||||
11. [MySQL: Delete test data]
|
||||
|
||||
Result: UI tested, screenshots captured, test data cleaned up
|
||||
```
|
||||
|
||||
### Workflow 3: Agent Deployment and Integration Test
|
||||
|
||||
**Scenario:** Build new agent version, deploy to VM, verify it connects
|
||||
|
||||
```
|
||||
You: "Build agent and deploy to VM for testing"
|
||||
|
||||
Claude:
|
||||
1. [Gortex: Create task "Test agent v1.2.4"]
|
||||
2. [Bash: Increment agent version in .csproj]
|
||||
3. [Bash: dotnet publish agent]
|
||||
4. [VM: Stop agent service if running]
|
||||
5. [VM: Copy new agent.exe to C:\Program Files\ShopDB\]
|
||||
6. [VM: Start agent service]
|
||||
7. [VM: Tail agent log file]
|
||||
8. [MySQL: Wait for endpoint heartbeat]
|
||||
9. [MySQL: Verify endpoint version = 1.2.4]
|
||||
10. [Browser: Navigate to endpoints page]
|
||||
11. [Browser: Screenshot showing new version]
|
||||
12. [Gortex: Mark task complete]
|
||||
|
||||
Result: Agent built, deployed, verified working
|
||||
```
|
||||
|
||||
### Workflow 4: Database Migration with Rollback Test
|
||||
|
||||
**Scenario:** Create migration, test forward and backward migration
|
||||
|
||||
```
|
||||
You: "Create migration to add 'tags' JSONB column to assets"
|
||||
|
||||
Claude:
|
||||
1. [MySQL: Backup current schema]
|
||||
2. [Edit: Create migration file]
|
||||
3. [Bash: Run migration (upgrade)]
|
||||
4. [MySQL: Verify column exists with correct type]
|
||||
5. [MySQL: Insert test data with tags]
|
||||
6. [Bash: Rollback migration (downgrade)]
|
||||
7. [MySQL: Verify column removed]
|
||||
8. [MySQL: Verify no data loss in other columns]
|
||||
9. [Bash: Re-run migration (upgrade)]
|
||||
10. [MySQL: Verify clean forward migration]
|
||||
|
||||
Result: Migration tested both directions, safe to deploy
|
||||
```
|
||||
|
||||
### Workflow 5: End-to-End Operator Report Test
|
||||
|
||||
**Scenario:** Verify operator report flow from tray to database
|
||||
|
||||
```
|
||||
You: "Test operator report submission from VM"
|
||||
|
||||
Claude:
|
||||
1. [VM: Restore to "Agent-Running" snapshot]
|
||||
2. [MySQL: Clear existing operator reports]
|
||||
3. [VM: Get current timestamp]
|
||||
4. [VM: Simulate tray submitting report via API]
|
||||
5. [MySQL: Query for new report record]
|
||||
6. [MySQL: Verify all fields populated correctly]
|
||||
7. [Browser: Navigate to operator reports page]
|
||||
8. [Browser: Verify report appears in UI]
|
||||
9. [Browser: Screenshot report details]
|
||||
10. [VM: Check agent log for submission confirmation]
|
||||
|
||||
Result: Operator report flow verified end-to-end
|
||||
```
|
||||
|
||||
### Workflow 6: Performance Testing and Monitoring
|
||||
|
||||
**Scenario:** Load test endpoints API, monitor database performance
|
||||
|
||||
```
|
||||
You: "Load test the endpoints API with 1000 concurrent requests"
|
||||
|
||||
Claude:
|
||||
1. [MySQL: Record current query performance stats]
|
||||
2. [Bash: Run load test script]
|
||||
3. [MySQL: Monitor slow query log during test]
|
||||
4. [MySQL: Check connection pool usage]
|
||||
5. [MySQL: Analyze query performance after test]
|
||||
6. [MySQL: Identify slow queries]
|
||||
7. [MySQL: Check index usage statistics]
|
||||
8. [Gortex: Create tasks for performance improvements]
|
||||
|
||||
Result: Performance baseline established, bottlenecks identified
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Pattern 1: Snapshot-Based Testing
|
||||
|
||||
**Use VM snapshots for rapid iteration:**
|
||||
|
||||
```
|
||||
You: "Test 3 different agent configurations"
|
||||
|
||||
Claude:
|
||||
1. [VM: Restore to "Agent-Installed" snapshot]
|
||||
2. [VM: Configure with settings A]
|
||||
3. [VM: Test and record results]
|
||||
4. [VM: Restore to "Agent-Installed" snapshot]
|
||||
5. [VM: Configure with settings B]
|
||||
6. [VM: Test and record results]
|
||||
7. [VM: Restore to "Agent-Installed" snapshot]
|
||||
8. [VM: Configure with settings C]
|
||||
9. [VM: Test and record results]
|
||||
10. [Compare results and recommend best config]
|
||||
```
|
||||
|
||||
### Pattern 2: Database-Driven UI Testing
|
||||
|
||||
**Generate test data in database, verify UI displays it correctly:**
|
||||
|
||||
```
|
||||
You: "Test UI with various alert configurations"
|
||||
|
||||
Claude:
|
||||
1. [MySQL: Create alert with priority=critical]
|
||||
2. [Browser: Screenshot alert display]
|
||||
3. [MySQL: Update alert to priority=info]
|
||||
4. [Browser: Refresh and screenshot]
|
||||
5. [MySQL: Create multi-line alert message]
|
||||
6. [Browser: Screenshot message display]
|
||||
7. [MySQL: Create alert with long title (100 chars)]
|
||||
8. [Browser: Screenshot title truncation]
|
||||
9. [MySQL: Delete all test alerts]
|
||||
```
|
||||
|
||||
### Pattern 3: Parallel Testing
|
||||
|
||||
**Test on multiple environments simultaneously:**
|
||||
|
||||
```
|
||||
You: "Test new plugin on both local and VM"
|
||||
|
||||
Claude:
|
||||
1. [Bash: Build frontend with new plugin]
|
||||
2. [Bash: Restart local Docker stack]
|
||||
3. [VM: Deploy to VM Docker stack]
|
||||
4. [Parallel:]
|
||||
a. [Browser: Test on localhost:5001]
|
||||
b. [Browser: Test on 192.168.100.10:5001]
|
||||
5. [Compare results]
|
||||
6. [Screenshot differences if any]
|
||||
```
|
||||
|
||||
### Pattern 4: Automated Debugging
|
||||
|
||||
**Use MCP tools to diagnose issues:**
|
||||
|
||||
```
|
||||
You: "Agent on VM is not receiving alerts, debug why"
|
||||
|
||||
Claude:
|
||||
1. [VM: Check agent service status]
|
||||
2. [VM: Check agent log for errors]
|
||||
3. [MySQL: Verify alerts exist in database]
|
||||
4. [MySQL: Check alert has target matching VM endpoint]
|
||||
5. [VM: Check network connectivity to API]
|
||||
6. [VM: Check agent config BaseUrl setting]
|
||||
7. [MySQL: Check endpoint record has correct IP]
|
||||
8. [VM: Test manual API call]
|
||||
9. [Identify root cause and suggest fix]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Database Credentials
|
||||
|
||||
**In mcp-servers.json:**
|
||||
```
|
||||
mysql://shopdb:shopdb-dev-password@127.0.0.1:3306/shopdb_flask
|
||||
```
|
||||
|
||||
- Only for local development
|
||||
- Database not exposed beyond localhost
|
||||
- Not used in production
|
||||
|
||||
**Production uses:**
|
||||
- Environment variables for credentials
|
||||
- Restricted database users
|
||||
- Encrypted connections
|
||||
|
||||
### VM SSH Credentials
|
||||
|
||||
**In mcp-servers.json:**
|
||||
```
|
||||
"--password", "vos313"
|
||||
```
|
||||
|
||||
- Test VM only, internal network (192.168.100.x)
|
||||
- No internet access on VM
|
||||
- VM destroyed/rebuilt regularly
|
||||
- Not a production system
|
||||
|
||||
**Better approach (optional):**
|
||||
- Use SSH key instead of password
|
||||
- See `.claude/setup-vm-ssh.md` for key-based auth
|
||||
|
||||
### MCP Server Permissions
|
||||
|
||||
**Claude Code permission prompts:**
|
||||
- First use of each MCP tool requires approval
|
||||
- Approve dangerous operations (DELETE, DROP) individually
|
||||
- Review SQL queries before execution
|
||||
|
||||
**Configure auto-approval for safe operations:**
|
||||
|
||||
Add to `.claude/settings.json`:
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"mcp__mysql__query(SELECT *)",
|
||||
"mcp__vm__exec(hostname)",
|
||||
"mcp__browser__screenshot(*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### MCP Server Not Loading
|
||||
|
||||
**Symptom:** Claude says "I don't have access to {server}"
|
||||
|
||||
**Fixes:**
|
||||
1. Verify running Claude Code from `flask-shopdb` directory
|
||||
2. Check `.claude/mcp-servers.json` exists
|
||||
3. Restart Claude Code completely
|
||||
4. Run `test-mcp-servers.ps1` to diagnose
|
||||
|
||||
### MySQL Connection Failed
|
||||
|
||||
**Symptom:** "Cannot connect to MySQL server"
|
||||
|
||||
**Fixes:**
|
||||
1. Start database: `docker compose up -d db`
|
||||
2. Check port: `netstat -ano | findstr 3306`
|
||||
3. Test connection: `mysql -h 127.0.0.1 -u shopdb -p`
|
||||
4. Check Docker network settings
|
||||
|
||||
### VM SSH Connection Failed
|
||||
|
||||
**Symptom:** "SSH connection refused" or "Authentication failed"
|
||||
|
||||
**Fixes:**
|
||||
1. Verify VM running: `Get-VM | Where-Object State -eq 'Running'`
|
||||
2. Test ping: `ping 192.168.100.10`
|
||||
3. Check SSH service on VM: `Get-Service sshd`
|
||||
4. Run `enable-vm-ssh.ps1` on VM
|
||||
5. Verify credentials: `ssh SupportUser@192.168.100.10`
|
||||
|
||||
### Browser Automation Failed
|
||||
|
||||
**Symptom:** "Browser launch failed" or "Navigation timeout"
|
||||
|
||||
**Fixes:**
|
||||
1. Check Chrome installed
|
||||
2. Close other Chrome instances
|
||||
3. Check no port conflicts
|
||||
4. Try manual command: `npx -y @agent-infra/mcp-server-browser`
|
||||
|
||||
### Gortex Not Found
|
||||
|
||||
**Symptom:** "Cannot find gortex.exe"
|
||||
|
||||
**Fixes:**
|
||||
1. Download: https://github.com/zzet/gortex/releases
|
||||
2. Extract to: `C:\Users\270015376\Documents\gortex.exe`
|
||||
3. Verify: `gortex.exe --version`
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Always Test MCP Setup First
|
||||
|
||||
**Before starting work:**
|
||||
```bash
|
||||
cd flask-shopdb
|
||||
.\\.claude\test-mcp-servers.ps1
|
||||
```
|
||||
|
||||
### 2. Use Snapshots for Risky Operations
|
||||
|
||||
**Before destructive VM operations:**
|
||||
```powershell
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Before-$(Get-Date -Format 'yyyyMMdd-HHmm')"
|
||||
```
|
||||
|
||||
### 3. Clean Up Test Data
|
||||
|
||||
**After testing with MySQL:**
|
||||
```sql
|
||||
-- Delete test records created during testing
|
||||
DELETE FROM fleetalerts WHERE title LIKE 'TEST:%';
|
||||
DELETE FROM operatorreports WHERE submittedby = 'test-user';
|
||||
```
|
||||
|
||||
### 4. Verify Results
|
||||
|
||||
**Don't trust logs alone:**
|
||||
- Use MySQL to verify database changes
|
||||
- Use Browser to verify UI changes
|
||||
- Use VM commands to verify agent behavior
|
||||
|
||||
### 5. Keep MCP Config in Sync
|
||||
|
||||
**When changing database password:**
|
||||
- Update `mcp-servers.json`
|
||||
- Update `.env` files
|
||||
- Update `docker-compose.yml` if needed
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Starting MCP-Enabled Session
|
||||
|
||||
```bash
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
claude
|
||||
```
|
||||
|
||||
### Common MCP Commands via Claude
|
||||
|
||||
| Task | Example Request |
|
||||
|------|----------------|
|
||||
| Query database | "Show me all endpoints that have not checked in for 24 hours" |
|
||||
| Execute on VM | "Run 'Get-Service shopdb*' on the VM" |
|
||||
| Screenshot UI | "Take a screenshot of the notifications page" |
|
||||
| Create task | "Create a task to fix endpoint heartbeat bug" |
|
||||
| Copy file to VM | "Upload the latest agent build to the VM" |
|
||||
| Run migration | "Apply the pending database migration" |
|
||||
| Test UI flow | "Test the login flow and capture screenshots" |
|
||||
| Check logs | "Show me the agent log from the VM" |
|
||||
|
||||
### Debugging MCP Issues
|
||||
|
||||
```bash
|
||||
# Test each server individually
|
||||
npx -y @benborla29/mcp-server-mysql --help
|
||||
npx -y @agent-infra/mcp-server-browser --help
|
||||
npx -y ssh-mcp --host 192.168.100.10 --user SupportUser --password vos313
|
||||
C:\Users\270015376\Documents\gortex.exe mcp --help
|
||||
|
||||
# Check permissions
|
||||
cat .claude/settings.json | grep -A 20 permissions
|
||||
|
||||
# Check MCP server logs
|
||||
# (Claude Code shows MCP errors in transcript)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **VM Snapshots:** `.claude/VM-SNAPSHOT-GUIDE.md`
|
||||
- **VM SSH Setup:** `.claude/setup-vm-ssh.md`
|
||||
- **Test MCP Servers:** `.claude/test-mcp-servers.ps1`
|
||||
- **VM Deployment:** `DEPLOY-TO-VM.md`
|
||||
- **Plugin Development:** `../shopdb-flask.wiki/PLUGIN-DEVELOPMENT.md`
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Run test suite:** `.\\.claude\test-mcp-servers.ps1`
|
||||
2. **Create baseline snapshots:** See `VM-SNAPSHOT-GUIDE.md`
|
||||
3. **Try example workflow:** Pick one from "Integrated Workflows" section
|
||||
4. **Document your workflows:** Add custom patterns to this guide
|
||||
5. **Automate repetitive tasks:** Create aliases for common MCP operations
|
||||
|
||||
---
|
||||
|
||||
**Ready to use all four MCP servers together for rapid development!**
|
||||
72
.claude/setup/MCP-QUICK-START.md
Normal file
72
.claude/setup/MCP-QUICK-START.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# MCP Quick Start Guide
|
||||
|
||||
Quick setup for ShopDB MCP (Model Context Protocol) servers.
|
||||
|
||||
## What is MCP?
|
||||
|
||||
MCP extends Claude Code with external tool access. ShopDB uses 5 MCP servers:
|
||||
|
||||
| Server | Purpose |
|
||||
|--------|---------|
|
||||
| **gortex** | Code intelligence and project management |
|
||||
| **mysql** | Database access and queries |
|
||||
| **browser** | Web automation and testing |
|
||||
| **vm** | VM automation and deployment |
|
||||
| **coordinator** | Multi-agent coordination |
|
||||
|
||||
## Quick Setup
|
||||
|
||||
### 1. Run Automated Setup
|
||||
|
||||
```powershell
|
||||
cd flask-shopdb
|
||||
.\.claude\quick-start-mcp.ps1
|
||||
```
|
||||
|
||||
This installs all required packages and verifies connectivity.
|
||||
|
||||
### 2. Configure GitHub Token
|
||||
|
||||
```bash
|
||||
# Create token at: https://github.com/settings/tokens/new
|
||||
# Scopes needed: repo, read:org
|
||||
|
||||
# Set environment variable (Windows)
|
||||
setx GITHUB_PERSONAL_ACCESS_TOKEN "ghp_YOUR_TOKEN_HERE"
|
||||
|
||||
# Or add to shell profile (Git Bash)
|
||||
echo 'export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_YOUR_TOKEN_HERE"' >> ~/.bashrc
|
||||
```
|
||||
|
||||
### 3. Verify Setup
|
||||
|
||||
```powershell
|
||||
.\.claude\test-mcp-servers.ps1
|
||||
```
|
||||
|
||||
Expected: All servers respond OK.
|
||||
|
||||
### 4. Restart Claude Code
|
||||
|
||||
Close and reopen Claude Code to load MCP servers.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Problem**: GitHub authorization error
|
||||
**Fix**: Set `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable and restart
|
||||
|
||||
**Problem**: MySQL connection fails
|
||||
**Fix**: Start MySQL with `docker-compose up -d db` or `start-dev.cmd`
|
||||
|
||||
**Problem**: VM connection fails
|
||||
**Fix**: Check VM is running and SSH is enabled (see `setup-vm-ssh.md`)
|
||||
|
||||
**Problem**: Coordinator not connecting
|
||||
**Fix**: Verify coordinator server is running and network is accessible
|
||||
|
||||
## More Documentation
|
||||
|
||||
- `INDEX-MCP-DOCS.md` - Complete documentation index
|
||||
- `MCP-INTEGRATION-GUIDE.md` - Detailed integration patterns and workflows
|
||||
- `MCP-COORDINATOR-CONNECTION-GUIDE.md` - Multi-agent coordination setup
|
||||
- `MCP-COORDINATOR-EVALUATION.md` - Coordinator capabilities and evaluation
|
||||
29
.claude/setup/README.md
Normal file
29
.claude/setup/README.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# Setup Guides
|
||||
|
||||
Configuration and environment setup documentation.
|
||||
|
||||
## MCP Server Setup
|
||||
|
||||
**Start here**: `MCP-QUICK-START.md` - Quick setup guide
|
||||
|
||||
**Detailed documentation**:
|
||||
- `INDEX-MCP-DOCS.md` - Complete documentation index
|
||||
- `MCP-INTEGRATION-GUIDE.md` - Detailed integration patterns and workflows
|
||||
- `MCP-COORDINATOR-CONNECTION-GUIDE.md` - Multi-agent coordination setup
|
||||
- `MCP-COORDINATOR-EVALUATION.md` - Coordinator capabilities and evaluation
|
||||
- `GORTEX-MCP-SETUP.md` - Gortex code intelligence server
|
||||
- `GITHUB-MCP-SETUP.md` - GitHub integration server
|
||||
|
||||
**Automation scripts**:
|
||||
- `quick-start-mcp.ps1` - Automated setup
|
||||
- `test-mcp-servers.ps1` - Verification tests
|
||||
|
||||
## VM and Infrastructure
|
||||
- `VM-SNAPSHOT-GUIDE.md` - Creating and managing VM snapshots
|
||||
- `VM-USERS.md` - VM user accounts and roles
|
||||
- `setup-vm-ssh.md` - SSH key authentication setup
|
||||
- `enable-vm-ssh.ps1` - SSH enablement script
|
||||
- `HYPER-V-SETUP.md` - Hyper-V permissions and configuration
|
||||
|
||||
## GitHub Integration
|
||||
- `setup-github-token.cmd` - GitHub PAT configuration
|
||||
360
.claude/setup/VM-SNAPSHOT-GUIDE.md
Normal file
360
.claude/setup/VM-SNAPSHOT-GUIDE.md
Normal file
@@ -0,0 +1,360 @@
|
||||
# VM Snapshot Management for ShopDB Testing
|
||||
|
||||
Guide for creating and managing Hyper-V VM snapshots for agent testing with Claude Code MCP integration.
|
||||
|
||||
---
|
||||
|
||||
## Why Snapshots Matter
|
||||
|
||||
**Snapshots enable rapid iteration:**
|
||||
- Test agent installation/uninstallation
|
||||
- Revert to clean state after failed deployments
|
||||
- Test different configurations without rebuilding VM
|
||||
- Capture known-good states (clean install, agent installed, agent configured)
|
||||
- Compare behavior across configurations
|
||||
|
||||
**With MCP integration, Claude can:**
|
||||
- Deploy agent to VM via SSH
|
||||
- Run tests and check results
|
||||
- Revert VM to snapshot if test fails
|
||||
- Retry with different configuration
|
||||
- All automated through conversation
|
||||
|
||||
---
|
||||
|
||||
## Snapshot Strategy
|
||||
|
||||
### Baseline Snapshots (Create Once)
|
||||
|
||||
| Snapshot Name | Description | When to Use |
|
||||
|--------------|-------------|-------------|
|
||||
| `Clean-Install` | Fresh Windows 11, no software | Starting from scratch |
|
||||
| `Docker-Ready` | Docker Desktop installed and running | Testing Docker deployments |
|
||||
| `SSH-Enabled` | OpenSSH server configured | Testing SSH/MCP connections |
|
||||
| `ShopDB-Deployed` | ShopDB running in Docker | Testing agent integration |
|
||||
|
||||
### Testing Snapshots (Create/Delete Frequently)
|
||||
|
||||
| Snapshot Name | Description | When to Use |
|
||||
|--------------|-------------|-------------|
|
||||
| `Agent-Installed` | Agent service installed but not configured | Testing agent configuration changes |
|
||||
| `Agent-Running` | Agent fully configured and running | Testing plugin changes |
|
||||
| `Before-Test-{name}` | State before specific test run | Easy rollback after test |
|
||||
|
||||
---
|
||||
|
||||
## Creating Snapshots
|
||||
|
||||
### Method 1: PowerShell (Recommended for Automation)
|
||||
|
||||
```powershell
|
||||
# From host PC (requires Administrator privileges)
|
||||
|
||||
# Create snapshot
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"
|
||||
|
||||
# Create snapshot with description
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Agent-Installed" `
|
||||
-Notes "ShopDB agent v1.2.3 installed, not yet configured"
|
||||
|
||||
# List all snapshots
|
||||
Get-VMSnapshot -VMName "ShopDB-Test-VM" | Select-Object Name, CreationTime, ParentSnapshotName | Format-Table
|
||||
|
||||
# Show snapshot tree
|
||||
Get-VMSnapshot -VMName "ShopDB-Test-VM" | Format-Table -Property Name, ParentSnapshotName, CreationTime
|
||||
```
|
||||
|
||||
### Method 2: Hyper-V Manager GUI
|
||||
|
||||
1. Open **Hyper-V Manager**
|
||||
2. Select VM in left pane
|
||||
3. Right-click VM -> **Checkpoint**
|
||||
4. Enter snapshot name in dialog
|
||||
5. Click **OK**
|
||||
|
||||
### Method 3: Via Claude Code (When MCP VM Server is Connected)
|
||||
|
||||
```
|
||||
You: "Create a snapshot of the VM named 'Before-Agent-Install'"
|
||||
|
||||
Claude: [Uses MCP SSH to run PowerShell command on host]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Restoring Snapshots
|
||||
|
||||
### Method 1: PowerShell
|
||||
|
||||
```powershell
|
||||
# Restore to specific snapshot
|
||||
Restore-VMSnapshot -Name "Clean-Install" -VMName "ShopDB-Test-VM" -Confirm:$false
|
||||
|
||||
# Restore to most recent snapshot
|
||||
$latest = Get-VMSnapshot -VMName "ShopDB-Test-VM" | Sort-Object CreationTime -Descending | Select-Object -First 1
|
||||
Restore-VMSnapshot -VMSnapshot $latest -Confirm:$false
|
||||
```
|
||||
|
||||
### Method 2: Hyper-V Manager GUI
|
||||
|
||||
1. Open **Hyper-V Manager**
|
||||
2. Select VM in left pane
|
||||
3. In bottom **Checkpoints** pane, right-click desired snapshot
|
||||
4. Select **Apply**
|
||||
5. Choose:
|
||||
- **Apply** (restore without creating new snapshot)
|
||||
- **Apply and Create Checkpoint** (save current state first)
|
||||
|
||||
### Method 3: Via Claude Code
|
||||
|
||||
```
|
||||
You: "Revert VM to 'Clean-Install' snapshot"
|
||||
|
||||
Claude: [Uses MCP to restore snapshot via PowerShell]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deleting Snapshots
|
||||
|
||||
### PowerShell
|
||||
|
||||
```powershell
|
||||
# Delete specific snapshot
|
||||
Remove-VMSnapshot -VMName "ShopDB-Test-VM" -Name "Before-Test-2024-09-09"
|
||||
|
||||
# Delete all snapshots (WARNING: cannot undo)
|
||||
Get-VMSnapshot -VMName "ShopDB-Test-VM" | Remove-VMSnapshot -Confirm:$false
|
||||
|
||||
# Delete snapshots older than 30 days
|
||||
$cutoff = (Get-Date).AddDays(-30)
|
||||
Get-VMSnapshot -VMName "ShopDB-Test-VM" |
|
||||
Where-Object { $_.CreationTime -lt $cutoff } |
|
||||
Remove-VMSnapshot -Confirm:$false
|
||||
```
|
||||
|
||||
### Notes on Deletion:
|
||||
- Deleting a snapshot **merges** its changes into parent snapshot
|
||||
- Does **not** delete the VM state that snapshot represents
|
||||
- Frees up disk space on host
|
||||
|
||||
---
|
||||
|
||||
## Snapshot Workflows with Claude Code
|
||||
|
||||
### Example 1: Clean Agent Installation Test
|
||||
|
||||
```
|
||||
You: "Test agent installation from scratch"
|
||||
|
||||
Claude:
|
||||
1. [Restore VM to "Docker-Ready" snapshot]
|
||||
2. [SSH to VM: Copy agent installer]
|
||||
3. [SSH to VM: Run installer]
|
||||
4. [SSH to VM: Verify service installed]
|
||||
5. [MySQL: Check no endpoint records exist yet]
|
||||
6. [SSH to VM: Start agent service]
|
||||
7. [MySQL: Wait for endpoint to register]
|
||||
8. [SSH to VM: Check agent logs for errors]
|
||||
9. Result: Agent installed successfully, endpoint registered
|
||||
|
||||
You: "Something failed, revert and try again"
|
||||
|
||||
Claude:
|
||||
1. [Restore VM to "Docker-Ready" snapshot]
|
||||
2. [Retry with adjusted configuration]
|
||||
```
|
||||
|
||||
### Example 2: Test Plugin Changes
|
||||
|
||||
```
|
||||
You: "Deploy new plugin version and test on VM"
|
||||
|
||||
Claude:
|
||||
1. [Create snapshot "Before-Plugin-Update"]
|
||||
2. [Build frontend with new plugin]
|
||||
3. [Rebuild Docker image]
|
||||
4. [SSH to VM: Pull new image]
|
||||
5. [SSH to VM: Restart containers]
|
||||
6. [Browser MCP: Open https://192.168.100.10:5001]
|
||||
7. [Test new plugin functionality]
|
||||
8. Result: Plugin works! (or: Plugin broken, reverting...)
|
||||
```
|
||||
|
||||
### Example 3: Automated Regression Testing
|
||||
|
||||
```
|
||||
You: "Run full regression test suite on VM"
|
||||
|
||||
Claude:
|
||||
1. [Restore to "ShopDB-Deployed" snapshot]
|
||||
2. [SSH: Install agent]
|
||||
3. [MySQL: Create test data (fleet alerts, operator reports)]
|
||||
4. [SSH: Verify agent receives alerts]
|
||||
5. [SSH: Submit test operator report]
|
||||
6. [MySQL: Verify report data stored correctly]
|
||||
7. [SSH: Capture screenshots of tray notifications]
|
||||
8. [SSH: Check agent logs for errors]
|
||||
9. [Restore to "ShopDB-Deployed" (clean up test data)]
|
||||
10. Result: All tests passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Snapshot Storage and Performance
|
||||
|
||||
### Disk Space Considerations
|
||||
|
||||
- Each snapshot stores **incremental changes** from parent
|
||||
- First snapshot after large change (OS update) will be large
|
||||
- Multiple small snapshots are more efficient than few large ones
|
||||
- Deleting snapshots merges changes (may take time for large snapshots)
|
||||
|
||||
### Check Snapshot Disk Usage
|
||||
|
||||
```powershell
|
||||
Get-VMSnapshot -VMName "ShopDB-Test-VM" |
|
||||
ForEach-Object {
|
||||
$path = $_.Path
|
||||
$size = (Get-ChildItem -Path $path -Recurse | Measure-Object -Property Length -Sum).Sum / 1GB
|
||||
[PSCustomObject]@{
|
||||
Name = $_.Name
|
||||
Created = $_.CreationTime
|
||||
SizeGB = [math]::Round($size, 2)
|
||||
}
|
||||
} | Format-Table
|
||||
```
|
||||
|
||||
### Performance Impact
|
||||
|
||||
- **Snapshots slow down VM I/O** (each write goes to differencing disk)
|
||||
- For long-running VMs, merge old snapshots periodically
|
||||
- Keep snapshot chain depth under 10 for best performance
|
||||
- Delete snapshots after merging changes into base disk
|
||||
|
||||
---
|
||||
|
||||
## Recommended Snapshot Schedule
|
||||
|
||||
### Initial Setup (Do Once)
|
||||
|
||||
```powershell
|
||||
# 1. Clean Windows 11 install
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"
|
||||
|
||||
# 2. Install Docker Desktop, reboot, then:
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Docker-Ready"
|
||||
|
||||
# 3. Enable SSH (run enable-vm-ssh.ps1 on VM), then:
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "SSH-Enabled"
|
||||
|
||||
# 4. Deploy ShopDB (run deploy-to-vm.ps1), then:
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "ShopDB-Deployed"
|
||||
```
|
||||
|
||||
### During Development
|
||||
|
||||
```powershell
|
||||
# Before risky changes
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Before-$(Get-Date -Format 'yyyyMMdd-HHmm')"
|
||||
|
||||
# After successful test
|
||||
Remove-VMSnapshot -VMName "ShopDB-Test-VM" -Name "Before-*" -Confirm:$false
|
||||
|
||||
# Weekly: Clean up old test snapshots
|
||||
Get-VMSnapshot -VMName "ShopDB-Test-VM" |
|
||||
Where-Object { $_.Name -like "Before-*" -and $_.CreationTime -lt (Get-Date).AddDays(-7) } |
|
||||
Remove-VMSnapshot -Confirm:$false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with MCP Test Script
|
||||
|
||||
The `test-mcp-servers.ps1` script checks for snapshots:
|
||||
|
||||
```powershell
|
||||
# Run test script
|
||||
.\\.claude\test-mcp-servers.ps1
|
||||
|
||||
# Output includes snapshot status:
|
||||
# [7/7] Checking VM snapshots...
|
||||
# OK: Found 4 snapshot(s)
|
||||
# - ShopDB-Test-VM: Clean-Install (2024-09-08 10:30)
|
||||
# - ShopDB-Test-VM: Docker-Ready (2024-09-08 11:45)
|
||||
# - ShopDB-Test-VM: SSH-Enabled (2024-09-08 12:15)
|
||||
# - ShopDB-Test-VM: ShopDB-Deployed (2024-09-09 09:00)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Cannot Create Snapshot
|
||||
|
||||
**Error:** "The operation cannot be performed while the virtual machine is running"
|
||||
- Some VM configurations prevent live snapshots
|
||||
- **Fix:** Shut down VM first, then create snapshot
|
||||
|
||||
**Error:** "Not enough disk space"
|
||||
- Snapshots require free space on host drive
|
||||
- **Fix:** Delete old snapshots or increase host drive space
|
||||
|
||||
### Cannot Restore Snapshot
|
||||
|
||||
**Error:** "The checkpoint operation failed"
|
||||
- VM may be in saved state
|
||||
- **Fix:** Shut down VM completely, then restore
|
||||
|
||||
### Snapshot Chain Too Deep
|
||||
|
||||
**Error:** "Performance degraded due to snapshot chain"
|
||||
- Too many snapshots slow down VM I/O
|
||||
- **Fix:** Merge snapshots by deleting intermediate ones
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```powershell
|
||||
# Create snapshot
|
||||
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "MySnapshot"
|
||||
|
||||
# List snapshots
|
||||
Get-VMSnapshot -VMName "ShopDB-Test-VM"
|
||||
|
||||
# Restore snapshot
|
||||
Restore-VMSnapshot -Name "MySnapshot" -VMName "ShopDB-Test-VM" -Confirm:$false
|
||||
|
||||
# Delete snapshot
|
||||
Remove-VMSnapshot -Name "MySnapshot" -VMName "ShopDB-Test-VM"
|
||||
|
||||
# Delete all snapshots
|
||||
Get-VMSnapshot -VMName "ShopDB-Test-VM" | Remove-VMSnapshot -Confirm:$false
|
||||
|
||||
# Export VM (with snapshots)
|
||||
Export-VM -Name "ShopDB-Test-VM" -Path "C:\VM-Backups"
|
||||
|
||||
# Get snapshot disk usage
|
||||
Get-VMSnapshot -VMName "ShopDB-Test-VM" |
|
||||
Select-Object Name, @{N='SizeMB';E={(Get-ChildItem $_.Path -Recurse | Measure-Object Length -Sum).Sum / 1MB}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Create baseline snapshots** using recommended schedule
|
||||
2. **Test snapshot restore** to verify it works
|
||||
3. **Run test-mcp-servers.ps1** to verify MCP integration
|
||||
4. **Practice snapshot workflow** with Claude Code
|
||||
5. **Set up automated snapshot cleanup** script for weekly maintenance
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Setup SSH:** `.claude/setup-vm-ssh.md`
|
||||
- **Test MCP Servers:** `.claude/test-mcp-servers.ps1`
|
||||
- **Deploy to VM:** `DEPLOY-TO-VM.md`
|
||||
- **VM Connectivity:** `test-vm-connectivity.ps1`
|
||||
321
.claude/setup/VM-USERS.md
Normal file
321
.claude/setup/VM-USERS.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# VM User Accounts for Testing
|
||||
|
||||
The SFTest VM has two user accounts configured for different testing scenarios.
|
||||
|
||||
---
|
||||
|
||||
## User Accounts
|
||||
|
||||
### 1. SupportUser (Administrator)
|
||||
|
||||
**Username:** SupportUser
|
||||
**Password:** vos313
|
||||
**Privileges:** Administrator
|
||||
**SSH:** Enabled
|
||||
**MCP Server:** `vm` (primary)
|
||||
|
||||
**Use for:**
|
||||
- Installing agent service (requires admin)
|
||||
- Configuring Windows services
|
||||
- Installing software/dependencies
|
||||
- Modifying system settings
|
||||
- Reading system logs
|
||||
- Managing Windows Firewall
|
||||
|
||||
**Example tasks:**
|
||||
```
|
||||
"Install the agent on VM as admin"
|
||||
"Configure Windows Firewall on VM"
|
||||
"Check Windows Event Logs on VM"
|
||||
"Install dependencies on VM"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. shopfloor (Standard User)
|
||||
|
||||
**Username:** shopfloor
|
||||
**Password:** vos313
|
||||
**Privileges:** Standard user (matches shop floor PCs)
|
||||
**SSH:** Enabled
|
||||
**Auto-login:** Yes (automatically logs in on boot/reboot)
|
||||
**MCP Server:** `vm-shopfloor`
|
||||
|
||||
**Use for:**
|
||||
- Testing agent behavior as standard user
|
||||
- Testing tray application (runs as user)
|
||||
- Simulating shop floor environment
|
||||
- Testing operator report submission
|
||||
- Verifying user-level permissions
|
||||
- Testing endpoint collector scenarios
|
||||
|
||||
**Example tasks:**
|
||||
```
|
||||
"Test agent as shopfloor user"
|
||||
"Check if tray is running for shopfloor user"
|
||||
"Submit operator report as shopfloor"
|
||||
"Verify shopfloor can access shared drives"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Configuration
|
||||
|
||||
Both users are configured in `.claude/mcp-servers.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"vm": {
|
||||
"command": "npx",
|
||||
"args": ["...", "--user", "SupportUser", "--password", "vos313"]
|
||||
},
|
||||
"vm-shopfloor": {
|
||||
"command": "npx",
|
||||
"args": ["...", "--user", "shopfloor", "--password", "vos313"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use Each Account
|
||||
|
||||
### Use SupportUser (vm) for:
|
||||
- Initial agent installation
|
||||
- Service management (`sc.exe`, `Get-Service`)
|
||||
- System-level configuration
|
||||
- Installing updates/patches
|
||||
- Deployment tasks
|
||||
- Administrative testing
|
||||
|
||||
### Use shopfloor (vm-shopfloor) for:
|
||||
- **Realistic endpoint testing** (shop floor PCs run as standard users)
|
||||
- Tray application testing (tray runs in user context)
|
||||
- Operator report submission
|
||||
- User-level permissions verification
|
||||
- Non-admin agent behavior
|
||||
- Production environment simulation
|
||||
|
||||
---
|
||||
|
||||
## Testing Workflow
|
||||
|
||||
### Complete Agent Test (Both Users)
|
||||
|
||||
```
|
||||
You: "Test agent installation and operation with both admin and standard user"
|
||||
|
||||
Claude:
|
||||
1. [vm (SupportUser): Install agent service]
|
||||
2. [vm (SupportUser): Start agent service]
|
||||
3. [vm (SupportUser): Verify service running]
|
||||
4. [vm-shopfloor (shopfloor): Check if tray appears]
|
||||
5. [MySQL: Create fleet alert]
|
||||
6. [vm-shopfloor (shopfloor): Verify tray notification]
|
||||
7. [vm-shopfloor (shopfloor): Submit operator report]
|
||||
8. [MySQL: Verify report received]
|
||||
```
|
||||
|
||||
### Tray-Only Testing (Standard User)
|
||||
|
||||
```
|
||||
You: "Test the tray application as a standard user"
|
||||
|
||||
Claude:
|
||||
1. [vm-shopfloor: Check if tray process running]
|
||||
2. [vm-shopfloor: Read tray log file]
|
||||
3. [MySQL: Create test alert]
|
||||
4. [vm-shopfloor: Verify notification appears]
|
||||
5. [vm-shopfloor: Test operator report UI]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SSH Connection Testing
|
||||
|
||||
### Test SupportUser
|
||||
```bash
|
||||
ssh SupportUser@192.168.100.10 "whoami"
|
||||
# Output: SFTest\SupportUser
|
||||
|
||||
ssh SupportUser@192.168.100.10 "net localgroup administrators"
|
||||
# Should show SupportUser in list
|
||||
```
|
||||
|
||||
### Test shopfloor
|
||||
```bash
|
||||
ssh shopfloor@192.168.100.10 "whoami"
|
||||
# Output: SFTest\shopfloor
|
||||
|
||||
ssh shopfloor@192.168.100.10 "net localgroup users"
|
||||
# Should show shopfloor in list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Permission Differences
|
||||
|
||||
| Task | SupportUser | shopfloor |
|
||||
|------|-------------|-----------|
|
||||
| Install service | ✓ Yes | ✗ No |
|
||||
| Start/stop service | ✓ Yes | ✗ No (needs admin) |
|
||||
| Read service logs | ✓ Yes | △ Limited |
|
||||
| Run tray app | ✓ Yes | ✓ Yes |
|
||||
| Submit reports | ✓ Yes | ✓ Yes |
|
||||
| Access user profile | Own only | Own only |
|
||||
| Windows Event Log | ✓ Full access | △ Limited |
|
||||
| Install software | ✓ Yes | ✗ No |
|
||||
| Modify registry | ✓ Yes | △ HKCU only |
|
||||
|
||||
---
|
||||
|
||||
## Realistic Shop Floor Testing
|
||||
|
||||
**Shop floor PCs typically run as standard users**, so testing with the shopfloor account ensures:
|
||||
|
||||
- Agent behavior matches production
|
||||
- Tray permissions are correct
|
||||
- User-level features work
|
||||
- No admin escalation issues
|
||||
- File access permissions correct
|
||||
- Network access verified
|
||||
|
||||
**Best practice:**
|
||||
```
|
||||
1. Install/configure agent as SupportUser (admin)
|
||||
2. Test operation as shopfloor (standard user)
|
||||
3. This matches actual deployment (IT installs, users run)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Claude Code Usage
|
||||
|
||||
### Ask Claude to use specific user:
|
||||
|
||||
**Admin tasks:**
|
||||
```
|
||||
"Install agent on VM" (uses vm/SupportUser by default)
|
||||
"Configure agent service on VM as admin"
|
||||
```
|
||||
|
||||
**Standard user tasks:**
|
||||
```
|
||||
"Check tray status as shopfloor user"
|
||||
"Test operator report submission as standard user"
|
||||
"Verify shopfloor user can see notifications"
|
||||
```
|
||||
|
||||
**Both users:**
|
||||
```
|
||||
"Test complete agent flow from installation to user notification"
|
||||
(Claude will use vm for install, vm-shopfloor for testing)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### shopfloor SSH fails
|
||||
|
||||
**Check if user exists:**
|
||||
```bash
|
||||
ssh SupportUser@192.168.100.10 "net user shopfloor"
|
||||
```
|
||||
|
||||
**Verify password:**
|
||||
```bash
|
||||
ssh shopfloor@192.168.100.10 "echo 'Connected successfully'"
|
||||
```
|
||||
|
||||
**Check SSH is enabled for both users:**
|
||||
```bash
|
||||
# On VM (as admin):
|
||||
Get-LocalGroupMember -Group "Remote Desktop Users"
|
||||
# Should show both users or "Everyone"
|
||||
```
|
||||
|
||||
### Service won't start for shopfloor
|
||||
|
||||
**Expected!** Standard users can't start/stop services. Use SupportUser:
|
||||
```bash
|
||||
ssh SupportUser@192.168.100.10 "sc.exe start ShopDBEndpointAgent"
|
||||
```
|
||||
|
||||
### Tray not visible for shopfloor
|
||||
|
||||
**Check if user is logged in:**
|
||||
```bash
|
||||
ssh shopfloor@192.168.100.10 "query user"
|
||||
```
|
||||
|
||||
**Tray only shows when user has desktop session.**
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
### Why Same Password?
|
||||
|
||||
Both accounts use `vos313` for simplicity in test environment:
|
||||
- VM is on isolated internal network (192.168.100.x)
|
||||
- No internet access
|
||||
- Test environment only
|
||||
- Matches actual shop floor password pattern (simple, memorable)
|
||||
|
||||
### Production Differences
|
||||
|
||||
Production shop floor PCs:
|
||||
- Domain accounts (not local)
|
||||
- Different passwords per user
|
||||
- Group Policy restrictions
|
||||
- Additional security software
|
||||
- Network access controls
|
||||
|
||||
---
|
||||
|
||||
## VM Configuration
|
||||
|
||||
**VM Name:** SFTest (Shop Floor Test)
|
||||
**IP:** 192.168.100.10
|
||||
**OS:** Windows 11
|
||||
**Network:** Internal only (192.168.100.x subnet)
|
||||
**Default User:** shopfloor (auto-login enabled)
|
||||
|
||||
### Auto-Login Configuration
|
||||
|
||||
**shopfloor user automatically logs in** on VM start/reboot. This means:
|
||||
- Tray application starts automatically
|
||||
- No need to manually log in for testing
|
||||
- Matches shop floor PC behavior (kiosk-like setup)
|
||||
- Desktop session always available for tray
|
||||
|
||||
**To test tray after VM restart:**
|
||||
```
|
||||
You: "Restart the VM and verify tray starts automatically"
|
||||
|
||||
Claude:
|
||||
1. [vm (SupportUser): Restart VM]
|
||||
2. [Wait 60 seconds for boot]
|
||||
3. [vm-shopfloor: Check tray process running]
|
||||
4. [vm-shopfloor: Verify tray log shows startup]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Two users = Two test scenarios:**
|
||||
|
||||
1. **SupportUser** - Admin for installation and configuration
|
||||
2. **shopfloor** - Standard user for realistic endpoint testing
|
||||
|
||||
**Both configured in MCP** - Claude can switch between them automatically based on task requirements.
|
||||
|
||||
**Realistic testing** - Matches actual shop floor deployment (IT installs as admin, users run as standard)
|
||||
|
||||
---
|
||||
|
||||
**Updated:** 2026-09-09 (added shopfloor user)
|
||||
36
.claude/setup/enable-vm-ssh.ps1
Normal file
36
.claude/setup/enable-vm-ssh.ps1
Normal file
@@ -0,0 +1,36 @@
|
||||
# Enable SSH Password Authentication on Windows VM
|
||||
# Run this script as Administrator in the VM
|
||||
|
||||
# 1. Set password for SupportUser
|
||||
Write-Host "Setting password for SupportUser..."
|
||||
net user SupportUser vos313
|
||||
|
||||
# 2. Enable password authentication in sshd_config
|
||||
Write-Host "Enabling password authentication..."
|
||||
$sshdConfig = "C:\ProgramData\ssh\sshd_config"
|
||||
|
||||
if (Test-Path $sshdConfig) {
|
||||
# Backup original
|
||||
Copy-Item $sshdConfig "$sshdConfig.backup"
|
||||
|
||||
# Enable password authentication
|
||||
$content = Get-Content $sshdConfig
|
||||
$content = $content -replace '#PasswordAuthentication yes', 'PasswordAuthentication yes'
|
||||
$content = $content -replace 'PasswordAuthentication no', 'PasswordAuthentication yes'
|
||||
$content | Set-Content $sshdConfig
|
||||
|
||||
Write-Host "Updated sshd_config"
|
||||
} else {
|
||||
Write-Host "sshd_config not found at $sshdConfig"
|
||||
}
|
||||
|
||||
# 3. Restart SSH service
|
||||
Write-Host "Restarting SSH service..."
|
||||
Restart-Service sshd
|
||||
|
||||
# 4. Verify service is running
|
||||
Get-Service sshd
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "SSH setup complete!"
|
||||
Write-Host "Test from host: ssh SupportUser@192.168.100.10"
|
||||
221
.claude/setup/quick-start-mcp.ps1
Normal file
221
.claude/setup/quick-start-mcp.ps1
Normal file
@@ -0,0 +1,221 @@
|
||||
# Quick Start MCP Servers for ShopDB Development
|
||||
# Sets up all prerequisites and tests MCP server configuration
|
||||
#
|
||||
# Usage:
|
||||
# .\\.claude\quick-start-mcp.ps1
|
||||
# .\\.claude\quick-start-mcp.ps1 -SkipVMSetup
|
||||
# .\\.claude\quick-start-mcp.ps1 -InstallOnly
|
||||
|
||||
param(
|
||||
[switch]$SkipVMSetup,
|
||||
[switch]$InstallOnly
|
||||
)
|
||||
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "==========================================" -ForegroundColor Cyan
|
||||
Write-Host "ShopDB MCP Quick Start" -ForegroundColor Cyan
|
||||
Write-Host "==========================================" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
|
||||
$installDir = "C:\Users\270015376\Documents"
|
||||
$repoDir = "C:\Users\270015376\Documents\github\flask-shopdb"
|
||||
|
||||
# Check we're in the right directory
|
||||
if ((Get-Location).Path -ne $repoDir) {
|
||||
Write-Host "Switching to flask-shopdb directory..." -ForegroundColor Yellow
|
||||
Set-Location $repoDir
|
||||
}
|
||||
|
||||
# Step 1: Check Node.js/npm
|
||||
Write-Host "[1/6] Checking Node.js/npm..." -ForegroundColor Yellow
|
||||
try {
|
||||
$nodeVersion = node --version
|
||||
$npmVersion = npm --version
|
||||
Write-Host " OK: Node.js $nodeVersion, npm $npmVersion" -ForegroundColor Green
|
||||
} catch {
|
||||
Write-Host " FAIL: Node.js not found" -ForegroundColor Red
|
||||
Write-Host ""
|
||||
Write-Host "Install Node.js from: https://nodejs.org/" -ForegroundColor Yellow
|
||||
Write-Host "After installing, restart this script" -ForegroundColor Yellow
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Step 2: Check/Install Gortex
|
||||
Write-Host "[2/6] Checking Gortex..." -ForegroundColor Yellow
|
||||
$gortexPath = Join-Path $installDir "gortex.exe"
|
||||
if (Test-Path $gortexPath) {
|
||||
try {
|
||||
$gortexVersion = & $gortexPath --version 2>&1
|
||||
Write-Host " OK: Gortex found ($gortexVersion)" -ForegroundColor Green
|
||||
} catch {
|
||||
Write-Host " WARN: Gortex found but may be corrupted" -ForegroundColor Yellow
|
||||
}
|
||||
} else {
|
||||
Write-Host " Installing Gortex..." -ForegroundColor Yellow
|
||||
try {
|
||||
$zipPath = Join-Path $installDir "gortex_windows_amd64.zip"
|
||||
|
||||
# Download latest release
|
||||
Write-Host " Downloading from GitHub..." -ForegroundColor Gray
|
||||
$latestUrl = "https://github.com/zzet/gortex/releases/latest/download/gortex_windows_amd64.zip"
|
||||
Invoke-WebRequest -Uri $latestUrl -OutFile $zipPath -UseBasicParsing
|
||||
|
||||
# Extract
|
||||
Write-Host " Extracting..." -ForegroundColor Gray
|
||||
Expand-Archive -Path $zipPath -DestinationPath $installDir -Force
|
||||
|
||||
# Cleanup
|
||||
Remove-Item $zipPath
|
||||
|
||||
Write-Host " OK: Gortex installed" -ForegroundColor Green
|
||||
} catch {
|
||||
Write-Host " FAIL: Could not install Gortex: $($_.Exception.Message)" -ForegroundColor Red
|
||||
Write-Host " Manual download: https://github.com/zzet/gortex/releases" -ForegroundColor Yellow
|
||||
}
|
||||
}
|
||||
|
||||
# Step 3: Check MySQL/Docker
|
||||
Write-Host "[3/6] Checking MySQL database..." -ForegroundColor Yellow
|
||||
$mysqlRunning = Test-NetConnection -ComputerName 127.0.0.1 -Port 3306 -WarningAction SilentlyContinue -InformationLevel Quiet
|
||||
if ($mysqlRunning) {
|
||||
Write-Host " OK: MySQL is running at 127.0.0.1:3306" -ForegroundColor Green
|
||||
} else {
|
||||
Write-Host " WARN: MySQL not running" -ForegroundColor Yellow
|
||||
Write-Host " Start with: docker compose up -d db" -ForegroundColor Gray
|
||||
|
||||
# Try to start Docker automatically
|
||||
try {
|
||||
$dockerRunning = docker ps 2>&1
|
||||
if ($LASTEXITCODE -eq 0) {
|
||||
Write-Host " Starting MySQL database..." -ForegroundColor Yellow
|
||||
docker compose up -d db
|
||||
Start-Sleep -Seconds 5
|
||||
|
||||
$mysqlRunning = Test-NetConnection -ComputerName 127.0.0.1 -Port 3306 -WarningAction SilentlyContinue -InformationLevel Quiet
|
||||
if ($mysqlRunning) {
|
||||
Write-Host " OK: MySQL started successfully" -ForegroundColor Green
|
||||
}
|
||||
} else {
|
||||
Write-Host " Docker not running. Start Docker Desktop first." -ForegroundColor Yellow
|
||||
}
|
||||
} catch {
|
||||
Write-Host " Docker not available. Install Docker Desktop." -ForegroundColor Yellow
|
||||
}
|
||||
}
|
||||
|
||||
# Step 4: Check MCP packages
|
||||
Write-Host "[4/6] Checking MCP packages..." -ForegroundColor Yellow
|
||||
$packages = @(
|
||||
"@benborla29/mcp-server-mysql",
|
||||
"@agent-infra/mcp-server-browser",
|
||||
"ssh-mcp"
|
||||
)
|
||||
|
||||
foreach ($pkg in $packages) {
|
||||
try {
|
||||
$pkgInfo = npm view $pkg version 2>&1
|
||||
if ($LASTEXITCODE -eq 0) {
|
||||
Write-Host " OK: $pkg available (v$pkgInfo)" -ForegroundColor Green
|
||||
} else {
|
||||
Write-Host " WARN: $pkg not found in registry" -ForegroundColor Yellow
|
||||
}
|
||||
} catch {
|
||||
Write-Host " WARN: Cannot check $pkg" -ForegroundColor Yellow
|
||||
}
|
||||
}
|
||||
|
||||
# Step 5: Check VM (if not skipped)
|
||||
if (-not $SkipVMSetup) {
|
||||
Write-Host "[5/6] Checking Hyper-V VM..." -ForegroundColor Yellow
|
||||
|
||||
$vmIP = "192.168.100.10"
|
||||
$vmReachable = Test-Connection -ComputerName $vmIP -Count 1 -Quiet -ErrorAction SilentlyContinue
|
||||
|
||||
if ($vmReachable) {
|
||||
Write-Host " OK: VM reachable at $vmIP" -ForegroundColor Green
|
||||
|
||||
# Check SSH port
|
||||
$sshOpen = Test-NetConnection -ComputerName $vmIP -Port 22 -WarningAction SilentlyContinue -InformationLevel Quiet
|
||||
if ($sshOpen) {
|
||||
Write-Host " OK: SSH port 22 is open" -ForegroundColor Green
|
||||
} else {
|
||||
Write-Host " WARN: SSH port not open on VM" -ForegroundColor Yellow
|
||||
Write-Host " Run on VM (as Admin): .\\.claude\enable-vm-ssh.ps1" -ForegroundColor Gray
|
||||
}
|
||||
} else {
|
||||
Write-Host " WARN: VM not reachable at $vmIP" -ForegroundColor Yellow
|
||||
Write-Host " Check: VM is running in Hyper-V Manager" -ForegroundColor Gray
|
||||
Write-Host " Check: VM has internal network adapter" -ForegroundColor Gray
|
||||
}
|
||||
} else {
|
||||
Write-Host "[5/6] Skipping VM check (--SkipVMSetup)" -ForegroundColor Gray
|
||||
}
|
||||
|
||||
# Step 6: Verify MCP config
|
||||
Write-Host "[6/6] Verifying MCP configuration..." -ForegroundColor Yellow
|
||||
$mcpConfigPath = Join-Path $repoDir ".claude\mcp-servers.json"
|
||||
if (Test-Path $mcpConfigPath) {
|
||||
$mcpConfig = Get-Content $mcpConfigPath | ConvertFrom-Json
|
||||
$serverCount = $mcpConfig.mcpServers.PSObject.Properties.Count
|
||||
Write-Host " OK: Config file found with $serverCount servers" -ForegroundColor Green
|
||||
|
||||
# List configured servers
|
||||
foreach ($server in $mcpConfig.mcpServers.PSObject.Properties) {
|
||||
Write-Host " - $($server.Name)" -ForegroundColor Gray
|
||||
}
|
||||
} else {
|
||||
Write-Host " FAIL: MCP config not found at $mcpConfigPath" -ForegroundColor Red
|
||||
exit 1
|
||||
}
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "==========================================" -ForegroundColor Cyan
|
||||
Write-Host "Setup Complete" -ForegroundColor Cyan
|
||||
Write-Host "==========================================" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
|
||||
if ($InstallOnly) {
|
||||
Write-Host "Installation complete! (Skipping tests)" -ForegroundColor Green
|
||||
exit 0
|
||||
}
|
||||
|
||||
# Run tests
|
||||
Write-Host "Running MCP test suite..." -ForegroundColor Yellow
|
||||
Write-Host ""
|
||||
|
||||
$testScript = Join-Path $repoDir ".claude\test-mcp-servers.ps1"
|
||||
if (Test-Path $testScript) {
|
||||
if ($SkipVMSetup) {
|
||||
& $testScript -SkipVM
|
||||
} else {
|
||||
& $testScript
|
||||
}
|
||||
} else {
|
||||
Write-Host "Test script not found at $testScript" -ForegroundColor Red
|
||||
exit 1
|
||||
}
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "==========================================" -ForegroundColor Cyan
|
||||
Write-Host "Next Steps" -ForegroundColor Cyan
|
||||
Write-Host "==========================================" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
Write-Host "1. Read the integration guide:" -ForegroundColor White
|
||||
Write-Host " cat .claude\MCP-INTEGRATION-GUIDE.md" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
Write-Host "2. Create VM snapshots (see guide):" -ForegroundColor White
|
||||
Write-Host " cat .claude\VM-SNAPSHOT-GUIDE.md" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
Write-Host "3. Start Claude Code from this directory:" -ForegroundColor White
|
||||
Write-Host " claude" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
Write-Host "4. Test MCP servers with Claude:" -ForegroundColor White
|
||||
Write-Host " - 'List all tasks in the current project'" -ForegroundColor Gray
|
||||
Write-Host " - 'Show me the endpoints table schema'" -ForegroundColor Gray
|
||||
Write-Host " - 'Take a screenshot of localhost:5001'" -ForegroundColor Gray
|
||||
Write-Host " - 'What is the hostname of the VM?'" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
|
||||
exit 0
|
||||
17
.claude/setup/setup-github-token.cmd
Normal file
17
.claude/setup/setup-github-token.cmd
Normal file
@@ -0,0 +1,17 @@
|
||||
@echo off
|
||||
echo GitHub Token Setup for Claude Code
|
||||
echo =====================================
|
||||
echo.
|
||||
echo Paste your GitHub Personal Access Token (starts with ghp_):
|
||||
set /p GITHUB_TOKEN=Token:
|
||||
|
||||
echo.
|
||||
echo Setting environment variable for current session...
|
||||
setx GITHUB_PERSONAL_ACCESS_TOKEN "%GITHUB_TOKEN%"
|
||||
|
||||
echo.
|
||||
echo Done! The token is now set.
|
||||
echo.
|
||||
echo IMPORTANT: Restart Claude Code completely for it to pick up the new token.
|
||||
echo.
|
||||
pause
|
||||
267
.claude/setup/setup-vm-ssh.md
Normal file
267
.claude/setup/setup-vm-ssh.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# Set Up SSH Access to VM for Claude Code
|
||||
|
||||
Guide to configure SSH MCP so Claude can interact with the Windows 11 test VM.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Configure VM (Run as Administrator in VM)
|
||||
|
||||
```powershell
|
||||
# Install OpenSSH Server
|
||||
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
|
||||
|
||||
# Start SSH service
|
||||
Start-Service sshd
|
||||
Set-Service -Name sshd -StartupType 'Automatic'
|
||||
|
||||
# Allow SSH through firewall
|
||||
New-NetFirewallRule -Name sshd -DisplayName 'OpenSSH Server (sshd)' -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22
|
||||
|
||||
# Verify SSH is listening
|
||||
netstat -ano | findstr :22
|
||||
# Should show: TCP 0.0.0.0:22 ... LISTENING
|
||||
|
||||
# Set password for local user (replace "ShopFloor" with actual username)
|
||||
net user ShopFloor YourPassword123
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Test SSH from Host
|
||||
|
||||
```bash
|
||||
# From host PC
|
||||
ssh ShopFloor@192.168.100.10
|
||||
|
||||
# Should connect and show Windows command prompt
|
||||
# If works, type 'exit' to disconnect
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Install SSH MCP Server
|
||||
|
||||
```bash
|
||||
# On host PC
|
||||
npm install -g ssh-mcp
|
||||
|
||||
# Verify installation
|
||||
npm list -g ssh-mcp
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Add to Claude Code Config
|
||||
|
||||
Edit `.claude/mcp-servers.json`:
|
||||
|
||||
```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", "ShopFloor",
|
||||
"--password", "YourPassword123"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Replace "ShopFloor" and "YourPassword123" with actual VM credentials.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Restart Claude Code
|
||||
|
||||
Close and reopen Claude Code completely to load the new MCP server.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Verify SSH MCP Works
|
||||
|
||||
In Claude Code conversation:
|
||||
|
||||
```
|
||||
You: "Run 'hostname' on the VM"
|
||||
|
||||
Claude: [Calls mcp__vm__exec]
|
||||
Claude: "VM hostname: DESKTOP-ABC123"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What Claude Can Do with SSH MCP:
|
||||
|
||||
### Execute Commands:
|
||||
```
|
||||
"Check if agent service is running on VM"
|
||||
"Get the VM's IP configuration"
|
||||
"List running processes on VM"
|
||||
"Read agent logs from VM"
|
||||
```
|
||||
|
||||
### File Operations:
|
||||
```
|
||||
"Copy shopdbagent.exe to VM at C:\Temp"
|
||||
"Read the agent config file from VM"
|
||||
"Upload the latest build to VM"
|
||||
"Download agent logs from VM"
|
||||
```
|
||||
|
||||
### Agent Testing:
|
||||
```
|
||||
"Install the agent on VM"
|
||||
"Start/stop the agent service"
|
||||
"Check if tray is running"
|
||||
"Tail the agent log file"
|
||||
"Verify agent is connecting to http://192.168.100.1:5000"
|
||||
```
|
||||
|
||||
### Integration Testing:
|
||||
```
|
||||
"Create a fleet alert and verify it appears on VM"
|
||||
"Submit operator report from VM and check database"
|
||||
"Test endpoint heartbeat from VM"
|
||||
"Run script on VM and check results in database"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
### Password in Config:
|
||||
- Config file contains plain-text password
|
||||
- Only for test VM on internal network
|
||||
- VM has no internet access (internal network only)
|
||||
- Not a production concern
|
||||
|
||||
### Better: Use SSH Key (Optional)
|
||||
|
||||
**Generate SSH key:**
|
||||
```bash
|
||||
ssh-keygen -t rsa -f ~/.ssh/vm_key
|
||||
```
|
||||
|
||||
**Copy public key to VM:**
|
||||
```powershell
|
||||
# In VM, create .ssh directory
|
||||
mkdir C:\Users\ShopFloor\.ssh
|
||||
|
||||
# Copy contents of ~/.ssh/vm_key.pub to:
|
||||
# C:\Users\ShopFloor\.ssh\authorized_keys
|
||||
```
|
||||
|
||||
**Update .mcp.json:**
|
||||
```json
|
||||
"vm": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"ssh-mcp",
|
||||
"--host", "192.168.100.10",
|
||||
"--user", "ShopFloor",
|
||||
"--key", "C:\\Users\\270015376\\.ssh\\vm_key"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### SSH Connection Refused:
|
||||
```bash
|
||||
# Check SSH service on VM
|
||||
ssh ShopFloor@192.168.100.10
|
||||
# If fails, verify service running:
|
||||
# In VM: Get-Service sshd
|
||||
```
|
||||
|
||||
### Authentication Failed:
|
||||
```bash
|
||||
# Verify password
|
||||
# In VM: net user ShopFloor NewPassword123
|
||||
```
|
||||
|
||||
### Port 22 Blocked:
|
||||
```powershell
|
||||
# In VM, check firewall rule exists
|
||||
Get-NetFirewallRule -Name sshd
|
||||
```
|
||||
|
||||
### MCP Server Not Loading:
|
||||
```bash
|
||||
# Verify ssh-mcp installed
|
||||
npm list -g ssh-mcp
|
||||
|
||||
# Test manually
|
||||
npx -y ssh-mcp --host 192.168.100.10 --user ShopFloor --password Test123
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example Test Workflow
|
||||
|
||||
### Full Agent Deployment Test:
|
||||
|
||||
```
|
||||
You: "Deploy and test the agent on the VM"
|
||||
|
||||
Claude:
|
||||
1. [Builds agent] dotnet publish...
|
||||
2. [SSH: Upload] Copying shopdbagent.exe to VM...
|
||||
3. [SSH: Install] Running installer on VM...
|
||||
4. [SSH: Configure] Setting API endpoint to http://192.168.100.1:5000...
|
||||
5. [SSH: Start] Starting ShopDBEndpointAgent service...
|
||||
6. [SSH: Verify] Checking service status... Running
|
||||
7. [SSH: Logs] Reading agent.log... "Connected to API successfully"
|
||||
8. [MySQL: Create alert] Inserting test fleet alert...
|
||||
9. [Wait 5s]
|
||||
10. [SSH: Check tray] Get-Process shopdb-endpoint-tray... Running
|
||||
11. [SSH: Screenshot] Capturing tray notification...
|
||||
12. ✅ Complete! Agent installed, connected, and received fleet alert.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VM Requirements Summary:
|
||||
|
||||
| Requirement | Status | Command to Check |
|
||||
|-------------|--------|------------------|
|
||||
| OpenSSH Server installed | ⏳ | `Get-WindowsCapability -Online -Name OpenSSH.Server*` |
|
||||
| SSH service running | ⏳ | `Get-Service sshd` |
|
||||
| Port 22 open in firewall | ⏳ | `Get-NetFirewallRule -Name sshd` |
|
||||
| User has password set | ⏳ | `net user ShopFloor` |
|
||||
| Network connectivity | ✅ | `arp -a` shows 192.168.100.10 |
|
||||
| Internal network configured | ✅ | VM has 192.168.100.10 |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps:
|
||||
|
||||
1. Run Step 1 commands in VM (as Administrator)
|
||||
2. Test SSH connection from host (Step 2)
|
||||
3. Install ssh-mcp on host (Step 3)
|
||||
4. Update .claude/mcp-servers.json (Step 4)
|
||||
5. Restart Claude Code (Step 5)
|
||||
6. Test with simple command (Step 6)
|
||||
|
||||
**Ready to proceed?**
|
||||
263
.claude/setup/test-mcp-servers.ps1
Normal file
263
.claude/setup/test-mcp-servers.ps1
Normal file
@@ -0,0 +1,263 @@
|
||||
# Test All MCP Servers for ShopDB Development
|
||||
# Run from flask-shopdb directory to verify all MCP servers are configured and working
|
||||
#
|
||||
# Usage:
|
||||
# .\\.claude\test-mcp-servers.ps1
|
||||
# .\\.claude\test-mcp-servers.ps1 -Verbose
|
||||
# .\\.claude\test-mcp-servers.ps1 -SkipVM
|
||||
|
||||
param(
|
||||
[switch]$SkipVM,
|
||||
[switch]$Verbose
|
||||
)
|
||||
|
||||
$ErrorActionPreference = "Continue"
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "==========================================" -ForegroundColor Cyan
|
||||
Write-Host "ShopDB MCP Server Test Suite" -ForegroundColor Cyan
|
||||
Write-Host "==========================================" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
|
||||
$results = @{}
|
||||
$configPath = Join-Path $PSScriptRoot "mcp-servers.json"
|
||||
|
||||
# Test 1: Configuration File Exists
|
||||
Write-Host "[1/7] Checking MCP configuration..." -ForegroundColor Yellow
|
||||
if (Test-Path $configPath) {
|
||||
$config = Get-Content $configPath | ConvertFrom-Json
|
||||
Write-Host " OK: Config file exists at $configPath" -ForegroundColor Green
|
||||
$results["config"] = $true
|
||||
} else {
|
||||
Write-Host " FAIL: Config file not found at $configPath" -ForegroundColor Red
|
||||
$results["config"] = $false
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Test 2: Gortex MCP Server
|
||||
Write-Host "[2/7] Testing Gortex MCP server..." -ForegroundColor Yellow
|
||||
$gortexPath = "C:\Users\270015376\Documents\gortex.exe"
|
||||
if (Test-Path $gortexPath) {
|
||||
try {
|
||||
$gortexVersion = & $gortexPath --version 2>&1
|
||||
Write-Host " OK: Gortex found at $gortexPath" -ForegroundColor Green
|
||||
if ($Verbose) { Write-Host " Version: $gortexVersion" -ForegroundColor Gray }
|
||||
$results["gortex"] = $true
|
||||
} catch {
|
||||
Write-Host " WARN: Gortex found but cannot execute: $($_.Exception.Message)" -ForegroundColor Yellow
|
||||
$results["gortex"] = $false
|
||||
}
|
||||
} else {
|
||||
Write-Host " FAIL: Gortex not found at $gortexPath" -ForegroundColor Red
|
||||
Write-Host " Download from: https://github.com/zzet/gortex/releases" -ForegroundColor Yellow
|
||||
$results["gortex"] = $false
|
||||
}
|
||||
|
||||
# Test 3: MySQL MCP Server (via npx)
|
||||
Write-Host "[3/7] Testing MySQL MCP server..." -ForegroundColor Yellow
|
||||
try {
|
||||
$npxCheck = Get-Command npx -ErrorAction Stop
|
||||
Write-Host " OK: npx found at $($npxCheck.Source)" -ForegroundColor Green
|
||||
|
||||
# Test MySQL connection
|
||||
$mysqlHost = "127.0.0.1"
|
||||
$mysqlPort = 3306
|
||||
$tcp = Test-NetConnection -ComputerName $mysqlHost -Port $mysqlPort -WarningAction SilentlyContinue -InformationLevel Quiet
|
||||
if ($tcp) {
|
||||
Write-Host " OK: MySQL server is reachable at ${mysqlHost}:${mysqlPort}" -ForegroundColor Green
|
||||
$results["mysql"] = $true
|
||||
} else {
|
||||
Write-Host " WARN: MySQL server not reachable at ${mysqlHost}:${mysqlPort}" -ForegroundColor Yellow
|
||||
Write-Host " Start with: docker compose up -d db" -ForegroundColor Yellow
|
||||
$results["mysql"] = $false
|
||||
}
|
||||
} catch {
|
||||
Write-Host " FAIL: npx not found (Node.js/npm not installed)" -ForegroundColor Red
|
||||
Write-Host " Install from: https://nodejs.org/" -ForegroundColor Yellow
|
||||
$results["mysql"] = $false
|
||||
}
|
||||
|
||||
# Test 4: Browser MCP Server (via npx)
|
||||
Write-Host "[4/7] Testing Browser MCP server..." -ForegroundColor Yellow
|
||||
if ($npxCheck) {
|
||||
try {
|
||||
# Check if package exists
|
||||
$browserPkg = npm view @agent-infra/mcp-server-browser version 2>&1
|
||||
if ($LASTEXITCODE -eq 0) {
|
||||
Write-Host " OK: Browser MCP package exists (version $browserPkg)" -ForegroundColor Green
|
||||
$results["browser"] = $true
|
||||
} else {
|
||||
Write-Host " WARN: Browser MCP package not found in npm registry" -ForegroundColor Yellow
|
||||
$results["browser"] = $false
|
||||
}
|
||||
} catch {
|
||||
Write-Host " WARN: Cannot verify browser MCP package" -ForegroundColor Yellow
|
||||
$results["browser"] = $false
|
||||
}
|
||||
} else {
|
||||
Write-Host " SKIP: npx not available" -ForegroundColor Gray
|
||||
$results["browser"] = $false
|
||||
}
|
||||
|
||||
# Test 5: VM SSH MCP Server
|
||||
if (-not $SkipVM) {
|
||||
Write-Host "[5/7] Testing VM SSH MCP server..." -ForegroundColor Yellow
|
||||
|
||||
# Check VM connectivity
|
||||
$vmIP = "192.168.100.10"
|
||||
$vmUser = "SupportUser"
|
||||
|
||||
# Test network connectivity
|
||||
$ping = Test-Connection -ComputerName $vmIP -Count 1 -Quiet -ErrorAction SilentlyContinue
|
||||
if ($ping) {
|
||||
Write-Host " OK: VM is reachable at $vmIP" -ForegroundColor Green
|
||||
|
||||
# Check SSH port
|
||||
$sshPort = Test-NetConnection -ComputerName $vmIP -Port 22 -WarningAction SilentlyContinue -InformationLevel Quiet
|
||||
if ($sshPort) {
|
||||
Write-Host " OK: SSH port 22 is open on VM" -ForegroundColor Green
|
||||
$results["vm"] = $true
|
||||
} else {
|
||||
Write-Host " WARN: SSH port 22 is not open on VM" -ForegroundColor Yellow
|
||||
Write-Host " Run enable-vm-ssh.ps1 on the VM (as Administrator)" -ForegroundColor Yellow
|
||||
$results["vm"] = $false
|
||||
}
|
||||
} else {
|
||||
Write-Host " FAIL: VM not reachable at $vmIP" -ForegroundColor Red
|
||||
Write-Host " Check: Hyper-V VM is running" -ForegroundColor Yellow
|
||||
Write-Host " Check: VM network adapter connected to internal switch" -ForegroundColor Yellow
|
||||
$results["vm"] = $false
|
||||
}
|
||||
|
||||
# Check ssh-mcp package
|
||||
if ($npxCheck) {
|
||||
try {
|
||||
$sshMcpPkg = npm view ssh-mcp version 2>&1
|
||||
if ($LASTEXITCODE -eq 0) {
|
||||
Write-Host " OK: ssh-mcp package available (version $sshMcpPkg)" -ForegroundColor Green
|
||||
} else {
|
||||
Write-Host " WARN: ssh-mcp package not found" -ForegroundColor Yellow
|
||||
}
|
||||
} catch {
|
||||
Write-Host " WARN: Cannot verify ssh-mcp package" -ForegroundColor Yellow
|
||||
}
|
||||
}
|
||||
|
||||
# Note about dual user setup
|
||||
if ($sshPort) {
|
||||
Write-Host " INFO: Two VM users configured:" -ForegroundColor Cyan
|
||||
Write-Host " - SupportUser (admin) for installation/config" -ForegroundColor Gray
|
||||
Write-Host " - shopfloor (standard user, auto-login) for testing" -ForegroundColor Gray
|
||||
}
|
||||
} else {
|
||||
Write-Host "[5/7] Skipping VM test (use -SkipVM switch)" -ForegroundColor Gray
|
||||
$results["vm"] = "skipped"
|
||||
}
|
||||
|
||||
# Test 6: Hyper-V Status
|
||||
Write-Host "[6/7] Checking Hyper-V VMs..." -ForegroundColor Yellow
|
||||
try {
|
||||
$vms = Get-VM -ErrorAction Stop
|
||||
if ($vms.Count -gt 0) {
|
||||
Write-Host " OK: Found $($vms.Count) VM(s)" -ForegroundColor Green
|
||||
foreach ($vm in $vms) {
|
||||
$stateColor = if ($vm.State -eq "Running") { "Green" } else { "Yellow" }
|
||||
Write-Host " - $($vm.Name): $($vm.State)" -ForegroundColor $stateColor
|
||||
}
|
||||
$results["hyperv"] = $true
|
||||
} else {
|
||||
Write-Host " INFO: No VMs found" -ForegroundColor Gray
|
||||
$results["hyperv"] = $true
|
||||
}
|
||||
} catch {
|
||||
Write-Host " INFO: Cannot use PowerShell Hyper-V cmdlets (need Hyper-V Administrators group)" -ForegroundColor Gray
|
||||
Write-Host " NOTE: VM MCP works via SSH - no admin needed for that!" -ForegroundColor Cyan
|
||||
Write-Host " TIP: Use Hyper-V Manager GUI to view/manage VMs" -ForegroundColor Gray
|
||||
if ($Verbose) { Write-Host " Error: $($_.Exception.Message)" -ForegroundColor Gray }
|
||||
$results["hyperv"] = "no-permission"
|
||||
}
|
||||
|
||||
# Test 7: VM Snapshots
|
||||
Write-Host "[7/7] Checking VM snapshots..." -ForegroundColor Yellow
|
||||
try {
|
||||
$snapshots = Get-VMSnapshot -VMName * -ErrorAction Stop
|
||||
if ($snapshots.Count -gt 0) {
|
||||
Write-Host " OK: Found $($snapshots.Count) snapshot(s)" -ForegroundColor Green
|
||||
foreach ($snap in $snapshots) {
|
||||
Write-Host " - $($snap.VMName): $($snap.Name) ($(Get-Date $snap.CreationTime -Format 'yyyy-MM-dd HH:mm'))" -ForegroundColor Gray
|
||||
}
|
||||
$results["snapshots"] = $true
|
||||
} else {
|
||||
Write-Host " INFO: No snapshots found" -ForegroundColor Gray
|
||||
Write-Host " Create snapshots via Hyper-V Manager GUI (right-click VM -> Checkpoint)" -ForegroundColor Gray
|
||||
$results["snapshots"] = "none"
|
||||
}
|
||||
} catch {
|
||||
Write-Host " INFO: Cannot use PowerShell snapshot cmdlets (need Hyper-V Administrators group)" -ForegroundColor Gray
|
||||
Write-Host " TIP: Use Hyper-V Manager GUI to create/restore snapshots" -ForegroundColor Cyan
|
||||
if ($Verbose) { Write-Host " Error: $($_.Exception.Message)" -ForegroundColor Gray }
|
||||
$results["snapshots"] = "no-permission"
|
||||
}
|
||||
|
||||
# Summary
|
||||
Write-Host ""
|
||||
Write-Host "==========================================" -ForegroundColor Cyan
|
||||
Write-Host "Summary" -ForegroundColor Cyan
|
||||
Write-Host "==========================================" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
|
||||
$passCount = ($results.Values | Where-Object { $_ -eq $true }).Count
|
||||
$totalCount = $results.Count
|
||||
$percentage = [math]::Round(($passCount / $totalCount) * 100)
|
||||
|
||||
foreach ($test in $results.Keys) {
|
||||
$status = $results[$test]
|
||||
$icon = switch ($status) {
|
||||
$true { "OK"; "Green" }
|
||||
$false { "FAIL"; "Red" }
|
||||
"skipped" { "SKIP"; "Gray" }
|
||||
"none" { "INFO"; "Yellow" }
|
||||
"no-permission" { "WARN"; "Yellow" }
|
||||
default { "UNKNOWN"; "Gray" }
|
||||
}
|
||||
Write-Host " $($test.PadRight(15)): $($icon[0])" -ForegroundColor $icon[1]
|
||||
}
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "Overall: $passCount/$totalCount tests passed ($percentage%)" -ForegroundColor $(if ($percentage -ge 80) { "Green" } elseif ($percentage -ge 50) { "Yellow" } else { "Red" })
|
||||
Write-Host ""
|
||||
|
||||
# Next Steps
|
||||
if ($passCount -lt $totalCount) {
|
||||
Write-Host "Next Steps:" -ForegroundColor Yellow
|
||||
Write-Host ""
|
||||
|
||||
if (-not $results["gortex"]) {
|
||||
Write-Host " 1. Install Gortex:" -ForegroundColor White
|
||||
Write-Host " curl -L -o gortex_windows_amd64.zip https://github.com/zzet/gortex/releases/latest/download/gortex_windows_amd64.zip" -ForegroundColor Gray
|
||||
Write-Host " unzip -o gortex_windows_amd64.zip -d C:\Users\270015376\Documents\" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
}
|
||||
|
||||
if (-not $results["mysql"]) {
|
||||
Write-Host " 2. Start MySQL database:" -ForegroundColor White
|
||||
Write-Host " docker compose up -d db" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
}
|
||||
|
||||
if ($results["vm"] -eq $false) {
|
||||
Write-Host " 3. Configure VM SSH:" -ForegroundColor White
|
||||
Write-Host " a. Start VM in Hyper-V Manager" -ForegroundColor Gray
|
||||
Write-Host " b. Run .claude\enable-vm-ssh.ps1 on VM (as Administrator)" -ForegroundColor Gray
|
||||
Write-Host " c. Test: ssh SupportUser@192.168.100.10" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
}
|
||||
}
|
||||
|
||||
Write-Host "To use MCP servers with Claude Code:" -ForegroundColor Cyan
|
||||
Write-Host " 1. Run Claude Code from this directory (flask-shopdb)" -ForegroundColor White
|
||||
Write-Host " 2. MCP servers will auto-load from .claude/mcp-servers.json" -ForegroundColor White
|
||||
Write-Host " 3. Test by asking Claude to use each server" -ForegroundColor White
|
||||
Write-Host ""
|
||||
|
||||
exit $(if ($passCount -eq $totalCount) { 0 } else { 1 })
|
||||
Reference in New Issue
Block a user