universalis-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Mucha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# universalis-mcp-server
+
+MCP server for Universalis market data and XIVAPI item lookup.
+
+## Capabilities
+
+This MCP server exposes read-only tools for Universalis market data and XIVAPI item lookup.
+All tools support `response_format` as `markdown` or `json`.
+
+### Market board data (Universalis)
+
+- `universalis_get_aggregated_prices`: Aggregated pricing stats for up to 100 item IDs on a world, data center, or region (cached values only).
+- `universalis_get_current_listings`: Current listings plus recent sales history; supports filters like `hq`, `listings`, `entries`, and field selection.
+- `universalis_get_sales_history`: Sales history with optional time windows and price filters.
+
+### Item lookup (XIVAPI)
+
+- `universalis_resolve_items_by_name`: Search items by name with `partial` or `exact` matching.
+- `universalis_get_item_by_id`: Fetch a single item row by ID.
+
+### Reference data (Universalis)
+
+- `universalis_list_worlds`: List worlds with pagination.
+- `universalis_list_data_centers`: List data centers with pagination.
+- `universalis_list_marketable_items`: List marketable item IDs with pagination.
+- `universalis_get_tax_rates`: Current tax rates for a world.
+- `universalis_get_list`: Fetch a Universalis list by ID.
+- `universalis_get_content`: Fetch content metadata by ID (best-effort endpoint).
+
+### Stats and activity (Universalis)
+
+- `universalis_get_most_recent_updates`: Most recently updated items for a world or data center.
+- `universalis_get_least_recent_updates`: Least recently updated items for a world or data center.
+- `universalis_get_recent_updates`: Legacy list of recent updates (no world/DC scoping).
+- `universalis_get_upload_counts_by_source`: Upload counts by client app.
+- `universalis_get_upload_counts_by_world`: Upload counts and proportions by world.
+- `universalis_get_upload_history`: Daily upload totals for the last 30 days.
+
+## Use with Codex and Claude Code
+
+Install from npm via MCP:
+
+```bash
+# Codex
+codex mcp add universalis-mcp-server -- npx universalis-mcp-server@latest
+
+# Claude Code
+claude mcp add universalis-mcp-server npx universalis-mcp-server@latest
+```
+
+To pass environment variables (optional), add them before the command:
+
+```bash
+# Codex
+codex mcp add universalis-mcp-server -- env UNIVERSALIS_TIMEOUT_MS=30000 XIVAPI_TIMEOUT_MS=30000 npx universalis-mcp-server@latest
+
+# Claude Code
+claude mcp add universalis-mcp-server env UNIVERSALIS_TIMEOUT_MS=30000 XIVAPI_TIMEOUT_MS=30000 npx universalis-mcp-server@latest
+```
+
+## Setup
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Run (stdio)
+
+```bash
+node dist/index.js
+```
+
+## Local Development with Codex and Claude Code
+
+Build the server and point MCP to the local `dist` entry:
+
+```bash
+pnpm build
+
+# Codex
+codex mcp add universalis-mcp-server -- node ./dist/index.js
+
+# Claude Code
+claude mcp add universalis-mcp-server node ./dist/index.js
+```
+
+If you change code, re-run `pnpm build` and restart the MCP connection.
+
+## Environment Variables
+
+- `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`).
+- `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).
+- `XIVAPI_LANGUAGE`: Default XIVAPI language (default: `en`).
+- `XIVAPI_VERSION`: Default XIVAPI version (default: `latest`).
+
+## Notes
+
+- Rate limits are enforced client-side for Universalis and XIVAPI.
+- Tools support `response_format` as `markdown` or `json`.

package/dist/constants.js

@@ -0,0 +1,10 @@
+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 DEFAULT_UNIVERSALIS_TIMEOUT_MS = 30000;
+export const DEFAULT_XIVAPI_TIMEOUT_MS = 30000;
+export const DEFAULT_TIMEOUT_MS = 30000;
+export const CHARACTER_LIMIT = 25000;
+export const DEFAULT_PAGE_LIMIT = 20;
+export const MAX_PAGE_LIMIT = 100;
+export const DEFAULT_XIVAPI_LANGUAGE = process.env.XIVAPI_LANGUAGE ?? "en";
+export const DEFAULT_XIVAPI_VERSION = process.env.XIVAPI_VERSION ?? "latest";

package/dist/index.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+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 { 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";
+function toNumber(value) {
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+async function main() {
+    const server = new McpServer({
+        name: "universalis-mcp-server",
+        version: pkg.version,
+    });
+    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),
+        xivapiLanguage: process.env.XIVAPI_LANGUAGE,
+        xivapiVersion: process.env.XIVAPI_VERSION,
+    });
+    registerMarketTools(server, clients);
+    registerReferenceTools(server, clients);
+    registerStatsTools(server, clients);
+    registerLookupTools(server, clients);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("universalis-mcp-server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/dist/schemas/common.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export var ResponseFormat;
+(function (ResponseFormat) {
+    ResponseFormat["MARKDOWN"] = "markdown";
+    ResponseFormat["JSON"] = "json";
+})(ResponseFormat || (ResponseFormat = {}));
+export const ResponseFormatSchema = z
+    .nativeEnum(ResponseFormat)
+    .default(ResponseFormat.MARKDOWN)
+    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable.");
+export const BaseOutputSchema = z.object({
+    data: z.unknown(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+});

package/dist/services/clients.js

@@ -0,0 +1,32 @@
+import Bottleneck from "bottleneck";
+import { DEFAULT_UNIVERSALIS_TIMEOUT_MS, DEFAULT_XIVAPI_TIMEOUT_MS } from "../constants.js";
+import { UniversalisClient } from "./universalis.js";
+import { XivapiClient } from "./xivapi.js";
+export function createClients(options = {}) {
+    const universalisLimiter = new Bottleneck({
+        maxConcurrent: 8,
+        reservoir: 50,
+        reservoirRefreshAmount: 25,
+        reservoirRefreshInterval: 1000,
+    });
+    const xivapiLimiter = new Bottleneck({
+        maxConcurrent: 4,
+        reservoir: 20,
+        reservoirRefreshAmount: 10,
+        reservoirRefreshInterval: 1000,
+    });
+    return {
+        universalis: new UniversalisClient({
+            limiter: universalisLimiter,
+            timeoutMs: options.universalisTimeoutMs ?? DEFAULT_UNIVERSALIS_TIMEOUT_MS,
+            userAgent: options.userAgent,
+        }),
+        xivapi: new XivapiClient({
+            limiter: xivapiLimiter,
+            timeoutMs: options.xivapiTimeoutMs ?? DEFAULT_XIVAPI_TIMEOUT_MS,
+            userAgent: options.userAgent,
+            defaultLanguage: options.xivapiLanguage,
+            defaultVersion: options.xivapiVersion,
+        }),
+    };
+}

package/dist/services/http.js

@@ -0,0 +1,93 @@
+import { DEFAULT_TIMEOUT_MS } from "../constants.js";
+export class ApiError extends Error {
+    status;
+    details;
+    constructor(message, status, details) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.details = details;
+    }
+}
+const arrayJoiner = {
+    query: " ",
+    fields: ",",
+    transient: ",",
+};
+function buildUrl(baseUrl, path, query) {
+    const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    const url = new URL(path.replace(/^\/+/, ""), base);
+    if (!query)
+        return url;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            const joiner = arrayJoiner[key] ?? ",";
+            params.set(key, value.join(joiner));
+        }
+        else {
+            params.set(key, String(value));
+        }
+    }
+    url.search = params.toString();
+    return url;
+}
+async function doRequest({ baseUrl, path, method = "GET", query, headers, body, timeoutMs = DEFAULT_TIMEOUT_MS, userAgent, responseType = "json", }) {
+    const url = buildUrl(baseUrl, path, query);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method,
+            headers: {
+                Accept: responseType === "json" ? "application/json" : "*/*",
+                ...(body ? { "Content-Type": "application/json" } : {}),
+                ...(userAgent ? { "User-Agent": userAgent } : {}),
+                ...headers,
+            },
+            body: body ? JSON.stringify(body) : undefined,
+            signal: controller.signal,
+        });
+        const contentType = response.headers.get("content-type") ?? "";
+        const rawText = await response.text();
+        if (!response.ok) {
+            const parsed = contentType.includes("application/json") ? safeJsonParse(rawText) : undefined;
+            const message = (parsed && typeof parsed === "object" && parsed && "message" in parsed && String(parsed.message)) ||
+                rawText ||
+                `Request failed with status ${response.status}`;
+            throw new ApiError(message, response.status, parsed ?? rawText);
+        }
+        if (responseType === "text" || !contentType.includes("application/json")) {
+            return rawText;
+        }
+        return safeJsonParse(rawText);
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : "Unknown request error";
+        throw new ApiError(message, 0);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function safeJsonParse(payload) {
+    if (!payload)
+        return null;
+    try {
+        return JSON.parse(payload);
+    }
+    catch {
+        return null;
+    }
+}
+export async function requestJson(options) {
+    if (options.limiter) {
+        return options.limiter.schedule(() => doRequest(options));
+    }
+    return doRequest(options);
+}

package/dist/services/universalis.js

@@ -0,0 +1,179 @@
+import { LRUCache } from "lru-cache";
+import { UNIVERSALIS_BASE_URL } from "../constants.js";
+import { requestJson } from "./http.js";
+export class UniversalisClient {
+    baseUrl;
+    timeoutMs;
+    limiter;
+    userAgent;
+    worldsCache = new LRUCache({ max: 1, ttl: 1000 * 60 * 60 });
+    dataCentersCache = new LRUCache({
+        max: 1,
+        ttl: 1000 * 60 * 60,
+    });
+    marketableCache = new LRUCache({ max: 1, ttl: 1000 * 60 * 60 * 6 });
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl ?? UNIVERSALIS_BASE_URL;
+        this.timeoutMs = options.timeoutMs;
+        this.limiter = options.limiter;
+        this.userAgent = options.userAgent;
+    }
+    async listWorlds() {
+        const cached = this.worldsCache.get("worlds");
+        if (cached)
+            return cached;
+        const data = await requestJson({
+            baseUrl: this.baseUrl,
+            path: "/worlds",
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+        this.worldsCache.set("worlds", data);
+        return data;
+    }
+    async listDataCenters() {
+        const cached = this.dataCentersCache.get("data-centers");
+        if (cached)
+            return cached;
+        const data = await requestJson({
+            baseUrl: this.baseUrl,
+            path: "/data-centers",
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+        this.dataCentersCache.set("data-centers", data);
+        return data;
+    }
+    async getAggregatedMarketData(worldDcRegion, itemIds) {
+        const path = `/aggregated/${encodeURIComponent(worldDcRegion)}/${itemIds.join(",")}`;
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path,
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+    async getCurrentMarketData(worldDcRegion, itemIds, query) {
+        const path = `/${encodeURIComponent(worldDcRegion)}/${itemIds.join(",")}`;
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path,
+            query,
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+    async getSalesHistory(worldDcRegion, itemIds, query) {
+        const path = `/history/${encodeURIComponent(worldDcRegion)}/${itemIds.join(",")}`;
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path,
+            query,
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+    async getTaxRates(world) {
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path: "/tax-rates",
+            query: { world },
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+    async listMarketableItems() {
+        const cached = this.marketableCache.get("marketable");
+        if (cached)
+            return cached;
+        const data = await requestJson({
+            baseUrl: this.baseUrl,
+            path: "/marketable",
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+        this.marketableCache.set("marketable", data);
+        return data;
+    }
+    async getMostRecentlyUpdated(world, dcName, entries) {
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path: "/extra/stats/most-recently-updated",
+            query: { world, dcName, entries },
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+    async getLeastRecentlyUpdated(world, dcName, entries) {
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path: "/extra/stats/least-recently-updated",
+            query: { world, dcName, entries },
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+    async getRecentlyUpdated() {
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path: "/extra/stats/recently-updated",
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+    async getUploaderUploadCounts() {
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path: "/extra/stats/uploader-upload-counts",
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+    async getWorldUploadCounts() {
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path: "/extra/stats/world-upload-counts",
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+    async getUploadHistory() {
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path: "/extra/stats/upload-history",
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+    async getList(listId) {
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path: `/lists/${encodeURIComponent(listId)}`,
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+    async getContent(contentId) {
+        return requestJson({
+            baseUrl: this.baseUrl,
+            path: `/extra/content/${encodeURIComponent(contentId)}`,
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+    }
+}

package/dist/services/xivapi.js

@@ -0,0 +1,62 @@
+import { LRUCache } from "lru-cache";
+import { DEFAULT_XIVAPI_LANGUAGE, DEFAULT_XIVAPI_VERSION, XIVAPI_BASE_URL } from "../constants.js";
+import { requestJson } from "./http.js";
+export class XivapiClient {
+    baseUrl;
+    timeoutMs;
+    limiter;
+    userAgent;
+    defaultLanguage;
+    defaultVersion;
+    itemCache = new LRUCache({ max: 500, ttl: 1000 * 60 * 60 * 24 });
+    searchCache = new LRUCache({ max: 200, ttl: 1000 * 60 * 15 });
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl ?? XIVAPI_BASE_URL;
+        this.timeoutMs = options.timeoutMs;
+        this.limiter = options.limiter;
+        this.userAgent = options.userAgent;
+        this.defaultLanguage = options.defaultLanguage ?? DEFAULT_XIVAPI_LANGUAGE;
+        this.defaultVersion = options.defaultVersion ?? DEFAULT_XIVAPI_VERSION;
+    }
+    async search(params) {
+        const normalized = this.withDefaults({ ...params });
+        const cacheKey = JSON.stringify(normalized);
+        const cached = this.searchCache.get(cacheKey);
+        if (cached)
+            return cached;
+        const data = await requestJson({
+            baseUrl: this.baseUrl,
+            path: "/search",
+            query: normalized,
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+        this.searchCache.set(cacheKey, data);
+        return data;
+    }
+    async getItemById(itemId, params = {}) {
+        const normalized = this.withDefaults({ ...params });
+        const cacheKey = JSON.stringify({ itemId, ...normalized });
+        const cached = this.itemCache.get(cacheKey);
+        if (cached)
+            return cached;
+        const data = await requestJson({
+            baseUrl: this.baseUrl,
+            path: `/sheet/Item/${itemId}`,
+            query: normalized,
+            limiter: this.limiter,
+            timeoutMs: this.timeoutMs,
+            userAgent: this.userAgent,
+        });
+        this.itemCache.set(cacheKey, data);
+        return data;
+    }
+    withDefaults(params) {
+        return {
+            ...params,
+            language: params.language ?? this.defaultLanguage,
+            version: params.version ?? this.defaultVersion,
+        };
+    }
+}

package/dist/tools/lookup.js

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { BaseOutputSchema, ResponseFormatSchema } from "../schemas/common.js";
+import { buildToolResponse } from "../utils/format.js";
+const LanguageSchema = z
+    .enum(["none", "ja", "en", "de", "fr", "chs", "cht", "kr"])
+    .optional()
+    .describe("XIVAPI language code.");
+const MatchModeSchema = z
+    .enum(["partial", "exact"])
+    .default("partial")
+    .describe("Match mode for item name queries.");
+const DefaultItemFields = "Name,Icon,ItemSearchCategory,LevelItem";
+function escapeQueryValue(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+export function registerLookupTools(server, clients) {
+    server.registerTool("universalis_resolve_items_by_name", {
+        title: "Resolve Items by Name (XIVAPI)",
+        description: "Search XIVAPI for items by name, returning matching rows and relevance scores.",
+        inputSchema: z
+            .object({
+            query: z
+                .string()
+                .min(1)
+                .describe('Item name to search for. Example: "Dark Matter".'),
+            match_mode: MatchModeSchema,
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe("Maximum results to return (default: 20)."),
+            language: LanguageSchema,
+            fields: z
+                .string()
+                .optional()
+                .describe("Comma-separated XIVAPI fields. Default: Name,Icon,ItemSearchCategory,LevelItem."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ query, match_mode, limit, language, fields, response_format }) => {
+        const escaped = escapeQueryValue(query);
+        const queryClause = match_mode === "exact" ? `Name="${escaped}"` : `Name~"${escaped}"`;
+        const data = await clients.xivapi.search({
+            query: queryClause,
+            sheets: "Item",
+            limit,
+            language,
+            fields: fields ?? DefaultItemFields,
+        });
+        return buildToolResponse({
+            title: "Resolved Items",
+            responseFormat: response_format,
+            data,
+            meta: {
+                source: "xivapi",
+                endpoint: "/search",
+                query: queryClause,
+                limit,
+                ...(language ? { language } : {}),
+            },
+        });
+    });
+    server.registerTool("universalis_get_item_by_id", {
+        title: "Get Item by ID (XIVAPI)",
+        description: "Fetch a single item row from XIVAPI by item ID.",
+        inputSchema: z
+            .object({
+            item_id: z.number().int().min(1).describe("Item ID. Example: 5333."),
+            language: LanguageSchema,
+            fields: z
+                .string()
+                .optional()
+                .describe("Comma-separated XIVAPI fields to select."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ item_id, language, fields, response_format }) => {
+        const data = await clients.xivapi.getItemById(item_id, {
+            language,
+            fields,
+        });
+        return buildToolResponse({
+            title: "Item Details",
+            responseFormat: response_format,
+            data,
+            meta: {
+                source: "xivapi",
+                endpoint: "/sheet/Item/{row}",
+                item_id,
+                ...(language ? { language } : {}),
+            },
+        });
+    });
+}

package/dist/tools/market.js

@@ -0,0 +1,205 @@
+import { z } from "zod";
+import { BaseOutputSchema, ResponseFormatSchema } from "../schemas/common.js";
+import { buildToolResponse } from "../utils/format.js";
+const ItemIdsSchema = z
+    .array(z.number().int().min(1))
+    .min(1)
+    .max(100)
+    .describe("Item IDs (max 100). Example: [5333, 5334]");
+const WorldDcRegionSchema = z
+    .string()
+    .min(1)
+    .describe('World, data center, or region. Example: "Primal" or "North-America".');
+function extractNumberArray(value, key) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const record = value;
+    const arr = record[key];
+    return Array.isArray(arr) ? arr : undefined;
+}
+export function registerMarketTools(server, clients) {
+    server.registerTool("universalis_get_aggregated_prices", {
+        title: "Universalis Aggregated Prices",
+        description: "Fetch aggregated market board data for up to 100 item IDs on a world, data center, or region. Uses cached values only.",
+        inputSchema: z
+            .object({
+            world_dc_region: WorldDcRegionSchema,
+            item_ids: ItemIdsSchema,
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ world_dc_region, item_ids, response_format }) => {
+        const data = await clients.universalis.getAggregatedMarketData(world_dc_region, item_ids);
+        const failedItems = extractNumberArray(data, "failedItems");
+        return buildToolResponse({
+            title: "Aggregated Prices",
+            responseFormat: response_format,
+            data,
+            meta: {
+                source: "universalis",
+                endpoint: "/aggregated/{worldDcRegion}/{itemIds}",
+                world_dc_region,
+                item_ids,
+                ...(failedItems ? { failed_items: failedItems } : {}),
+            },
+        });
+    });
+    server.registerTool("universalis_get_current_listings", {
+        title: "Universalis Current Listings",
+        description: "Fetch current market board listings and recent history for up to 100 item IDs on a world, data center, or region.",
+        inputSchema: z
+            .object({
+            world_dc_region: WorldDcRegionSchema,
+            item_ids: ItemIdsSchema,
+            listings: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Listings to return per item (default: all)."),
+            entries: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("History entries to return per item (default: 5)."),
+            hq: z
+                .boolean()
+                .optional()
+                .describe("Filter for HQ listings and entries."),
+            stats_within_ms: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Time window for stats in milliseconds (default: 7 days)."),
+            entries_within_seconds: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Time window for entries in seconds."),
+            fields: z
+                .string()
+                .optional()
+                .describe("Comma-separated field list. For multi-item queries use items.<field> (e.g. items.listings.pricePerUnit)."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ world_dc_region, item_ids, listings, entries, hq, stats_within_ms, entries_within_seconds, fields, response_format, }) => {
+        const query = {
+            listings,
+            entries,
+            hq,
+            statsWithin: stats_within_ms,
+            entriesWithin: entries_within_seconds,
+            fields,
+        };
+        const data = await clients.universalis.getCurrentMarketData(world_dc_region, item_ids, query);
+        const unresolvedItems = extractNumberArray(data, "unresolvedItems");
+        return buildToolResponse({
+            title: "Current Listings",
+            responseFormat: response_format,
+            data,
+            meta: {
+                source: "universalis",
+                endpoint: "/{worldDcRegion}/{itemIds}",
+                world_dc_region,
+                item_ids,
+                ...(unresolvedItems ? { unresolved_items: unresolvedItems } : {}),
+            },
+        });
+    });
+    server.registerTool("universalis_get_sales_history", {
+        title: "Universalis Sales History",
+        description: "Fetch market board sales history for up to 100 item IDs on a world or data center.",
+        inputSchema: z
+            .object({
+            world_dc_region: WorldDcRegionSchema,
+            item_ids: ItemIdsSchema,
+            entries_to_return: z
+                .number()
+                .int()
+                .min(1)
+                .max(99999)
+                .optional()
+                .describe("Entries to return per item (default: 1800, max: 99999)."),
+            stats_within_ms: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Time window for stats in milliseconds (default: 7 days)."),
+            entries_within_seconds: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Time window for entries in seconds (default: 7 days)."),
+            entries_until: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("UNIX timestamp (seconds) to include entries up to."),
+            min_sale_price: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Minimum sale price per unit."),
+            max_sale_price: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Maximum sale price per unit."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ world_dc_region, item_ids, entries_to_return, stats_within_ms, entries_within_seconds, entries_until, min_sale_price, max_sale_price, response_format, }) => {
+        const query = {
+            entriesToReturn: entries_to_return,
+            statsWithin: stats_within_ms,
+            entriesWithin: entries_within_seconds,
+            entriesUntil: entries_until,
+            minSalePrice: min_sale_price,
+            maxSalePrice: max_sale_price,
+        };
+        const data = await clients.universalis.getSalesHistory(world_dc_region, item_ids, query);
+        const unresolvedItems = extractNumberArray(data, "unresolvedItems");
+        return buildToolResponse({
+            title: "Sales History",
+            responseFormat: response_format,
+            data,
+            meta: {
+                source: "universalis",
+                endpoint: "/history/{worldDcRegion}/{itemIds}",
+                world_dc_region,
+                item_ids,
+                ...(unresolvedItems ? { unresolved_items: unresolvedItems } : {}),
+            },
+        });
+    });
+}

package/dist/tools/reference.js

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import { BaseOutputSchema, ResponseFormatSchema } from "../schemas/common.js";
+import { buildToolResponse } from "../utils/format.js";
+import { paginateArray } from "../utils/pagination.js";
+import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from "../constants.js";
+const PaginationSchema = z
+    .object({
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_PAGE_LIMIT)
+        .default(DEFAULT_PAGE_LIMIT)
+        .describe("Maximum results to return (default: 20, max: 100)."),
+    offset: z.number().int().min(0).default(0).describe("Results offset for pagination."),
+})
+    .strict();
+export function registerReferenceTools(server, clients) {
+    server.registerTool("universalis_list_worlds", {
+        title: "List Universalis Worlds",
+        description: "List all worlds supported by Universalis, with optional pagination.",
+        inputSchema: PaginationSchema.extend({
+            response_format: ResponseFormatSchema,
+        }).strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ limit, offset, response_format }) => {
+        const worlds = await clients.universalis.listWorlds();
+        const page = paginateArray(worlds, offset, limit);
+        return buildToolResponse({
+            title: "Universalis Worlds",
+            responseFormat: response_format,
+            data: page,
+            meta: { source: "universalis", endpoint: "/worlds" },
+            summaryLines: [
+                `Total worlds: ${page.total}`,
+                `Showing ${page.count} starting at offset ${page.offset}`,
+            ],
+        });
+    });
+    server.registerTool("universalis_list_data_centers", {
+        title: "List Universalis Data Centers",
+        description: "List all data centers supported by Universalis, with optional pagination.",
+        inputSchema: PaginationSchema.extend({
+            response_format: ResponseFormatSchema,
+        }).strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ limit, offset, response_format }) => {
+        const dataCenters = await clients.universalis.listDataCenters();
+        const page = paginateArray(dataCenters, offset, limit);
+        return buildToolResponse({
+            title: "Universalis Data Centers",
+            responseFormat: response_format,
+            data: page,
+            meta: { source: "universalis", endpoint: "/data-centers" },
+            summaryLines: [
+                `Total data centers: ${page.total}`,
+                `Showing ${page.count} starting at offset ${page.offset}`,
+            ],
+        });
+    });
+    server.registerTool("universalis_get_tax_rates", {
+        title: "Universalis Tax Rates",
+        description: "Retrieve current market tax rates for a world.",
+        inputSchema: z
+            .object({
+            world: z
+                .string()
+                .min(1)
+                .describe('World name or ID. Example: "Ragnarok" or "74".'),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ world, response_format }) => {
+        const data = await clients.universalis.getTaxRates(world);
+        return buildToolResponse({
+            title: "Tax Rates",
+            responseFormat: response_format,
+            data,
+            meta: { source: "universalis", endpoint: "/tax-rates", world },
+        });
+    });
+    server.registerTool("universalis_list_marketable_items", {
+        title: "List Marketable Items",
+        description: "Return marketable item IDs from Universalis, with optional pagination.",
+        inputSchema: PaginationSchema.extend({
+            response_format: ResponseFormatSchema,
+        }).strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ limit, offset, response_format }) => {
+        const items = await clients.universalis.listMarketableItems();
+        const page = paginateArray(items, offset, limit);
+        return buildToolResponse({
+            title: "Marketable Items",
+            responseFormat: response_format,
+            data: page,
+            meta: { source: "universalis", endpoint: "/marketable" },
+            summaryLines: [
+                `Total IDs: ${page.total}`,
+                `Showing ${page.count} starting at offset ${page.offset}`,
+            ],
+        });
+    });
+    server.registerTool("universalis_get_list", {
+        title: "Get Universalis List",
+        description: "Retrieve a user list by ID from Universalis.",
+        inputSchema: z
+            .object({
+            list_id: z.string().min(1).describe("List ID from Universalis."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ list_id, response_format }) => {
+        const data = await clients.universalis.getList(list_id);
+        return buildToolResponse({
+            title: "Universalis List",
+            responseFormat: response_format,
+            data,
+            meta: { source: "universalis", endpoint: "/lists/{listId}", list_id },
+        });
+    });
+    server.registerTool("universalis_get_content", {
+        title: "Get Universalis Content",
+        description: "Retrieve content metadata by content ID (best-effort, endpoint may be inconsistent).",
+        inputSchema: z
+            .object({
+            content_id: z.string().min(1).describe("Content ID from Universalis."),
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ content_id, response_format }) => {
+        const data = await clients.universalis.getContent(content_id);
+        return buildToolResponse({
+            title: "Universalis Content",
+            responseFormat: response_format,
+            data,
+            meta: { source: "universalis", endpoint: "/extra/content/{contentId}", content_id },
+        });
+    });
+}

package/dist/tools/stats.js

@@ -0,0 +1,190 @@
+import { z } from "zod";
+import { BaseOutputSchema, ResponseFormatSchema } from "../schemas/common.js";
+import { buildToolResponse } from "../utils/format.js";
+const StatsScopeBase = z
+    .object({
+    world: z.string().min(1).optional().describe('World name or ID. Example: "Gilgamesh".'),
+    dc_name: z.string().min(1).optional().describe('Data center name. Example: "Aether".'),
+})
+    .strict();
+const EntriesSchema = z
+    .number()
+    .int()
+    .min(1)
+    .max(200)
+    .default(50)
+    .describe("Number of entries to return (default: 50, max: 200).");
+export function registerStatsTools(server, clients) {
+    server.registerTool("universalis_get_most_recent_updates", {
+        title: "Most Recently Updated Items",
+        description: "Get the most recently updated items for a world or data center.",
+        inputSchema: StatsScopeBase.extend({
+            entries: EntriesSchema.optional(),
+            response_format: ResponseFormatSchema,
+        })
+            .strict()
+            .superRefine((value, ctx) => {
+            if (!value.world && !value.dc_name) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "Provide either world or dc_name.",
+                });
+            }
+        }),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ world, dc_name, entries, response_format }) => {
+        const data = await clients.universalis.getMostRecentlyUpdated(world, dc_name, entries);
+        return buildToolResponse({
+            title: "Most Recently Updated Items",
+            responseFormat: response_format,
+            data,
+            meta: {
+                source: "universalis",
+                endpoint: "/extra/stats/most-recently-updated",
+                ...(world ? { world } : {}),
+                ...(dc_name ? { dc_name } : {}),
+                ...(entries ? { entries } : {}),
+            },
+        });
+    });
+    server.registerTool("universalis_get_least_recent_updates", {
+        title: "Least Recently Updated Items",
+        description: "Get the least recently updated items for a world or data center.",
+        inputSchema: StatsScopeBase.extend({
+            entries: EntriesSchema.optional(),
+            response_format: ResponseFormatSchema,
+        })
+            .strict()
+            .superRefine((value, ctx) => {
+            if (!value.world && !value.dc_name) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "Provide either world or dc_name.",
+                });
+            }
+        }),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ world, dc_name, entries, response_format }) => {
+        const data = await clients.universalis.getLeastRecentlyUpdated(world, dc_name, entries);
+        return buildToolResponse({
+            title: "Least Recently Updated Items",
+            responseFormat: response_format,
+            data,
+            meta: {
+                source: "universalis",
+                endpoint: "/extra/stats/least-recently-updated",
+                ...(world ? { world } : {}),
+                ...(dc_name ? { dc_name } : {}),
+                ...(entries ? { entries } : {}),
+            },
+        });
+    });
+    server.registerTool("universalis_get_recent_updates", {
+        title: "Recently Updated Items (Legacy)",
+        description: "Get a legacy list of recently updated items (no world/DC info).",
+        inputSchema: z
+            .object({
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ response_format }) => {
+        const data = await clients.universalis.getRecentlyUpdated();
+        return buildToolResponse({
+            title: "Recently Updated Items",
+            responseFormat: response_format,
+            data,
+            meta: { source: "universalis", endpoint: "/extra/stats/recently-updated" },
+        });
+    });
+    server.registerTool("universalis_get_upload_counts_by_source", {
+        title: "Upload Counts by Source",
+        description: "Return total upload counts for each client application.",
+        inputSchema: z
+            .object({
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ response_format }) => {
+        const data = await clients.universalis.getUploaderUploadCounts();
+        return buildToolResponse({
+            title: "Upload Counts by Source",
+            responseFormat: response_format,
+            data,
+            meta: { source: "universalis", endpoint: "/extra/stats/uploader-upload-counts" },
+        });
+    });
+    server.registerTool("universalis_get_upload_counts_by_world", {
+        title: "Upload Counts by World",
+        description: "Return upload counts and proportions for each world.",
+        inputSchema: z
+            .object({
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ response_format }) => {
+        const data = await clients.universalis.getWorldUploadCounts();
+        return buildToolResponse({
+            title: "Upload Counts by World",
+            responseFormat: response_format,
+            data,
+            meta: { source: "universalis", endpoint: "/extra/stats/world-upload-counts" },
+        });
+    });
+    server.registerTool("universalis_get_upload_history", {
+        title: "Upload History",
+        description: "Return the number of uploads per day over the past 30 days.",
+        inputSchema: z
+            .object({
+            response_format: ResponseFormatSchema,
+        })
+            .strict(),
+        outputSchema: BaseOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ response_format }) => {
+        const data = await clients.universalis.getUploadHistory();
+        return buildToolResponse({
+            title: "Upload History",
+            responseFormat: response_format,
+            data,
+            meta: { source: "universalis", endpoint: "/extra/stats/upload-history" },
+        });
+    });
+}

package/dist/utils/format.js

@@ -0,0 +1,38 @@
+import { CHARACTER_LIMIT } from "../constants.js";
+import { ResponseFormat } from "../schemas/common.js";
+export function buildToolResponse({ title, responseFormat, data, meta, summaryLines, }) {
+    let metaOut = meta ? { ...meta } : undefined;
+    let output = {
+        data,
+        ...(metaOut ? { meta: metaOut } : {}),
+    };
+    let text = renderText(responseFormat, title, summaryLines, output);
+    let textTruncated = false;
+    if (text.length > CHARACTER_LIMIT) {
+        textTruncated = true;
+        metaOut = { ...(metaOut ?? {}), text_truncated: true };
+        output = { data, meta: metaOut };
+        text = renderText(responseFormat, title, summaryLines, output);
+        if (text.length > CHARACTER_LIMIT) {
+            text = `${text.slice(0, CHARACTER_LIMIT - 120)}\n\n... truncated ...`;
+        }
+    }
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: {
+            data,
+            ...(metaOut ? { meta: metaOut } : {}),
+        },
+    };
+}
+function renderText(responseFormat, title, summaryLines, output) {
+    if (responseFormat === ResponseFormat.JSON) {
+        return JSON.stringify(output, null, 2);
+    }
+    const lines = [`# ${title}`];
+    if (summaryLines && summaryLines.length > 0) {
+        lines.push("", ...summaryLines.map((line) => `- ${line}`));
+    }
+    lines.push("", "```json", JSON.stringify(output, null, 2), "```");
+    return lines.join("\n");
+}

package/dist/utils/pagination.js

@@ -0,0 +1,16 @@
+export function paginateArray(items, offset, limit) {
+    const total = items.length;
+    const safeOffset = Math.max(0, Math.min(offset, total));
+    const safeLimit = Math.max(0, limit);
+    const end = Math.min(safeOffset + safeLimit, total);
+    const pageItems = items.slice(safeOffset, end);
+    const hasMore = end < total;
+    return {
+        total,
+        count: pageItems.length,
+        offset: safeOffset,
+        items: pageItems,
+        has_more: hasMore,
+        ...(hasMore ? { next_offset: end } : {}),
+    };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "universalis-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Universalis and XIVAPI",
+  "author": "Jakub Mucha <jakub.mucha@icloud.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drptbl/universalis-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/drptbl/universalis-mcp-server/issues"
+  },
+  "homepage": "https://github.com/drptbl/universalis-mcp-server#readme",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "universalis-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "universalis",
+    "ffxiv"
+  ],
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.25.2",
+    "bottleneck": "2.19.5",
+    "lru-cache": "11.2.4",
+    "zod": "4.3.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@types/node": "25.0.6",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 ./dist/index.js",
+    "lint": "biome check .",
+    "format": "biome format --write ."
+  }
+}