EVE Online Companion — MCP 服务器

一个用于 Claude Code 的 MCP (Model Context Protocol) 服务器，作为你的个人 EVE Online 伴侣。它让 Claude 能够通过自然语言直接访问角色数据、市场价格、击杀板情报、维基知识等。

它能做什么？

“我能驾驶伊什塔级吗？” — 检查你的技能，并显示缺失的技能及训练时间。

“吉他 (Jita) 的跃迁扰频器 II 多少钱？” — 从 ESI 获取实时市场数据。

“飞行员 XY 有多危险？” — 检查 zKillboard 统计数据、危险等级和常用舰船。

“给我看看我的毒蜥级配置” — 以 EFT 格式列出已保存的配置。

“给我解释一下虫洞机制” — 搜索 EVE University 维基。

全部 29 个工具

分类	工具	描述
认证	`eve_auth_login`	SSO 登录（阻塞直到回调）
	`eve_auth_start`	SSO 登录（非阻塞，打开 localhost:8834）
	`eve_auth_status`	认证状态 + 角色信息
角色	`eve_character_info`	姓名、军团、联盟、钱包、技能点、位置、舰船
	`eve_character_skills`	按组或名称筛选技能
	`eve_character_skillqueue`	当前技能队列及时间
	`eve_character_implants`	已植入的植入体
位置	`eve_location_current`	星系、空间站、舰船、在线状态
	`eve_route_plan`	计算路线（最短/安全/不安全）
	`eve_set_destination`	在游戏中设置自动导航目的地
配置	`eve_fitting_list`	已保存的配置（EFT 格式）
	`eve_fitting_save`	保存 EFT 字符串格式的配置
	`eve_fitting_analyze`	配置分析（防御、DPS、电容 — 基于 Dogma）
市场	`eve_market_price`	价格查询（默认为吉他，支持其他地区）
	`eve_market_appraise`	物品列表估价（从游戏中复制粘贴）
	`eve_market_orders`	个人活跃的买入/卖出订单
情报	`eve_intel_character`	飞行员情报：军团、击杀、危险等级、常用舰船
	`eve_intel_corporation`	军团情报：成员、联盟、击杀板统计
	`eve_intel_system`	星系情报：击杀、跳跃、NPC 击杀、刷怪情况
	`eve_killmail_analyze`	击杀报告解析：配置、攻击者、伤害
资产	`eve_assets_search`	按名称/类型搜索资产
	`eve_wallet_balance`	钱包余额
	`eve_wallet_journal`	最近的钱包记录
宇宙	`eve_type_info`	物品/舰船详情及 Dogma 属性
	`eve_system_info`	星系详情：安全等级、区域、空间站
	`eve_search`	通用搜索（角色、军团、星系、物品）
维基	`eve_wiki_search`	搜索 EVE University 维基
	`eve_wiki_article`	阅读维基文章（以 Markdown 格式）
舰队	`eve_fleet_info`	舰队状态（如果在舰队中）

设置

1. EVE 开发者应用程序

前往 https://developers.eveonline.com/
点击 "Create New Application"
应用程序类型：Authentication & API Access
回调 URL：http://localhost:8834/callback
从下方的列表中选择所有必要的 Scopes
记录下 Client ID（Secret Key 可选，仅用于机密应用程序）

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. 安装

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

3. 配置

mkdir -p ~/.eve-mcp

创建 ~/.eve-mcp/config.json：

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

可选的 Secret Key（仅限机密应用程序）：

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

或者通过环境变量：

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 集成

将 MCP 服务器添加到你的 Claude Code 设置中。

选项 A — settings.json（推荐）：

文件：~/.claude/settings.json

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

选项 B — 项目范围（项目目录下的 .mcp.json）：

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

5. 首次登录

启动 Claude Code 并输入：

"Verbinde mich mit EVE Online"

Claude 将调用 eve_auth_start 并启动一个本地认证服务器。在浏览器中打开 http://localhost:8834 — 那里会出现一个 EVE 风格的登录页面。点击 "Authenticate via EVE SSO"，使用 CCP 账号登录，你将被重定向到一个显示你角色头像的成功页面。关闭窗口，完成。

架构

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 客户端

客户端	基础 URL	认证	速率限制	缓存
ESI	`esi.evetech.net/latest`	OAuth2 Bearer	错误限制 Header	Expires-Header + 自定义 TTL
zKillboard	`zkillboard.com/api`	无	10 req/s	10 分钟
EVE Tycoon	`evetycoon.com/api/v1`	无	Expires-Header	5 分钟
Wiki	`wiki.eveuniversity.org/api.php`	无	无	1 小时

缓存

所有 API 响应均在内存中缓存：

数据类型	TTL
位置 / 舰船 / 在线状态	30 秒
钱包余额	2 分钟
技能队列	5 分钟
市场价格 / 订单	5 分钟
zKillboard 统计	10 分钟
资产	30 分钟
角色技能	1 小时
维基文章	1 小时
类型信息 / 星系信息	24 小时
名称到 ID 解析	24 小时

ESI 速率限制

ESI 客户端会跟踪 X-ESI-Error-Limit-Remain 和 X-ESI-Error-Limit-Reset 头部。当错误限制低于 20 时，请求将被阻塞直到重置。错误 420 (Error Limit) 将被抛出为 RateLimitError。

Token 安全性

Token 存储在 ~/.eve-mcp/tokens.json 中
如果设置了 EVE_MCP_TOKEN_PASSPHRASE：使用 AES-256-GCM 加密，并采用 scrypt 密钥派生
无密码短语：明文存储（stderr 会有警告）
访问令牌会在过期前 2 分钟自动刷新
刷新令牌在每次刷新时都会更新（PKCE 易失性令牌模式）

开发

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

# Build
npm run build

# Ausfuehren
npm start

添加新工具

将处理器插入 src/tools/ 下的相应文件中
使用 server.tool(name, description, zodSchema, handler) 模式
错误始终使用 formatToolError(err) 返回
ESI 调用通过 esi.get() / esi.publicGet() 并配合适当的缓存 TTL
类型 ID 使用 resolveTypeName() / resolveTypeId() 进行解析

故障排除

"Config not found" — 创建 ~/.eve-mcp/config.json 或设置 EVE_MCP_CLIENT_ID。

"Authentication required" — 调用 eve_auth_login 或 eve_auth_start。

"Token refresh failed" — 刷新令牌已过期。请重新登录。

"ESI error limit reached" — 错误请求过多。系统会自动等待。

端口 8834 被占用 — 在 config.json 中设置其他端口，并在 CCP 开发者后台更新回调 URL。

EVE Online Companion MCP Server