From 5d24ec368787bbd3c218ca3535085bc8de097942 Mon Sep 17 00:00:00 2001 From: latte Date: Sun, 5 Jul 2026 18:30:10 +0200 Subject: [PATCH] hello :) --- CLAUDE.md | 6 +++++- README.md | 4 ++-- docker-compose.yml | 14 +++++++------- 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 41c33af..1949ca5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,13 +22,15 @@ uv run familiar login # browser EVE SSO login (adds a character; run onc uv run familiar login --no-browser # headless login: paste the callback URL on stdin uv run familiar status # list logged-in characters uv run familiar writes disable # block write actions (default: enabled on stdio, disabled on HTTP) +uv run familiar sde download # download + install the local SDE for offline name/type lookups +uv run familiar sde status # is the local SDE present, and where (also: sde path) ``` There is no separate build step; `uv build` produces the wheel (CI does this on merge). ## Architecture -**Server assembly.** [src/familiar/server.py](src/familiar/server.py) creates the single `FastMCP` instance and calls `register(mcp)` on each tool module. Every tool module (market, universe, account, industry, trade, structures, killmails, profile, corp, corp_economy, misc, comms, contacts, fittings, fleet, ui, planets, writes) follows the same shape: **module-level async functions** + a `TOOLS` list + `register(mcp)` that loops `mcp.tool(fn)`. Tools are plain importable functions (so tests call them directly); registration is separate. To add tools: new module → import + register in server.py. +**Server assembly.** [src/familiar/server.py](src/familiar/server.py) creates the single `FastMCP` instance and calls `register(mcp)` on each tool module. Every tool module (market, universe, account, industry, trade, structures, killmails, profile, corp, corp_economy, misc, comms, contacts, fittings, fleet, ui, planets, sde, writes) follows the same shape: **module-level async functions** + a `TOOLS` list + `register(mcp)` that loops `mcp.tool(fn)`. Tools are plain importable functions (so tests call them directly); registration is separate. To add tools: new module → import + register in server.py. **Transport (stdio default, opt-in HTTP).** `familiar` (no args) runs `mcp.run()` over **stdio** (how Claude launches it) — local, no auth. `familiar serve` runs `server.serve_http()`: the FastMCP **streamable-HTTP** transport bound to loopback (`FAMILIAR_HTTP_HOST`/`FAMILIAR_HTTP_PORT`/`FAMILIAR_HTTP_PATH`, default `127.0.0.1:8080/mcp`) behind a TLS reverse proxy, for remote MCP clients (Mistral, Claude web/desktop/code, VS Code — see [doc/clients/](doc/clients/)). An unauthenticated `GET /healthz` liveness route (returns only status/server/version) is served for Docker/proxy probes. This transport-level auth is separate from the EVE-SSO/ESI auth in auth.py. @@ -41,6 +43,8 @@ Either mode calls `writes.set_http_context(True)`, flipping the **write default **ESI access.** [esi.py](src/familiar/esi.py) is a thin async httpx wrapper (`client()` singleton, `get/post/put/delete`, `get_all_pages` for `X-Pages` pagination, Bearer `token=` for authed calls, uniform `EsiError`). Base URL and datasource are env-overridable. [zkill.py](src/familiar/zkill.py) mirrors it for zKillboard. Both expose `set_client()` so tests inject an `httpx.MockTransport`. +**Name resolution & offline SDE.** Callers pass human names ("Tritanium", "Jita"), not numeric IDs. [lookup.py](src/familiar/lookup.py) `resolve_name(name, *categories)` resolves them against ESI's `/universe/ids/`. [hubs.py](src/familiar/hubs.py) hardcodes the major NPC trade hubs (Jita/Amarr/Dodixie/Rens/Hek) with their stable region/system/station IDs so the common "price in Jita" case skips a lookup. [sde.py](src/familiar/sde.py) is an **optional** local SQLite copy of EVE's Static Data Export (path from `FAMILIAR_SDE_PATH`, else `data_dir()/sde.sqlite`) that backs offline name/type resolution; every accessor degrades gracefully — `sde.available()` returns `False` when the file or a needed table is absent, and callers fall back to ESI. `sde` also registers one tool (`sde_status`); the `familiar sde` CLI downloads/installs it. + **Auth is multi-character.** [auth.py](src/familiar/auth.py) does EVE SSO PKCE (no client secret), stores a **dict of characters keyed by id** in one Fernet-encrypted file (`load_store`/`_save_character`/`list_characters`/`remove_character`), and `get_auth(character_id)` returns a valid access token, refreshing via the rotating refresh token when near expiry. The legacy single-character file is migrated on load. Config (client id, callback `localhost:8765`, the 73 read+write scopes split into `READ_SCOPES`/`WRITE_SCOPES`) lives in [config.py](src/familiar/config.py), all env-overridable. **Per-character / per-corp pattern.** [charutil.py](src/familiar/charutil.py) is the backbone of every authenticated tool. `run_per_character(character, fetch)` runs a fetcher for one named character or **all** logged-in ones (when `character` is None), returning a uniform `{"characters": [...]}`. `run_per_corp` additionally resolves each character's `corporation_id` (corp endpoints need the right corp role or ESI 403s). `one_token` picks a single token for thing-scoped lookups (e.g. a structure). `summarize(items, limit)` gives `{count, sample}`. account.py and all read modules build on these. diff --git a/README.md b/README.md index 06282e6..246eeba 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# familiar + # 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. @@ -156,4 +156,4 @@ Phases 0–4 done on `dev`, plus Phase 5 caching/back-off and docs: public marke ## License -MIT \ No newline at end of file +MIT diff --git a/docker-compose.yml b/docker-compose.yml index 3b852ce..09cdc6f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -46,8 +46,8 @@ services: cap_drop: - ALL user: "1000:1000" - networks: - - proxy + # networks: + # - proxy healthcheck: test: [ @@ -63,8 +63,8 @@ services: # No proxy labels: Pangolin discovers this service on the shared `proxy` # network and forwards to :8080 — configure the route in Pangolin, not here. -networks: - # Shared reverse-proxy network (Pangolin). Create once with: - # docker network create proxy - proxy: - external: true +# networks: +# # Shared reverse-proxy network (Pangolin). Create once with: +# # docker network create proxy +# proxy: +# external: true -- 2.54.0