diff --git a/IP-ASSIGNMENTS.md b/IP-ASSIGNMENTS.md index f0ed04f..3f8771a 100644 --- a/IP-ASSIGNMENTS.md +++ b/IP-ASSIGNMENTS.md @@ -72,6 +72,7 @@ This document tracks all IP addresses in the homelab infrastructure. | Excalidraw | excalidraw.htsn.io | 10.10.10.206:8080 | Traefik-Primary | | MetaMCP | metamcp.htsn.io | 10.10.10.207:12008 | Traefik-Primary | | n8n | n8n.htsn.io | 10.10.10.207:5678 | Traefik-Primary | +| PA API | pa.htsn.io | 10.10.10.207:8401 | Traefik-Primary (Tailscale only) | | Crafty Controller | mc.htsn.io | 10.10.10.207:8443 | Traefik-Primary | | Plex | plex.htsn.io | 10.10.10.100:32400 | Traefik-Saltbox | | Sonarr | sonarr.htsn.io | 10.10.10.100:8989 | Traefik-Saltbox | @@ -132,6 +133,7 @@ This document tracks all IP addresses in the homelab infrastructure. | Service | Port | Purpose | |---------|------|---------| +| PA API | 8401 | Personal Assistant API (pa.htsn.io) - Tailscale only | | MetaMCP | 12008 | MCP Aggregator/Gateway (metamcp.htsn.io) | | n8n | 5678 | Workflow automation | | Crafty Controller | 8443 | Minecraft server management (mc.htsn.io) | @@ -149,6 +151,16 @@ This document tracks all IP addresses in the homelab infrastructure. | Android Phone | 10.10.10.54 | 8384 | Xxz3jDT4akUJe6psfwZsbZwG2LhfZuDM | | TrueNAS | 10.10.10.200 | 8384 | (check TrueNAS config) | +## Mac Mini Services (10.10.10.125) + +| Service | Port | Purpose | +|---------|------|---------| +| MCP Bridge | 8400 | HTTP bridge for MCP tool execution (PA API backend) | +| Beeper Desktop | 23373 | Message aggregation (Telegram, iMessage, SMS) | +| Proton Bridge IMAP | 1143 | Personal email access | +| Proton Bridge SMTP | 1025 | Personal email sending | +| Syncthing | 8384 | File sync API | + ## Notes - **MTU 9000** (jumbo frames) enabled on storage networks diff --git a/PA-API.md b/PA-API.md new file mode 100644 index 0000000..496a721 --- /dev/null +++ b/PA-API.md @@ -0,0 +1,339 @@ +# Personal Assistant API + +Backend API for the Personal Assistant system - provides Claude-powered voice/text interface to all PA capabilities (calendar, tasks, messages, smart home, etc.). + +--- + +## Quick Reference + +| Setting | Value | +|---------|-------| +| **Domain** | pa.htsn.io | +| **Local IP** | 10.10.10.207:8401 | +| **Server** | docker-host2 (PVE2 VMID 302) | +| **Compose** | `/opt/pa-api/docker-compose.yml` | +| **Access** | Tailscale only (not publicly exposed) | +| **GitHub** | Private repo: `pa-api` | + +--- + +## Architecture + +``` +Android/Telegram + │ + ▼ +┌─────────────────┐ +│ PA API │ ← Claude SDK, model routing +│ docker-host2 │ +│ :8401 │ +└────────┬────────┘ + │ + ┌────┴────┐ + │ │ + ▼ ▼ +┌───────┐ ┌──────────┐ +│ Rube │ │MCP Bridge│ ← Mac Mini (Beeper, Proton, etc.) +│ Exa │ │ :8400 │ +│ etc. │ └──────────┘ +└───────┘ +``` + +**PA API handles:** +- Claude SDK integration (no CLI startup delay) +- Model routing (Haiku/Sonnet/Opus) +- Session management +- Direct API tools (Exa, Ref, Rube, Airtable) + +**MCP Bridge handles:** +- Tools requiring Mac Mini (Beeper, Proton Bridge, filesystem) +- Runs on Mac Mini at 10.10.10.125:8400 + +--- + +## API Endpoints + +| Endpoint | Method | Purpose | +|----------|--------|---------| +| `/chat` | POST | Main query endpoint (streaming SSE) | +| `/health` | GET | Health check | + +### POST /chat + +**Request:** +```json +{ + "message": "What's on my calendar today?", + "session_id": "abc123" +} +``` + +**Response (Server-Sent Events):** +``` +data: {"type": "model", "name": "sonnet"} +data: {"type": "chunk", "text": "You have "} +data: {"type": "chunk", "text": "3 meetings today..."} +data: {"type": "done", "full_text": "You have 3 meetings today..."} +``` + +### Model Routing + +| Query Type | Model | Examples | +|------------|-------|----------| +| Simple facts | Haiku | "How old is X?", "What's 15% of 80?" | +| PA queries | Sonnet | "What's on my calendar?", "Add task" | +| Complex reasoning | Opus | "Help me plan my week" | + +**Override:** Say "Use Opus" to force model selection (sticky per session). + +--- + +## Deployment + +### Docker Compose + +Location: `/opt/pa-api/docker-compose.yml` + +```yaml +version: '3.8' + +services: + pa-api: + image: pa-api:latest + build: . + container_name: pa-api + restart: unless-stopped + ports: + - "8401:8401" + environment: + - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} + - MCP_BRIDGE_URL=http://10.10.10.125:8400 + - EXA_API_KEY=${EXA_API_KEY} + # Add other API keys as needed + volumes: + - ./data:/app/data + networks: + - pa-network + +networks: + pa-network: + driver: bridge +``` + +### Environment Variables + +| Variable | Purpose | +|----------|---------| +| `ANTHROPIC_API_KEY` | Claude API access | +| `MCP_BRIDGE_URL` | Mac Mini bridge endpoint | +| `EXA_API_KEY` | Exa web search | +| `AIRTABLE_API_KEY` | Airtable access | + +Store in `/opt/pa-api/.env` (not committed to git). + +--- + +## Traefik Configuration + +File: `/etc/traefik/conf.d/pa-api.yaml` (on CT 202) + +```yaml +http: + routers: + pa-api: + rule: "Host(`pa.htsn.io`)" + entryPoints: + - websecure + service: pa-api + tls: + certResolver: cloudflare + + services: + pa-api: + loadBalancer: + servers: + - url: "http://10.10.10.207:8401" +``` + +**Note:** This service is Tailscale-only. The Traefik route exists for convenience but should not be exposed publicly via Cloudflare. + +--- + +## Common Tasks + +### Start/Stop Service + +```bash +# SSH to docker-host2 +ssh docker-host2 + +# Start +cd /opt/pa-api && docker-compose up -d + +# Stop +cd /opt/pa-api && docker-compose down + +# View logs +docker logs -f pa-api + +# Restart +docker-compose restart pa-api +``` + +### Update Service + +```bash +ssh docker-host2 +cd /opt/pa-api +git pull +docker-compose build +docker-compose up -d +``` + +### Health Check + +```bash +# From any machine on network +curl http://10.10.10.207:8401/health + +# Test chat endpoint +curl -X POST http://10.10.10.207:8401/chat \ + -H "Content-Type: application/json" \ + -d '{"message": "Hello", "session_id": "test"}' +``` + +--- + +## MCP Bridge (Mac Mini) + +The MCP Bridge runs on Mac Mini and exposes MCP tools as HTTP endpoints. + +| Setting | Value | +|---------|-------| +| **Location** | Mac Mini (10.10.10.125) | +| **Port** | 8400 | +| **Purpose** | Execute MCP tools (Beeper, Proton, TickTick, HA, etc.) | + +### Bridge Endpoints + +| Endpoint | Method | Purpose | +|----------|--------|---------| +| `/tools` | GET | List available tools | +| `/execute` | POST | Execute a tool | +| `/health` | GET | Health check | + +### Start MCP Bridge + +```bash +# SSH to Mac Mini +ssh macmini + +# Start bridge (managed by launchd) +launchctl load ~/Library/LaunchAgents/com.hutson.mcp-bridge.plist + +# Check status +curl http://localhost:8400/health +``` + +--- + +## Integration Points + +### Related Services + +| Service | Relationship | +|---------|--------------| +| n8n | Telegram bot uses n8n → Claude CLI (separate path) | +| MetaMCP | PA API does NOT use MetaMCP (direct MCP Bridge) | +| Home Assistant | Controlled via MCP Bridge | +| Claude-Mem | Shared memory database for context | + +### Clients + +| Client | Connection | +|--------|------------| +| Android App | HTTPS via Tailscale → pa.htsn.io | +| (Future) Web UI | Same endpoint | + +--- + +## Monitoring + +### Health Checks + +```bash +# PA API +curl -s http://10.10.10.207:8401/health | jq + +# MCP Bridge +curl -s http://10.10.10.125:8400/health | jq +``` + +### Logs + +```bash +# PA API logs +ssh docker-host2 'docker logs -f pa-api --tail 100' + +# MCP Bridge logs (Mac Mini) +ssh macmini 'tail -f ~/Library/Logs/mcp-bridge.log' +``` + +--- + +## Troubleshooting + +### PA API Not Responding + +1. Check container status: + ```bash + ssh docker-host2 'docker ps | grep pa-api' + ``` + +2. Check logs for errors: + ```bash + ssh docker-host2 'docker logs pa-api --tail 50' + ``` + +3. Verify network: + ```bash + curl http://10.10.10.207:8401/health + ``` + +### MCP Bridge Not Responding + +1. Check if Mac Mini is reachable: + ```bash + ping 10.10.10.125 + ``` + +2. Check bridge process: + ```bash + ssh macmini 'pgrep -f mcp-bridge' + ``` + +3. Restart bridge: + ```bash + ssh macmini 'launchctl unload ~/Library/LaunchAgents/com.hutson.mcp-bridge.plist' + ssh macmini 'launchctl load ~/Library/LaunchAgents/com.hutson.mcp-bridge.plist' + ``` + +### Model Routing Issues + +- Check Claude API key is valid +- Verify Haiku classifier is responding +- Check session storage for stuck model overrides + +--- + +## Related Documentation + +- [IP-ASSIGNMENTS.md](IP-ASSIGNMENTS.md) - Service IP mapping +- [VMS.md](VMS.md) - docker-host2 VM details +- [TRAEFIK.md](TRAEFIK.md) - Reverse proxy configuration +- [Personal Assistant Project](~/Projects/personal-assistant/CLAUDE.md) - PA system overview +- [Services Matrix](~/Projects/personal-assistant/docs/services-matrix.md) - All MCP tools + +--- + +**Last Updated**: 2026-01-07 diff --git a/README.md b/README.md index ca6140f..885be73 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ Documentation for Hutson's home infrastructure - two Proxmox servers running VMs | [SERVICES.md](SERVICES.md) | Complete service inventory with URLs and credentials | | [TRAEFIK.md](TRAEFIK.md) | Reverse proxy setup, adding services, SSL certificates | | [HOMEASSISTANT.md](HOMEASSISTANT.md) | Home Assistant API, automations, integrations | +| [PA-API.md](PA-API.md) | Personal Assistant API, MCP Bridge, Claude integration | | [SYNCTHING.md](SYNCTHING.md) | File sync across all devices, API access, troubleshooting | | [SALTBOX.md](#) | Media automation stack (Plex, *arr apps) (coming soon) | @@ -83,6 +84,7 @@ Documentation for Hutson's home infrastructure - two Proxmox servers running VMs | **Plex** | Saltbox VM | https://plex.htsn.io | | **Home Assistant** | VM 110 | https://homeassistant.htsn.io | | **Gitea** | VM 300 | https://git.htsn.io | +| **PA API** | docker-host2 | https://pa.htsn.io (Tailscale) | | **Pi-hole** | CT 200 | http://10.10.10.10/admin | | **Traefik** | CT 202 | http://10.10.10.250:8080 |