universalis-mcp-server 0.1.1 → 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)
@@ -24,6 +24,25 @@ All tools support `response_format` as `markdown` or `json`.
 
 - `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)
 
 - `universalis_list_worlds`: List worlds with pagination.
@@ -97,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`).
 
@@ -107,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

@@ -1,5 +1,5 @@
 {
-  "generated_at": "2026-01-11T19:43:16.262Z",
+  "generated_at": "2026-01-11T21:38:40.756Z",
   "xivapi_version": "309a1e90d28b6bc6",
   "categories": {
     "combat": {

package/dist/constants.js

@@ -1,7 +1,9 @@
 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;

package/dist/index.js

@@ -7,6 +7,7 @@ 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) {
@@ -27,6 +28,7 @@ async function main() {
         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,
     });
@@ -34,6 +36,7 @@ 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",

package/dist/instructions.js

@@ -1,4 +1,4 @@
-export const SERVER_INSTRUCTIONS = `Use this server to analyze FFXIV market data via Universalis and item data via XIVAPI.
+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).
@@ -25,6 +25,22 @@ Tool guide:
 - 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.
@@ -33,4 +49,8 @@ Notes:
 - 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,

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/tools/saddlebag.js

@@ -0,0 +1,682 @@
+import { z } from "zod";
+import { BaseOutputSchema, ResponseFormatSchema } from "../schemas/common.js";
+import { buildToolResponse } from "../utils/format.js";
+const ServerSchema = z.string().min(1).describe("Server name.");
+const RegionSchema = z.string().min(1).describe('Region name. Example: "Europe".');
+const ItemIdSchema = z.number().int().min(1).describe("Item ID.");
+const ItemIdsSchema = z
+    .array(ItemIdSchema)
+    .min(1)
+    .max(100)
+    .describe("Item IDs (max 100). Example: [5333, 5334].");
+const RawStatsItemIdsSchema = z
+    .array(z.number().int().min(-1))
+    .min(1)
+    .describe("Item IDs (-1 for all items, may be very large).");
+const FiltersSchema = z
+    .array(z.number().int())
+    .min(1)
+    .describe("Category filter IDs. See https://github.com/ff14-advanced-market-search/saddlebag-with-pockets/wiki/Item-categories-ids-and-list");
+const DesiredStateSchema = z
+    .enum(["above", "below"])
+    .describe('Desired state: "above" or "below".');
+const ShoppingListItemSchema = z
+    .object({
+    itemID: ItemIdSchema.describe("Item ID to craft."),
+    craft_amount: z.number().int().min(1).describe("Amount to craft."),
+    hq: z.boolean().describe("True for HQ crafting."),
+    job: z
+        .number()
+        .int()
+        .min(0)
+        .max(15)
+        .describe("Job ID (0 for any). See https://github.com/ff14-advanced-market-search/saddlebag-with-pockets/wiki/FFXIV-job-category-ids"),
+})
+    .strict();
+const PriceGroupSchema = z
+    .object({
+    name: z.string().min(1).max(64).describe("Name of the price group."),
+    hq_only: z.boolean().describe("If true, include only HQ items in this group."),
+    item_ids: z.array(ItemIdSchema).optional().describe("Explicit item IDs to include."),
+    categories: z
+        .array(z.number().int())
+        .optional()
+        .describe("Category IDs to include (see wiki for category IDs)."),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const hasItems = Array.isArray(value.item_ids) && value.item_ids.length > 0;
+    const hasCategories = Array.isArray(value.categories) && value.categories.length > 0;
+    if (!hasItems && !hasCategories) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Provide at least one of item_ids or categories.",
+        });
+    }
+});
+const UserAuctionPriceSchema = z
+    .object({
+    itemID: ItemIdSchema.describe("Item ID to monitor."),
+    price: z.number().int().min(0).describe("Target price per unit."),
+    desired_state: DesiredStateSchema,
+    hq: z.boolean().describe("True for HQ items."),
+})
+    .strict();
+const UserAuctionQuantitySchema = z
+    .object({
+    itemID: ItemIdSchema.describe("Item ID to monitor."),
+    quantity: z.number().int().min(0).describe("Target quantity."),
+    desired_state: DesiredStateSchema,
+    hq: z.boolean().describe("True for HQ items."),
+})
+    .strict();
+export function registerSaddlebagTools(server, clients) {
+    server.registerTool("saddlebag_get_blog_description", {
+        title: "Saddlebag Item Description",
+        description: "Fetch the XIVAPI description text for an item ID.",
+        inputSchema: z
+            .object({
+            item_id: ItemIdSchema,
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ item_id, response_format }) => {
+        const data = await clients.saddlebag.post("/ffxiv/blog", { item_id });
+        return buildToolResponse({
+            title: "Saddlebag Item Description",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/ffxiv/blog", item_id },
+        });
+    });
+    server.registerTool("saddlebag_get_raw_stats", {
+        title: "Saddlebag Raw Market Stats",
+        description: "Fetch daily snapshot stats (median, average, sales volume) for a list of item IDs.",
+        inputSchema: z
+            .object({
+            region: RegionSchema.describe('Region name (e.g. "North-America", "Europe").'),
+            item_ids: RawStatsItemIdsSchema,
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ region, item_ids, response_format }) => {
+        const data = await clients.saddlebag.post("/ffxivrawstats", { region, item_ids });
+        return buildToolResponse({
+            title: "Saddlebag Raw Market Stats",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/ffxivrawstats", region, item_ids },
+        });
+    });
+    server.registerTool("saddlebag_get_listing_metrics", {
+        title: "Saddlebag Listing Metrics",
+        description: "Fetch listing competition metrics and current listings for an item.",
+        inputSchema: z
+            .object({
+            item_id: ItemIdSchema,
+            home_server: ServerSchema,
+            initial_days: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Deprecated age filter (days)."),
+            end_days: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Deprecated age filter (days)."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ item_id, home_server, initial_days, end_days, response_format }) => {
+        const payload = {
+            item_id,
+            home_server,
+            ...(initial_days !== undefined ? { initial_days } : {}),
+            ...(end_days !== undefined ? { end_days } : {}),
+        };
+        const data = await clients.saddlebag.post("/ffxiv/v2/listing", payload);
+        return buildToolResponse({
+            title: "Saddlebag Listing Metrics",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/ffxiv/v2/listing", item_id, home_server },
+        });
+    });
+    server.registerTool("saddlebag_get_history_metrics", {
+        title: "Saddlebag History Metrics",
+        description: "Fetch aggregated history metrics and price distributions for an item.",
+        inputSchema: z
+            .object({
+            item_id: ItemIdSchema,
+            home_server: ServerSchema,
+            item_type: z
+                .enum(["hq_only", "nq_only", "all"])
+                .optional()
+                .describe('Type of history to return: "hq_only", "nq_only", or "all".'),
+            initial_days: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Deprecated age filter (days)."),
+            end_days: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Deprecated age filter (days)."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ item_id, home_server, item_type, initial_days, end_days, response_format }) => {
+        const payload = {
+            item_id,
+            home_server,
+            ...(item_type ? { item_type } : {}),
+            ...(initial_days !== undefined ? { initial_days } : {}),
+            ...(end_days !== undefined ? { end_days } : {}),
+        };
+        const data = await clients.saddlebag.post("/ffxiv/v2/history", payload);
+        return buildToolResponse({
+            title: "Saddlebag History Metrics",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/ffxiv/v2/history", item_id, home_server },
+        });
+    });
+    server.registerTool("saddlebag_get_scrip_exchange", {
+        title: "Saddlebag Scrip Exchange",
+        description: "Rank scrip exchange items by gil value per scrip.",
+        inputSchema: z
+            .object({
+            home_server: ServerSchema,
+            color: z
+                .enum([
+                "Orange Gatherers",
+                "Purple Gatherers",
+                "Purple Crafters",
+                "Orange Crafters",
+            ])
+                .describe("Scrip category."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ home_server, color, response_format }) => {
+        const data = await clients.saddlebag.post("/ffxiv/scripexchange", { home_server, color });
+        return buildToolResponse({
+            title: "Saddlebag Scrip Exchange",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/ffxiv/scripexchange", home_server, color },
+        });
+    });
+    server.registerTool("saddlebag_get_shopping_list", {
+        title: "Saddlebag Shopping List",
+        description: "Build a crafting shopping list across servers (may return an exception payload for some items).",
+        inputSchema: z
+            .object({
+            home_server: ServerSchema,
+            shopping_list: z
+                .array(ShoppingListItemSchema)
+                .min(1)
+                .max(10)
+                .describe("Up to 10 items to craft."),
+            region_wide: z
+                .boolean()
+                .describe("If true, search all data centers in your region."),
+            ignore_after_hours: z
+                .number()
+                .int()
+                .min(0)
+                .describe("Ignore listings older than this many hours."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ home_server, shopping_list, region_wide, ignore_after_hours, response_format }) => {
+        const data = await clients.saddlebag.post("/v2/shoppinglist", {
+            home_server,
+            shopping_list,
+            region_wide,
+            ignore_after_hours,
+        });
+        return buildToolResponse({
+            title: "Saddlebag Shopping List",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/v2/shoppinglist", home_server },
+        });
+    });
+    server.registerTool("saddlebag_get_export_prices", {
+        title: "Saddlebag Export Prices",
+        description: "Compare item prices across multiple servers for export trading.",
+        inputSchema: z
+            .object({
+            home_server: ServerSchema,
+            export_servers: z
+                .array(z.string().min(1))
+                .min(1)
+                .describe("Servers to compare against."),
+            item_ids: ItemIdsSchema,
+            hq_only: z.boolean().describe("If true, include only HQ prices."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ home_server, export_servers, item_ids, hq_only, response_format }) => {
+        const data = await clients.saddlebag.post("/export", {
+            home_server,
+            export_servers,
+            item_ids,
+            hq_only,
+        });
+        return buildToolResponse({
+            title: "Saddlebag Export Prices",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/export", home_server, item_ids },
+        });
+    });
+    server.registerTool("saddlebag_get_marketshare", {
+        title: "Saddlebag Marketshare",
+        description: "Fetch marketshare leaderboard data for a server.",
+        inputSchema: z
+            .object({
+            server: ServerSchema,
+            time_period: z.number().int().min(1).describe("Time period in hours."),
+            sales_amount: z.number().int().min(0).describe("Minimum sales amount."),
+            average_price: z.number().int().min(0).describe("Minimum average price."),
+            filters: FiltersSchema,
+            sort_by: z
+                .enum([
+                "avg",
+                "marketValue",
+                "median",
+                "purchaseAmount",
+                "quantitySold",
+                "percentChange",
+            ])
+                .describe("Sort field."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ server, time_period, sales_amount, average_price, filters, sort_by, response_format }) => {
+        const data = await clients.saddlebag.post("/ffxivmarketshare", {
+            server,
+            time_period,
+            sales_amount,
+            average_price,
+            filters,
+            sort_by,
+        });
+        return buildToolResponse({
+            title: "Saddlebag Marketshare",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/ffxivmarketshare", server },
+        });
+    });
+    server.registerTool("saddlebag_get_reselling_scan", {
+        title: "Saddlebag Reselling Scan",
+        description: "Find reselling opportunities across servers or vendors.",
+        inputSchema: z
+            .object({
+            preferred_roi: z.number().int().min(0).describe("Preferred ROI percentage."),
+            min_profit_amount: z.number().int().min(0).describe("Minimum profit per item."),
+            min_desired_avg_ppu: z.number().int().min(0).describe("Minimum average price."),
+            min_stack_size: z.number().int().min(1).describe("Minimum stack size."),
+            hours_ago: z.number().int().min(1).describe("Sales window in hours."),
+            min_sales: z.number().int().min(0).describe("Minimum sales in window."),
+            hq: z.boolean().describe("HQ-only if true."),
+            home_server: ServerSchema,
+            filters: FiltersSchema,
+            region_wide: z.boolean().describe("Search region-wide if true."),
+            include_vendor: z.boolean().describe("Include vendor prices if true."),
+            show_out_stock: z.boolean().describe("Include out-of-stock items if true."),
+            universalis_list_uid: z
+                .string()
+                .optional()
+                .describe("Universalis list UID (deprecated)."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ preferred_roi, min_profit_amount, min_desired_avg_ppu, min_stack_size, hours_ago, min_sales, hq, home_server, filters, region_wide, include_vendor, show_out_stock, universalis_list_uid, response_format, }) => {
+        const payload = {
+            preferred_roi,
+            min_profit_amount,
+            min_desired_avg_ppu,
+            min_stack_size,
+            hours_ago,
+            min_sales,
+            hq,
+            home_server,
+            filters,
+            region_wide,
+            include_vendor,
+            show_out_stock,
+            ...(universalis_list_uid ? { universalis_list_uid } : {}),
+        };
+        const data = await clients.saddlebag.post("/scan", payload);
+        return buildToolResponse({
+            title: "Saddlebag Reselling Scan",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/scan", home_server },
+        });
+    });
+    server.registerTool("saddlebag_get_weekly_price_group_delta", {
+        title: "Saddlebag Weekly Price Group Delta",
+        description: "Compute weekly price deltas for custom item groups.",
+        inputSchema: z
+            .object({
+            region: RegionSchema,
+            start_year: z.number().int().min(2022).describe("Start year (>= 2022)."),
+            start_month: z.number().int().min(1).max(12).describe("Start month (1-12)."),
+            start_day: z.number().int().min(1).max(31).describe("Start day (1-31)."),
+            end_year: z.number().int().min(2022).describe("End year (>= 2022)."),
+            end_month: z.number().int().min(1).max(12).describe("End month (1-12)."),
+            end_day: z.number().int().min(1).max(31).describe("End day (1-31)."),
+            price_groups: z.array(PriceGroupSchema).min(1).describe("Price groups to aggregate."),
+            price_setting: z.enum(["average", "median"]).describe("Price metric."),
+            quantity_setting: z
+                .enum(["quantitySold", "salesAmount"])
+                .describe("Quantity metric."),
+            minimum_marketshare: z.number().int().min(0).describe("Minimum marketshare."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ region, start_year, start_month, start_day, end_year, end_month, end_day, price_groups, price_setting, quantity_setting, minimum_marketshare, response_format, }) => {
+        const data = await clients.saddlebag.post("/ffxiv/weekly-price-group-delta", {
+            region,
+            start_year,
+            start_month,
+            start_day,
+            end_year,
+            end_month,
+            end_day,
+            price_groups,
+            price_setting,
+            quantity_setting,
+            minimum_marketshare,
+        });
+        return buildToolResponse({
+            title: "Saddlebag Weekly Price Group Delta",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/ffxiv/weekly-price-group-delta", region },
+        });
+    });
+    server.registerTool("saddlebag_get_price_check", {
+        title: "Saddlebag Price Check",
+        description: "Check price alerts against current market listings.",
+        inputSchema: z
+            .object({
+            home_server: ServerSchema,
+            dc_only: z.boolean().optional().describe("If true, check data center only."),
+            user_auctions: z
+                .array(UserAuctionPriceSchema)
+                .min(1)
+                .describe("User auction alerts."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ home_server, dc_only, user_auctions, response_format }) => {
+        const payload = {
+            home_server,
+            user_auctions,
+            ...(dc_only !== undefined ? { dc_only } : {}),
+        };
+        const data = await clients.saddlebag.post("/pricecheck", payload);
+        return buildToolResponse({
+            title: "Saddlebag Price Check",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/pricecheck", home_server },
+        });
+    });
+    server.registerTool("saddlebag_get_quantity_check", {
+        title: "Saddlebag Quantity Check",
+        description: "Check quantity alerts against current market listings.",
+        inputSchema: z
+            .object({
+            home_server: ServerSchema,
+            user_auctions: z
+                .array(UserAuctionQuantitySchema)
+                .min(1)
+                .describe("User auction alerts."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ home_server, user_auctions, response_format }) => {
+        const data = await clients.saddlebag.post("/quantitycheck", {
+            home_server,
+            user_auctions,
+        });
+        return buildToolResponse({
+            title: "Saddlebag Quantity Check",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/quantitycheck", home_server },
+        });
+    });
+    server.registerTool("saddlebag_get_sale_alert", {
+        title: "Saddlebag Sale Alerts",
+        description: "Check if tracked items have sold based on retainer listings.",
+        inputSchema: z
+            .object({
+            retainer_names: z
+                .array(z.string().min(1))
+                .min(1)
+                .describe("Retainer names to track."),
+            server: ServerSchema,
+            item_ids: ItemIdsSchema,
+            seller_id: z.string().optional().describe("Seller ID (deprecated)."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ retainer_names, server, item_ids, seller_id, response_format }) => {
+        const payload = {
+            retainer_names,
+            server,
+            item_ids,
+            ...(seller_id ? { seller_id } : {}),
+        };
+        const data = await clients.saddlebag.post("/salealert", payload);
+        return buildToolResponse({
+            title: "Saddlebag Sale Alerts",
+            responseFormat: response_format,
+            data,
+            meta: { source: "saddlebag", endpoint: "/salealert", server },
+        });
+    });
+    server.registerTool("saddlebag_get_craftsim", {
+        title: "Saddlebag Craftsim",
+        description: "Calculate profitable crafting recipes. Results can be very large; max_results limits output size.",
+        inputSchema: z
+            .object({
+            home_server: ServerSchema,
+            cost_metric: z
+                .enum([
+                "material_avg_cost",
+                "material_median_cost",
+                "material_min_listing_cost",
+            ])
+                .describe("Cost metric."),
+            revenue_metric: z
+                .enum([
+                "revenue_avg",
+                "revenue_median",
+                "revenue_home_min_listing",
+                "revenue_region_min_listing",
+            ])
+                .describe("Revenue metric."),
+            sales_per_week: z.number().int().min(0).describe("Minimum sales per week."),
+            median_sale_price: z.number().int().min(0).describe("Minimum median sale price."),
+            max_material_cost: z.number().int().min(0).describe("Maximum material cost."),
+            filters: FiltersSchema,
+            jobs: z
+                .array(z.number().int())
+                .min(1)
+                .max(15)
+                .describe("Job IDs to scan ([0] for all jobs). See https://github.com/ff14-advanced-market-search/saddlebag-with-pockets/wiki/FFXIV-job-category-ids"),
+            stars: z
+                .number()
+                .int()
+                .min(-1)
+                .describe("Stars required (-1 for any)."),
+            lvl_lower_limit: z
+                .number()
+                .int()
+                .min(-1)
+                .max(99)
+                .describe("Lower level limit (max 99)."),
+            lvl_upper_limit: z
+                .number()
+                .int()
+                .min(2)
+                .describe("Upper level limit (min 2)."),
+            yields: z.number().int().min(-1).describe("Yield amount (-1 for any)."),
+            hide_expert_recipes: z.boolean().describe("Hide expert recipes if true."),
+            max_results: z
+                .number()
+                .int()
+                .min(1)
+                .max(5000)
+                .default(200)
+                .describe("Limit number of recipes returned (default: 200)."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ home_server, cost_metric, revenue_metric, sales_per_week, median_sale_price, max_material_cost, filters, jobs, stars, lvl_lower_limit, lvl_upper_limit, yields, hide_expert_recipes, max_results, response_format, }) => {
+        const data = await clients.saddlebag.post("/v2/craftsim", {
+            home_server,
+            cost_metric,
+            revenue_metric,
+            sales_per_week,
+            median_sale_price,
+            max_material_cost,
+            filters,
+            jobs,
+            stars,
+            lvl_lower_limit,
+            lvl_upper_limit,
+            yields,
+            hide_expert_recipes,
+        });
+        let output = data;
+        let summaryLines;
+        if (output && typeof output === "object" && Array.isArray(output.data)) {
+            const total = output.data.length;
+            if (total > max_results) {
+                output = { ...output, data: output.data.slice(0, max_results) };
+                summaryLines = [`Showing ${max_results} of ${total} recipes.`];
+            }
+        }
+        return buildToolResponse({
+            title: "Saddlebag Craftsim",
+            responseFormat: response_format,
+            data: output,
+            meta: { source: "saddlebag", endpoint: "/v2/craftsim", home_server, max_results },
+            summaryLines,
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universalis-mcp-server",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "MCP server for Universalis and XIVAPI",
   "author": "Jakub Mucha <jakub.mucha@icloud.com>",
   "repository": {