universalis-mcp-server 0.1.1 → 0.2.1

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,30 @@ 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).
+
+### Guides (Wiki snapshots)
+
+- `wiki_list_pages`: List curated wiki pages for Saddlebag and Universalis guides.
+- `wiki_get_page`: Fetch a wiki page by slug for extra context.
+
 ### Reference data (Universalis)
 
 - `universalis_list_worlds`: List worlds with pagination.
@@ -71,6 +95,12 @@ pnpm install
 pnpm build
 ```
 
+To refresh curated wiki snapshots:
+
+```bash
+pnpm update-wiki-docs
+```
+
 ## Run (stdio)
 
 ```bash
@@ -97,9 +127,13 @@ 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).
+- `WIKI_FETCH_MODE`: `local` (default) for snapshot files or `live` to fetch from GitHub.
+- `WIKI_REFRESH_TTL_MS`: Cache TTL for live wiki fetches (default: 3600000).
 - `XIVAPI_LANGUAGE`: Default XIVAPI language (default: `en`).
 - `XIVAPI_VERSION`: Default XIVAPI version (default: `latest`).
 
@@ -107,3 +141,6 @@ 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.
+- Wiki pages are curated snapshots stored in `docs/wiki`.
+- Set `WIKI_FETCH_MODE=live` to refresh wiki pages at runtime using the allowlisted index.

package/data/materia.json

@@ -1,5 +1,5 @@
 {
-  "generated_at": "2026-01-11T19:43:16.262Z",
+  "generated_at": "2026-01-11T22:27:50.340Z",
   "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,7 +7,9 @@ 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 { registerWikiTools } from "./tools/wiki.js";
 import { registerWorkflowTools } from "./tools/workflows.js";
 function toNumber(value) {
     if (!value)
@@ -27,6 +29,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 +37,8 @@ async function main() {
     registerReferenceTools(server, clients);
     registerStatsTools(server, clients);
     registerLookupTools(server, clients);
+    registerSaddlebagTools(server, clients);
+    registerWikiTools(server);
     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,26 @@ 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.
+
+Wiki tools:
+- wiki_list_pages: list curated Saddlebag/Universalis guide pages.
+- wiki_get_page: fetch a wiki page by slug for extra context.
+
 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 +53,10 @@ 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.
+- Wiki pages are curated snapshots; refresh with scripts/update-wiki-docs.mjs as needed.
+- Set WIKI_FETCH_MODE=live to fetch allowlisted wiki pages from GitHub (cached by WIKI_REFRESH_TTL_MS).
 `;

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