From 35c66099a5130491cdb0f36647675cc710e1c41d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 9 Apr 2026 14:49:10 +0000 Subject: [PATCH] docs(tasks): Create Task #92 - Trinity Core MCP Gateway Full task definition with 6 phases: 1. Ubuntu Server Setup (detailed checklist created) 2. SSH Infrastructure (claude_executor users) 3. Cloudflare Tunnel 4. MCP Server Development 5. Arbiter Integration (approval workflow) 6. Testing & Monitoring Phase 1 checklist has copy-paste friendly commands for: - Ubuntu install, Cockpit, UFW, fail2ban - Lid switch ignore (shelf mode) - Docker and Node.js Architecture based on Gemini consultations from April 8-9. Chronicler #73 --- .../task-092-trinity-core-mcp-gateway.md | 168 ++++++++++ .../phase-1-ubuntu-setup.md | 287 ++++++++++++++++++ 2 files changed, 455 insertions(+) create mode 100644 docs/tasks-index/task-092-trinity-core-mcp-gateway.md create mode 100644 docs/tasks/task-092-trinity-core/phase-1-ubuntu-setup.md diff --git a/docs/tasks-index/task-092-trinity-core-mcp-gateway.md b/docs/tasks-index/task-092-trinity-core-mcp-gateway.md new file mode 100644 index 0000000..287cae3 --- /dev/null +++ b/docs/tasks-index/task-092-trinity-core-mcp-gateway.md @@ -0,0 +1,168 @@ +--- +task_number: 92 +title: Trinity Core — Desktop MCP Gateway +status: In Progress +priority: P1-High +is_blocker: false +owner: Michael +tags: + - infrastructure + - mcp + - security + - automation +estimated_hours: 8 +--- + +# Task #92: Trinity Core — Desktop MCP Gateway + +## Overview + +A dedicated Ubuntu Server on Michael's HP laptop that acts as an MCP gateway, allowing Claude.ai to execute commands on Firefrost servers with approval workflows. + +**Hardware:** HP Laptop (dedicated, shelf-mode) +**OS:** Ubuntu Server 24.04 LTS +**Codename:** Trinity Core + +## The Vision + +``` +Claude.ai → MCP Request → Laptop (Trinity Core) → SSH → Firefrost Servers + ↓ + Arbiter (Discord Approval) + ↓ + Michael clicks "Approve" + ↓ + Command executes +``` + +No more copy-paste from Claude to MobaXterm. Claude can execute commands directly with Michael's approval. + +## Architecture (Gemini-Approved) + +| Component | Decision | Rationale | +|-----------|----------|-----------| +| MCP Server | Docker container | Isolation — bugs stay contained | +| SSH Keys | One Ed25519 key | `claude_executor` user on all target servers | +| Firewall | UFW | Allow 22, 9090 only; deny all else | +| Security | fail2ban + Cloudflare Access | Defense in depth | +| Approval | Arbiter integration | Don't reinvent — use existing Discord bot | +| Tunnel | cloudflared | Zero incoming ports needed | +| Startup | docker-compose + systemd | Auto-recovery on reboot | +| Monitoring | Uptime Kuma | CPU temp, disk I/O, endpoint health | + +## Implementation Phases + +### Phase 1: Ubuntu Server Setup ⬅️ CURRENT + +**Status:** Ready to begin (laptop is wiped) + +1. [ ] Download Ubuntu Server 24.04 LTS ISO +2. [ ] Flash to USB with Rufus or balenaEtcher +3. [ ] Install Ubuntu Server on HP laptop +4. [ ] During install: enable OpenSSH server +5. [ ] First boot: update system (`apt update && apt upgrade`) +6. [ ] Install Cockpit for web management +7. [ ] Configure UFW firewall +8. [ ] Install fail2ban +9. [ ] Configure lid switch behavior +10. [ ] Install Docker and docker-compose + +**Detailed checklist:** `docs/tasks/task-092-trinity-core/phase-1-ubuntu-setup.md` + +### Phase 2: SSH Infrastructure + +1. [ ] Generate Ed25519 key pair on laptop +2. [ ] Create `claude_executor` user on Command Center +3. [ ] Create `claude_executor` user on TX1 +4. [ ] Create `claude_executor` user on NC1 +5. [ ] Create `claude_executor` user on Panel (if needed) +6. [ ] Add public key to all `authorized_keys` +7. [ ] Test SSH connections +8. [ ] Configure restricted sudo for `claude_executor` + +### Phase 3: Cloudflare Tunnel + +1. [ ] Install cloudflared +2. [ ] Create tunnel in Cloudflare Zero Trust dashboard +3. [ ] Configure tunnel to point to MCP server port +4. [ ] Set up Cloudflare Access policy (Service Token) +5. [ ] Create systemd service for cloudflared +6. [ ] Test tunnel connectivity + +### Phase 4: MCP Server Development + +1. [ ] Scaffold MCP server (Node.js) +2. [ ] Implement SSH command execution +3. [ ] Add Arbiter webhook integration (approval requests) +4. [ ] Handle approval responses +5. [ ] Add command allowlist/denylist +6. [ ] Containerize with Docker +7. [ ] Create docker-compose.yml +8. [ ] Mount SSH keys as read-only volume + +### Phase 5: Arbiter Integration + +1. [ ] Add MCP approval endpoint to Arbiter +2. [ ] Create `#mcp-approvals` Discord channel +3. [ ] Implement approval button UI +4. [ ] Add timeout handling (auto-deny after X minutes) +5. [ ] Implement callback to MCP server +6. [ ] Add audit logging + +### Phase 6: Testing & Monitoring + +1. [ ] Add to Uptime Kuma (endpoint health) +2. [ ] Add CPU temp monitoring +3. [ ] Add disk I/O monitoring +4. [ ] Test full flow: Claude → MCP → Approval → Execute +5. [ ] Test failure scenarios +6. [ ] Document troubleshooting guide + +## Target Servers + +| Server | IP | claude_executor needed | +|--------|-----|------------------------| +| Command Center | 63.143.34.217 | Yes | +| TX1 Dallas | 38.68.14.26 | Yes | +| NC1 Charlotte | 216.239.104.130 | Yes | +| Panel VPS | 45.94.168.138 | Maybe | +| Dev Panel | 64.50.188.128 | Maybe | + +## Security Model + +**Zero-Trust Principles:** +- Cloudflare Access validates identity before traffic reaches laptop +- MCP server validates request format/signature +- Arbiter requires Discord button approval for execution +- `claude_executor` has restricted sudo (no root) +- SSH keys mounted read-only in container +- All commands logged for audit + +**Command Classification:** +- **Safe:** Read-only commands (ls, cat, systemctl status) — maybe auto-approve +- **Moderate:** Service restarts, git operations — require approval +- **Dangerous:** File deletion, user management — require approval + confirmation + +## Related Tasks + +- **Task #93:** Trinity Codex (RAG knowledge base) — could query via MCP +- **Task #94:** Global Restart Scheduler — could trigger via MCP +- **Task #87:** Arbiter lifecycle handlers — approval system extends this + +## Consultations + +- `docs/consultations/gemini-claude-code-workflow-2026-04-08.md` — Original architecture +- `docs/consultations/gemini-task-92-ubuntu-setup-2026-04-09.md` — Implementation guidance + +## Success Criteria + +- [ ] Laptop runs Ubuntu Server, accessible via Cockpit +- [ ] Claude.ai can send MCP requests through Cloudflare Tunnel +- [ ] Approval buttons appear in Discord +- [ ] Commands execute on target servers after approval +- [ ] Full audit trail exists +- [ ] System auto-recovers from reboots + +--- + +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️ diff --git a/docs/tasks/task-092-trinity-core/phase-1-ubuntu-setup.md b/docs/tasks/task-092-trinity-core/phase-1-ubuntu-setup.md new file mode 100644 index 0000000..33d7f2f --- /dev/null +++ b/docs/tasks/task-092-trinity-core/phase-1-ubuntu-setup.md @@ -0,0 +1,287 @@ +# Task #92 Phase 1: Ubuntu Server Setup + +**Status:** Ready to begin +**Hardware:** HP Laptop +**Target OS:** Ubuntu Server 24.04 LTS + +--- + +## Step 1: Create Bootable USB + +**On another computer:** + +1. Download Ubuntu Server 24.04 LTS: + https://ubuntu.com/download/server + +2. Download Rufus (Windows): + https://rufus.ie/ + +3. Flash the ISO to USB: + - Insert USB drive (8GB+) + - Open Rufus + - Select the USB drive + - Select the Ubuntu ISO + - Click Start + - Wait for completion + +--- + +## Step 2: Install Ubuntu Server + +**On the HP laptop:** + +1. Insert USB drive +2. Power on, press F9 (or F12/ESC) for boot menu +3. Select USB drive +4. Follow installer: + +| Screen | Selection | +|--------|-----------| +| Language | English | +| Keyboard | English (US) | +| Install type | Ubuntu Server | +| Network | Use DHCP (auto) | +| Proxy | Leave blank | +| Mirror | Default | +| Storage | Use entire disk | +| Your name | michael | +| Server name | trinity-core | +| Username | michael | +| Password | [your choice] | +| OpenSSH | ✅ Install OpenSSH server | +| Snaps | Skip (none needed) | + +5. Wait for install to complete +6. Remove USB, reboot + +--- + +## Step 3: First Boot — System Update + +SSH in from your main PC, or use the laptop directly: + +```bash +sudo apt update +``` + +```bash +sudo apt upgrade -y +``` + +```bash +sudo reboot +``` + +--- + +## Step 4: Install Cockpit (Web Management) + +```bash +sudo apt install cockpit -y +``` + +```bash +sudo systemctl enable --now cockpit.socket +``` + +**Access:** https://[laptop-ip]:9090 +**Login:** michael / [your password] + +--- + +## Step 5: Configure UFW Firewall + +```bash +sudo apt install ufw -y +``` + +```bash +sudo ufw default deny incoming +``` + +```bash +sudo ufw default allow outgoing +``` + +```bash +sudo ufw allow 22/tcp +``` + +```bash +sudo ufw allow 9090/tcp +``` + +```bash +sudo ufw enable +``` + +```bash +sudo ufw status +``` + +**Expected output:** +``` +Status: active + +To Action From +-- ------ ---- +22/tcp ALLOW Anywhere +9090/tcp ALLOW Anywhere +``` + +--- + +## Step 6: Install fail2ban + +```bash +sudo apt install fail2ban -y +``` + +```bash +sudo systemctl enable fail2ban +``` + +```bash +sudo systemctl start fail2ban +``` + +```bash +sudo fail2ban-client status +``` + +--- + +## Step 7: Configure Lid Switch (Shelf Mode) + +Edit the config: + +```bash +sudo nano /etc/systemd/logind.conf +``` + +Find and uncomment/change this line: +``` +HandleLidSwitch=ignore +``` + +Save (Ctrl+O, Enter, Ctrl+X), then: + +```bash +sudo systemctl restart systemd-logind +``` + +**Test:** Close the lid — laptop should stay on. + +--- + +## Step 8: Install Docker + +```bash +sudo apt install ca-certificates curl -y +``` + +```bash +sudo install -m 0755 -d /etc/apt/keyrings +``` + +```bash +sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc +``` + +```bash +sudo chmod a+r /etc/apt/keyrings/docker.asc +``` + +```bash +echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +``` + +```bash +sudo apt update +``` + +```bash +sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y +``` + +Add yourself to docker group (no sudo needed for docker commands): + +```bash +sudo usermod -aG docker michael +``` + +**Log out and back in**, then test: + +```bash +docker run hello-world +``` + +--- + +## Step 9: Install Node.js (for MCP development) + +```bash +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +``` + +```bash +sudo apt install nodejs -y +``` + +```bash +node --version +``` + +```bash +npm --version +``` + +--- + +## Step 10: Verify Installation + +Run these checks: + +```bash +echo "=== System ===" && uname -a +``` + +```bash +echo "=== Cockpit ===" && systemctl status cockpit.socket --no-pager +``` + +```bash +echo "=== UFW ===" && sudo ufw status +``` + +```bash +echo "=== fail2ban ===" && sudo fail2ban-client status +``` + +```bash +echo "=== Docker ===" && docker --version +``` + +```bash +echo "=== Node ===" && node --version +``` + +--- + +## Phase 1 Complete Checklist + +- [ ] Ubuntu Server 24.04 installed +- [ ] SSH working from main PC +- [ ] System updated +- [ ] Cockpit accessible at :9090 +- [ ] UFW configured (22, 9090 only) +- [ ] fail2ban running +- [ ] Lid switch ignored (shelf mode) +- [ ] Docker installed and working +- [ ] Node.js 20.x installed + +**Next:** Phase 2 — SSH Infrastructure + +--- + +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️