# EVE Online Companion — MCP Server

Ein MCP-Server (Model Context Protocol) fuer Claude Code, der als persoenlicher EVE Online Companion dient. Gibt Claude direkten Zugriff auf Character-Daten, Marktpreise, Killboard-Intel, Wiki-Wissen und mehr — alles ueber natuerliche Sprache.

## Was kann das?

**"Kann ich die Ishtar fliegen?"** — Prueft deine Skills und zeigt fehlende mit Trainingszeit.

**"Was kostet ein Warp Disruptor II in Jita?"** — Holt Live-Marktdaten von ESI.

**"Wie gefaehrlich ist der Pilot XY?"** — Checkt zKillboard-Stats, Danger-Rating, Top-Ships.

**"Zeig mir meine Fittings fuer die Vexor"** — Listet gespeicherte Fits im EFT-Format.

**"Erklaer mir Wormhole-Mechaniken"** — Durchsucht die EVE University Wiki.

### Alle 29 Tools

| Kategorie | Tools | Beschreibung |
|---|---|---|
| **Auth** | `eve_auth_login` | SSO-Login (blockiert bis Callback) |
| | `eve_auth_start` | SSO-Login (non-blocking, oeffne localhost:8834) |
| | `eve_auth_status` | Auth-Status + Character-Info |
| **Character** | `eve_character_info` | Name, Corp, Alliance, Wallet, SP, Location, Ship |
| | `eve_character_skills` | Skills filtern nach Gruppe oder Name |
| | `eve_character_skillqueue` | Aktuelle Skill-Queue mit Zeiten |
| | `eve_character_implants` | Eingesteckte Implants |
| **Location** | `eve_location_current` | System, Station, Schiff, Online-Status |
| | `eve_route_plan` | Route berechnen (shortest/secure/insecure) |
| | `eve_set_destination` | Autopilot-Ziel im Spiel setzen |
| **Fittings** | `eve_fitting_list` | Gespeicherte Fittings (EFT-Format) |
| | `eve_fitting_save` | Fitting aus EFT-String speichern |
| | `eve_fitting_analyze` | Fitting-Analyse (Tank, DPS, Cap — Dogma-basiert) |
| **Market** | `eve_market_price` | Preis-Check (Jita default, andere Regionen moeglich) |
| | `eve_market_appraise` | Itemliste bewerten (Copy-Paste aus dem Spiel) |
| | `eve_market_orders` | Eigene aktive Kauf-/Verkaufsauftraege |
| **Intel** | `eve_intel_character` | Pilot-Intel: Corp, Kills, Danger-Rating, Top-Ships |
| | `eve_intel_corporation` | Corp-Intel: Members, Alliance, Killboard-Stats |
| | `eve_intel_system` | System-Intel: Kills, Jumps, NPC-Kills, Ratting |
| | `eve_killmail_analyze` | Killmail aufschluesseln: Fit, Attacker, Damage |
| **Assets** | `eve_assets_search` | Assets nach Name/Typ durchsuchen |
| | `eve_wallet_balance` | Wallet-Balance |
| | `eve_wallet_journal` | Letzte Wallet-Eintraege |
| **Universe** | `eve_type_info` | Item/Ship-Details mit Dogma-Attributen |
| | `eve_system_info` | System-Details: Sec, Region, Stationen |
| | `eve_search` | Universelle Suche (Chars, Corps, Systems, Items) |
| **Wiki** | `eve_wiki_search` | EVE University Wiki durchsuchen |
| | `eve_wiki_article` | Wiki-Artikel lesen (als Markdown) |
| **Fleet** | `eve_fleet_info` | Fleet-Status (wenn in Fleet) |

---

## Setup

### 1. EVE Developer Application

1. Gehe zu **https://developers.eveonline.com/**
2. "Create New Application"
3. Application Type: **Authentication & API Access**
4. Callback URL: **`http://localhost:8834/callback`**
5. Alle Scopes aus der Liste unten auswaehlen
6. **Client ID** notieren (Secret Key optional, nur fuer confidential apps)

<details>
<summary><strong>Benoetigte ESI Scopes (20)</strong></summary>

```
esi-skills.read_skills.v1
esi-skills.read_skillqueue.v1
esi-clones.read_implants.v1
esi-assets.read_assets.v1
esi-wallet.read_character_wallet.v1
esi-fittings.read_fittings.v1
esi-fittings.write_fittings.v1
esi-characters.read_standings.v1
esi-killmails.read_killmails.v1
esi-location.read_location.v1
esi-location.read_ship_type.v1
esi-location.read_online.v1
esi-fleets.read_fleet.v1
esi-markets.read_character_orders.v1
esi-contracts.read_character_contracts.v1
esi-mail.read_mail.v1
esi-ui.open_window.v1
esi-ui.write_waypoint.v1
esi-search.search_structures.v1
esi-universe.read_structures.v1
```
</details>

### 2. Installation

```bash
git clone <repo>
cd eve
npm install
npm run build
```

### 3. Konfiguration

```bash
mkdir -p ~/.eve-mcp
```

Erstelle `~/.eve-mcp/config.json`:

```json
{
  "clientId": "deine-client-id-von-ccp",
  "callbackUrl": "http://localhost:8834/callback",
  "userAgent": "eve-mcp-companion/1.0 (dein-character-name)"
}
```

Optional mit Secret Key (nur bei confidential apps):

```json
{
  "clientId": "deine-client-id",
  "secretKey": "dein-secret-key",
  "callbackUrl": "http://localhost:8834/callback",
  "userAgent": "eve-mcp-companion/1.0 (dein-character-name)"
}
```

Alternativ via Environment-Variablen:
```bash
export EVE_MCP_CLIENT_ID="deine-client-id"
export EVE_MCP_CALLBACK_URL="http://localhost:8834/callback"
export EVE_MCP_USER_AGENT="eve-mcp-companion/1.0"
```

### 4. Claude Code Integration

Fuege den MCP-Server in deine Claude Code Settings ein.

**Option A — settings.json** (empfohlen):

Datei: `~/.claude/settings.json`

```json
{
  "mcpServers": {
    "eve-online": {
      "command": "node",
      "args": ["/absoluter/pfad/zu/eve/dist/index.js"],
      "env": {
        "EVE_MCP_TOKEN_PASSPHRASE": "ein-sicheres-passwort"
      }
    }
  }
}
```

**Option B — Projekt-scope** (`.mcp.json` im Projektverzeichnis):

```json
{
  "mcpServers": {
    "eve-online": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "EVE_MCP_TOKEN_PASSPHRASE": "ein-sicheres-passwort"
      }
    }
  }
}
```

### 5. Erster Login

Starte Claude Code und sage:

> "Verbinde mich mit EVE Online"

Claude ruft `eve_auth_start` auf und startet einen lokalen Auth-Server. Oeffne **http://localhost:8834** im Browser — dort erscheint eine Login-Seite im EVE-Stil. Klicke "Authenticate via EVE SSO", logge dich bei CCP ein, und du wirst zurueckgeleitet zu einer Erfolgsseite mit deinem Character-Portrait. Fenster schliessen, fertig.

---

## Architektur

```
eve/
├── src/
│   ├── index.ts                 # Server-Entry, registriert alle Tools
│   ├── config.ts                # Laedt ~/.eve-mcp/config.json
│   ├── auth/
│   │   ├── scopes.ts            # ESI Scope-Definitionen
│   │   ├── sso.ts               # OAuth2 PKCE Flow, Callback-Server
│   │   ├── tokens.ts            # Token-Persistence (AES-256-GCM)
│   │   └── pages.ts             # HTML-Seiten fuer Auth-Flow
│   ├── clients/
│   │   ├── esi.ts               # ESI API Client (Auth, Rate-Limiting, Cache)
│   │   ├── zkillboard.ts        # zKillboard Client (10 req/s Throttle)
│   │   ├── evetycoon.ts         # EVE Tycoon Markt-Client
│   │   └── wiki.ts              # EVE University Wiki (MediaWiki API)
│   ├── tools/
│   │   ├── auth.ts              # Login, Status
│   │   ├── character.ts         # Character Info, Skills, Queue, Implants
│   │   ├── location.ts          # Location, Route, Autopilot
│   │   ├── fitting.ts           # Fittings, EFT, Analyse
│   │   ├── universe.ts          # Type Info, System Info, Search
│   │   ├── market.ts            # Preise, Appraisal, Orders
│   │   ├── killboard.ts         # Character/Corp/System Intel, Killmails
│   │   ├── assets.ts            # Assets, Wallet
│   │   ├── wiki.ts              # Wiki Search, Article
│   │   └── fleet.ts             # Fleet Info
│   └── utils/
│       ├── cache.ts             # In-Memory Cache mit TTL
│       ├── errors.ts            # Error-Klassen + formatToolError()
│       ├── formatting.ts        # ISK, Zeit, EVE-Time Formatierung
│       ├── eft.ts               # EFT-Format Parser + Generator
│       └── sde.ts               # Type/System Name-Resolution (ESI-backed)
├── package.json
├── tsconfig.json
└── README.md
```

### API-Clients

| Client | Base URL | Auth | Rate Limit | Cache |
|---|---|---|---|---|
| ESI | `esi.evetech.net/latest` | OAuth2 Bearer | Error-Limit Header | Expires-Header + custom TTL |
| zKillboard | `zkillboard.com/api` | keine | 10 req/s | 10 Minuten |
| EVE Tycoon | `evetycoon.com/api/v1` | keine | Expires-Header | 5 Minuten |
| Wiki | `wiki.eveuniversity.org/api.php` | keine | keine | 1 Stunde |

### Caching

Alle API-Antworten werden in-memory gecacht:

| Datentyp | TTL |
|---|---|
| Location / Ship / Online | 30 Sekunden |
| Wallet Balance | 2 Minuten |
| Skill Queue | 5 Minuten |
| Market Prices / Orders | 5 Minuten |
| zKillboard Stats | 10 Minuten |
| Assets | 30 Minuten |
| Character Skills | 1 Stunde |
| Wiki Articles | 1 Stunde |
| Type Info / System Info | 24 Stunden |
| Name-zu-ID Resolution | 24 Stunden |

### ESI Rate-Limiting

Der ESI-Client trackt `X-ESI-Error-Limit-Remain` und `X-ESI-Error-Limit-Reset` Header. Wenn das Error-Limit unter 20 faellt, werden Requests bis zum Reset blockiert. Fehler 420 (Error Limit) werden als `RateLimitError` geworfen.

### Token-Sicherheit

- Tokens werden in `~/.eve-mcp/tokens.json` gespeichert
- Wenn `EVE_MCP_TOKEN_PASSPHRASE` gesetzt ist: **AES-256-GCM** Verschluesselung mit scrypt-Key-Derivation
- Ohne Passphrase: Klartext-Speicherung (mit Warnung auf stderr)
- Access-Token wird automatisch 2 Minuten vor Ablauf refreshed
- Refresh-Token wird bei jedem Refresh erneuert (PKCE volatile token pattern)

---

## Entwicklung

```bash
# Dev-Mode (tsx, kein Build noetig)
npm run dev

# Build
npm run build

# Ausfuehren
npm start
```

### Neues Tool hinzufuegen

1. Handler in die passende Datei unter `src/tools/` einfuegen
2. `server.tool(name, description, zodSchema, handler)` Pattern verwenden
3. Fehler immer mit `formatToolError(err)` zurueckgeben
4. ESI-Calls ueber `esi.get()` / `esi.publicGet()` mit passendem Cache-TTL
5. Type-IDs mit `resolveTypeName()` / `resolveTypeId()` aufloesen

### Troubleshooting

**"Config not found"** — `~/.eve-mcp/config.json` anlegen oder `EVE_MCP_CLIENT_ID` setzen.

**"Authentication required"** — `eve_auth_login` oder `eve_auth_start` aufrufen.

**"Token refresh failed"** — Refresh-Token abgelaufen. Erneut einloggen.

**"ESI error limit reached"** — Zu viele fehlerhafte Requests. Wartet automatisch.

**Port 8834 belegt** — Anderen Port in config.json setzen und Callback-URL bei CCP anpassen.