Latte
df9e06a3e7
- doc/deployment.md: run familiar as a remote MCP server — secure defaults, bearer vs OAuth modes, the full env-var reference, one-time login / token-store provisioning, the published images, docker compose, and TLS reverse-proxy blocks for nginx (proxy_buffering off + long read timeout), Caddy, and Traefik. - doc/clients/: one page per client with exact working steps — Claude Code, VS Code (.vscode/mcp.json with a masked token input, and the workspace .mcp.json header gotcha), Mistral Le Chat, Claude Desktop + Cowork (mcp-remote bridge, per-OS config paths), and Claude web (oauth mode + external IdP, with "use Desktop + bearer" as the simpler alternative). Plus a clients/ index. - README: a "Connect a client" matrix (client -> auth -> guide) and a compact "Deploy with Docker" section linking to doc/deployment.md; oauth mode noted. - doc/README.md index: rows for Deployment and Client setup. - doc/getting-started.md: pointer from the HTTPS quickstart to the full docs. - CLAUDE.md: FAMILIAR_AUTH_MODE / FAMILIAR_OAUTH_* / FAMILIAR_ALLOW_INSECURE_BIND and /healthz in the transport note; the split ci.yml / docker.yml workflows. Deployment docs live under the existing doc/ tree (the repo uses doc/, not a separate docs/) to keep a single documentation directory.
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. |