EVE Online MCP

A read-only Model Context Protocol server for EVE Online, with the complete ESI API surface, public zKillboard killmails, skill planning and map rendering. It lets an AI assistant retrieve public or character data and turn that context into practical plans for your next adventure.

The server is generated at runtime from a pinned copy of CCP's OpenAPI 3.1 document. Today it exposes all GET/HEAD routes plus an explicitly audited allowlist of semantically read-only POST lookups (bulk ID/name resolution, affiliations, CSPA calculation, and asset name/location lookup). Every state-changing operation is excluded.

What the MCP server exposes

• list_eve_characters lists saved character IDs, names, and granted scopes without exposing credentials.
• authorize_eve_character opens browser consent for a specific character, verifies the selected identity, and stores that character's refresh credential. select_eve_character chooses a saved character for protected operations that do not name one. These tools manage local authentication only; they never change game state.
• search_esi_operations ranks endpoints using deterministic lexical and curated intent matching, supports hard tag/authentication filters and offsets, and explains every match.
• get_esi_operation returns exact parameters, request-body schema, required caller inputs, defaults, pagination guidance, OAuth scopes, cache hints, safe examples where available, and rate-limit metadata.
• call_esi invokes one page of one catalogued read operation. It rejects undeclared parameters, validates values, fixes the origin to ESI, supplies compatibility headers, and never accepts an Authorization header from a tool call.
• resolve_eve_entities performs one exact-only public batch lookup from names to every matching ID/category, or from IDs to names/categories. Ambiguous and unresolved values remain explicit.
• get_character_context retrieves only the requested profile, location, ship, skills, skillQueue, and/or wallet sections for an explicit character ID, with per-section data, freshness, and errors.
• get_market_snapshot collects bounded pages of public regional orders for one type, optionally filters one exact location, and returns observed aggregates with honest completeness warnings.
• search_zkillmails searches public zKillboard killmails by character, corporation, alliance, ship or location, with kill/loss, time-window and space filters. No EVE login is required.
• get_zkillmail retrieves one public zKillboard killmail by ID, including victim, attackers and zkb metadata. Both tools return bounded results with explicit freshness and incomplete-history warnings.
• Skill tools automatically initialize CCP's official static data and report its build/freshness. Startup warms the local skill cache in the background.
• resolve_skill_plan_targets resolves exact skill/ship names or type IDs against the cache, including explicit skill levels and unique singular skill names. Ambiguous or unresolved inputs return candidates.
• get_skill_dependencies returns a public prerequisite graph with skill-level nodes and prerequisite-to-dependent edges, without login.
• generate_skill_plan computes a personalized, dependency-checked plan from cached requirements and scoped character skills/queue, removes completed levels, and returns training text and estimated remaining SP.
• plan_eve_route computes a complete directed permanent-stargate route or pickup loop, using shortest paths and exact stop optimization. Submit all stops and constraints together; the MCP owns ordering and totals. It returns a private expiring routeId.
• render_eve_map renders that routeId unchanged, with a larger padded canvas for crowded maps and plain route text if rendering fails. Context maps use an explicit boundary and points of interest. Raw route arrays are rejected. Request preview:"png" for inline images; SVG originals are MCP resources. The assistant must never compute, merge or draw substitute routes or skill plans. See cartography.
• eve-esi://catalog describes pinned API coverage, excluded operation count, and guidance for the generic and focused workflows.
• plan_eve_adventure is a prompt for evidence-based recommendations with costs, preparation, risk, travel, and a concrete first action. Its optional activity playbooks cover exploration, factional warfare, mining, industry, trading, hauling, agent missions, PvE, and PvP.
• plan_eve_skills interprets activity/class goals, resolves material choices, and calls the deterministic planning tools. It explains practical support, optional upgrades and eligibility limits.

ESI cache headers are respected in memory, protected cache entries are isolated by credential context, and every response reports fetch/serve/expiry timestamps plus defensive page metadata. Errors include stable codes, retryability, Retry-After guidance, and a suggested action. Individual responses and bounded composite workflows use 5 MB safety ceilings. A descriptive User-Agent is sent as recommended by ESI; it is derived from the installed package version and has the form eve-online-mcp/<version> ([email protected]; +https://github.com/HammoTime/eve-online-mcp).

The response cache is bounded to 128 entries and 20,000,000 serialized UTF-8 bytes, with expiry eviction. Identical concurrent GETs share a credential-isolated request after each caller is authorized; POSTs do not. There are at most 64 tracked wire requests with 64 waiters each, and a 30-second wire/body deadline. Each waiter can cancel independently, including with telemetry disabled. Cancellation does not interrupt refresh-token persistence. Protected pagination preserves an explicit acting character even when served from cache.

zKillboard killmail integration

Available from 0.10.0, search_zkillmails and get_zkillmail work immediately after configuring the MCP server. No zKillboard API key or EVE login is needed. After upgrading an existing installation, restart or reconnect the MCP host to refresh its tool list; the server exposes 16 tools.

Ask your assistant: "Show public zKillboard killmails in Jita from the past 24 hours." It should first resolve the system with resolve_eve_entities, then call search_zkillmails. Example search arguments:

{
  "entityType": "solarSystem",
  "entityId": 30000142,
  "pastSeconds": 86400,
  "page": 1
}

For a known killmail, call get_zkillmail with {"killmailId":138006538}. It returns the public record when available; an unavailable record produces an explicit error. The server never submits killmails.

Searches read one upstream page of at most 200 records. Results are cached for one hour, and upstream withholds killmails less than five minutes old. Combat history is delayed and incomplete; an empty result does not prove a system is safe or inactive. complete:false describes that historical coverage, while output.complete describes whether the selected response value was fully returned. Follow output continuation metadata before requesting the next upstream page.

See the full zKillboard filters and limits and response-budget and continuation examples.

Development container

All project commands are intended to run in the devcontainer. In VS Code, choose Dev Containers: Reopen in Container. The container installs the locked dependencies automatically.

From another devcontainer-capable editor, open this repository using .devcontainer/devcontainer.json. If you only have Docker, the equivalent environment is:

docker build --target development -f .devcontainer/Dockerfile -t eve-online-mcp-dev .
docker run --rm -it -v "$PWD:/workspace" -w /workspace eve-online-mcp-dev npm ci

The supported commands are:

npm run dev           # serve MCP over stdio from TypeScript
npm run validate      # formatting, lint, typecheck, tests/coverage, build
npm run schema:check  # compare the pinned and current upstream schemas
npm run schema:update # replace the pin with canonical current OpenAPI JSON

Install and configure an MCP host

Requires Node.js 22.13.0 or newer, including its built-in node:sqlite module. No SQLite CLI, database service, or additional native database package is needed. Node versions that label SQLite experimental may print a warning to stderr; stdout remains reserved for MCP. Once published, configure your MCP host to run the npm package directly:

{
  "mcpServers": {
    "eve-online": {
      "command": "npx",
      "args": ["-y", "eve-online-mcp"]
    }
  }
}

For a local checkout, build in the devcontainer and use node /absolute/path/to/eve-online-mcp/dist/index.js instead.

During MCP initialization, the server reports the version from its installed package.json, so MCP host diagnostics identify the running package release.

Optional OpenTelemetry exports traces, correlated logs and delta metrics. Set OTEL_EXPORTER_OTLP_ENDPOINT to an OTLP HTTP base endpoint and OTEL_EXPORTER_OTLP_HEADERS to a JSON object of ingestion headers. Both values belong in the MCP host's private environment. The endpoint is HTTPS, with HTTP allowed only for a localhost collector. Omit it to disable telemetry.

Reviewed public inputs, effective limits, decisions and output counts provide context without credentials or private character data. MCP result metadata includes eve/trace-id. Diagnostic files default to ~/.eve-online-mcp/diagnostics; override with EVE_DIAGNOSTICS_DIR. OTEL_DEPLOYMENT_ENVIRONMENT defaults to local. Shutdown flushes on EOF, SIGINT and SIGTERM; stdout remains reserved for JSON-RPC. See the capture and offline replay runbook. Replay/export commands run from a source checkout and its devcontainer. Dirty or unversioned builds explicitly produce partial captures.

Discovery in Codex and other MCP hosts

Installing the npm package makes the executable available; the MCP host must also be configured to launch it. For Codex, register the stdio server with:

codex mcp add eve-online -- npx -y eve-online-mcp
codex mcp list

The server advertises EVE Online use cases in every tool's title and description, and returns workflow guidance in the MCP initialization instructions field. This lets hosts recognize character sheets, skills, skill queues, markets and other ESI data requests before a prompt or catalog resource is opened. Codex reads these instructions; other hosts may handle them differently. Tool selection remains the host's decision.

All 16 tools advertise structured output schemas, matching the shared contracts used by the hosted server. Successful results retain their direct object shape, including explicit partial results and freshness; they are not wrapped in a result property. Refresh the host's tool listing after an upgrade.

For public combat history, see zKillboard killmail integration. Tool responses use bounded model-facing slices; follow output continuation metadata for omitted details. Map PNG previews now require preview: "png"; SVG remains the primary artifact.

For a named character's training plan, use resolve_eve_entities to select the character-category ID, resolve_skill_plan_targets to verify goals, then generate_skill_plan with that explicit character ID. The planner retrieves skills and queue itself. get_character_context remains available for character inspection, and other ESI questions use search_esi_operations, get_esi_operation, then call_esi. Public discovery needs no login; protected data uses EVE SSO. ESI does not expose Omega subscription status or saved in-game skill plans, and skill injector recommendations require current game rules and explicit assumptions in addition to character data.

To check discovery after updating the configured server, reconnect it or start a fresh host session and confirm that its tool list contains EVE Online tool titles. Try a request such as: "Use EVE Online data to review the character sheet, skills and skill queue for , and suggest a hauling training plan." The host should discover the EVE tools and resolve the name before retrieving the needed sections. Inspect the tool-call trace to verify that it uses MCP for ESI-covered data before inspecting the game client. This is a manual host check; the automated tests verify initialization metadata and tool listings, not model selection behavior.

If the host still overlooks the server, capture the exact prompt, host/model version, configured server command and arguments, initialization instructions, tool listing and relevant tool-call sequence. Exclude credentials, tokens and private character responses from a shared report. This distinguishes a connection or stale-metadata problem from a host tool-selection problem.

EVE SSO

Public ESI routes need no credentials and never trigger login. Ask Codex for a character's protected data: when that character has no saved authorization, the server automatically opens EVE SSO in the browser. Select the requested character and approve access; the server verifies the identity, saves its separate refresh credential, and continues the request. Repeat for another character on the same or a different EVE account. Previously authorized characters remain available. No commands, client secret, or manual token handling are required.

Credentials are stored per character, not per EVE account. Both call_esi and get_character_context select the credential matching the requested character_id/characterId. A wrong-character browser selection saves nothing and reports the requested and selected IDs. Tokens with a different or unreadable character subject are rejected before making a protected character request. A remaining upstream 403 identifies the character and required scopes; ownership or corporation roles can still deny access even with the correct character.

Codex can inspect saved authorizations using list_eve_characters and renew consent using authorize_eve_character when scopes are missing or a grant has expired or been revoked. For corporation, fleet, or structure operations without a character path parameter, a sole saved character is used automatically. With multiple saved characters and no default, the server asks Codex to use select_eve_character for the intended character. This default never overrides a character-specific request. Login dialogs are serialized, and simultaneous requests for the same missing character share a successful login.

The selected default persists across sessions sharing the local credential file. Prefer call_esi.actingCharacterId for a single request. get_character_context returns permitted sections even when another requested section lacks a scope; blocked sections retain explicit errors.

The versioned credential file lives in the user's OS configuration directory. Each entry stores a character ID/name, client ID, granted scopes, creation time, and refresh token. Access tokens stay in memory. Login and refresh validate EVE's signature, issuer, audiences, expiration, and character claims. Refresh-token rotation updates only the matching character; writes use a restricted-permission temporary file, atomic replacement, and locks to coordinate concurrent processes. Running servers reread the store to notice new consent or removal. Old single-credential files migrate on their next protected use after the character identity is verified; adding a new character before migration preserves the legacy credential.

The package ships with this public PKCE client configuration:

• Client ID: 6a65f1e650d240659dafbad29fb55e05
• Callback URL: http://localhost:52765/callback

The callback must match the EVE application registration exactly. PKCE is intended for local applications that cannot keep a client secret, so never distribute or commit the client secret. Optional maintenance commands are available, but are not needed for the Codex workflow. auth logout removes all local character credentials:

npx eve-online-mcp auth login
npx eve-online-mcp auth status
npx eve-online-mcp auth logout

The default login requests the complete authenticated read-only scope set from the pinned schema. A narrower login can be requested with auth login --scopes "scope.one scope.two", though operations outside that grant will remain unavailable.

esi-alliances.read_contacts.v1
esi-assets.read_assets.v1
esi-assets.read_corporation_assets.v1
esi-calendar.read_calendar_events.v1
esi-characters.read_agents_research.v1
esi-characters.read_blueprints.v1
esi-characters.read_contacts.v1
esi-characters.read_corporation_roles.v1
esi-characters.read_fatigue.v1
esi-characters.read_fw_stats.v1
esi-characters.read_loyalty.v1
esi-characters.read_medals.v1
esi-characters.read_notifications.v1
esi-characters.read_standings.v1
esi-characters.read_titles.v1
esi-clones.read_clones.v1
esi-clones.read_implants.v1
esi-contracts.read_character_contracts.v1
esi-contracts.read_corporation_contracts.v1
esi-corporations.read_blueprints.v1
esi-corporations.read_contacts.v1
esi-corporations.read_container_logs.v1
esi-corporations.read_corporation_membership.v1
esi-corporations.read_divisions.v1
esi-corporations.read_facilities.v1
esi-corporations.read_fw_stats.v1
esi-corporations.read_medals.v1
esi-corporations.read_standings.v1
esi-corporations.read_starbases.v1
esi-corporations.read_structures.v1
esi-corporations.read_titles.v1
esi-corporations.track_members.v1
esi-fittings.read_fittings.v1
esi-fleets.read_fleet.v1
esi-industry.read_character_jobs.v1
esi-industry.read_character_mining.v1
esi-industry.read_corporation_jobs.v1
esi-industry.read_corporation_mining.v1
esi-killmails.read_corporation_killmails.v1
esi-killmails.read_killmails.v1
esi-location.read_location.v1
esi-location.read_online.v1
esi-location.read_ship_type.v1
esi-mail.read_mail.v1
esi-markets.read_character_orders.v1
esi-markets.read_corporation_orders.v1
esi-markets.structure_markets.v1
esi-planets.manage_planets.v1
esi-planets.read_customs_offices.v1
esi-search.search_structures.v1
esi-skills.read_skillqueue.v1
esi-skills.read_skills.v1
esi-universe.read_structures.v1
esi-wallet.read_character_wallet.v1
esi-wallet.read_corporation_wallets.v1

EVE_ACCESS_TOKEN, EVE_REFRESH_TOKEN, EVE_CLIENT_ID, and EVE_CLIENT_SECRET remain supported as non-default overrides for automation or existing credentials. An environment token override represents one character and takes precedence over the local store; browser authorization tools are unavailable in that mode. Character requests still check the token subject and required scopes before spending an ESI request. Remove the token override to use automatic multi-character login.

Optional settings:

| Variable | Purpose | | ------------------------ | --------------------------------------------------------------------------------------------------- | | ESI_USER_AGENT | Optional override for a downstream app's identity/contact | | ESI_MAX_RESPONSE_BYTES | Positive finite integer overriding the 5,000,000-byte response ceiling; invalid values fail startup | | ESI_OPENAPI_PATH | Loads a different local OpenAPI document for development | | EVE_CREDENTIALS_PATH | Overrides the OS credential file location | | EVE_DISABLE_AUTO_SSO | Set to 1 to prevent browser login on protected calls | | EVE_SSO_REDIRECT_URI | Overrides the localhost callback for a custom application | | EVE_SDE_CACHE_DIR | Overrides the local CCP static-data cache directory |

Do not commit tokens or client secrets. Tool responses never include the token, and callers cannot override the ESI origin or inject arbitrary headers.

Suggested usage

Plan and visualize a route

Call plan_eve_route with exact names or numeric IDs for origin, destination and every required stop in stops. Use the origin again as destination for a loop. The default stopOrder:"optimize" computes the exact minimum-jump order; as_given preserves a requested sequence. Optional avoid and raw-SDE minimumSecurity are hard constraints. The planner supports 12 stops and 250 visits, uses public cached permanent-stargate data, and fails explicitly if a complete route cannot be produced. It makes no live safety or cargo guarantee.

Pass its returned routeId to render_eve_map with preview:"png". Crowded maps retry on a larger padded canvas. If rendering fails, the complete stored route remains available as text. Never concatenate pairwise ESI routes, merge plans, generate solving/drawing scripts, or trim route steps. Missing or failed tools mean the limitation must be reported. The MCP is the sole planning authority.

For a context map without a route, provide boundary and pointsOfInterest:

{
  "boundary": { "kind": "constellation", "constellation": "Kimotoro" },
  "pointsOfInterest": [
    { "system": "Jita", "kind": "staging", "label": "Departure" }
  ],
  "theme": "dark",
  "preview": "png"
}

This is an illustration, not a safety recommendation. SVG is the primary artifact; PNG preview and actual inline display depend on rasterizer/host support. The eve-map:// resource URI is read through MCP, not opened as a public website. Generated files expire after seven days or earlier storage eviction. Configure their directory with EVE_MAP_ARTIFACT_DIR. The tool writes these local artifacts but never changes game state. See the interface, limits and development examples.

For a center and all directly connected permanent-stargate neighbors, one call is enough. No ESI system/gate lookup sequence or character login is needed:

{
  "boundary": { "kind": "neighborhood", "center": "Jita", "jumps": 1 },
  "pointsOfInterest": []
}

Character skill training plans

The executable planner supports published skills and ship hulls from CCP's official JSONL SDE. On first startup it downloads the archive in the background; planning waits for initialization. The archive is roughly 95 MB at the previously verified build and can change in size. The public cache uses normalized skills-v1.sqlite tables and indexed maps-v1.sqlite projections. SQLite is the runtime data source, not a container for a full in-memory skill catalog. Skills and maps share a bounded, persistent archive cache for their independent imports. No character snapshots, credentials, private ESI responses, or map annotations are written to these databases.

Defaults are %LOCALAPPDATA%\eve-online-mcp\sde on Windows, ~/Library/Caches/eve-online-mcp/sde on macOS, and $XDG_CACHE_HOME/eve-online-mcp/sde or ~/.cache/eve-online-mcp/sde on Linux. Set EVE_SDE_CACHE_DIR in the MCP server environment for a different location. In a container this is a container path: mount a persistent volume there to retain data between runs.

Each initialization checks CCP's latest-build manifest when the last successful check is at least five minutes old; the operator command eve-online-mcp static-data refresh checks immediately and prints build/freshness status. Conditional ETag requests avoid unchanged downloads. SQLite transactions fence build publication and freshness updates so a slower older writer cannot replace a newer build. A failed refresh retains the last validated build with a stale warning rather than supplying empty requirements. Downloads use fixed CCP URLs, bounded streaming and selected ZIP entries, without extracting archive paths.

Existing checksum-validated JSON caches migrate automatically when the corresponding database is absent. Legacy files remain untouched, and an existing corrupt or unsupported database never silently falls back to older JSON. Maps read only the selected geography and touching connections from one SQLite snapshot; normal map requests do not deserialize the whole universe. Skills resolve names and read only required type/prerequisite rows from a request-scoped snapshot. Existing 0.8.0 skill databases migrate transactionally to the normalized schema in place. See local storage for migration, recovery, concurrency, and performance limits.

Example MCP tool arguments (replace 42 with the intended, verified character ID):

resolve_skill_plan_targets {"target":"exhumer"}
get_skill_dependencies {"target":"Hulk"}
generate_skill_plan {"characterId":42,"target":"Mining II"}
generate_skill_plan {"characterId":42,"target":"exhumer"}
generate_skill_plan {"characterId":42,"targets":[{"typeId":3386,"level":2},"Hulk"],"queuePolicy":"reorder"}

target and targets are mutually exclusive; at most 50 targets are accepted. Names match case-insensitively, with surrounding whitespace removed. Skills accept Roman or numeric levels I–V / 1–5. A bare skill defaults to I, so exhumer resolves to Exhumers I, not a guessed Hulk fit. Exact ship names produce minimum hull requirements; training the class skill alone does not establish that every hull can be flown. Partial names return suggestions without selecting one. Modules, rigs and complete fitting plans are outside the engine's scope.

The graph uses (skillId, level) nodes, all six dogma prerequisite slots, and preceding-level edges. An iterative dependency traversal deduplicates shared nodes, then Kahn's topological sort orders them in O(V + E) time and memory for the expanded graph. A separate replay checks every step against the source requirements. Cycles and missing prerequisite metadata fail closed. Already satisfied permanent levels prune completed branches; requesting another level checks current requirements.

generate_skill_plan requires both esi-skills.read_skills.v1 and esi-skills.read_skillqueue.v1 for the chosen character, checked together before either ESI request. It validates complete skills and queue snapshots, credits partial SP once, and distinguishes trained levels from active restrictions. queuePolicy=preserve (default) keeps the observed queue and returns additions after that queue, using a conditional projected baseline. reorder returns a proposed replacement that includes unrelated queued commitments. Future queue rows never become observed completion; contradictory past completion requires refreshed evidence. Neither policy edits the live queue.

Results contain resolved targets, SDE build/freshness, character source timestamps, retained queue, ordered plan, graph edges, estimated missing SP, acquisition checks, and copyable trainingText. An empty plan means no additional levels under its declared baseline. Estimates do not establish Alpha/Omega eligibility, fit validity, budget, training duration, or optimal milestone timing. Formula rounding may differ by one SP; source caveats are returned with the result. Review the in-game import preview and available queue slots before applying text.

Natural-language goals

Select the plan_eve_skills MCP prompt in your host. It requires character (an exact character name or ID, as a string) and goal (a role, hull/fit, doctrine, or target skill list). Optional constraints captures the time horizon, Alpha/Omega state, budget, and preferences. Optional queuePolicy is preserve by default, or reorder to request a proposed new order while retaining unrelated commitments.

Example prompt arguments:

{
  "character": "Exact Character Name",
  "goal": "Build a practical hauling training plan with an early usable milestone",
  "constraints": "Omega; prioritize the first two weeks; no remap or paid skill points",
  "queuePolicy": "preserve"
}

The prompt handles requests such as "I want to fly Jump Freighters" by distinguishing the class skill from a specific racial hull and asking for a material choice when needed. It verifies selected targets and calls generate_skill_plan for dependencies, progress subtraction, ordering and SP estimates. It separates mandatory hull unlocks, practical support and discretionary upgrades, labels eligibility and timing gaps, and preserves the tool's training text unchanged. The model does not reconstruct the dependency graph or perform a second calculation.

Fetching the prompt does not fetch private data or trigger SSO. The host model subsequently uses the read-only tools. The prompt cannot change a queue, save an in-game plan, purchase/inject skills, or allocate SP. Goal interpretation and discretionary recommendations still depend on the host model; dependency expansion and personalized plan computation execute in tested code. See the research, algorithm rationale and review scenarios for provenance and limits.

Adventure planning

Select the plan_eve_adventure prompt in your MCP host, or ask something like:

Using my current location, skills, wallet, assets, and the nearby market, give me three two-hour exploration plans. Explain risk and startup cost, then recommend the best first step.

The prompt accepts a required free-form goal, plus optional activity, characterId, and constraints arguments. Supported activity values are exploration, factional_warfare, mining, industry, trading, hauling, missions, pve, and pvp. Omitting activity retains the general planning workflow.

Each activity selects a focused evidence and advice playbook. For example, mining planning can locate owned mining-capable ships, compare the work needed to retrieve them, examine recent mining and skills, compare routes to accessible public markets, and recommend a resource only when price, demand, logistics, and capability support it. Factional-warfare planning checks enrollment, skills, owned ships, budget, war-zone and route evidence, then provides enrollment, staging, ship, and in-game FW-map guidance. Loyalty-point recommendations require current in-game offer details because ESI does not expose the LP Store catalogue.

The model can resolve exact names/IDs, request explicit character sections, and use the bounded public market workflow without relying on memorized route names. Generic questions still use search, inspect, and call. call_esi always remains one page; when its validated page count is available, another page can be requested with the returned pagination.nextCall.

Character context is not an atomic snapshot: each requested section reports its own source and freshness, and successful public profile retrieval can coexist with a protected-section authentication failure. Skill and skill-queue results retain ESI's warning that completed queue entries may not appear in the skills endpoint until the next character login.

Market snapshots cover the public regional orders endpoint only. locationId is an exact local filter over those regional rows, not access to private structure markets. Completeness means all reported pages were accepted within the selected page/byte bounds without detected inconsistency; it does not mean prices are real-time, universally accessible, or executable. Buy-order range and minimum volume still apply, and an observed spread is not guaranteed profit.

Schema monitoring

The shared runtime and pinned schema live in the public eve-online-mcp-lib Git submodule at lib/. Clone this repository with git clone --recurse-submodules, or run git submodule update --init --recursive in an existing checkout before installing dependencies. The devcontainer and CI initialize the submodule.

The library owns ESI validation and caching, token refresh and verification, MCP tool/resource/prompt registration, static-data parsing, and skill planning. This application supplies stdio transport, browser PKCE login, local credential and SQLite SDE storage, and package metadata. Its small src/ forwarding modules preserve the existing local integration points. The build compiles the pinned library into dist/ with the schema; npm installs need neither Git nor a library checkout.

To update shared code, commit and push the library change first, then commit the new lib submodule pointer here. Run the library's npm run validate in its own devcontainer and this application's npm run validate and npm pack --dry-run in the application devcontainer. Application tests include the pinned library suite and local auth, credential, archive, and MCP integration coverage.

The hosted application uses the same shared tools with its own MCP OAuth, Cloudflare D1/R2 storage, and transport adapters. Those host-specific authentication and networking layers are not needed by the local stdio server.

esi-schema-monitor.yml remains in eve-online-mcp, not the library repository. It runs daily at 07:23 UTC and on demand. It checks out this application's pinned lib revision, downloads CCP's current schema, canonicalizes both documents, and compares SHA-256 hashes and operation definitions. It does not automatically replace the schema or approve new operations.

When a difference is detected, the workflow automatically files ESI OpenAPI schema update required in HammoTime/eve-online-mcp, with the hashes and added, removed, and modified routes. An existing open issue is updated with the latest diff; an identical repeat leaves it unchanged, without duplicate issues or comments. The issue lookup checks every page directly rather than relying on search indexing. Matching schemas do not create an issue. Forks do not run this monitor against the upstream repository.

After reviewing an update:

npm run schema:update
npm run validate

Review any new non-GET operation manually. Read-only POST routes are deliberately allowlisted in lib/src/openapi.ts; a new route is not exposed until its semantics are verified.

schema:update changes lib/openapi/esi-openapi.json. Review and publish that library commit before advancing this application's submodule pointer; do not leave the schema only in a modified or detached submodule checkout.

Publishing to npm and GitHub Packages

release.yml runs on every push to main and on explicit dispatches from the maintenance automation. Release Please maintains a release pull request using Conventional Commit history; use subjects such as fix: repair release workflow or feat: add route planning. Dependabot uses fix(deps): and fix(deps-dev): subjects so dependency maintenance produces patch releases. A verified release pull request from the dedicated release app is approved and squash-merged automatically after required checks pass. That pull request updates package.json, package-lock.json, and CHANGELOG.md together. Merging it creates the matching Git tag and GitHub Release, then validates and packs the project inside the devcontainer and publishes that exact version as eve-online-mcp on npmjs and @hammotime/eve-online-mcp on GitHub Packages. A guarded assertion compares the release version, Git tag, and the tagged package.json before publishing. Registry-specific checks make reruns safe after a partial publish and also bootstrap an existing matching GitHub Release when either registry is missing its package version.

Publishing to npmjs uses npm trusted publishing through GitHub OIDC and produces provenance. On npm, configure the trusted publisher as repository HammoTime/eve-online-mcp, workflow release.yml, and environment npmjs.com, with direct publishing allowed. Because an unclaimed package cannot have trusted publishing configured yet, its first release requires a granular npm automation token stored as the NPM_TOKEN GitHub secret. That one-time bootstrap publish does not request provenance, which also permits recovery of a historical tag whose repository metadata predates the current GitHub owner. After the initial publish, configure trusted publishing and remove the secret; subsequent OIDC releases publish provenance. The separate GitHub Packages job deploys to the github.com environment and uses the workflow's short-lived GITHUB_TOKEN with packages: write; no additional package secret is required.

Test suite

Vitest covers catalog filtering, local $ref resolution, safe URL and header construction, schema validation, OAuth refresh and scopes, caching, response limits, error handling, schema diffing, and end-to-end MCP tool/resource/prompt calls over an in-memory transport. Coverage gates require at least 80% for statements, lines, functions, and branches. GitHub CI executes the same npm run validate command inside the devcontainer image.

CI then packs that validated build and checks the installed package on Linux, Windows and macOS with Node 22.13.0, plus Linux with Node 26.8.1. These native jobs do not build source: they install only the tarball/runtime dependencies with install scripts disabled, then block network/browser calls during the stdio, SQLite-restart, skill-query and PNG/SVG smoke. The existing required validate check waits for the full matrix. These checks do not benchmark the real SDE or certify network filesystems.

Licensed under the GNU AGPL v3.