universalis-mcp-server 0.1.0 → 0.2.0

package/dist/services/materia.js

@@ -0,0 +1,189 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_MATERIA_CACHE_TTL_MS } from "../constants.js";
+import { extractMateriaGrade, parseMateriaCategoryInput } from "../utils/materia.js";
+const DEFAULT_MATERIA_FIELDS = "BaseParam.Name,Item[].Name";
+const DEFAULT_MATERIA_LIMIT = 200;
+const craftingParams = new Set(["Craftsmanship", "Control", "CP"]);
+const gatheringParams = new Set(["Gathering", "Perception", "GP"]);
+const defaultIndex = {
+    generated_at: new Date(0).toISOString(),
+    categories: {
+        combat: {},
+        crafting: {},
+        gathering: {},
+    },
+};
+const dataPath = (() => {
+    if (process.env.MATERIA_DATA_PATH) {
+        return path.resolve(process.env.MATERIA_DATA_PATH);
+    }
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(currentDir, "../../data/materia.json");
+})();
+let cachedIndex = null;
+let refreshPromise = null;
+function parseTtlMs() {
+    const raw = process.env.MATERIA_CACHE_TTL_MS;
+    if (!raw)
+        return DEFAULT_MATERIA_CACHE_TTL_MS;
+    const parsed = Number(raw);
+    return Number.isNaN(parsed) ? DEFAULT_MATERIA_CACHE_TTL_MS : parsed;
+}
+function isRefreshEnabled() {
+    const raw = process.env.MATERIA_REFRESH;
+    if (!raw)
+        return true;
+    return raw.toLowerCase() !== "false";
+}
+function isStale(index) {
+    if (!index?.generated_at)
+        return true;
+    const generatedAt = Date.parse(index.generated_at);
+    if (Number.isNaN(generatedAt))
+        return true;
+    return Date.now() - generatedAt > parseTtlMs();
+}
+function categorizeBaseParam(name) {
+    if (craftingParams.has(name))
+        return "crafting";
+    if (gatheringParams.has(name))
+        return "gathering";
+    return "combat";
+}
+async function loadMateriaIndexFromDisk() {
+    try {
+        const raw = await readFile(dataPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed?.categories)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+async function saveMateriaIndex(index) {
+    const payload = JSON.stringify(index, null, 2);
+    await mkdir(path.dirname(dataPath), { recursive: true });
+    await writeFile(dataPath, `${payload}\n`, "utf8");
+}
+async function fetchMateriaIndex(xivapi) {
+    const categories = {
+        combat: {},
+        crafting: {},
+        gathering: {},
+    };
+    const baseParamCategory = {};
+    let after;
+    let version;
+    while (true) {
+        const data = await xivapi.getSheetRows("Materia", {
+            limit: DEFAULT_MATERIA_LIMIT,
+            after,
+            fields: DEFAULT_MATERIA_FIELDS,
+        });
+        if (!data || !Array.isArray(data.rows) || data.rows.length === 0) {
+            if (!version && typeof data?.version === "string") {
+                version = data.version;
+            }
+            break;
+        }
+        if (!version && typeof data.version === "string") {
+            version = data.version;
+        }
+        for (const row of data.rows) {
+            const baseParamName = row.fields?.BaseParam?.fields?.Name;
+            if (!baseParamName)
+                continue;
+            const category = categorizeBaseParam(baseParamName);
+            baseParamCategory[baseParamName] = category;
+            const items = row.fields?.Item ?? [];
+            for (const item of items) {
+                const itemName = item.fields?.Name;
+                if (!itemName)
+                    continue;
+                const grade = extractMateriaGrade(itemName);
+                if (!grade)
+                    continue;
+                const gradeBucket = categories[category][grade] ?? [];
+                if (!gradeBucket.includes(itemName)) {
+                    gradeBucket.push(itemName);
+                }
+                categories[category][grade] = gradeBucket;
+            }
+        }
+        const lastRow = data.rows[data.rows.length - 1];
+        const lastId = lastRow?.row_id;
+        if (!lastId || data.rows.length < DEFAULT_MATERIA_LIMIT) {
+            break;
+        }
+        if (after === lastId) {
+            break;
+        }
+        after = lastId;
+    }
+    for (const category of Object.keys(categories)) {
+        for (const grade of Object.keys(categories[category])) {
+            categories[category][grade] = categories[category][grade].sort();
+        }
+    }
+    return {
+        generated_at: new Date().toISOString(),
+        ...(version ? { xivapi_version: version } : {}),
+        categories,
+        base_param_category: baseParamCategory,
+    };
+}
+async function refreshIndex(xivapi, waitForResult) {
+    if (!isRefreshEnabled()) {
+        cachedIndex = cachedIndex ?? defaultIndex;
+        return cachedIndex;
+    }
+    if (refreshPromise) {
+        return waitForResult ? refreshPromise : cachedIndex ?? defaultIndex;
+    }
+    refreshPromise = (async () => {
+        try {
+            const index = await fetchMateriaIndex(xivapi);
+            cachedIndex = index;
+            await saveMateriaIndex(index);
+            return index;
+        }
+        catch (error) {
+            cachedIndex = cachedIndex ?? defaultIndex;
+            return cachedIndex;
+        }
+        finally {
+            refreshPromise = null;
+        }
+    })();
+    return waitForResult ? refreshPromise : cachedIndex ?? defaultIndex;
+}
+async function getMateriaIndex(xivapi) {
+    if (!cachedIndex) {
+        cachedIndex = (await loadMateriaIndexFromDisk()) ?? null;
+    }
+    if (!cachedIndex) {
+        return refreshIndex(xivapi, true);
+    }
+    if (isStale(cachedIndex)) {
+        void refreshIndex(xivapi, false);
+    }
+    return cachedIndex;
+}
+export async function expandMateriaCategory(input, xivapi) {
+    const parsed = parseMateriaCategoryInput(input);
+    if (!parsed)
+        return null;
+    const index = await getMateriaIndex(xivapi);
+    const expandedNames = parsed.grade
+        ? index.categories[parsed.category]?.[parsed.grade] ?? []
+        : [];
+    return {
+        category: parsed.category,
+        grade: parsed.grade,
+        expandedNames,
+    };
+}

package/dist/services/saddlebag.js

@@ -0,0 +1,25 @@
+import { SADDLEBAG_BASE_URL } from "../constants.js";
+import { requestJson } from "./http.js";
+export class SaddlebagClient {
+    baseUrl;
+    timeoutMs;
+    limiter;
+    userAgent;
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl ?? SADDLEBAG_BASE_URL;
+        this.timeoutMs = options.timeoutMs;
+        this.limiter = options.limiter;
+        this.userAgent = options.userAgent;
+    }
+    async post(path, body) {
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path,
+            method: "POST",
+            body,
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+}

package/dist/services/xivapi.js

@@ -1,6 +1,7 @@
 import { LRUCache } from "lru-cache";
 import { DEFAULT_XIVAPI_LANGUAGE, DEFAULT_XIVAPI_VERSION, XIVAPI_BASE_URL } from "../constants.js";
 import { requestJson } from "./http.js";
+import { chunkArray } from "../utils/array.js";
 export class XivapiClient {
     baseUrl;
     timeoutMs;
@@ -52,6 +53,55 @@ export class XivapiClient {
         this.itemCache.set(cacheKey, data);
         return data;
     }
+    async getItemsByIds(itemIds, params = {}, chunkSize = 100) {
+        const uniqueIds = Array.from(new Set(itemIds));
+        if (uniqueIds.length === 0) {
+            return { rows: [] };
+        }
+        const chunks = chunkArray(uniqueIds, chunkSize);
+        const rows = [];
+        let schema;
+        let version;
+        for (const chunk of chunks) {
+            const normalized = this.withDefaults({ ...params });
+            const data = await requestJson({
+                baseUrl: this.baseUrl,
+                path: "/sheet/Item",
+                query: {
+                    ...normalized,
+                    rows: chunk.join(","),
+                },
+                limiter: this.limiter,
+                timeoutMs: this.timeoutMs,
+                userAgent: this.userAgent,
+            });
+            if (schema === undefined && "schema" in data) {
+                schema = data.schema;
+            }
+            if (version === undefined && "version" in data) {
+                version = data.version;
+            }
+            if (Array.isArray(data.rows)) {
+                rows.push(...data.rows);
+            }
+        }
+        return {
+            rows,
+            ...(schema !== undefined ? { schema } : {}),
+            ...(version !== undefined ? { version } : {}),
+        };
+    }
+    async getSheetRows(sheet, params = {}) {
+        const normalized = this.withDefaults({ ...params });
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path: `/sheet/${sheet}`,
+            query: normalized,
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
     withDefaults(params) {
         return {
             ...params,

package/dist/tools/lookup.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { BaseOutputSchema, ResponseFormatSchema } from "../schemas/common.js";
 import { buildToolResponse } from "../utils/format.js";
+import { expandMateriaCategory } from "../services/materia.js";
+import { buildNameQueryFromTargets, dedupeNameTargets, ensureFieldsInclude, extractNamedResults, findBestResult, } from "../utils/xivapi.js";
 const LanguageSchema = z
     .enum(["none", "ja", "en", "de", "fr", "chs", "cht", "kr"])
     .optional()
@@ -10,8 +12,49 @@ const MatchModeSchema = z
     .default("partial")
     .describe("Match mode for item name queries.");
 const DefaultItemFields = "Name,Icon,ItemSearchCategory,LevelItem";
-function escapeQueryValue(value) {
-    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+const NamesSchema = z
+    .array(z.string().min(1))
+    .min(1)
+    .max(100)
+    .describe("Item names to resolve (max 100).");
+async function buildSearchTargets(names, matchMode, clients) {
+    const targets = [];
+    const expandedItems = [];
+    const missingGradeInputs = [];
+    for (const name of names) {
+        const expansion = await expandMateriaCategory(name, clients.xivapi);
+        if (!expansion) {
+            targets.push({
+                name,
+                sourceInput: name,
+                matchMode,
+                origin: "direct",
+            });
+            continue;
+        }
+        expandedItems.push({
+            input_name: name,
+            category: expansion.category,
+            grade: expansion.grade,
+            expanded_names: expansion.expandedNames,
+        });
+        if (!expansion.grade) {
+            missingGradeInputs.push(name);
+            continue;
+        }
+        for (const expandedName of expansion.expandedNames) {
+            targets.push({
+                name: expandedName,
+                sourceInput: name,
+                matchMode: "exact",
+                origin: "expanded",
+            });
+        }
+    }
+    return { targets, expandedItems, missingGradeInputs };
+}
+function buildQueryTargets(targets) {
+    return dedupeNameTargets(targets.map((target) => ({ name: target.name, matchMode: target.matchMode })));
 }
 export function registerLookupTools(server, clients) {
     server.registerTool("universalis_resolve_items_by_name", {
@@ -47,8 +90,12 @@ export function registerLookupTools(server, clients) {
             openWorldHint: true,
         },
     }, async ({ query, match_mode, limit, language, fields, response_format }) => {
-        const escaped = escapeQueryValue(query);
-        const queryClause = match_mode === "exact" ? `Name="${escaped}"` : `Name~"${escaped}"`;
+        const expansion = await expandMateriaCategory(query, clients.xivapi);
+        const expandedNames = expansion?.grade ? expansion.expandedNames : null;
+        const queryTargets = expandedNames
+            ? expandedNames.map((name) => ({ name, matchMode: "exact" }))
+            : [{ name: query, matchMode: match_mode }];
+        const queryClause = buildNameQueryFromTargets(queryTargets);
         const data = await clients.xivapi.search({
             query: queryClause,
             sheets: "Item",
@@ -65,6 +112,159 @@ export function registerLookupTools(server, clients) {
                 endpoint: "/search",
                 query: queryClause,
                 limit,
+                ...(expansion
+                    ? {
+                        expanded_items: {
+                            input_name: query,
+                            category: expansion.category,
+                            grade: expansion.grade,
+                            expanded_names: expansion.expandedNames,
+                        },
+                    }
+                    : {}),
+                ...(expansion && !expansion.grade
+                    ? { notes: ["Materia category missing grade. Specify I-XII to expand."] }
+                    : {}),
+                ...(language ? { language } : {}),
+            },
+        });
+    });
+    server.registerTool("universalis_resolve_items_by_names", {
+        title: "Resolve Items by Names (XIVAPI)",
+        description: "Resolve multiple item names in a single XIVAPI search query, returning best matches per name.",
+        inputSchema: z
+            .object({
+            names: NamesSchema,
+            match_mode: MatchModeSchema.default("exact"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe("Maximum results to return (default: names.length * 5, max: 500)."),
+            language: LanguageSchema,
+            fields: z
+                .string()
+                .optional()
+                .describe("Comma-separated XIVAPI fields. Name is always included."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ names, match_mode, limit, language, fields, response_format }) => {
+        const { targets, expandedItems, missingGradeInputs } = await buildSearchTargets(names, match_mode, clients);
+        const queryTargets = buildQueryTargets(targets);
+        const queryClause = queryTargets.length ? buildNameQueryFromTargets(queryTargets) : "";
+        const effectiveLimit = limit ?? Math.min(queryTargets.length * 5, 500);
+        const searchFields = ensureFieldsInclude(fields, ["Name"]);
+        const data = queryTargets.length
+            ? await clients.xivapi.search({
+                query: queryClause,
+                sheets: "Item",
+                limit: effectiveLimit,
+                language,
+                fields: searchFields,
+            })
+            : { results: [] };
+        const results = Array.isArray(data.results)
+            ? (data.results ?? [])
+            : [];
+        const namedResults = extractNamedResults(results);
+        const matches = targets.map((target) => {
+            const best = findBestResult(namedResults, target.name, target.matchMode);
+            const fieldsObj = best?.fields;
+            return {
+                input_name: target.sourceInput,
+                expanded_name: target.origin === "expanded" ? target.name : null,
+                matched_name: typeof fieldsObj?.Name === "string" ? fieldsObj.Name : null,
+                item_id: typeof best?.row_id === "number" ? best.row_id : null,
+                score: typeof best?.score === "number" ? best.score : null,
+                match_type: best ? (target.origin === "expanded" ? "expanded" : target.matchMode) : "none",
+                match_mode: target.matchMode,
+                resolution_source: target.origin,
+            };
+        });
+        const missingGradeMatches = missingGradeInputs.map((name) => ({
+            input_name: name,
+            expanded_name: null,
+            matched_name: null,
+            item_id: null,
+            score: null,
+            match_type: "missing_grade",
+            match_mode: match_mode,
+            resolution_source: "category",
+            notes: ["Materia category missing grade. Specify I-XII to expand."],
+        }));
+        const unresolvedDirect = targets
+            .map((target, index) => ({ target, index }))
+            .filter(({ target, index }) => target.origin === "direct" && target.matchMode === "exact" && matches[index]?.item_id == null);
+        let fallbackResults = [];
+        let fallbackQueryClause = null;
+        if (unresolvedDirect.length > 0) {
+            const fallbackTargets = dedupeNameTargets(unresolvedDirect.map(({ target }) => ({
+                name: target.name,
+                matchMode: "partial",
+            })));
+            fallbackQueryClause = buildNameQueryFromTargets(fallbackTargets);
+            const fallbackLimit = Math.min(fallbackTargets.length * 5, 500);
+            const fallbackData = await clients.xivapi.search({
+                query: fallbackQueryClause,
+                sheets: "Item",
+                limit: fallbackLimit,
+                language,
+                fields: searchFields,
+            });
+            fallbackResults = Array.isArray(fallbackData.results)
+                ? (fallbackData.results ?? [])
+                : [];
+            const fallbackNamedResults = extractNamedResults(fallbackResults);
+            for (const { target, index } of unresolvedDirect) {
+                const best = findBestResult(fallbackNamedResults, target.name, "partial");
+                if (!best)
+                    continue;
+                const fieldsObj = best.fields;
+                matches[index] = {
+                    input_name: target.sourceInput,
+                    expanded_name: null,
+                    matched_name: typeof fieldsObj?.Name === "string" ? fieldsObj.Name : null,
+                    item_id: typeof best.row_id === "number" ? best.row_id : null,
+                    score: typeof best.score === "number" ? best.score : null,
+                    match_type: "fallback_partial",
+                    match_mode: target.matchMode,
+                    resolution_source: target.origin,
+                };
+            }
+        }
+        const allMatches = [...matches, ...missingGradeMatches];
+        const resolvedInputs = new Set(allMatches.filter((entry) => entry.item_id != null).map((entry) => entry.input_name));
+        const unmatched = names.filter((name) => !resolvedInputs.has(name));
+        const unmatchedExpanded = allMatches
+            .filter((entry) => entry.resolution_source === "expanded" && entry.item_id == null)
+            .map((entry) => entry.expanded_name ?? entry.input_name);
+        return buildToolResponse({
+            title: "Resolved Items (Bulk)",
+            responseFormat: response_format,
+            data: {
+                matches: allMatches,
+                unmatched,
+                unmatched_expanded: unmatchedExpanded,
+                results: results.concat(fallbackResults),
+                expanded_items: expandedItems,
+                missing_expansions: missingGradeInputs,
+            },
+            meta: {
+                source: "xivapi",
+                endpoint: "/search",
+                query: queryClause,
+                ...(fallbackQueryClause ? { fallback_query: fallbackQueryClause } : {}),
+                limit: effectiveLimit,
                 ...(language ? { language } : {}),
             },
         });
@@ -107,4 +307,46 @@ export function registerLookupTools(server, clients) {
             },
         });
     });
+    server.registerTool("universalis_get_items_by_ids", {
+        title: "Get Items by IDs (XIVAPI)",
+        description: "Fetch multiple item rows from XIVAPI by item IDs.",
+        inputSchema: z
+            .object({
+            item_ids: z
+                .array(z.number().int().min(1))
+                .min(1)
+                .max(200)
+                .describe("Item IDs to fetch (max 200 per call)."),
+            language: LanguageSchema,
+            fields: z
+                .string()
+                .optional()
+                .describe("Comma-separated XIVAPI fields to select."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ item_ids, language, fields, response_format }) => {
+        const data = await clients.xivapi.getItemsByIds(item_ids, {
+            language,
+            fields,
+        });
+        return buildToolResponse({
+            title: "Item Details (Bulk)",
+            responseFormat: response_format,
+            data,
+            meta: {
+                source: "xivapi",
+                endpoint: "/sheet/Item",
+                item_ids: item_ids,
+                ...(language ? { language } : {}),
+            },
+        });
+    });
 }