eve-online-mcp 0.1.2 → 0.2.0

package/README.md

@@ -6,13 +6,16 @@ The server is generated at runtime from a pinned copy of CCP's OpenAPI 3.1 docum
 
 ## What the MCP server exposes
 
-- `search_esi_operations` finds endpoints using ordinary keywords, ESI tags, and authentication requirements.
-- `get_esi_operation` returns exact parameters, request-body schema, OAuth scopes, cache hints, and rate-limit metadata.
-- `call_esi` invokes only catalogued read operations. It rejects undeclared parameters, validates values, fixes the origin to ESI, supplies compatibility headers, and never accepts an Authorization header from a tool call.
-- `eve-esi://catalog` describes the pinned API coverage and excluded operation count.
+- `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.
+- `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.
 
-ESI cache headers are respected in memory, pagination/rate-limit headers are returned to the model, errors remain structured, responses are limited to 5 MB by default, and a descriptive User-Agent is sent as [recommended by ESI](https://developers.eveonline.com/docs/services/esi/best-practices/). It is derived from the installed package version and has the form `eve-online-mcp/<version> (adam@hammo.dev; +https://github.com/HammoTime/eve-online-mcp)`.
+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](https://developers.eveonline.com/docs/services/esi/best-practices/); it is derived from the installed package version and has the form `eve-online-mcp/<version> (adam@hammo.dev; +https://github.com/HammoTime/eve-online-mcp)`.
 
 ## Development container
 
@@ -154,7 +157,11 @@ 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 model can discover the relevant endpoints instead of relying on memorized route names. Large paginated datasets should be requested one page at a time using the returned `x-pages` header.
+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
 

package/dist/character-context.d.ts

@@ -0,0 +1,17 @@
+import { type EsiClient } from "./esi-client.js";
+import type { OperationCatalog } from "./openapi.js";
+export declare const CHARACTER_SECTIONS: {
+    readonly profile: "GetCharactersCharacterId";
+    readonly location: "GetCharactersCharacterIdLocation";
+    readonly ship: "GetCharactersCharacterIdShip";
+    readonly skills: "GetCharactersCharacterIdSkills";
+    readonly skillQueue: "GetCharactersCharacterIdSkillqueue";
+    readonly wallet: "GetCharactersCharacterIdWallet";
+};
+export type CharacterSection = keyof typeof CHARACTER_SECTIONS;
+export declare function getCharacterContext(client: EsiClient, catalog: OperationCatalog, input: {
+    characterId: number;
+    sections: CharacterSection[];
+}, options?: {
+    maxResultBytes?: number;
+}): Promise<Record<string, unknown>>;

package/dist/character-context.js

@@ -0,0 +1,119 @@
+import { EsiRequestError, publicEsiError, } from "./esi-client.js";
+import { sourceMetadata } from "./workflow-common.js";
+export const CHARACTER_SECTIONS = {
+    profile: "GetCharactersCharacterId",
+    location: "GetCharactersCharacterIdLocation",
+    ship: "GetCharactersCharacterIdShip",
+    skills: "GetCharactersCharacterIdSkills",
+    skillQueue: "GetCharactersCharacterIdSkillqueue",
+    wallet: "GetCharactersCharacterIdWallet",
+};
+const SKILLS_CAVEAT = "Completed skill-queue entries can precede updates to the skills endpoint until the character next logs in; this tool does not infer adjusted skill levels.";
+function responseLimitError(limit) {
+    return new EsiRequestError(`Character context section exceeds the ${limit} byte aggregate result limit`, undefined, undefined, { code: "RESPONSE_LIMIT", retryable: false });
+}
+function serializedBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value));
+}
+export async function getCharacterContext(client, catalog, input, options = {}) {
+    const maxResultBytes = options.maxResultBytes ?? 5_000_000;
+    const caveats = input.sections.some((section) => section === "skills" || section === "skillQueue")
+        ? [
+            SKILLS_CAVEAT,
+            "Each section is fetched separately; successful retrieval does not guarantee identical observation time or freshness.",
+        ]
+        : [
+            "Each section is fetched separately; successful retrieval does not guarantee identical observation time or freshness.",
+        ];
+    const selected = input.sections.map((section) => ({
+        section,
+        operation: catalog.get(CHARACTER_SECTIONS[section]),
+    }));
+    const requiredScopes = [
+        ...new Set(selected.flatMap(({ operation }) => operation.requiredScopes)),
+    ].sort();
+    let authorization;
+    let authorizationError;
+    if (requiredScopes.length > 0) {
+        try {
+            authorization = await client.authorize(requiredScopes);
+        }
+        catch (error) {
+            authorizationError = error;
+        }
+    }
+    const sections = {};
+    let successes = 0;
+    for (const { section, operation } of selected) {
+        if (operation.requiredScopes.length > 0 && authorizationError) {
+            sections[section] = {
+                status: "error",
+                error: publicEsiError(authorizationError),
+            };
+            continue;
+        }
+        try {
+            const response = await client.call({
+                operationId: operation.operationId,
+                path: { character_id: input.characterId },
+            }, operation.requiredScopes.length > 0 ? authorization : undefined);
+            const sectionResult = {
+                status: "ok",
+                data: response.data,
+                source: sourceMetadata(response),
+            };
+            const candidate = {
+                characterId: input.characterId,
+                requestedSections: input.sections,
+                status: "complete",
+                sections: { ...sections, [section]: sectionResult },
+                atomic: false,
+                caveats,
+            };
+            if (serializedBytes(candidate) > maxResultBytes) {
+                sections[section] = {
+                    status: "error",
+                    error: publicEsiError(responseLimitError(maxResultBytes)),
+                };
+            }
+            else {
+                sections[section] = sectionResult;
+                successes += 1;
+            }
+        }
+        catch (error) {
+            sections[section] = { status: "error", error: publicEsiError(error) };
+        }
+    }
+    const buildResult = () => ({
+        characterId: input.characterId,
+        requestedSections: input.sections,
+        status: successes === selected.length
+            ? "complete"
+            : successes === 0
+                ? "failed"
+                : "partial",
+        sections,
+        atomic: false,
+        caveats,
+    });
+    let result = buildResult();
+    for (const section of [...input.sections].reverse()) {
+        if (serializedBytes(result) <= maxResultBytes)
+            break;
+        const sectionResult = sections[section];
+        if (typeof sectionResult === "object" &&
+            sectionResult !== null &&
+            "status" in sectionResult &&
+            sectionResult.status === "ok") {
+            sections[section] = {
+                status: "error",
+                error: publicEsiError(responseLimitError(maxResultBytes)),
+            };
+            successes -= 1;
+            result = buildResult();
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=character-context.js.map

package/dist/character-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"character-context.js","sourceRoot":"","sources":["../src/character-context.ts"],"names":[],"mappings":"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"}

package/dist/entity-resolution.d.ts

@@ -0,0 +1,7 @@
+import { type EsiClient } from "./esi-client.js";
+export type EntityResolutionInput = {
+    names: string[];
+} | {
+    ids: number[];
+};
+export declare function resolveEveEntities(client: EsiClient, input: EntityResolutionInput): Promise<Record<string, unknown>>;

package/dist/entity-resolution.js

@@ -0,0 +1,115 @@
+import { EsiRequestError } from "./esi-client.js";
+import { sourceMetadata } from "./workflow-common.js";
+const CATEGORY_MAP = {
+    agents: "agent",
+    agent: "agent",
+    alliances: "alliance",
+    alliance: "alliance",
+    characters: "character",
+    character: "character",
+    constellations: "constellation",
+    constellation: "constellation",
+    corporations: "corporation",
+    corporation: "corporation",
+    factions: "faction",
+    faction: "faction",
+    inventory_types: "inventory_type",
+    inventory_type: "inventory_type",
+    regions: "region",
+    region: "region",
+    stations: "station",
+    station: "station",
+    systems: "solar_system",
+    solar_system: "solar_system",
+};
+function invalidResponse(message) {
+    return new EsiRequestError(message, undefined, undefined, {
+        code: "INVALID_UPSTREAM_RESPONSE",
+        retryable: false,
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function candidateFrom(value, upstreamCategory) {
+    if (!isRecord(value) ||
+        typeof value.id !== "number" ||
+        !Number.isSafeInteger(value.id) ||
+        value.id <= 0 ||
+        typeof value.name !== "string")
+        throw invalidResponse("ESI entity resolution returned a malformed candidate");
+    return {
+        id: value.id,
+        name: value.name,
+        category: CATEGORY_MAP[upstreamCategory] ?? upstreamCategory,
+    };
+}
+function statusFor(candidates) {
+    if (candidates.length === 0)
+        return "unresolved";
+    return candidates.length === 1 ? "resolved" : "ambiguous";
+}
+function uniqueNames(names) {
+    const seen = new Set();
+    return names.filter((name) => {
+        const key = name.toLocaleLowerCase("en-US");
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+export async function resolveEveEntities(client, input) {
+    if ("names" in input) {
+        const response = await client.call({
+            operationId: "PostUniverseIds",
+            body: uniqueNames(input.names),
+        });
+        if (!isRecord(response.data))
+            throw invalidResponse("ESI name resolution did not return an object");
+        const candidates = [];
+        for (const [category, values] of Object.entries(response.data)) {
+            if (!Array.isArray(values))
+                throw invalidResponse(`ESI name resolution category ${category} was not an array`);
+            candidates.push(...values.map((value) => candidateFrom(value, category)));
+        }
+        return {
+            matchMode: "exact",
+            results: input.names.map((name) => {
+                const matches = candidates.filter((candidate) => candidate.name.toLocaleLowerCase("en-US") ===
+                    name.toLocaleLowerCase("en-US"));
+                return {
+                    input: name,
+                    status: statusFor(matches),
+                    candidates: matches,
+                };
+            }),
+            source: sourceMetadata(response),
+        };
+    }
+    const response = await client.call({
+        operationId: "PostUniverseNames",
+        body: [...new Set(input.ids)],
+    });
+    if (!Array.isArray(response.data))
+        throw invalidResponse("ESI ID resolution did not return an array");
+    const candidates = response.data.map((value) => {
+        if (!isRecord(value) || typeof value.category !== "string")
+            throw invalidResponse("ESI ID resolution returned a malformed candidate");
+        return candidateFrom(value, value.category);
+    });
+    return {
+        matchMode: "exact",
+        results: input.ids.map((id) => {
+            const matches = candidates.filter((candidate) => candidate.id === id);
+            return {
+                input: id,
+                status: statusFor(matches),
+                candidates: matches,
+            };
+        }),
+        source: sourceMetadata(response),
+        caveat: "Depending on upstream behavior, one invalid ID can cause ESI to reject the entire batch.",
+    };
+}
+//# sourceMappingURL=entity-resolution.js.map

package/dist/entity-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-resolution.js","sourceRoot":"","sources":["../src/entity-resolution.ts"],"names":[],"mappings":"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"}

package/dist/esi-client.d.ts

@@ -15,25 +15,67 @@ export interface EsiResponse {
     cached: boolean;
     headers: Record<string, string>;
     data: JsonValue | string | null;
+    freshness: {
+        fetchedAt: string;
+        servedAt: string;
+        expiresAt: string | null;
+        sourceLastModified: string | null;
+    };
+    pagination: {
+        mode: "page" | "none";
+        currentPage: number | null;
+        totalPages: number | null;
+        hasMore: boolean | null;
+        nextCall: EsiCallInput | null;
+    };
 }
+export type EsiErrorCode = "UNKNOWN_OPERATION" | "VALIDATION_ERROR" | "AUTHENTICATION_REQUIRED" | "AUTHENTICATION_FAILED" | "MISSING_SCOPES" | "FORBIDDEN" | "NOT_FOUND" | "THROTTLED" | "NETWORK_ERROR" | "UPSTREAM_ERROR" | "RESPONSE_LIMIT" | "INVALID_UPSTREAM_RESPONSE";
 export declare class EsiRequestError extends Error {
     readonly status?: number | undefined;
     readonly details?: (JsonValue | string) | undefined;
-    constructor(message: string, status?: number | undefined, details?: (JsonValue | string) | undefined);
+    readonly metadata: {
+        code?: EsiErrorCode;
+        retryable?: boolean;
+        retryAfterSeconds?: number | null;
+        suggestedAction?: string | null;
+    };
+    constructor(message: string, status?: number | undefined, details?: (JsonValue | string) | undefined, metadata?: {
+        code?: EsiErrorCode;
+        retryable?: boolean;
+        retryAfterSeconds?: number | null;
+        suggestedAction?: string | null;
+    });
+    get code(): EsiErrorCode;
+    get retryable(): boolean;
+    get retryAfterSeconds(): number | null;
+    get suggestedAction(): string | null;
+}
+export interface EsiAuthorization {
+    readonly authorizationContext: "esi";
 }
+export declare function publicEsiError(error: unknown): Record<string, unknown>;
 export declare class EsiClient {
     private readonly catalog;
     private readonly tokenProvider;
     private readonly options;
     private readonly cache;
+    private readonly authorizationTokens;
+    private readonly responseSizes;
     private readonly baseUrl;
     constructor(catalog: OperationCatalog, tokenProvider: TokenProvider, options?: {
         fetchImplementation?: typeof fetch;
         userAgent?: string;
         maxResponseBytes?: number;
         baseUrl?: string;
+        clock?: () => Date;
     });
-    call(input: EsiCallInput): Promise<EsiResponse>;
+    authorize(requiredScopes: string[]): Promise<EsiAuthorization>;
+    responseByteLength(response: EsiResponse): number;
+    call(input: EsiCallInput, authorization?: EsiAuthorization): Promise<EsiResponse>;
+    private now;
+    private requireToken;
+    private tokenFor;
+    private paginationFor;
     private buildUrl;
     private buildHeaders;
     private rejectUnknown;