universalis-mcp-server 0.1.0 → 0.2.0

package/dist/tools/workflows.js

@@ -0,0 +1,435 @@
+import { z } from "zod";
+import { BaseOutputSchema, ResponseFormatSchema } from "../schemas/common.js";
+import { expandMateriaCategory } from "../services/materia.js";
+import { buildToolResponse } from "../utils/format.js";
+import { buildNameQueryFromTargets, dedupeNameTargets, ensureFieldsInclude, extractNamedResults, findBestResult, } from "../utils/xivapi.js";
+import { chunkArray } from "../utils/array.js";
+const LanguageSchema = z
+    .enum(["none", "ja", "en", "de", "fr", "chs", "cht", "kr"])
+    .optional()
+    .describe("XIVAPI language code.");
+const MatchModeSchema = z
+    .enum(["partial", "exact"])
+    .default("exact")
+    .describe("Match mode for item name queries.");
+const PriceMetricSchema = z
+    .enum(["min_listing", "average_sale_price"])
+    .default("min_listing")
+    .describe("Price metric to use for profitability.");
+const PriceVariantSchema = z
+    .enum(["nq", "hq", "best"])
+    .default("best")
+    .describe("Which price variant to consider when ranking.");
+const CostItemSchema = z
+    .object({
+    name: z.string().min(1).describe("Item name."),
+    cost: z.number().positive().describe("Cost to acquire the item (numeric)."),
+    cost_unit: z.string().optional().describe('Cost unit label. Example: "Bicolor Gemstone".'),
+})
+    .strict();
+async function buildCostTargets(items, matchMode, clients) {
+    const targets = [];
+    const expandedItems = [];
+    const missingGradeItems = [];
+    for (const item of items) {
+        const costUnit = item.cost_unit ?? "Bicolor Gemstone";
+        const expansion = await expandMateriaCategory(item.name, clients.xivapi);
+        if (!expansion) {
+            targets.push({
+                name: item.name,
+                sourceInput: item.name,
+                cost: item.cost,
+                cost_unit: costUnit,
+                matchMode,
+                origin: "direct",
+            });
+            continue;
+        }
+        expandedItems.push({
+            input_name: item.name,
+            category: expansion.category,
+            grade: expansion.grade,
+            expanded_names: expansion.expandedNames,
+        });
+        if (!expansion.grade) {
+            missingGradeItems.push({
+                input_name: item.name,
+                cost: item.cost,
+                cost_unit: costUnit,
+            });
+            continue;
+        }
+        for (const expandedName of expansion.expandedNames) {
+            targets.push({
+                name: expandedName,
+                sourceInput: item.name,
+                cost: item.cost,
+                cost_unit: costUnit,
+                matchMode: "exact",
+                origin: "expanded",
+            });
+        }
+    }
+    return { targets, expandedItems, missingGradeItems };
+}
+function buildQueryTargets(targets) {
+    return dedupeNameTargets(targets.map((target) => ({ name: target.name, matchMode: target.matchMode })));
+}
+const AggregatedScopeOrder = ["world", "dc", "region"];
+function pickScopedMetric(node, key) {
+    if (!node || typeof node !== "object")
+        return { value: null, scope: null };
+    const record = node;
+    for (const scope of AggregatedScopeOrder) {
+        const entry = record[scope];
+        const value = entry ? entry[key] : undefined;
+        if (typeof value === "number") {
+            return { value, scope };
+        }
+    }
+    return { value: null, scope: null };
+}
+function scoreItem(price, velocity, cost) {
+    if (!price || cost <= 0)
+        return { gilPerCost: null, score: null };
+    const gilPerCost = price / cost;
+    if (!velocity) {
+        return { gilPerCost, score: gilPerCost };
+    }
+    return { gilPerCost, score: gilPerCost * velocity };
+}
+export function registerWorkflowTools(server, clients) {
+    server.registerTool("universalis_rank_items_by_profitability", {
+        title: "Rank Items by Profitability",
+        description: "Resolve item names with XIVAPI, fetch aggregated market data, and rank items by demand, profit, and supply context.",
+        inputSchema: z
+            .object({
+            world_dc_region: z
+                .string()
+                .min(1)
+                .describe('World, data center, or region. Example: "Moogle".'),
+            items: z.array(CostItemSchema).min(1).max(300),
+            match_mode: MatchModeSchema,
+            price_metric: PriceMetricSchema,
+            price_variant: PriceVariantSchema,
+            marketable_only: z
+                .boolean()
+                .default(true)
+                .describe("Filter out unmarketable items using Universalis marketable list."),
+            min_velocity: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe("Minimum daily sale velocity required to score an item."),
+            include_supply: z
+                .boolean()
+                .default(true)
+                .describe("Include supply metrics (units for sale, listings count)."),
+            language: LanguageSchema,
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ world_dc_region, items, match_mode, price_metric, price_variant, marketable_only, min_velocity, include_supply, language, response_format, }) => {
+        const { targets, expandedItems, missingGradeItems } = await buildCostTargets(items, match_mode, clients);
+        const queryTargets = buildQueryTargets(targets);
+        const queryClause = queryTargets.length ? buildNameQueryFromTargets(queryTargets) : "";
+        const searchFields = ensureFieldsInclude(undefined, ["Name"]);
+        const searchData = queryTargets.length
+            ? await clients.xivapi.search({
+                query: queryClause,
+                sheets: "Item",
+                limit: Math.min(queryTargets.length * 5, 500),
+                language,
+                fields: searchFields,
+            })
+            : { results: [] };
+        const results = Array.isArray(searchData.results)
+            ? (searchData.results ?? [])
+            : [];
+        const namedResults = extractNamedResults(results);
+        const resolved = 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,
+                resolved_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,
+                cost: target.cost,
+                cost_unit: target.cost_unit,
+            };
+        });
+        const unresolvedDirect = targets
+            .map((target, index) => ({ target, index }))
+            .filter(({ target, index }) => target.origin === "direct" && target.matchMode === "exact" && resolved[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 fallbackData = await clients.xivapi.search({
+                query: fallbackQueryClause,
+                sheets: "Item",
+                limit: Math.min(fallbackTargets.length * 5, 500),
+                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;
+                resolved[index] = {
+                    input_name: target.sourceInput,
+                    expanded_name: null,
+                    resolved_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,
+                    cost: target.cost,
+                    cost_unit: target.cost_unit,
+                };
+            }
+        }
+        const missingGradeResolved = missingGradeItems.map((item) => ({
+            input_name: item.input_name,
+            expanded_name: null,
+            resolved_name: null,
+            item_id: null,
+            score: null,
+            match_type: "missing_grade",
+            match_mode: match_mode,
+            resolution_source: "category",
+            cost: item.cost,
+            cost_unit: item.cost_unit,
+            notes: ["Materia category missing grade. Specify I-XII to expand."],
+        }));
+        const allResolved = [...resolved, ...missingGradeResolved];
+        const marketableIds = marketable_only && resolved.some((entry) => entry.item_id != null)
+            ? new Set(await clients.universalis.listMarketableItems())
+            : null;
+        const resolvedIdSet = new Set();
+        const marketableFilteredIds = [];
+        for (const entry of resolved) {
+            if (entry.item_id == null)
+                continue;
+            if (marketableIds && !marketableIds.has(entry.item_id)) {
+                entry.marketable = false;
+                entry.notes = [...(entry.notes ?? []), "Item is not marketable on Universalis."];
+                marketableFilteredIds.push(entry.item_id);
+                continue;
+            }
+            if (marketableIds)
+                entry.marketable = true;
+            resolvedIdSet.add(entry.item_id);
+        }
+        const resolvedIds = Array.from(resolvedIdSet);
+        const aggregatedResults = [];
+        const failedItems = [];
+        for (const chunk of chunkArray(resolvedIds, 100)) {
+            const aggregated = await clients.universalis.getAggregatedMarketData(world_dc_region, chunk);
+            const chunkResults = Array.isArray(aggregated.results)
+                ? (aggregated.results ?? [])
+                : [];
+            const chunkFailed = Array.isArray(aggregated.failedItems)
+                ? (aggregated.failedItems ?? [])
+                : [];
+            aggregatedResults.push(...chunkResults);
+            failedItems.push(...chunkFailed);
+        }
+        const aggregatedMap = new Map();
+        for (const entry of aggregatedResults) {
+            if (typeof entry.itemId === "number") {
+                aggregatedMap.set(entry.itemId, entry);
+            }
+        }
+        const supplyMap = new Map();
+        if (include_supply && resolvedIds.length > 0) {
+            for (const chunk of chunkArray(resolvedIds, 100)) {
+                const fields = chunk.length === 1
+                    ? "itemID,unitsForSale,listingsCount,worldName,dcName,regionName"
+                    : "items.unitsForSale,items.listingsCount,worldName,dcName,regionName";
+                const currentData = await clients.universalis.getCurrentMarketData(world_dc_region, chunk, {
+                    fields,
+                });
+                const current = currentData;
+                const scope = typeof current.worldName === "string"
+                    ? "world"
+                    : typeof current.dcName === "string"
+                        ? "dc"
+                        : typeof current.regionName === "string"
+                            ? "region"
+                            : null;
+                const itemsMap = current.items;
+                if (itemsMap) {
+                    for (const [key, value] of Object.entries(itemsMap)) {
+                        const itemId = Number(key);
+                        if (Number.isNaN(itemId))
+                            continue;
+                        const listingsCount = typeof value?.listingsCount === "number" ? value.listingsCount : null;
+                        const unitsForSale = typeof value?.unitsForSale === "number" ? value.unitsForSale : null;
+                        supplyMap.set(itemId, { unitsForSale, listingsCount, scope });
+                    }
+                    continue;
+                }
+                const itemId = typeof current.itemID === "number" ? current.itemID : null;
+                if (itemId != null) {
+                    const listingsCount = typeof current.listingsCount === "number" ? current.listingsCount : null;
+                    const unitsForSale = typeof current.unitsForSale === "number" ? current.unitsForSale : null;
+                    supplyMap.set(itemId, { unitsForSale, listingsCount, scope });
+                }
+            }
+        }
+        const resolvedInputs = new Set(allResolved.filter((entry) => entry.item_id != null).map((entry) => entry.input_name));
+        const unmatched = items.map((item) => item.name).filter((name) => !resolvedInputs.has(name));
+        const unmatchedExpanded = allResolved
+            .filter((entry) => entry.resolution_source === "expanded" && entry.item_id == null)
+            .map((entry) => entry.expanded_name ?? entry.input_name);
+        const ranked = allResolved.map((entry) => {
+            const supply = entry.item_id ? supplyMap.get(entry.item_id) : null;
+            if (!entry.item_id) {
+                const notes = Array.isArray(entry.notes) ? [...entry.notes] : [];
+                if (notes.length === 0)
+                    notes.push("Unresolved item name.");
+                return {
+                    ...entry,
+                    price: null,
+                    price_scope: null,
+                    demand_per_day: null,
+                    demand_scope: null,
+                    supply_units: null,
+                    listings_count: null,
+                    supply_scope: null,
+                    saturation_ratio: null,
+                    gil_per_cost: null,
+                    ranking_score: null,
+                    notes,
+                };
+            }
+            if (entry.marketable === false) {
+                const notes = Array.isArray(entry.notes) ? [...entry.notes] : [];
+                return {
+                    ...entry,
+                    price: null,
+                    price_scope: null,
+                    demand_per_day: null,
+                    demand_scope: null,
+                    supply_units: supply?.unitsForSale ?? null,
+                    listings_count: supply?.listingsCount ?? null,
+                    supply_scope: supply?.scope ?? null,
+                    saturation_ratio: null,
+                    gil_per_cost: null,
+                    ranking_score: null,
+                    notes,
+                };
+            }
+            const aggregatedEntry = aggregatedMap.get(entry.item_id);
+            const metricKey = price_metric === "min_listing" ? "minListing" : "averageSalePrice";
+            const evaluateVariant = (variant) => {
+                const variantData = aggregatedEntry?.[variant];
+                const priceMetric = pickScopedMetric(variantData?.[metricKey], "price");
+                const velocityMetric = pickScopedMetric(variantData?.dailySaleVelocity, "quantity");
+                const scored = scoreItem(priceMetric.value, velocityMetric.value, entry.cost);
+                return {
+                    variant,
+                    price: priceMetric.value,
+                    price_scope: priceMetric.scope,
+                    demand_per_day: velocityMetric.value,
+                    demand_scope: velocityMetric.scope,
+                    gil_per_cost: scored.gilPerCost,
+                    ranking_score: scored.score,
+                };
+            };
+            const candidates = price_variant === "best"
+                ? [evaluateVariant("nq"), evaluateVariant("hq")]
+                : [evaluateVariant(price_variant)];
+            const best = candidates.sort((a, b) => (b.ranking_score ?? -1) - (a.ranking_score ?? -1))[0];
+            const notes = [];
+            if (best.price == null)
+                notes.push("No price data available.");
+            if (best.demand_per_day == null)
+                notes.push("No demand data available.");
+            if (min_velocity != null) {
+                if (best.demand_per_day == null) {
+                    notes.push(`Minimum demand threshold (${min_velocity}) not applied.`);
+                }
+                else if (best.demand_per_day < min_velocity) {
+                    notes.push(`Below minimum demand threshold (${min_velocity}).`);
+                }
+            }
+            return {
+                ...entry,
+                price_variant: best.variant,
+                price_metric,
+                price: best.price,
+                price_scope: best.price_scope,
+                demand_per_day: best.demand_per_day,
+                demand_scope: best.demand_scope,
+                supply_units: supply?.unitsForSale ?? null,
+                listings_count: supply?.listingsCount ?? null,
+                supply_scope: supply?.scope ?? null,
+                saturation_ratio: supply?.unitsForSale != null && best.demand_per_day != null && best.demand_per_day > 0
+                    ? supply.unitsForSale / best.demand_per_day
+                    : null,
+                gil_per_cost: best.gil_per_cost,
+                ranking_score: min_velocity != null && best.demand_per_day != null && best.demand_per_day < min_velocity
+                    ? null
+                    : best.ranking_score,
+                notes: notes.length ? notes : undefined,
+            };
+        });
+        ranked.sort((a, b) => (b.ranking_score ?? -1) - (a.ranking_score ?? -1));
+        const top = ranked.filter((entry) => entry.ranking_score != null).slice(0, 3);
+        const summaryLines = top.map((entry, index) => {
+            const name = entry.resolved_name ?? entry.expanded_name ?? entry.input_name;
+            const score = entry.ranking_score != null ? entry.ranking_score.toFixed(2) : "n/a";
+            return `${index + 1}. ${name} (${score} score)`;
+        });
+        return buildToolResponse({
+            title: "Profitability Ranking",
+            responseFormat: response_format,
+            data: {
+                ranking: ranked,
+                unmatched,
+                unmatched_expanded: unmatchedExpanded,
+                expanded_items: expandedItems,
+                missing_expansions: missingGradeItems.map((item) => item.input_name),
+                unmarketable_item_ids: marketableFilteredIds,
+                failed_items: failedItems,
+            },
+            meta: {
+                source: "universalis",
+                endpoint: "/aggregated/{worldDcRegion}/{itemIds}",
+                world_dc_region,
+                price_metric,
+                price_variant,
+                marketable_only,
+                min_velocity,
+                include_supply,
+                query: queryClause,
+                ...(fallbackQueryClause ? { fallback_query: fallbackQueryClause } : {}),
+            },
+            summaryLines,
+        });
+    });
+}

package/dist/utils/array.js

@@ -0,0 +1,9 @@
+export function chunkArray(items, chunkSize) {
+    if (chunkSize <= 0)
+        return [items];
+    const chunks = [];
+    for (let i = 0; i < items.length; i += chunkSize) {
+        chunks.push(items.slice(i, i + chunkSize));
+    }
+    return chunks;
+}

package/dist/utils/materia.js

@@ -0,0 +1,71 @@
+import { normalizeName } from "./xivapi.js";
+const ROMAN_PATTERN = /^[ivxlcdm]+$/i;
+const ROMAN_TABLE = [
+    [1000, "M"],
+    [900, "CM"],
+    [500, "D"],
+    [400, "CD"],
+    [100, "C"],
+    [90, "XC"],
+    [50, "L"],
+    [40, "XL"],
+    [10, "X"],
+    [9, "IX"],
+    [5, "V"],
+    [4, "IV"],
+    [1, "I"],
+];
+function toRoman(value) {
+    if (value <= 0 || value >= 4000)
+        return null;
+    let remaining = value;
+    let result = "";
+    for (const [amount, numeral] of ROMAN_TABLE) {
+        while (remaining >= amount) {
+            result += numeral;
+            remaining -= amount;
+        }
+    }
+    return result || null;
+}
+export function normalizeGradeToken(token) {
+    const trimmed = token.trim();
+    if (!trimmed)
+        return null;
+    if (ROMAN_PATTERN.test(trimmed)) {
+        return trimmed.toUpperCase();
+    }
+    const num = Number(trimmed);
+    if (!Number.isNaN(num)) {
+        return toRoman(num);
+    }
+    return null;
+}
+export function extractMateriaGrade(input) {
+    const match = input.match(/\bmateria\s+([ivxlcdm\d]+)\b/i);
+    if (!match)
+        return null;
+    return normalizeGradeToken(match[1]);
+}
+export function detectMateriaCategory(input) {
+    const normalized = normalizeName(input);
+    if (/^combat\s+materia(\s+[ivxlcdm\d]+)?$/.test(normalized)) {
+        return "combat";
+    }
+    if (/^(crafting|craftsman'?s)\s+materia(\s+[ivxlcdm\d]+)?$/.test(normalized)) {
+        return "crafting";
+    }
+    if (/^(gathering|gatherer'?s)\s+materia(\s+[ivxlcdm\d]+)?$/.test(normalized)) {
+        return "gathering";
+    }
+    return null;
+}
+export function parseMateriaCategoryInput(input) {
+    const category = detectMateriaCategory(input);
+    if (!category)
+        return null;
+    return {
+        category,
+        grade: extractMateriaGrade(input),
+    };
+}

package/dist/utils/xivapi.js

@@ -0,0 +1,71 @@
+export function escapeQueryValue(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+export function buildNameClause(name, matchMode) {
+    const escaped = escapeQueryValue(name);
+    return matchMode === "exact" ? `Name="${escaped}"` : `Name~"${escaped}"`;
+}
+export function buildNameQueryFromTargets(targets) {
+    const clauses = targets.map((target) => buildNameClause(target.name, target.matchMode));
+    return clauses.join(" ");
+}
+export function buildNameQuery(names, matchMode) {
+    return buildNameQueryFromTargets(names.map((name) => ({ name, matchMode })));
+}
+export function dedupeNameTargets(targets) {
+    const targetMap = new Map();
+    for (const target of targets) {
+        const key = normalizeName(target.name);
+        const existing = targetMap.get(key);
+        if (!existing) {
+            targetMap.set(key, target);
+            continue;
+        }
+        if (existing.matchMode === "partial" && target.matchMode === "exact") {
+            targetMap.set(key, target);
+        }
+    }
+    return Array.from(targetMap.values());
+}
+export function normalizeName(value) {
+    return value.trim().toLowerCase();
+}
+export function ensureFieldsInclude(fields, required) {
+    if (!fields)
+        return required.join(",");
+    const parts = fields.split(",").map((part) => part.trim()).filter(Boolean);
+    for (const req of required) {
+        if (!parts.includes(req))
+            parts.push(req);
+    }
+    return parts.join(",");
+}
+export function extractNamedResults(results) {
+    return results
+        .map((result) => {
+        const fieldsObj = result.fields;
+        const name = typeof fieldsObj?.Name === "string" ? fieldsObj.Name : undefined;
+        if (!name)
+            return null;
+        return {
+            name,
+            normalizedName: normalizeName(name),
+            result,
+        };
+    })
+        .filter((entry) => Boolean(entry));
+}
+export function findBestResult(namedResults, targetName, matchMode) {
+    const key = normalizeName(targetName);
+    const candidates = namedResults
+        .filter((entry) => matchMode === "exact" ? entry.normalizedName === key : entry.normalizedName.includes(key))
+        .map((entry) => entry.result);
+    if (candidates.length === 0) {
+        return null;
+    }
+    return candidates.sort((a, b) => {
+        const scoreA = typeof a.score === "number" ? a.score : 0;
+        const scoreB = typeof b.score === "number" ? b.score : 0;
+        return scoreB - scoreA;
+    })[0];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universalis-mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for Universalis and XIVAPI",
   "author": "Jakub Mucha <jakub.mucha@icloud.com>",
   "repository": {
@@ -17,7 +17,8 @@
     "universalis-mcp-server": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "data"
   ],
   "keywords": [
     "mcp",
@@ -38,6 +39,7 @@
   },
   "scripts": {
     "build": "tsc && chmod 755 ./dist/index.js",
+    "update-materia": "node scripts/update-materia-data.js",
     "lint": "biome check .",
     "format": "biome format --write ."
   }