universalis-mcp-server 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,10 @@
 # universalis-mcp-server
 
-MCP server for Universalis market data and XIVAPI item lookup.
+MCP server for FFXIV market data via Universalis + Saddlebag Exchange, plus XIVAPI item lookup.
 
 ## Capabilities
 
-This MCP server exposes read-only tools for Universalis market data and XIVAPI item lookup.
+This MCP server exposes read-only tools for Universalis market data, Saddlebag Exchange analytics, and XIVAPI item lookup.
 All tools support `response_format` as `markdown` or `json`.
 
 ### Market board data (Universalis)
@@ -16,7 +16,32 @@ 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.
+
+### Market analytics (Saddlebag Exchange)
+
+- `saddlebag_get_listing_metrics`: Listing competition metrics and current listings.
+- `saddlebag_get_history_metrics`: Aggregated history metrics and price distributions.
+- `saddlebag_get_raw_stats`: Daily snapshot stats (median, average, sales volume).
+- `saddlebag_get_scrip_exchange`: Gil-per-scrip rankings.
+- `saddlebag_get_shopping_list`: Crafting shopping list across servers (may return exception payloads).
+- `saddlebag_get_export_prices`: Cross-world price comparison for export trading.
+- `saddlebag_get_marketshare`: Marketshare leaderboard snapshot for a server.
+- `saddlebag_get_reselling_scan`: Reselling opportunities (region/DC/vendor filters).
+- `saddlebag_get_weekly_price_group_delta`: Weekly deltas for custom item groups.
+- `saddlebag_get_price_check`: Price alert checks (user-supplied auctions).
+- `saddlebag_get_quantity_check`: Quantity alert checks (user-supplied auctions).
+- `saddlebag_get_sale_alert`: Sale alerts for retainer listings.
+- `saddlebag_get_craftsim`: Crafting profitability scan (use `max_results` to limit payloads).
+- `saddlebag_get_blog_description`: Item description text lookup.
+
+Best-deals is excluded (premium gated + inconsistent API validation).
 
 ### Reference data (Universalis)
 
@@ -91,9 +116,11 @@ If you change code, re-run `pnpm build` and restart the MCP connection.
 
 - `UNIVERSALIS_BASE_URL`: Override Universalis base URL (default: `https://universalis.app/api/v2`).
 - `XIVAPI_BASE_URL`: Override XIVAPI base URL (default: `https://v2.xivapi.com/api`).
+- `SADDLEBAG_BASE_URL`: Override Saddlebag base URL (default: `https://docs.saddlebagexchange.com/api`).
 - `UNIVERSALIS_MCP_USER_AGENT`: Custom User-Agent header.
 - `UNIVERSALIS_TIMEOUT_MS`: Request timeout for Universalis (default: 30000).
 - `XIVAPI_TIMEOUT_MS`: Request timeout for XIVAPI (default: 30000).
+- `SADDLEBAG_TIMEOUT_MS`: Request timeout for Saddlebag (default: 30000).
 - `XIVAPI_LANGUAGE`: Default XIVAPI language (default: `en`).
 - `XIVAPI_VERSION`: Default XIVAPI version (default: `latest`).
 
@@ -101,3 +128,4 @@ If you change code, re-run `pnpm build` and restart the MCP connection.
 
 - Rate limits are enforced client-side for Universalis and XIVAPI.
 - Tools support `response_format` as `markdown` or `json`.
+- Some Saddlebag endpoints proxy Universalis data; avoid excessive polling.

package/data/materia.json

@@ -0,0 +1,347 @@
+{
+  "generated_at": "2026-01-11T21:38:40.756Z",
+  "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

@@ -1,8 +1,11 @@
 export const UNIVERSALIS_BASE_URL = process.env.UNIVERSALIS_BASE_URL ?? "https://universalis.app/api/v2";
 export const XIVAPI_BASE_URL = process.env.XIVAPI_BASE_URL ?? "https://v2.xivapi.com/api";
+export const SADDLEBAG_BASE_URL = process.env.SADDLEBAG_BASE_URL ?? "https://docs.saddlebagexchange.com/api";
 export const DEFAULT_UNIVERSALIS_TIMEOUT_MS = 30000;
 export const DEFAULT_XIVAPI_TIMEOUT_MS = 30000;
+export const DEFAULT_SADDLEBAG_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,14 @@
 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 { registerSaddlebagTools } from "./tools/saddlebag.js";
 import { registerStatsTools } from "./tools/stats.js";
+import { registerWorkflowTools } from "./tools/workflows.js";
 function toNumber(value) {
     if (!value)
         return undefined;
@@ -17,12 +20,15 @@ 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({
         userAgent,
         universalisTimeoutMs: toNumber(process.env.UNIVERSALIS_TIMEOUT_MS),
         xivapiTimeoutMs: toNumber(process.env.XIVAPI_TIMEOUT_MS),
+        saddlebagTimeoutMs: toNumber(process.env.SADDLEBAG_TIMEOUT_MS),
         xivapiLanguage: process.env.XIVAPI_LANGUAGE,
         xivapiVersion: process.env.XIVAPI_VERSION,
     });
@@ -30,6 +36,22 @@ async function main() {
     registerReferenceTools(server, clients);
     registerStatsTools(server, clients);
     registerLookupTools(server, clients);
+    registerSaddlebagTools(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,56 @@
+export const SERVER_INSTRUCTIONS = `Use this server to analyze FFXIV market data via Universalis and Saddlebag Exchange, plus 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.
+
+Saddlebag tools (FFXIV):
+- saddlebag_get_listing_metrics: listing competition metrics and current listings.
+- saddlebag_get_history_metrics: aggregated history metrics and price distributions.
+- saddlebag_get_raw_stats: daily snapshot stats (median, average, sales volume).
+- saddlebag_get_scrip_exchange: gil-per-scrip rankings.
+- saddlebag_get_shopping_list: crafting shopping list (may return exception payloads).
+- saddlebag_get_export_prices: cross-world price comparison for export trading.
+- saddlebag_get_marketshare: marketshare leaderboard snapshot for a server.
+- saddlebag_get_reselling_scan: reselling opportunities (region/DC/vendor filters).
+- saddlebag_get_weekly_price_group_delta: weekly deltas for custom item groups.
+- saddlebag_get_price_check: price alert checks (user-supplied auctions).
+- saddlebag_get_quantity_check: quantity alert checks (user-supplied auctions).
+- saddlebag_get_sale_alert: sale alerts for retainer listings.
+- saddlebag_get_craftsim: crafting profitability scan (use max_results to limit payloads).
+- saddlebag_get_blog_description: item description text lookup.
+
+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".
+- Prefer Universalis for raw listings/sales history; use Saddlebag for competition metrics, rankings, and aggregate distributions.
+- Saddlebag best-deals is excluded (premium gated + inconsistent API validation).
+- Some Saddlebag endpoints call Universalis directly; be mindful of rate limits.
+- saddlebag_get_raw_stats supports item_ids = -1 for all items and can return very large payloads.
+`;

package/dist/services/clients.js

@@ -1,5 +1,6 @@
 import Bottleneck from "bottleneck";
-import { DEFAULT_UNIVERSALIS_TIMEOUT_MS, DEFAULT_XIVAPI_TIMEOUT_MS } from "../constants.js";
+import { DEFAULT_SADDLEBAG_TIMEOUT_MS, DEFAULT_UNIVERSALIS_TIMEOUT_MS, DEFAULT_XIVAPI_TIMEOUT_MS, } from "../constants.js";
+import { SaddlebagClient } from "./saddlebag.js";
 import { UniversalisClient } from "./universalis.js";
 import { XivapiClient } from "./xivapi.js";
 export function createClients(options = {}) {
@@ -15,7 +16,18 @@ export function createClients(options = {}) {
         reservoirRefreshAmount: 10,
         reservoirRefreshInterval: 1000,
     });
+    const saddlebagLimiter = new Bottleneck({
+        maxConcurrent: 4,
+        reservoir: 20,
+        reservoirRefreshAmount: 10,
+        reservoirRefreshInterval: 1000,
+    });
     return {
+        saddlebag: new SaddlebagClient({
+            limiter: saddlebagLimiter,
+            timeoutMs: options.saddlebagTimeoutMs ?? DEFAULT_SADDLEBAG_TIMEOUT_MS,
+            userAgent: options.userAgent,
+        }),
         universalis: new UniversalisClient({
             limiter: universalisLimiter,
             timeoutMs: options.universalisTimeoutMs ?? DEFAULT_UNIVERSALIS_TIMEOUT_MS,