universalis-mcp-server 0.1.0 → 0.1.1

package/README.md

@@ -16,7 +16,13 @@ All tools support `response_format` as `markdown` or `json`.
 ### Item lookup (XIVAPI)
 
 - `universalis_resolve_items_by_name`: Search items by name with `partial` or `exact` matching.
+- `universalis_resolve_items_by_names`: Resolve multiple item names in one search query.
 - `universalis_get_item_by_id`: Fetch a single item row by ID.
+- `universalis_get_items_by_ids`: Fetch multiple item rows by ID in one request.
+
+### Workflows
+
+- `universalis_rank_items_by_profitability`: Resolve names, fetch aggregated data, and rank by demand and profit.
 
 ### Reference data (Universalis)
 

package/data/materia.json

@@ -0,0 +1,347 @@
+{
+  "generated_at": "2026-01-11T19:43:16.262Z",
+  "xivapi_version": "309a1e90d28b6bc6",
+  "categories": {
+    "combat": {
+      "I": [
+        "Aurelia Kiss Materia I",
+        "Battledance Materia I",
+        "Bison Hoof Materia I",
+        "Cactuar Foot Materia I",
+        "Chocobo Down Materia I",
+        "Coeurl Eye Materia I",
+        "Dexterity Materia I",
+        "Earth Materia I",
+        "Fire Materia I",
+        "Funguar Shriek Materia I",
+        "Heavens' Eye Materia I",
+        "Ice Materia I",
+        "Intelligence Materia I",
+        "Lightning Materia I",
+        "Mind Materia I",
+        "Piety Materia I",
+        "Quickarm Materia I",
+        "Quicktongue Materia I",
+        "Savage Aim Materia I",
+        "Savage Might Materia I",
+        "Strength Materia I",
+        "Treant Root Materia I",
+        "Vitality Materia I",
+        "Water Materia I",
+        "Wind Materia I"
+      ],
+      "II": [
+        "Battledance Materia II",
+        "Dexterity Materia II",
+        "Earth Materia II",
+        "Fire Materia II",
+        "Heavens' Eye Materia II",
+        "Ice Materia II",
+        "Intelligence Materia II",
+        "Lightning Materia II",
+        "Mind Materia II",
+        "Piety Materia II",
+        "Quickarm Materia II",
+        "Quicktongue Materia II",
+        "Savage Aim Materia II",
+        "Savage Might Materia II",
+        "Strength Materia II",
+        "Vitality Materia II",
+        "Water Materia II",
+        "Wind Materia II"
+      ],
+      "III": [
+        "Battledance Materia III",
+        "Dexterity Materia III",
+        "Earth Materia III",
+        "Fire Materia III",
+        "Heavens' Eye Materia III",
+        "Ice Materia III",
+        "Intelligence Materia III",
+        "Lightning Materia III",
+        "Mind Materia III",
+        "Piety Materia III",
+        "Quickarm Materia III",
+        "Quicktongue Materia III",
+        "Savage Aim Materia III",
+        "Savage Might Materia III",
+        "Strength Materia III",
+        "Vitality Materia III",
+        "Water Materia III",
+        "Wind Materia III"
+      ],
+      "IV": [
+        "Battledance Materia IV",
+        "Dexterity Materia IV",
+        "Earth Materia IV",
+        "Fire Materia IV",
+        "Heavens' Eye Materia IV",
+        "Ice Materia IV",
+        "Intelligence Materia IV",
+        "Lightning Materia IV",
+        "Mind Materia IV",
+        "Piety Materia IV",
+        "Quickarm Materia IV",
+        "Quicktongue Materia IV",
+        "Savage Aim Materia IV",
+        "Savage Might Materia IV",
+        "Strength Materia IV",
+        "Vitality Materia IV",
+        "Water Materia IV",
+        "Wind Materia IV"
+      ],
+      "V": [
+        "Battledance Materia V",
+        "Dexterity Materia V",
+        "Earth Materia V",
+        "Fire Materia V",
+        "Heavens' Eye Materia V",
+        "Ice Materia V",
+        "Intelligence Materia V",
+        "Lightning Materia V",
+        "Mind Materia V",
+        "Piety Materia V",
+        "Quickarm Materia V",
+        "Quicktongue Materia V",
+        "Savage Aim Materia V",
+        "Savage Might Materia V",
+        "Strength Materia V",
+        "Vitality Materia V",
+        "Water Materia V",
+        "Wind Materia V"
+      ],
+      "VI": [
+        "Battledance Materia VI",
+        "Dexterity Materia VI",
+        "Earth Materia VI",
+        "Fire Materia VI",
+        "Heavens' Eye Materia VI",
+        "Ice Materia VI",
+        "Intelligence Materia VI",
+        "Lightning Materia VI",
+        "Mind Materia VI",
+        "Piety Materia VI",
+        "Quickarm Materia VI",
+        "Quicktongue Materia VI",
+        "Savage Aim Materia VI",
+        "Savage Might Materia VI",
+        "Strength Materia VI",
+        "Vitality Materia VI",
+        "Water Materia VI",
+        "Wind Materia VI"
+      ],
+      "VII": [
+        "Battledance Materia VII",
+        "Heavens' Eye Materia VII",
+        "Piety Materia VII",
+        "Quickarm Materia VII",
+        "Quicktongue Materia VII",
+        "Savage Aim Materia VII",
+        "Savage Might Materia VII"
+      ],
+      "VIII": [
+        "Battledance Materia VIII",
+        "Heavens' Eye Materia VIII",
+        "Piety Materia VIII",
+        "Quickarm Materia VIII",
+        "Quicktongue Materia VIII",
+        "Savage Aim Materia VIII",
+        "Savage Might Materia VIII"
+      ],
+      "IX": [
+        "Battledance Materia IX",
+        "Heavens' Eye Materia IX",
+        "Piety Materia IX",
+        "Quickarm Materia IX",
+        "Quicktongue Materia IX",
+        "Savage Aim Materia IX",
+        "Savage Might Materia IX"
+      ],
+      "X": [
+        "Battledance Materia X",
+        "Heavens' Eye Materia X",
+        "Piety Materia X",
+        "Quickarm Materia X",
+        "Quicktongue Materia X",
+        "Savage Aim Materia X",
+        "Savage Might Materia X"
+      ],
+      "XI": [
+        "Battledance Materia XI",
+        "Heavens' Eye Materia XI",
+        "Piety Materia XI",
+        "Quickarm Materia XI",
+        "Quicktongue Materia XI",
+        "Savage Aim Materia XI",
+        "Savage Might Materia XI"
+      ],
+      "XII": [
+        "Battledance Materia XII",
+        "Heavens' Eye Materia XII",
+        "Piety Materia XII",
+        "Quickarm Materia XII",
+        "Quicktongue Materia XII",
+        "Savage Aim Materia XII",
+        "Savage Might Materia XII"
+      ]
+    },
+    "crafting": {
+      "I": [
+        "Craftsman's Command Materia I",
+        "Craftsman's Competence Materia I",
+        "Craftsman's Cunning Materia I"
+      ],
+      "II": [
+        "Craftsman's Command Materia II",
+        "Craftsman's Competence Materia II",
+        "Craftsman's Cunning Materia II"
+      ],
+      "III": [
+        "Craftsman's Command Materia III",
+        "Craftsman's Competence Materia III",
+        "Craftsman's Cunning Materia III"
+      ],
+      "IV": [
+        "Craftsman's Command Materia IV",
+        "Craftsman's Competence Materia IV",
+        "Craftsman's Cunning Materia IV"
+      ],
+      "V": [
+        "Craftsman's Command Materia V",
+        "Craftsman's Competence Materia V",
+        "Craftsman's Cunning Materia V"
+      ],
+      "VI": [
+        "Craftsman's Command Materia VI",
+        "Craftsman's Competence Materia VI",
+        "Craftsman's Cunning Materia VI"
+      ],
+      "VII": [
+        "Craftsman's Command Materia VII",
+        "Craftsman's Competence Materia VII",
+        "Craftsman's Cunning Materia VII"
+      ],
+      "VIII": [
+        "Craftsman's Command Materia VIII",
+        "Craftsman's Competence Materia VIII",
+        "Craftsman's Cunning Materia VIII"
+      ],
+      "IX": [
+        "Craftsman's Command Materia IX",
+        "Craftsman's Competence Materia IX",
+        "Craftsman's Cunning Materia IX"
+      ],
+      "X": [
+        "Craftsman's Command Materia X",
+        "Craftsman's Competence Materia X",
+        "Craftsman's Cunning Materia X"
+      ],
+      "XI": [
+        "Craftsman's Command Materia XI",
+        "Craftsman's Competence Materia XI",
+        "Craftsman's Cunning Materia XI"
+      ],
+      "XII": [
+        "Craftsman's Command Materia XII",
+        "Craftsman's Competence Materia XII",
+        "Craftsman's Cunning Materia XII"
+      ]
+    },
+    "gathering": {
+      "I": [
+        "Gatherer's Grasp Materia I",
+        "Gatherer's Guerdon Materia I",
+        "Gatherer's Guile Materia I"
+      ],
+      "II": [
+        "Gatherer's Grasp Materia II",
+        "Gatherer's Guerdon Materia II",
+        "Gatherer's Guile Materia II"
+      ],
+      "III": [
+        "Gatherer's Grasp Materia III",
+        "Gatherer's Guerdon Materia III",
+        "Gatherer's Guile Materia III"
+      ],
+      "IV": [
+        "Gatherer's Grasp Materia IV",
+        "Gatherer's Guerdon Materia IV",
+        "Gatherer's Guile Materia IV"
+      ],
+      "V": [
+        "Gatherer's Grasp Materia V",
+        "Gatherer's Guerdon Materia V",
+        "Gatherer's Guile Materia V"
+      ],
+      "VI": [
+        "Gatherer's Grasp Materia VI",
+        "Gatherer's Guerdon Materia VI",
+        "Gatherer's Guile Materia VI"
+      ],
+      "VII": [
+        "Gatherer's Grasp Materia VII",
+        "Gatherer's Guerdon Materia VII",
+        "Gatherer's Guile Materia VII"
+      ],
+      "VIII": [
+        "Gatherer's Grasp Materia VIII",
+        "Gatherer's Guerdon Materia VIII",
+        "Gatherer's Guile Materia VIII"
+      ],
+      "IX": [
+        "Gatherer's Grasp Materia IX",
+        "Gatherer's Guerdon Materia IX",
+        "Gatherer's Guile Materia IX"
+      ],
+      "X": [
+        "Gatherer's Grasp Materia X",
+        "Gatherer's Guerdon Materia X",
+        "Gatherer's Guile Materia X"
+      ],
+      "XI": [
+        "Gatherer's Grasp Materia XI",
+        "Gatherer's Guerdon Materia XI",
+        "Gatherer's Guile Materia XI"
+      ],
+      "XII": [
+        "Gatherer's Grasp Materia XII",
+        "Gatherer's Guerdon Materia XII",
+        "Gatherer's Guile Materia XII"
+      ]
+    }
+  },
+  "base_param_category": {
+    "Strength": "combat",
+    "Vitality": "combat",
+    "Dexterity": "combat",
+    "Intelligence": "combat",
+    "Mind": "combat",
+    "Piety": "combat",
+    "Fire Resistance": "combat",
+    "Ice Resistance": "combat",
+    "Wind Resistance": "combat",
+    "Earth Resistance": "combat",
+    "Lightning Resistance": "combat",
+    "Water Resistance": "combat",
+    "Direct Hit Rate": "combat",
+    "Critical Hit": "combat",
+    "Determination": "combat",
+    "Tenacity": "combat",
+    "Gathering": "gathering",
+    "Perception": "gathering",
+    "GP": "gathering",
+    "Craftsmanship": "crafting",
+    "CP": "crafting",
+    "Control": "crafting",
+    "Skill Speed": "combat",
+    "Spell Speed": "combat",
+    "Slow Resistance": "combat",
+    "Silence Resistance": "combat",
+    "Blind Resistance": "combat",
+    "Poison Resistance": "combat",
+    "Stun Resistance": "combat",
+    "Sleep Resistance": "combat",
+    "Bind Resistance": "combat",
+    "Heavy Resistance": "combat"
+  }
+}

package/dist/constants.js

@@ -3,6 +3,7 @@ export const XIVAPI_BASE_URL = process.env.XIVAPI_BASE_URL ?? "https://v2.xivapi
 export const DEFAULT_UNIVERSALIS_TIMEOUT_MS = 30000;
 export const DEFAULT_XIVAPI_TIMEOUT_MS = 30000;
 export const DEFAULT_TIMEOUT_MS = 30000;
+export const DEFAULT_MATERIA_CACHE_TTL_MS = 1000 * 60 * 60 * 24;
 export const CHARACTER_LIMIT = 25000;
 export const DEFAULT_PAGE_LIMIT = 20;
 export const MAX_PAGE_LIMIT = 100;

package/dist/index.js

@@ -2,11 +2,13 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import pkg from "../package.json" with { type: "json" };
+import { SERVER_INSTRUCTIONS } from "./instructions.js";
 import { createClients } from "./services/clients.js";
 import { registerLookupTools } from "./tools/lookup.js";
 import { registerMarketTools } from "./tools/market.js";
 import { registerReferenceTools } from "./tools/reference.js";
 import { registerStatsTools } from "./tools/stats.js";
+import { registerWorkflowTools } from "./tools/workflows.js";
 function toNumber(value) {
     if (!value)
         return undefined;
@@ -17,6 +19,8 @@ async function main() {
     const server = new McpServer({
         name: "universalis-mcp-server",
         version: pkg.version,
+    }, {
+        instructions: SERVER_INSTRUCTIONS,
     });
     const userAgent = process.env.UNIVERSALIS_MCP_USER_AGENT ?? `universalis-mcp-server/${pkg.version}`;
     const clients = createClients({
@@ -30,6 +34,21 @@ async function main() {
     registerReferenceTools(server, clients);
     registerStatsTools(server, clients);
     registerLookupTools(server, clients);
+    registerWorkflowTools(server, clients);
+    server.registerPrompt("universalis_usage_guide", {
+        title: "Universalis Usage Guide",
+        description: "Quick guidance on which tools to use and when.",
+    }, async () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: SERVER_INSTRUCTIONS,
+                },
+            },
+        ],
+    }));
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("universalis-mcp-server running on stdio");

package/dist/instructions.js

@@ -0,0 +1,36 @@
+export const SERVER_INSTRUCTIONS = `Use this server to analyze FFXIV market data via Universalis and item data via XIVAPI.
+
+Tool guide:
+- universalis_rank_items_by_profitability: best for "most profitable to farm" questions with cost inputs; ranks by demand and profit (defaults to best HQ/NQ price, can filter unmarketable items, and includes supply metrics).
+- universalis_resolve_items_by_names: bulk name-to-ID resolution in one query; prefer over per-item search.
+- universalis_resolve_items_by_name: single-item name search.
+- universalis_get_item_by_id: fetch one item row by ID from XIVAPI.
+- universalis_get_items_by_ids: fetch multiple item rows by ID in one request.
+
+- universalis_get_aggregated_prices: cached summary stats (min listing, recent purchase, averages, velocity). Use for most analysis.
+- universalis_get_current_listings: listings + recent history when the user needs live listings or example sales.
+- universalis_get_sales_history: detailed sales history when trend analysis or filters are required.
+
+- universalis_list_worlds: list and validate worlds.
+- universalis_list_data_centers: list and validate data centers.
+- universalis_get_tax_rates: current tax rates for a world.
+- universalis_list_marketable_items: marketable item IDs (paginate).
+- universalis_get_list: retrieve a Universalis list by ID.
+- universalis_get_content: content metadata by ID (best-effort endpoint).
+
+- universalis_get_most_recent_updates: most recently updated items for a world or DC.
+- universalis_get_least_recent_updates: least recently updated items for a world or DC.
+- universalis_get_recent_updates: legacy list of recently updated items (no world/DC info).
+- universalis_get_upload_counts_by_source: upload counts by client app.
+- universalis_get_upload_counts_by_world: upload counts by world.
+- universalis_get_upload_history: daily upload totals for the last 30 days.
+
+Notes:
+- world_dc_region accepts a world name/ID, data center name, or region.
+- response_format defaults to markdown; use json for structured processing.
+- Materia categories like "Combat Materia VII", "Crafting Materia VII", and "Gathering Materia VII" are expanded to their specific item names; grade is required.
+- Bulk resolve and profitability tools can fall back to partial matches for unresolved exact inputs; check match_type for "fallback_partial".
+- Materia expansion uses cached XIVAPI data; refresh is controlled by MATERIA_CACHE_TTL_MS and MATERIA_REFRESH.
+- Profitability tool options: marketable_only (default true), min_velocity threshold, include_supply (default true).
+- price_variant defaults to "best".
+`;

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