caoimhinr 37b2c21720 feat: initial corvid — standalone ticket service extracted from homelab-dashboard

Extracts the ticket/attachment system into a reusable pip-installable package.
Centralises homelab MCP server (tickets, attachments, system logs) here.

- corvid package: models, router (make_router factory), config, standalone main
- Alembic migration chain for fresh standalone deployments
- Docker Compose for standalone deployment (port 8090)
- mcp_server.py: moved from homelab-dashboard, CORVID_REPO_PATH configurable

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-25 19:23:07 +02:00

2.4 KiB

Raw Blame History

corvid

Standalone ticket-management service for AI agents. FastAPI + Postgres + MCP server.

Extracted from homelab-dashboard — the homelab-dashboard app continues to use corvid as a pip package (Option A integration).

Package

corvid/
  models.py    — Ticket, TicketAttachment, Base (SQLAlchemy ORM)
  router.py    — make_router(api_key, get_db, require_user=None) → APIRouter
  config.py    — DATABASE_URL, TICKETS_API_KEY env vars
  main.py      — standalone FastAPI app (no web UI)
  database.py  — engine, get_db
alembic/       — migration chain for standalone deployments
mcp_server.py  — FastMCP server; primary agent interface

MCP server

mcp_server.py is the centralized homelab MCP server. It exposes:

Ticket CRUD + attachments (via HOMEDASH_URL API)
Homelab system logs (/api/logs)

Configure in ~/.claude/mcp.json:

"homelab-tickets": {
  "command": "python3",
  "args": ["/home/caoimhinr/Projects/corvid/mcp_server.py"],
  "env": {
    "HOMEDASH_URL":   "https://homedash.welvaert.org",
    "HOMEDASH_API_KEY": "<TICKETS_API_KEY>"
  }
}

TICKETS_API_KEY value is in pve/ansible/host_vars/hetzner.yml (gitignored).

Standalone deployment

cp .env.example .env   # set DATABASE_URL and TICKETS_API_KEY
docker compose up -d

Default port: 8090 (maps to internal 8080).

homelab-dashboard integration

The dashboard depends on corvid as an editable pip install:

# Local dev
pip install -e ~/Projects/corvid

# VPS deploy — corvid is rsynced alongside the dashboard, then installed
rsync -az ~/Projects/corvid/ root@157.180.29.73:/opt/corvid/
ssh root@157.180.29.73 'pip install -e /opt/corvid'

The dashboard's Dockerfile copies corvid source before installing:

COPY ../corvid/ /tmp/corvid/      # requires parent-dir build context
RUN pip install --no-cache-dir /tmp/corvid/

See homelab-dashboard/CLAUDE.md for the full deploy procedure.

Local dev

pip install -e ".[dev,mcp]"
TICKETS_API_KEY="" DATABASE_URL="sqlite+aiosqlite:///dev.db" \
  uvicorn corvid.main:app --reload --port 8090

DB migrations

Alembic runs at startup (entrypoint.sh). Add new migrations in alembic/versions/ following the NNNN_<slug>.py naming convention.

The dashboard keeps its own separate migration chain — corvid's migrations are only for fresh standalone deployments.

2.4 KiB Raw Blame History