Latte
6b9c550d10
familiar is issuer-agnostic (resource server only), so Gitea can back oauth mode with config alone: RS256 JWTs, JWKS at /login/oauth/keys, and OIDC discovery. Add a deployment.md section covering the env config, the aud=client-ID audience pitfall, and the no-DCR caveat; add a Gitea block to .env.example; and note in claude-web.md that Gitea can't back the claude.ai web connector (which requires DCR).
familiar — Documentation
Your familiar across New Eden — an MCP server that gives a local AI a complete window into your EVE Online account and the New Eden universe, plus opt-in hands to act on it.
This folder contains the full English documentation for the familiar project. Start with Getting Started if you just want to run it, or Architecture if you want to understand or extend the code.
What is familiar?
familiar is a local-first MCP server, written in Python with
FastMCP, that connects a local AI assistant
(Claude Code, Claude Desktop, Cowork, or any MCP client) to two data sources:
- ESI — the EVE Swagger Interface, CCP's official REST API. Public endpoints (market, universe, industry indices) need no login; character and corp data flow through EVE SSO with read and write OAuth2 scopes.
- SDE — the Static Data Export, EVE's static dataset of items, systems and stations, optionally cached locally for fast offline lookups.
It exposes roughly 80 tools across market, universe, account, industry, trade, structures, killmails, profile, corp, communications, contacts, fittings, fleet, UI, and planetary interaction — the vast majority read-only, with a small set of guarded write actions (mail, waypoints, contacts, fittings, fleet, UI windows, PI) gated behind a safety choke point.
Design principles
- Safe by default. Reading is free. Every write is previewed before it runs (nothing happens
without
confirm=true), recorded in an audit log, and can be turned off entirely. See Write Safety. - Local-first. Runs on your own machine. Your refresh token and account data never leave your control — the token store is Fernet-encrypted on disk.
- Everything, eventually. The goal is full ESI coverage (character and corp, read and write) plus the complete static universe, built in phases so the project stays shippable.
Documentation map
| Document | What's in it |
|---|---|
| Getting Started | Install with uv, log in via EVE SSO, connect to Claude, first queries. |
| Deployment | Run familiar as a remote MCP server: Docker, reverse proxy + TLS, bearer/OAuth, env reference. |
| Client setup | Exact connection steps per client — Claude Code, VS Code, Desktop, Cowork, web, Mistral. |
| Architecture | How the server is assembled, the ESI/auth/charutil/writes layers, the module pattern. |
| Authentication | EVE SSO PKCE flow, the encrypted multi-character store, scopes, CLI commands. |
| Write Safety | The writes.guard choke point, dry-run previews, the audit log, enabling/disabling. |
| Tool Reference | Every MCP tool, grouped by module, with parameters and descriptions. |
| Configuration | Every environment variable and on-disk file. |
| Contributing & Development | Dev setup, testing conventions, lint/format, the Git/CI workflow. |