Latte
f4d2dcb1d8
Add an opt-in streamable-HTTP transport alongside the default stdio, so familiar can be reached from a home lab over HTTPS behind a TLS reverse proxy. - config.http_settings(): env-driven transport/host/port/path/token settings. - serve.run(): dispatch stdio vs http; fail closed on a non-loopback bind without a bearer token (FAMILIAR_ALLOW_INSECURE_BIND escape hatch). - server.build_http_auth(): FastMCP StaticTokenVerifier bearer gate; add an unauthenticated /healthz route for container/proxy probes. - `familiar serve` CLI alias; clean exit on InsecureBind. - docker/Dockerfile (multi-stage, non-root) + hardened docker-compose.yml (read-only rootfs, cap_drop ALL, no-new-privileges, Traefik TLS labels), .dockerignore, .env.example. Token store mounts at /data; writes off by default. - .gitea/workflows/docker.yml: build + smoke-test, opt-in image publish. - docs/deployment.md + README/CLAUDE.md notes; tests for settings, fail-closed validation, and the bearer verifier.
131 lines
6.8 KiB
Markdown
131 lines
6.8 KiB
Markdown
# familiar
|
||
|
||
> Your familiar across New Eden — an EVE Online MCP server that lets a local AI see your whole account and the universe, and act on your behalf when you ask.
|
||
|
||
In EVE, your familiar isn't a cat on the windowsill. It's the companion that rides along through New Eden, sees what you see, remembers what you can't, and fetches — or does — whatever you ask. `familiar` is exactly that: an [MCP](https://modelcontextprotocol.io) server that gives a local AI (Claude Code, Claude Desktop, Cowork) a complete window into your EVE Online account and the entire game universe, plus hands to act on it.
|
||
|
||
Ask your familiar where your assets are, what your skill queue looks like, what Tritanium sells for in Jita, the safest route to a lowsec system, or whether a fit is worth building — and have it set a waypoint or draft a mail when you say so. It looks, it finds, it reports back, and it acts when asked.
|
||
|
||
## Principles
|
||
|
||
- **Safe by default.** Reading is free; every *write* — sending mail, setting waypoints, editing contacts/fittings/PI, fleet commands — is previewed before it runs (nothing happens without `confirm=true`) and recorded in an audit log. Writes are on by default but can be turned off entirely with `familiar writes disable`. The AI can see everything and changes nothing without your explicit confirm.
|
||
- **Local-first.** Runs on your own machine. Your refresh token and account data never leave your control.
|
||
- **Everything, eventually.** The goal is full coverage: the ESI scopes you grant (character *and* corp, read and write), plus the complete static universe. Built in phases so it actually ships.
|
||
|
||
## How it works
|
||
|
||
Two data sources sit behind the server:
|
||
|
||
- **ESI** (the [EVE Swagger Interface](https://esi.evetech.net/)) — the official REST API. Public endpoints (market, universe, industry indices) need no login. Character and corp data (wallet, assets, skills, industry, contracts, mail, location, and more) come through EVE SSO with **read and write OAuth2 scopes** across both character and corp; write scopes power the opt-in actions.
|
||
- **SDE** (the [Static Data Export](https://developers.eveonline.com/resource/resources)) — the full static dataset of items, blueprints, systems and stations, cached locally for fast lookups and anything name- or recipe-based.
|
||
|
||
Built in **Python with FastMCP**, OAuth via PKCE with a localhost callback, refresh token stored encrypted on disk. ESI `Expires` headers are respected for caching, the rolling ESI error limit is honored with back-off, and (eventually) the SDE is loaded into a local store.
|
||
|
||
## Setup
|
||
|
||
Requires [uv](https://docs.astral.sh/uv/).
|
||
|
||
```bash
|
||
uv sync # install
|
||
uv run familiar login # browser EVE SSO login; run once per character
|
||
uv run familiar status # list logged-in characters
|
||
```
|
||
|
||
Re-run `login` for each character (switch EVE accounts in the browser as needed); they all live in one encrypted store. Changing the requested scopes requires logging in again.
|
||
|
||
### Offline SDE (optional)
|
||
|
||
For network-free item / system / station lookups, install a local copy of EVE's Static Data Export (the Fuzzwork SQLite conversion):
|
||
|
||
```bash
|
||
uv run familiar sde download # download + decompress the SDE (a few hundred MB)
|
||
uv run familiar sde status # show whether it's installed and where
|
||
```
|
||
|
||
Once present, `get_item` / `get_system` / `get_station` serve from it without hitting ESI; familiar falls back to ESI whenever the SDE is absent or doesn't know the id.
|
||
|
||
### Connect to Claude
|
||
|
||
Claude Code:
|
||
|
||
```bash
|
||
claude mcp add familiar -- uv --directory /path/to/familiar run familiar
|
||
```
|
||
|
||
Claude Desktop — add this to `claude_desktop_config.json`:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"familiar": {
|
||
"command": "uv",
|
||
"args": ["--directory", "/path/to/familiar", "run", "familiar"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
Then ask in natural language — "what's Tritanium worth in Jita?", "how much ISK across all my characters?", "where are my characters?".
|
||
|
||
### Write actions
|
||
|
||
Write actions (send mail, set waypoints, edit contacts/fittings, fleet commands) are **on by default**. Even so, every write tool returns a dry-run preview unless called with `confirm=true` per call, and each executed write is recorded in an audit log — so nothing changes by accident.
|
||
|
||
To opt out and block all writes globally:
|
||
|
||
```bash
|
||
uv run familiar writes disable # turn writes off (uv run familiar writes enable to re-allow)
|
||
```
|
||
|
||
### Run it publicly (HTTP over Docker)
|
||
|
||
By default familiar talks **stdio** to a local client. It can also serve
|
||
**streamable HTTP** for reaching it from your home lab over HTTPS — opt-in,
|
||
behind a TLS reverse proxy, gated by a bearer token:
|
||
|
||
```bash
|
||
cp .env.example .env # set FAMILIAR_HTTP_AUTH_TOKEN + FAMILIAR_DOMAIN
|
||
docker compose up -d --build # Traefik/Caddy terminates TLS on the `proxy` network
|
||
```
|
||
|
||
Secure by default: it binds loopback unless told otherwise, **refuses to start**
|
||
on a public interface without a bearer token, and ships with writes off. Log in
|
||
once on a machine with a browser (`familiar login`) and mount that token store
|
||
into the container. Full walkthrough — token, TLS, client wiring — in
|
||
[docs/deployment.md](docs/deployment.md).
|
||
|
||
## Roadmap
|
||
|
||
Built in phases. Each phase is independently useful, so the project stays shippable.
|
||
|
||
**Phase 0 — Skeleton**
|
||
- Repo, project scaffold, FastMCP server that starts and exposes a health/ping tool.
|
||
- App registered on [developers.eveonline.com](https://developers.eveonline.com/).
|
||
|
||
**Phase 1 — Public lookups (no auth)**
|
||
- Market: prices and order book for any item in any hub, spreads between hubs.
|
||
- Universe via SDE: items, systems, stations, security, basic route/jumps.
|
||
- Quick win: useful before any OAuth complexity exists.
|
||
|
||
**Phase 2 — Account read (OAuth)**
|
||
- EVE SSO login flow, encrypted refresh token storage.
|
||
- Wallet, assets (search across characters), skills + skill queue, current location and clones.
|
||
|
||
**Phase 3 — Industry & contracts**
|
||
- Industry jobs, blueprints (SDE-backed), manufacturing cost/profit lookups.
|
||
- Personal and corp contracts, market orders.
|
||
|
||
**Phase 4 — Everything else**
|
||
- Mail, planetary interaction, loyalty points, fittings, corp roles.
|
||
- zKillboard integration for kill/PvP data.
|
||
|
||
**Phase 5 — Polish**
|
||
- Caching, error-limit safety, packaging, setup docs. Optional: prep a public, generic single-user release as a portfolio case.
|
||
|
||
## Status
|
||
|
||
Phases 0–4 done on `dev`, plus Phase 5 caching/back-off and docs: public market & universe lookups; EVE SSO (PKCE) login with an encrypted, multi-character token store; full character **and** corp coverage across skills, wallet, assets, industry, trade, structures, killmails, profile, fleet, mail, contacts, fittings, PI and more; and opt-in, audited write actions. ~80 tools. Remaining: the full SDE bulk-load. `main` stays untouched until the first complete version is ready.
|
||
|
||
## License
|
||
|
||
MIT |