110 lines
3.7 KiB
Markdown
110 lines
3.7 KiB
Markdown
# 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.
|