diff --git a/docs/infrastructure/trinity-core.md b/docs/infrastructure/trinity-core.md index 220b1c0..b82dbc7 100644 --- a/docs/infrastructure/trinity-core.md +++ b/docs/infrastructure/trinity-core.md @@ -2,15 +2,18 @@ ## Overview -Trinity Core is a Raspberry Pi 4B running in Michael's home network, providing a secure bridge for Claude to execute commands on Firefrost infrastructure. +Trinity Core is a Raspberry Pi 4B running in Michael's home network, providing a secure bridge for Claude to execute commands on Firefrost infrastructure. As of v2.1.0, Trinity Core can also audit itself via local execution. **Deployed:** April 11, 2026 by Chronicler #76 +**v2.1.0:** April 11, 2026 by Chronicler #78 (local execution, git version control) ## Hardware -- **Device:** Raspberry Pi 4B (4GB) -- **Storage:** 16GB SD card -- **OS:** Raspberry Pi OS Lite (64-bit) +- **Device:** Raspberry Pi 4B (8GB) +- **Storage:** 16GB SD card (4.4GB used, 33%) +- **OS:** Debian GNU/Linux 13 (Trixie) aarch64 +- **Kernel:** 6.12.75+rpt-rpi-v8 +- **CPU:** Cortex-A72, 4 cores - **Hostname:** `trinity-core` - **Local access:** `ssh claude_executor@trinity-core.local` - **Network:** WiFi (TheDungeon) with ethernet backup option @@ -19,51 +22,87 @@ Trinity Core is a Raspberry Pi 4B running in Michael's home network, providing a ``` Claude → mcp.firefrostgaming.com → Cloudflare Tunnel → Trinity Core → SSH → Target Server + → local exec (trinity-core) ``` ## Endpoint - **URL:** `https://mcp.firefrostgaming.com` -- **Health check:** `GET /` (no auth) -- **List servers:** `GET /servers` (requires auth) -- **Execute command:** `POST /exec` (requires auth) +- **MCP SSE:** `GET /mcp` (Claude.ai connector) +- **MCP Messages:** `POST /mcp/messages` (Claude.ai connector) +- **OAuth Discovery:** `GET /.well-known/oauth-protected-resource` ## Authentication -- **Type:** Bearer token +- **Type:** Bearer token (via OAuth shim for Claude.ai) - **Token:** `FFG-Trinity-2026-Core-Access` -- **Header:** `Authorization: Bearer FFG-Trinity-2026-Core-Access` +- **OAuth Client ID:** `trinity-core` +- **OAuth Client Secret:** `FFG-Trinity-2026-Core-Access` ## Registered Servers -| Name | Host | User | -|------|------|------| -| command-center | 63.143.34.217 | root | -| tx1-dallas | 38.68.14.26 | root | -| nc1-charlotte | 216.239.104.130 | root | -| panel-vps | 45.94.168.138 | root | -| dev-panel | 64.50.188.128 | root | -| wiki-vps | 64.50.188.14 | architect | -| services-vps | 38.68.14.188 | root | +| Name | Host | User | Type | +|------|------|------|------| +| command-center | 63.143.34.217 | root | SSH | +| tx1-dallas | 38.68.14.26 | root | SSH | +| nc1-charlotte | 216.239.104.130 | root | SSH | +| panel-vps | 45.94.168.138 | root | SSH | +| dev-panel | 64.50.188.128 | root | SSH | +| wiki-vps | 64.50.188.14 | architect | SSH | +| services-vps | 38.68.14.188 | root | SSH | +| trinity-core | localhost | claude_executor | Local | -## Usage Examples +## MCP Tools -### Health check +| Tool | Description | +|------|-------------| +| `list_servers` | Returns available Firefrost servers | +| `run_command` | Execute command on any server (SSH or local) | + +## Source Code + +**Git repo:** `firefrost-services` → `services/trinity-core/` + +**Production location:** `/home/claude_executor/mcp-server/` on the Pi + +### Deployment Procedure + +1. Edit code in `firefrost-services/services/trinity-core/` +2. Commit and push to Gitea +3. SSH to the Pi: ```bash -curl https://mcp.firefrostgaming.com +ssh claude_executor@trinity-core.local ``` -### List servers +4. Back up current version: ```bash -curl -H "Authorization: Bearer FFG-Trinity-2026-Core-Access" https://mcp.firefrostgaming.com/servers +cd ~/mcp-server +cp index.js index.js.bak ``` -### Execute command +5. Fetch new code from Gitea: ```bash -curl -X POST https://mcp.firefrostgaming.com/exec \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer FFG-Trinity-2026-Core-Access" \ - -d '{"server":"command-center","command":"hostname"}' +curl -s -H "Authorization: token e0e330cba1749b01ab505093a160e4423ebbbe36" \ + "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-services/raw/services/trinity-core/index.js?ref=main" \ + -o index.js +``` + +6. Check if package.json changed (if so, run npm install): +```bash +curl -s -H "Authorization: token e0e330cba1749b01ab505093a160e4423ebbbe36" \ + "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-services/raw/services/trinity-core/package.json?ref=main" \ + -o package.json.new +diff package.json package.json.new && rm package.json.new || (mv package.json.new package.json && npm install) +``` + +7. Restart service: +```bash +sudo systemctl restart mcp-server +``` + +8. Verify: +```bash +sudo systemctl status mcp-server ``` ## Services @@ -71,7 +110,7 @@ curl -X POST https://mcp.firefrostgaming.com/exec \ Both services are enabled and auto-start on boot: - **cloudflared** — Cloudflare Tunnel to expose MCP endpoint -- **mcp-server** — Node.js Express server handling requests +- **mcp-server** — Node.js Express server (v2.1.0, SDK 1.29.0) ### Service management ```bash @@ -94,6 +133,7 @@ tail -f ~/mcp-server/command.log | File | Path | |------|------| | MCP server code | `/home/claude_executor/mcp-server/index.js` | +| Package manifest | `/home/claude_executor/mcp-server/package.json` | | Command log | `/home/claude_executor/mcp-server/command.log` | | Cloudflare config | `/etc/cloudflared/config.yml` | | Cloudflare credentials | `/etc/cloudflared/*.json` | @@ -105,9 +145,20 @@ tail -f ~/mcp-server/command.log - **Tunnel ID:** 446d70b0-abd1-4ec7-8e06-6c277f99cbc7 - **Routes:** mcp.firefrostgaming.com → localhost:3000 +## Version History + +| Version | Date | Chronicler | Changes | +|---------|------|------------|---------| +| 1.0.0 | Apr 10, 2026 | #76 The Bridgekeeper | Initial deployment, SSH to 7 servers | +| 2.0.0 | Apr 11, 2026 | #77 The Socket | Claude.ai MCP connector, OAuth shim, SDK 1.29.0 | +| 2.1.0 | Apr 11, 2026 | #78 | Local self-execution, added to firefrost-services repo | + ## Future Enhancements +- [x] ~~Claude MCP connector integration~~ (v2.0.0) +- [x] ~~Self-audit capability~~ (v2.1.0) +- [x] ~~Git version control~~ (v2.1.0) - [ ] Discord notifications for command execution -- [ ] Claude MCP connector integration - [ ] Command allowlist/categories - [ ] Rate limiting +- [ ] Move token to environment variable