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
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?**
|
||||
Reference in New Issue
Block a user