ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reorganize repository structure and clean up documentation

Browse Source 
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
2026-09-11 15:45:05 -04:00
parent 0b252db7d2
commit bd48814021
57 changed files with 11978 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

716
.claude/setup/MCP-COORDINATOR-CONNECTION-GUIDE.md Normal file
View 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