Metadata-Version: 2.4
Name: familiar
Version: 0.0.1.dev14
Summary: Your familiar across New Eden — a read-only EVE Online MCP server.
License: MIT License
        
        Copyright (c) 2026 Hiddenden
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
        associated documentation files (the "Software"), to deal in the Software without restriction, including 
        without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
        copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the 
        following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial 
        portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 
        LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO 
        EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
        IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE 
        USE OR OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0.0
Requires-Dist: fastmcp>=2.3.0
Requires-Dist: httpx>=0.27.0
Description-Content-Type: text/markdown

# familiar

> Your familiar across New Eden — a read-only EVE Online MCP server that lets a local AI see your entire account and find anything in EVE.

In EVE, your familiar isn't a cat on the windowsill. It's the companion that rides along through New Eden, sees what you see, remembers what you can't, and fetches anything you ask for. `familiar` is exactly that: an [MCP](https://modelcontextprotocol.io) server that gives a local AI (Claude Code, Claude Desktop, Cowork) a complete, read-only window into your EVE Online account and the entire game universe.

Ask your familiar where your assets are, what your skill queue looks like, what Tritanium sells for in Jita, the safest route to a lowsec system, or whether a fit is worth building. It looks, it finds, it reports back.

## Principles

- **Read-only by design.** `familiar` only ever *reads*. No market orders, no fittings changes, no mail sent, no waypoints set. The AI can see everything and break nothing.
- **Local-first.** Runs on your own machine. Your refresh token and account data never leave your control.
- **Everything, eventually.** The goal is full coverage: every read scope ESI exposes, plus the complete static universe. Built in phases so it actually ships.

## How it works

Two data sources sit behind the server:

- **ESI** (the [EVE Swagger Interface](https://esi.evetech.net/)) — the official REST API. Public endpoints (market, universe, industry indices) need no login. Character and corp data (wallet, assets, skills, industry, contracts, mail, location) come through EVE SSO with **read-only OAuth2 scopes**.
- **SDE** (the [Static Data Export](https://developers.eveonline.com/resource/resources)) — the full static dataset of items, blueprints, systems and stations, cached locally for fast lookups and anything name- or recipe-based.

Built in **Python with FastMCP**, OAuth via PKCE with a localhost callback, refresh token stored encrypted on disk. ESI `Expires` headers are respected for caching, and the SDE is loaded into a local store.

## Roadmap

Built in phases. Each phase is independently useful, so the project stays shippable.

**Phase 0 — Skeleton**
- Repo, project scaffold, FastMCP server that starts and exposes a health/ping tool.
- App registered on [developers.eveonline.com](https://developers.eveonline.com/).

**Phase 1 — Public lookups (no auth)**
- Market: prices and order book for any item in any hub, spreads between hubs.
- Universe via SDE: items, systems, stations, security, basic route/jumps.
- Quick win: useful before any OAuth complexity exists.

**Phase 2 — Account read (OAuth)**
- EVE SSO login flow, encrypted refresh token storage.
- Wallet, assets (search across characters), skills + skill queue, current location and clones.

**Phase 3 — Industry & contracts**
- Industry jobs, blueprints (SDE-backed), manufacturing cost/profit lookups.
- Personal and corp contracts, market orders.

**Phase 4 — Everything else**
- Mail, planetary interaction, loyalty points, fittings, corp roles.
- zKillboard integration for kill/PvP data.

**Phase 5 — Polish**
- Caching, error-limit safety, packaging, setup docs. Optional: prep a public, generic single-user release as a portfolio case.

## Status

Phase 0. Just hatched.

## License

MIT