LatteandClaude Opus 4.8
0dfd6d2350
Invert the global write toggle so writes are ENABLED by default and the user opts OUT, while keeping all other safety intact (per-call confirm=true dry-run preview and the on-disk audit log are unchanged). - writes.py: use a `writes_disabled` flag file instead of `writes_enabled`; `writes_enabled()` returns True unless the flag exists (env var still honored either way); `set_writes(False)` creates the flag, `set_writes(True)` removes it. Update user-facing notes. - tests: default is now ENABLED; adjust toggle/disabled tests (set disabled explicitly via set_writes(False) or FAMILIAR_ENABLE_WRITES=0). - README.md / CLAUDE.md: document writes are on by default, opt out via `familiar writes disable`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
48 lines
5.4 KiB
Markdown
48 lines
5.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What this is
|
|
|
|
`familiar` is an [MCP](https://modelcontextprotocol.io) server giving a local AI a window into an EVE Online account and the New Eden universe — public market/universe lookups plus authenticated character **and corp** data, with opt-in write actions. Python + [FastMCP](https://github.com/jlowin/fastmcp), managed with `uv`.
|
|
|
|
Note: the project began "read-only by design" but is now **read + write** (writes gated behind safety, see below). The README's older read-only framing is superseded.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
uv sync # install deps (incl. dev group)
|
|
uv run pytest # full suite; FAILS under 80% coverage (configured in pyproject addopts)
|
|
uv run pytest tests/test_market.py::test_get_market_price # single test
|
|
uv run ruff format . # format
|
|
uv run ruff check . # lint (run both before committing; CI enforces them)
|
|
uv run familiar # run the MCP server over stdio (how Claude launches it)
|
|
uv run familiar login # browser EVE SSO login (adds a character; run once per character)
|
|
uv run familiar status # list logged-in characters
|
|
uv run familiar writes disable # block write actions (default: enabled)
|
|
```
|
|
|
|
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.
|
|
|
|
**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`.
|
|
|
|
**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.
|
|
|
|
**Write safety — the choke point.** [writes.py](src/familiar/writes.py) `guard(action, params, confirm, execute)` is the single gate every mutating tool calls. `confirm=False` → dry-run preview (nothing happens); `confirm=True` but writes disabled → `WriteDisabled`; `confirm=True` + enabled → execute + append to an audit log. Writes are **on by default** (opt out via `familiar writes disable`; toggle via `familiar writes enable`/`disable` or `FAMILIAR_ENABLE_WRITES`). Write tools take a *required* `character` and a `confirm` flag; reads take an *optional* `character`. When adding a write tool, route it through `writes.guard` — never call a mutating ESI endpoint directly.
|
|
|
|
## Testing conventions
|
|
|
|
Tests use [tests/conftest.py](tests/conftest.py): the `mock_esi` fixture installs a mock ESI client driven by a request handler, and `route(req, {substring: body})` dispatches by path substring. Async tools are driven with `asyncio.run(...)` (no async-test plugin). Authenticated-tool tests monkeypatch `auth.list_characters` / `auth.get_auth` / `auth.resolve_character` rather than touching the real token store; write tests set `FAMILIAR_DATA_DIR` to a tmp dir and `FAMILIAR_ENABLE_WRITES`. `make_jwt(claims)` builds fake access tokens.
|
|
|
|
## Git / CI workflow
|
|
|
|
- Work happens on `dev`; **`main` is not touched until the first complete version** (it triggers the real release publish). Feature branches → PR → fast-forward merge into `dev` → delete branch.
|
|
- `main` and `dev` are protected: no direct pushes, **signed commits required** (the user's git auto-signs), merge via PR.
|
|
- CI (`.gitea/workflows/ci.yml`) runs lint + test on every PR/push; on a merge to main/dev it builds and publishes to the Gitea PyPI registry (auth via the `REGISTRY_TOKEN` secret; twine must NOT use `--skip-existing`). dev publishes a unique `.devN` pre-release.
|