corvid/CLAUDE.md

# 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`:

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

```bash
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 via Forgejo:

```
# requirements.txt
corvid @ git+https://forgejo.welvaert.org/caoimhinr/corvid.git@main
```

Local dev: `pip install -e ~/Projects/corvid`

**Push corvid to Forgejo before rebuilding the dashboard image** — the Docker
build pulls `@main` at build time. See `homelab-dashboard/CLAUDE.md` for the
full deploy procedure.

## Local dev

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

## IaC sync

Corvid runs embedded inside the homelab-dashboard Docker image — it is not deployed
as a standalone service via Ansible. However, its config surface (env vars, ports,
API key) is reflected in `pve/ansible/roles/homedash/templates/env.j2` and
`pve/ansible/host_vars/hetzner.yml`. If corvid's env requirements change (new vars,
renamed keys), update those files to prevent drift flagged by the compliance runner.

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