unofficial-ravensburger-playhub-mcp 1.0.0

package/dist/lib/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Shared types for the Lorcana Event Finder MCP server (API responses and domain models).
+ */
+export interface GameplayFormat {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface EventCategory {
+    id: string;
+    name: string;
+}
+export interface Store {
+    id: number;
+    name: string;
+    full_address?: string;
+    city?: string | null;
+    state?: string | null;
+    country?: string;
+    latitude?: number;
+    longitude?: number;
+    website?: string;
+    email?: string;
+    phone_number?: string;
+    street_address?: string;
+    zipcode?: string;
+    bio?: string | null;
+    discord_url?: string;
+    facebook_url?: string;
+    twitter_handle?: string;
+    instagram_handle?: string;
+}
+export interface GameStore {
+    id: string;
+    store: Store;
+    store_types: string[];
+    store_types_pretty: string[];
+}
+export interface StoresResponse {
+    count: number;
+    total: number;
+    page_size: number;
+    current_page_number: number;
+    next_page_number: number | null;
+    previous_page_number: number | null;
+    results: GameStore[];
+}
+export interface Event {
+    id: number;
+    name: string;
+    description?: string;
+    start_datetime: string;
+    end_datetime?: string | null;
+    full_address?: string;
+    latitude?: number;
+    longitude?: number;
+    gameplay_format?: GameplayFormat | null;
+    event_configuration_template?: string;
+    event_format?: string;
+    event_type?: string;
+    cost_in_cents?: number;
+    currency?: string;
+    capacity?: number;
+    registered_user_count?: number;
+    starting_player_count?: number;
+    display_status?: string;
+    is_headlining_event?: boolean;
+    event_is_online?: boolean;
+    distance_in_miles?: number;
+    store?: Store;
+    url?: string | null;
+    settings?: {
+        event_lifecycle_status?: string;
+    };
+}
+export interface EventsResponse {
+    count: number;
+    total: number;
+    page_size: number;
+    current_page_number: number;
+    next_page_number: number | null;
+    previous_page_number: number | null;
+    results: Event[];
+}
+/** Tournament round standings (paginated). */
+export interface StandingEntry {
+    rank?: number;
+    placement?: number;
+    player_name?: string;
+    username?: string;
+    display_name?: string;
+    wins?: number;
+    losses?: number;
+    match_points?: number;
+    opponent_match_win_pct?: number;
+    game_win_pct?: number;
+    [key: string]: unknown;
+}
+export interface StandingsResponse {
+    count: number;
+    total: number;
+    page_size: number;
+    current_page_number: number;
+    next_page_number: number | null;
+    previous_page_number: number | null;
+    results: StandingEntry[];
+}
+/** Event registrations (paginated). */
+export interface RegistrationEntry {
+    id?: number;
+    user?: {
+        username?: string;
+        display_name?: string;
+        first_name?: string;
+        last_name?: string;
+        [key: string]: unknown;
+    };
+    display_name?: string;
+    username?: string;
+    status?: string;
+    registered_at?: string;
+    [key: string]: unknown;
+}
+export interface RegistrationsResponse {
+    count: number;
+    total: number;
+    page_size: number;
+    current_page_number: number;
+    next_page_number: number | null;
+    previous_page_number: number | null;
+    results: RegistrationEntry[];
+}

package/dist/lib/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types for the Lorcana Event Finder MCP server (API responses and domain models).
+ */
+export {};

package/dist/mcp-tools.integration.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Integration tests: spawn the Lorcana Event Finder MCP server and run each tool
+ * with one or more call variations to ensure the server and all tools work end-to-end.
+ *
+ * Run after build: npm run build && npm test
+ * Requires network (Ravensburger API, Nominatim geocoding).
+ */
+export {};

package/dist/mcp-tools.integration.test.js

@@ -0,0 +1,186 @@
+/**
+ * Integration tests: spawn the Lorcana Event Finder MCP server and run each tool
+ * with one or more call variations to ensure the server and all tools work end-to-end.
+ *
+ * Run after build: npm run build && npm test
+ * Requires network (Ravensburger API, Nominatim geocoding).
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client";
+// StdioClientTransport is not re-exported from the client entry; load from SDK dist.
+import { StdioClientTransport } from "../node_modules/@modelcontextprotocol/sdk/dist/esm/client/stdio.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, "..");
+const EXPECTED_TOOL_NAMES = [
+    "list_capabilities",
+    "list_filters",
+    "search_events",
+    "get_event_details",
+    "get_tournament_round_standings",
+    "get_event_registrations",
+    "search_events_by_city",
+    "search_stores",
+    "search_stores_by_city",
+];
+describe("MCP server integration – all tools and call variations", { timeout: 60_000 }, () => {
+    let client;
+    let transport;
+    before(async () => {
+        transport = new StdioClientTransport({
+            command: "node",
+            args: [resolve(projectRoot, "dist/index.js")],
+            cwd: projectRoot,
+            stderr: "pipe",
+        });
+        client = new Client({ name: "mcp-tools-integration-test", version: "1.0.0" }, { capabilities: {} });
+        await client.connect(transport);
+    });
+    after(async () => {
+        await transport.close();
+    });
+    it("lists all expected tools", async () => {
+        const { tools } = await client.listTools();
+        const names = tools.map((t) => t.name).sort();
+        const expected = [...EXPECTED_TOOL_NAMES].sort();
+        assert.deepStrictEqual(names, expected, `Expected tools ${expected.join(", ")}; got ${names.join(", ")}`);
+    });
+    async function callTool(name, args) {
+        const result = await client.callTool({ name, arguments: args });
+        assert.ok(result, "callTool should return a result");
+        if ("content" in result && Array.isArray(result.content)) {
+            const textPart = result.content.find((c) => c.type === "text" && "text" in c);
+            return {
+                content: result.content,
+                text: textPart && "text" in textPart ? textPart.text : "",
+                isError: "isError" in result ? !!result.isError : false,
+            };
+        }
+        return { content: result, text: "", isError: false };
+    }
+    it("list_filters – no args", async () => {
+        const { text, isError } = await callTool("list_filters", {});
+        assert.ok(!isError, `list_filters should not error: ${text}`);
+        assert.ok(text.includes("Formats") || text.includes("Categories") || text.includes("filters"), `Expected filter info in: ${text.slice(0, 200)}`);
+    });
+    it("search_events – required only", async () => {
+        const { text, isError } = await callTool("search_events", {
+            latitude: 42.33,
+            longitude: -83.05,
+        });
+        assert.ok(!isError, `search_events should not error: ${text}`);
+        assert.ok(typeof text === "string" && text.length > 0, "should return non-empty text");
+    });
+    it("search_events – with optional params", async () => {
+        const { text, isError } = await callTool("search_events", {
+            latitude: 42.33,
+            longitude: -83.05,
+            radius_miles: 10,
+            page: 1,
+            page_size: 5,
+            statuses: ["upcoming", "inProgress"],
+            featured_only: false,
+        });
+        assert.ok(!isError, `search_events (optional) should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("get_event_details – valid-looking id", async () => {
+        const { text, isError } = await callTool("get_event_details", { event_id: 1 });
+        // API may return 404 for id=1; server still returns content (possibly error message)
+        assert.ok(typeof text === "string" && text.length > 0, "should return some content");
+    });
+    it("get_tournament_round_standings – required only", async () => {
+        const { text, isError } = await callTool("get_tournament_round_standings", {
+            round_id: 414976,
+        });
+        assert.ok(!isError, `get_tournament_round_standings should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("get_tournament_round_standings – with pagination", async () => {
+        const { text, isError } = await callTool("get_tournament_round_standings", {
+            round_id: 414976,
+            page: 1,
+            page_size: 10,
+        });
+        assert.ok(!isError, `get_tournament_round_standings (pagination) should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("get_event_registrations – required only", async () => {
+        const { text, isError } = await callTool("get_event_registrations", {
+            event_id: 333450,
+        });
+        assert.ok(!isError, `get_event_registrations should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("get_event_registrations – with pagination", async () => {
+        const { text, isError } = await callTool("get_event_registrations", {
+            event_id: 333450,
+            page: 1,
+            page_size: 10,
+        });
+        assert.ok(!isError, `get_event_registrations (pagination) should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("search_events_by_city – required only", async () => {
+        const { text, isError } = await callTool("search_events_by_city", {
+            city: "Detroit, MI",
+        });
+        assert.ok(!isError, `search_events_by_city should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("search_events_by_city – with optional params", async () => {
+        const { text, isError } = await callTool("search_events_by_city", {
+            city: "New York, NY",
+            radius_miles: 15,
+            page: 1,
+        });
+        assert.ok(!isError, `search_events_by_city (optional) should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("search_stores – no args (list first page)", async () => {
+        const { text, isError } = await callTool("search_stores", {
+            page: 1,
+            page_size: 5,
+        });
+        assert.ok(!isError, `search_stores should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("search_stores – by name", async () => {
+        const { text, isError } = await callTool("search_stores", {
+            search: "game",
+            page: 1,
+            page_size: 5,
+        });
+        assert.ok(!isError, `search_stores (search) should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("search_stores – by location", async () => {
+        const { text, isError } = await callTool("search_stores", {
+            latitude: 42.33,
+            longitude: -83.05,
+            radius_miles: 10,
+            page: 1,
+            page_size: 5,
+        });
+        assert.ok(!isError, `search_stores (location) should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("search_stores_by_city – required only", async () => {
+        const { text, isError } = await callTool("search_stores_by_city", {
+            city: "Detroit, MI",
+        });
+        assert.ok(!isError, `search_stores_by_city should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("search_stores_by_city – with optional params", async () => {
+        const { text, isError } = await callTool("search_stores_by_city", {
+            city: "Chicago, IL",
+            radius_miles: 20,
+            page: 1,
+        });
+        assert.ok(!isError, `search_stores_by_city (optional) should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+});

package/dist/test/api.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/api.test.js

@@ -0,0 +1,209 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import { loadFilterOptions, updateFilterMaps, resolveFormatIds, resolveCategoryIds, getCategoryName, fetchGameplayFormats, fetchCategories, fetchEvents, fetchEventDetails, fetchEventRegistrations, fetchTournamentRoundStandings, fetchStores, } from "../lib/api.js";
+const sampleFormats = [
+    { id: "fmt-1", name: "Constructed" },
+    { id: "fmt-2", name: "Draft" },
+];
+const sampleCategories = [
+    { id: "cat-1", name: "League" },
+    { id: "cat-2", name: "Tournament" },
+];
+describe("api – filter maps and resolution", () => {
+    beforeEach(() => {
+        updateFilterMaps(sampleFormats, sampleCategories);
+    });
+    it("updateFilterMaps sets format and category maps", () => {
+        const formatIds = resolveFormatIds(["Constructed", "Draft"]);
+        assert.deepStrictEqual(formatIds, ["fmt-1", "fmt-2"]);
+        const categoryIds = resolveCategoryIds(["League", "Tournament"]);
+        assert.deepStrictEqual(categoryIds, ["cat-1", "cat-2"]);
+    });
+    it("resolveFormatIds returns only known names and skips unknown", () => {
+        const stub = () => { };
+        const orig = console.error;
+        console.error = stub;
+        try {
+            const ids = resolveFormatIds(["Constructed", "UnknownFormat", "Draft"]);
+            assert.deepStrictEqual(ids, ["fmt-1", "fmt-2"]);
+        }
+        finally {
+            console.error = orig;
+        }
+    });
+    it("resolveFormatIds returns empty for empty input", () => {
+        assert.deepStrictEqual(resolveFormatIds([]), []);
+    });
+    it("resolveCategoryIds returns only known names and skips unknown", () => {
+        const stub = () => { };
+        const orig = console.error;
+        console.error = stub;
+        try {
+            const ids = resolveCategoryIds(["League", "UnknownCat", "Tournament"]);
+            assert.deepStrictEqual(ids, ["cat-1", "cat-2"]);
+        }
+        finally {
+            console.error = orig;
+        }
+    });
+    it("resolveCategoryIds returns empty for empty input", () => {
+        assert.deepStrictEqual(resolveCategoryIds([]), []);
+    });
+    it("getCategoryName returns name for known template id", () => {
+        assert.strictEqual(getCategoryName("cat-1"), "League");
+        assert.strictEqual(getCategoryName("cat-2"), "Tournament");
+    });
+    it("getCategoryName returns templateId when not in map", () => {
+        assert.strictEqual(getCategoryName("unknown-id"), "unknown-id");
+    });
+});
+describe("api – fetch with mocked global fetch", () => {
+    let originalFetch;
+    beforeEach(() => {
+        originalFetch = globalThis.fetch;
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    it("fetchGameplayFormats returns json on ok response", async () => {
+        const data = [{ id: "1", name: "Constructed" }];
+        globalThis.fetch = async (_input) => new Response(JSON.stringify(data), { status: 200 });
+        const result = await fetchGameplayFormats();
+        assert.deepStrictEqual(result, data);
+    });
+    it("fetchGameplayFormats throws on non-ok response", async () => {
+        globalThis.fetch = async (_input) => new Response("error", { status: 500 });
+        await assert.rejects(fetchGameplayFormats, /Failed to fetch formats/);
+    });
+    it("fetchCategories returns json on ok response", async () => {
+        const data = [{ id: "1", name: "League" }];
+        globalThis.fetch = async (_input) => new Response(JSON.stringify(data), { status: 200 });
+        const result = await fetchCategories();
+        assert.deepStrictEqual(result, data);
+    });
+    it("fetchCategories throws on non-ok response", async () => {
+        globalThis.fetch = async (_input) => new Response("error", { status: 500 });
+        await assert.rejects(fetchCategories, /Failed to fetch categories/);
+    });
+    it("fetchEvents builds url with params and returns json", async () => {
+        const data = { count: 0, total: 0, results: [], page_size: 25, current_page_number: 1, next_page_number: null, previous_page_number: null };
+        globalThis.fetch = async (input) => {
+            const u = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+            assert.ok(u.includes("game_slug"));
+            return new Response(JSON.stringify(data), { status: 200 });
+        };
+        const result = await fetchEvents({ game_slug: "disney-lorcana", latitude: "42", longitude: "-83" });
+        assert.strictEqual(result.count, 0);
+        assert.deepStrictEqual(result.results, []);
+    });
+    it("fetchEvents appends array params as multiple query params", async () => {
+        const data = { count: 0, total: 0, results: [], page_size: 25, current_page_number: 1, next_page_number: null, previous_page_number: null };
+        let capturedUrl = "";
+        globalThis.fetch = async (input) => {
+            capturedUrl = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+            return new Response(JSON.stringify(data), { status: 200 });
+        };
+        await fetchEvents({ display_statuses: ["upcoming", "inProgress"] });
+        assert.ok(capturedUrl.includes("display_statuses=upcoming"));
+        assert.ok(capturedUrl.includes("display_statuses=inProgress"));
+    });
+    it("fetchEvents throws with response text on non-ok", async () => {
+        globalThis.fetch = async (_input) => new Response("API error body", { status: 400 });
+        await assert.rejects(() => fetchEvents({ game_slug: "x" }), /API request failed.*API error body/);
+    });
+    it("fetchEventDetails returns event on ok", async () => {
+        const event = { id: 1, name: "Test Event", start_datetime: "2025-01-01T12:00:00Z" };
+        globalThis.fetch = async (_input) => new Response(JSON.stringify(event), { status: 200 });
+        const result = await fetchEventDetails(1);
+        assert.strictEqual(result.id, 1);
+        assert.strictEqual(result.name, "Test Event");
+    });
+    it("fetchEventDetails throws on non-ok", async () => {
+        globalThis.fetch = async (_input) => new Response("Not found", { status: 404 });
+        await assert.rejects(() => fetchEventDetails(999), /API request failed/);
+    });
+    it("fetchEventRegistrations builds url with page and page_size", async () => {
+        const data = { count: 0, total: 0, results: [], page_size: 10, current_page_number: 2, next_page_number: null, previous_page_number: null };
+        let capturedUrl = "";
+        globalThis.fetch = async (input) => {
+            capturedUrl = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+            return new Response(JSON.stringify(data), { status: 200 });
+        };
+        await fetchEventRegistrations(1, 2, 10);
+        assert.ok(capturedUrl.includes("page=2"));
+        assert.ok(capturedUrl.includes("page_size=10"));
+    });
+    it("fetchEventRegistrations throws on non-ok", async () => {
+        globalThis.fetch = async (_input) => new Response("error", { status: 500 });
+        await assert.rejects(() => fetchEventRegistrations(1), /API request failed/);
+    });
+    it("fetchTournamentRoundStandings returns json on ok", async () => {
+        const data = { count: 0, total: 0, results: [], page_size: 25, current_page_number: 1, next_page_number: null, previous_page_number: null };
+        globalThis.fetch = async (_input) => new Response(JSON.stringify(data), { status: 200 });
+        const result = await fetchTournamentRoundStandings(100, 1, 25);
+        assert.strictEqual(result.count, 0);
+    });
+    it("fetchTournamentRoundStandings throws on non-ok", async () => {
+        globalThis.fetch = async (_input) => new Response("error", { status: 500 });
+        await assert.rejects(() => fetchTournamentRoundStandings(100), /API request failed/);
+    });
+    it("fetchStores builds url with game_id and params", async () => {
+        const data = { count: 0, total: 0, results: [], page_size: 25, current_page_number: 1, next_page_number: null, previous_page_number: null };
+        let capturedUrl = "";
+        globalThis.fetch = async (input) => {
+            capturedUrl = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+            return new Response(JSON.stringify(data), { status: 200 });
+        };
+        await fetchStores({ search: "game" });
+        assert.ok(capturedUrl.includes("game_id=1"));
+        assert.ok(capturedUrl.includes("search=game"));
+    });
+    it("fetchStores skips empty string params", async () => {
+        const data = { count: 0, total: 0, results: [], page_size: 25, current_page_number: 1, next_page_number: null, previous_page_number: null };
+        let capturedUrl = "";
+        globalThis.fetch = async (input) => {
+            capturedUrl = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+            return new Response(JSON.stringify(data), { status: 200 });
+        };
+        await fetchStores({ search: "", other: "value" });
+        assert.ok(!capturedUrl.includes("search="));
+        assert.ok(capturedUrl.includes("other=value"));
+    });
+    it("fetchStores throws on non-ok", async () => {
+        globalThis.fetch = async (_input) => new Response("error", { status: 500 });
+        await assert.rejects(() => fetchStores({}), /API request failed/);
+    });
+});
+describe("api – loadFilterOptions", () => {
+    let originalFetch;
+    let originalConsoleError;
+    beforeEach(() => {
+        originalFetch = globalThis.fetch;
+        originalConsoleError = console.error;
+        console.error = () => { }; // suppress expected "Loaded..." / "Failed to load..." messages
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        console.error = originalConsoleError;
+    });
+    it("loads formats and categories and updates maps on success", async () => {
+        const formats = [{ id: "lf1", name: "Constructed" }];
+        const categories = [{ id: "lc1", name: "League" }];
+        globalThis.fetch = async (input) => {
+            const u = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+            if (u.includes("gameplay-formats"))
+                return new Response(JSON.stringify(formats), { status: 200 });
+            if (u.includes("event-configuration-templates"))
+                return new Response(JSON.stringify(categories), { status: 200 });
+            return new Response("", { status: 404 });
+        };
+        await loadFilterOptions();
+        assert.deepStrictEqual(resolveFormatIds(["Constructed"]), ["lf1"]);
+        assert.deepStrictEqual(resolveCategoryIds(["League"]), ["lc1"]);
+        assert.strictEqual(getCategoryName("lc1"), "League");
+    });
+    it("does not throw when fetch fails (logs warning)", async () => {
+        globalThis.fetch = async (_input) => new Response("error", { status: 500 });
+        await assert.doesNotReject(loadFilterOptions());
+    });
+});

package/dist/test/formatters.test.d.ts

@@ -0,0 +1 @@
+export {};