53 lines
3.2 KiB
Markdown
53 lines
3.2 KiB
Markdown
# 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).
|