firefrost-operations-manual/docs/infrastructure/trinity-core.md

# Trinity Core MCP Gateway

## 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. 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 (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

## Architecture

```
Claude → mcp.firefrostgaming.com → Cloudflare Tunnel → Trinity Core → SSH → Target Server
                                                                      → local exec (trinity-core)
```

## Endpoint

- **URL:** `https://mcp.firefrostgaming.com`
- **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 (via OAuth shim for Claude.ai)
- **Token:** `FFG-Trinity-2026-Core-Access`
- **OAuth Client ID:** `trinity-core`
- **OAuth Client Secret:** `FFG-Trinity-2026-Core-Access`

## Registered Servers

| 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 |

## MCP Tools

| 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
ssh claude_executor@trinity-core.local
```

4. Back up current version:
```bash
cd ~/mcp-server
cp index.js index.js.bak
```

5. Fetch new code from Gitea:
```bash
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

Both services are enabled and auto-start on boot:

- **cloudflared** — Cloudflare Tunnel to expose MCP endpoint
- **mcp-server** — Node.js Express server (v2.1.0, SDK 1.29.0)

### Service management
```bash
sudo systemctl status cloudflared
sudo systemctl status mcp-server
sudo systemctl restart mcp-server
```

## Logging

Command log location: `/home/claude_executor/mcp-server/command.log`

```bash
cat ~/mcp-server/command.log
tail -f ~/mcp-server/command.log
```

## File Locations

| 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` |
| SSH keys | `/home/claude_executor/.ssh/` |

## Cloudflare Tunnel

- **Tunnel name:** trinity-core
- **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
- [ ] Command allowlist/categories
- [ ] Rate limiting
- [ ] Move token to environment variable