37b2c21720
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>
87 lines
2.4 KiB
Markdown
87 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.
|