EVE Online Companion — Servidor MCP

Un servidor MCP (Model Context Protocol) para Claude Code que sirve como tu compañero personal de EVE Online. Proporciona a Claude acceso directo a datos de personajes, precios de mercado, inteligencia de killboards, conocimiento de la wiki y más, todo mediante lenguaje natural.

¿Qué puede hacer?

"¿Puedo volar el Ishtar?" — Comprueba tus habilidades y muestra las que faltan junto con el tiempo de entrenamiento.

"¿Cuánto cuesta un Warp Disruptor II en Jita?" — Obtiene datos de mercado en vivo desde ESI.

"¿Qué tan peligroso es el piloto XY?" — Comprueba las estadísticas de zKillboard, el nivel de peligro y las naves principales.

"Muéstrame mis equipamientos para el Vexor" — Lista los equipamientos guardados en formato EFT.

"Explícame las mecánicas de los agujeros de gusano" — Busca en la wiki de EVE University.

Las 29 herramientas

Configuración

1. Aplicación de desarrollador de EVE

1. Ve a https://developers.eveonline.com/

2. "Create New Application"

3. Tipo de aplicación: Authentication & API Access

4. URL de callback: http://localhost:8834/callback

5. Selecciona todos los alcances (scopes) de la lista a continuación

6. Anota el Client ID (Secret Key opcional, solo para aplicaciones confidenciales)

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

2. Instalación

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

3. Configuración

mkdir -p ~/.eve-mcp

Crea ~/.eve-mcp/config.json:

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

Opcional con Secret Key (solo para aplicaciones confidenciales):

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

Alternativamente mediante variables de entorno:

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. Integración con Claude Code

Añade el servidor MCP a tus ajustes de Claude Code.

Opción A — settings.json (recomendado):

Archivo: ~/.claude/settings.json

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

Opción B — Alcance del proyecto (.mcp.json en el directorio del proyecto):

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

5. Primer inicio de sesión

Inicia Claude Code y di:

"Conéctame con EVE Online"

Claude llamará a eve_auth_start e iniciará un servidor de autenticación local. Abre http://localhost:8834 en el navegador; allí aparecerá una página de inicio de sesión al estilo EVE. Haz clic en "Authenticate via EVE SSO", inicia sesión en CCP y serás redirigido a una página de éxito con el retrato de tu personaje. Cierra la ventana, listo.

Arquitectura

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

Clientes API

Caché

Todas las respuestas de la API se almacenan en caché en memoria:

Límite de tasa de ESI

El cliente ESI rastrea las cabeceras X-ESI-Error-Limit-Remain y X-ESI-Error-Limit-Reset. Si el límite de error cae por debajo de 20, las solicitudes se bloquean hasta el reinicio. Los errores 420 (límite de error) se lanzan como RateLimitError.

Seguridad de tokens

• Los tokens se guardan en ~/.eve-mcp/tokens.json

• Si EVE_MCP_TOKEN_PASSPHRASE está configurado: cifrado AES-256-GCM con derivación de clave scrypt

• Sin frase de contraseña: almacenamiento en texto plano (con advertencia en stderr)

• El token de acceso se actualiza automáticamente 2 minutos antes de caducar

• El token de actualización se renueva en cada actualización (patrón de token volátil PKCE)

Desarrollo

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

# Build
npm run build

# Ausfuehren
npm start

Añadir una nueva herramienta

1. Inserta el manejador en el archivo correspondiente en src/tools/

2. Usa el patrón server.tool(name, description, zodSchema, handler)

3. Devuelve siempre los errores con formatToolError(err)

4. Realiza llamadas ESI mediante esi.get() / esi.publicGet() con el TTL de caché adecuado

5. Resuelve IDs de tipo con resolveTypeName() / resolveTypeId()

Solución de problemas

"Config not found" — Crea ~/.eve-mcp/config.json o establece EVE_MCP_CLIENT_ID.

"Authentication required" — Llama a eve_auth_login o eve_auth_start.

"Token refresh failed" — El token de actualización ha caducado. Inicia sesión de nuevo.

"ESI error limit reached" — Demasiadas solicitudes erróneas. Espera automáticamente.

Puerto 8834 ocupado — Establece otro puerto en config.json y ajusta la URL de callback en CCP.