universalis-mcp-server 0.1.0 → 0.1.1

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 } : {}),
+            },
+        });
+    });
 }