88 lines
2.4 KiB
Markdown
88 lines
2.4 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 as an editable pip install:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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:
|
||
|
|
|
||
|
|
```dockerfile
|
||
|
|
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
|
||
|
|
|
||
|
|
```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.
|