Latte
df9e06a3e7
CI / lint (pull_request) Successful in 55s
docker / lint (pull_request) Successful in 56s
CI / test (pull_request) Successful in 1m6s
docker / test (pull_request) Successful in 1m4s
CI / publish (pull_request) Has been skipped
docker / docker (pull_request) Failing after 1m11s
- 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.
55 lines
3.4 KiB
Markdown
55 lines
3.4 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. |
|
|
| [Deployment](deployment.md) | Run familiar as a remote MCP server: Docker, reverse proxy + TLS, bearer/OAuth, env reference. |
|
|
| [Client setup](clients/) | Exact connection steps per client — Claude Code, VS Code, Desktop, Cowork, web, Mistral. |
|
|
| [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).
|