80 lines
2.2 KiB
Markdown
80 lines
2.2 KiB
Markdown
# 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
|
|
```
|
|
|
|
## 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.
|