# familiar — Documentation

> Your familiar across New Eden — an [MCP](https://modelcontextprotocol.io) 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](getting-started.md) if you just want to run it, or [Architecture](architecture.md)
if you want to understand or extend the code.

## What is familiar?

`familiar` is a local-first MCP server, written in Python with
[FastMCP](https://github.com/jlowin/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](https://esi.evetech.net/), 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](https://developers.eveonline.com/resource/resources), 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](write-safety.md).
- **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](getting-started.md) | Install with `uv`, log in via EVE SSO, connect to Claude, first queries. |
| [Architecture](architecture.md) | How the server is assembled, the ESI/auth/charutil/writes layers, the module pattern. |
| [Authentication](authentication.md) | EVE SSO PKCE flow, the encrypted multi-character store, scopes, CLI commands. |
| [Write Safety](write-safety.md) | The `writes.guard` choke point, dry-run previews, the audit log, enabling/disabling. |
| [Tool Reference](tool-reference.md) | Every MCP tool, grouped by module, with parameters and descriptions. |
| [Configuration](configuration.md) | Every environment variable and on-disk file. |
| [Contributing & Development](contributing.md) | Dev setup, testing conventions, lint/format, the Git/CI workflow. |

## Quick links

- Project root [README.md](../README.md) — the marketing-facing overview and roadmap.
- [CLAUDE.md](../CLAUDE.md) — guidance for AI coding assistants working in this repo.
- License: [MIT](../LICENSE).