# Getting Started

This guide takes you from a fresh clone to a working AI assistant that can read your EVE Online
account and act on it when you ask.

## 1. Prerequisites

- **[uv](https://docs.astral.sh/uv/)** — the Python project/dependency manager familiar is built
  around. Install it first (see the uv docs for your platform).
- **Python 3.11+** — uv will fetch a suitable interpreter if you don't have one.
- An **EVE Online account** (for the authenticated tools; public market/universe lookups work
  without one).
- An MCP-capable client: **Claude Code**, **Claude Desktop**, **Cowork**, or any other MCP client.

## 2. Install

```bash
uv sync          # install the project and all dependencies (incl. the dev group)
```

There is no separate build step for local use. `uv run familiar` runs the server straight from
source.

## 3. Log in (EVE SSO)

familiar uses EVE's Single Sign-On with PKCE — no client secret, nothing to configure. Run the
login once **per character**:

```bash
uv run familiar login    # opens your browser to the EVE SSO consent page
```

The browser opens CCP's login page. Approve the requested scopes; the callback lands on
`localhost:8765`, the code is exchanged for tokens, and the (rotating) refresh token is stored
**encrypted** on disk. You'll see a "login complete" page — close the tab and return to the terminal.

To add more characters, switch EVE accounts in the browser and run `login` again. All characters live
in one encrypted store:

```bash
uv run familiar status   # list logged-in characters
uv run familiar logout NAME   # forget one character (by name or id)
uv run familiar logout        # forget ALL characters
```

> **Changing scopes:** if the set of requested scopes changes (e.g. a new familiar version adds
> tools), you must log in again to grant them.

See [Authentication](authentication.md) for the full flow and the scope list.

## 4. Connect to your AI client

### Claude Code

```bash
claude mcp add familiar -- uv --directory /path/to/familiar run familiar
```

### Claude Desktop

Add this to `claude_desktop_config.json` (replace the directory with your clone's absolute path):

```json
{
  "mcpServers": {
    "familiar": {
      "command": "uv",
      "args": ["--directory", "/path/to/familiar", "run", "familiar"]
    }
  }
}
```

The client launches `uv run familiar` with no arguments, which starts the MCP server over **stdio** —
the transport MCP clients speak.

## 5. First queries

Ask in natural language. The AI picks the right tools:

- *"Is the familiar server up?"* → calls `ping`.
- *"What's Tritanium worth in Jita?"* → `get_market_price`.
- *"Compare Plex prices across all trade hubs."* → `compare_hubs`.
- *"How much ISK do I have across all my characters?"* → wallet tools, per character.
- *"Where are my characters right now?"* → location tools.
- *"Set a waypoint to Amarr for my main."* → `set_waypoint` (a **write** — previewed first; see below).

## 6. Write actions

Write tools (send mail, set waypoints, edit contacts/fittings, fleet commands, open windows, PI) are
**enabled by default**, but every write is still previewed unless you pass `confirm=true`, and each
executed write is logged. To block all writes globally:

```bash
uv run familiar writes disable    # turn writes off
uv run familiar writes enable     # turn them back on
uv run familiar writes            # show current state
```

Full details in [Write Safety](write-safety.md).

## 7. Verify everything works

```bash
uv run pytest          # full test suite (fails under 80% coverage)
uv run familiar        # start the server manually (Ctrl-C to stop) — it waits on stdio
```

If `uv run familiar` starts without error and `familiar status` shows your characters, you're ready.