unofficial-ravensburger-playhub-mcp 1.0.0

package/dist/test/formatters.test.js

@@ -0,0 +1,230 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { formatStore, formatEvent, formatStandingEntry, formatRegistrationEntry, } from "../lib/formatters.js";
+describe("formatStore", () => {
+    it("formats minimal store with name and id", () => {
+        const gameStore = {
+            id: "gs1",
+            store: { id: 1, name: "Test Store" },
+            store_types: [],
+            store_types_pretty: [],
+        };
+        const out = formatStore(gameStore);
+        assert.ok(out.includes("**Test Store**"));
+        assert.ok(out.includes("Store ID: 1"));
+    });
+    it("includes address, phone, email, website when present", () => {
+        const gameStore = {
+            id: "gs1",
+            store: {
+                id: 1,
+                name: "Full Store",
+                full_address: "123 Main St",
+                phone_number: "555-1234",
+                email: "store@example.com",
+                website: "https://store.example.com",
+            },
+            store_types: [],
+            store_types_pretty: [],
+        };
+        const out = formatStore(gameStore);
+        assert.ok(out.includes("📍 123 Main St"));
+        assert.ok(out.includes("📞 555-1234"));
+        assert.ok(out.includes("📧 store@example.com"));
+        assert.ok(out.includes("🌐 https://store.example.com"));
+    });
+    it("includes store_types_pretty when present", () => {
+        const gameStore = {
+            id: "gs1",
+            store: { id: 1, name: "Store" },
+            store_types: ["flgs"],
+            store_types_pretty: ["Friendly Local Game Store"],
+        };
+        const out = formatStore(gameStore);
+        assert.ok(out.includes("🏷️ Types: Friendly Local Game Store"));
+    });
+    it("includes bio when present", () => {
+        const gameStore = {
+            id: "gs1",
+            store: { id: 1, name: "Store", bio: "We sell cards." },
+            store_types: [],
+            store_types_pretty: [],
+        };
+        const out = formatStore(gameStore);
+        assert.ok(out.includes("We sell cards."));
+    });
+    it("includes social links when present", () => {
+        const gameStore = {
+            id: "gs1",
+            store: {
+                id: 1,
+                name: "Store",
+                discord_url: "https://discord.gg/abc",
+                facebook_url: "https://facebook.com/store",
+                instagram_handle: "store",
+                twitter_handle: "store",
+            },
+            store_types: [],
+            store_types_pretty: [],
+        };
+        const out = formatStore(gameStore);
+        assert.ok(out.includes("Discord: https://discord.gg/abc"));
+        assert.ok(out.includes("Facebook: https://facebook.com/store"));
+        assert.ok(out.includes("Instagram: @store"));
+        assert.ok(out.includes("Twitter: @store"));
+    });
+});
+describe("formatEvent", () => {
+    it("formats minimal event with name and id", () => {
+        const event = {
+            id: 100,
+            name: "Weekly League",
+            start_datetime: "2025-02-01T18:00:00Z",
+        };
+        const out = formatEvent(event);
+        assert.ok(out.includes("**Weekly League**"));
+        assert.ok(out.includes("ID: 100"));
+        assert.ok(out.includes("📅"));
+    });
+    it("includes format, category, store, address when present", () => {
+        const event = {
+            id: 101,
+            name: "Event",
+            start_datetime: "2025-02-01T18:00:00Z",
+            gameplay_format: { id: "f1", name: "Constructed" },
+            event_configuration_template: "template-id",
+            store: { id: 1, name: "Game Store" },
+            full_address: "456 Oak Ave",
+        };
+        const out = formatEvent(event);
+        assert.ok(out.includes("🎮 Format: Constructed"));
+        assert.ok(out.includes("📁 Category:"));
+        assert.ok(out.includes("🏪 Store: Game Store"));
+        assert.ok(out.includes("📍 456 Oak Ave"));
+    });
+    it("includes distance when present", () => {
+        const event = {
+            id: 102,
+            name: "Event",
+            start_datetime: "2025-02-01T18:00:00Z",
+            distance_in_miles: 5.5,
+        };
+        const out = formatEvent(event);
+        assert.ok(out.includes("🚗 Distance: 5.5 miles"));
+    });
+    it("shows paid entry when cost_in_cents > 0", () => {
+        const event = {
+            id: 103,
+            name: "Event",
+            start_datetime: "2025-02-01T18:00:00Z",
+            cost_in_cents: 1500,
+            currency: "USD",
+        };
+        const out = formatEvent(event);
+        assert.ok(out.includes("💰 Entry: USD $15.00"));
+    });
+    it("shows free entry when cost_in_cents is 0", () => {
+        const event = {
+            id: 104,
+            name: "Event",
+            start_datetime: "2025-02-01T18:00:00Z",
+            cost_in_cents: 0,
+        };
+        const out = formatEvent(event);
+        assert.ok(out.includes("💰 Entry: Free"));
+    });
+    it("shows participants when capacity present", () => {
+        const event = {
+            id: 105,
+            name: "Event",
+            start_datetime: "2025-02-01T18:00:00Z",
+            capacity: 32,
+            registered_user_count: 20,
+        };
+        const out = formatEvent(event);
+        assert.ok(out.includes("👥 Participants: 20/32"));
+    });
+    it("shows registered count when no capacity", () => {
+        const event = {
+            id: 106,
+            name: "Event",
+            start_datetime: "2025-02-01T18:00:00Z",
+            registered_user_count: 8,
+        };
+        const out = formatEvent(event);
+        assert.ok(out.includes("👥 Registered: 8"));
+    });
+    it("includes display_status and settings when present", () => {
+        const event = {
+            id: 107,
+            name: "Event",
+            start_datetime: "2025-02-01T18:00:00Z",
+            display_status: "Upcoming",
+            settings: { event_lifecycle_status: "REGISTRATION_OPEN" },
+        };
+        const out = formatEvent(event);
+        assert.ok(out.includes("📊 Status: Upcoming"));
+        assert.ok(out.includes("🎟️ Registration: registration open"));
+    });
+    it("includes featured and online flags when true", () => {
+        const event = {
+            id: 108,
+            name: "Event",
+            start_datetime: "2025-02-01T18:00:00Z",
+            is_headlining_event: true,
+            event_is_online: true,
+        };
+        const out = formatEvent(event);
+        assert.ok(out.includes("⭐ Featured Event"));
+        assert.ok(out.includes("🌐 Online Event"));
+    });
+    it("includes description when present", () => {
+        const event = {
+            id: 109,
+            name: "Event",
+            start_datetime: "2025-02-01T18:00:00Z",
+            description: "Bring your deck!",
+        };
+        const out = formatEvent(event);
+        assert.ok(out.includes("Bring your deck!"));
+    });
+});
+describe("formatStandingEntry", () => {
+    it("falls back to username when player_name and display_name missing", () => {
+        const entry = { username: "player1" };
+        const out = formatStandingEntry(entry, 0);
+        assert.ok(out.includes("1. player1"));
+    });
+    it("uses em dash when no name fields", () => {
+        const entry = {};
+        const out = formatStandingEntry(entry, 0);
+        assert.ok(out.includes("1. —"));
+    });
+    it("shows record with only wins (losses 0)", () => {
+        const entry = { player_name: "A", wins: 3 };
+        const out = formatStandingEntry(entry, 0);
+        assert.ok(out.includes("Record: 3-0"));
+    });
+});
+describe("formatRegistrationEntry", () => {
+    it("falls back to em dash when no name available", () => {
+        const entry = {};
+        const out = formatRegistrationEntry(entry, 0);
+        assert.ok(out.includes("1. —"));
+    });
+    it("uses user.username when display_name missing", () => {
+        const entry = { user: { username: "u1" } };
+        const out = formatRegistrationEntry(entry, 0);
+        assert.ok(out.includes("1. u1"));
+    });
+    it("includes Registered line for invalid date string (Invalid Date or raw fallback)", () => {
+        const entry = {
+            display_name: "X",
+            registered_at: "not-a-date",
+        };
+        const out = formatRegistrationEntry(entry, 0);
+        assert.ok(out.includes("Registered:"), "should include Registered line");
+        // new Date("not-a-date") does not throw; toLocaleString() yields "Invalid Date" in most envs
+        assert.ok(out.includes("Invalid Date") || out.includes("not-a-date"), "should show Invalid Date or raw value");
+    });
+});

package/dist/test/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/test/mcp-tools.integration.test.js

@@ -0,0 +1,264 @@
+/**
+ * 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));
+// When run from dist/test/, go up to repo root
+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_capabilities – no args", async () => {
+        const { text, isError } = await callTool("list_capabilities", {});
+        assert.ok(!isError, `list_capabilities should not error: ${text}`);
+        assert.ok(text.includes("search_events"), "capabilities should mention search_events");
+        assert.ok(text.includes("search_events_by_city"), "capabilities should mention search_events_by_city");
+        assert.ok(text.includes("get_event_details") || text.includes("get_event"), "capabilities should mention event details");
+        assert.ok(text.includes("list_filters"), "capabilities should mention list_filters");
+    });
+    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("formats"), "list_filters should include formats");
+        assert.ok(text.includes("Categories") || text.includes("categories"), "list_filters should include categories");
+        assert.ok(text.includes("Example") || text.includes("formats"), "list_filters should include usage example or param names");
+    });
+    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("search_events – with text_search", async () => {
+        const { text, isError } = await callTool("search_events", {
+            latitude: 42.33,
+            longitude: -83.05,
+            radius_miles: 50,
+            text_search: "Lorcana",
+            page: 1,
+            page_size: 5,
+        });
+        assert.ok(!isError, `search_events (text_search) should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("search_events – with store_id", async () => {
+        const { text, isError } = await callTool("search_events", {
+            latitude: 42.33,
+            longitude: -83.05,
+            radius_miles: 100,
+            store_id: 1,
+            page: 1,
+            page_size: 5,
+        });
+        assert.ok(!isError, `search_events (store_id) should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("search_events – with start_date", async () => {
+        const { text, isError } = await callTool("search_events", {
+            latitude: 42.33,
+            longitude: -83.05,
+            start_date: "2025-01-01",
+            page: 1,
+            page_size: 5,
+        });
+        assert.ok(!isError, `search_events (start_date) 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_events_by_city – with page_size", async () => {
+        const { text, isError } = await callTool("search_events_by_city", {
+            city: "Detroit, MI",
+            radius_miles: 25,
+            page: 1,
+            page_size: 10,
+        });
+        assert.ok(!isError, `search_events_by_city (page_size) 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");
+    });
+    it("search_stores_by_city – with page_size", async () => {
+        const { text, isError } = await callTool("search_stores_by_city", {
+            city: "Detroit, MI",
+            radius_miles: 25,
+            page: 1,
+            page_size: 10,
+        });
+        assert.ok(!isError, `search_stores_by_city (page_size) should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+    it("search_events – with status past", async () => {
+        const { text, isError } = await callTool("search_events", {
+            latitude: 42.33,
+            longitude: -83.05,
+            radius_miles: 100,
+            statuses: ["past"],
+            page: 1,
+            page_size: 5,
+        });
+        assert.ok(!isError, `search_events (status past) should not error: ${text}`);
+        assert.ok(typeof text === "string", "should return text");
+    });
+});

package/dist/test/registrations.test.d.ts

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

package/dist/test/registrations.test.js

@@ -0,0 +1,37 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { formatRegistrationEntry } from "../lib/formatters.js";
+describe("formatRegistrationEntry", () => {
+    it("formats entry with display_name", () => {
+        const entry = { display_name: "Alice" };
+        const out = formatRegistrationEntry(entry, 0);
+        assert.ok(out.startsWith("1. Alice"));
+    });
+    it("falls back to username", () => {
+        const entry = { username: "bob123" };
+        const out = formatRegistrationEntry(entry, 1);
+        assert.ok(out.includes("2. bob123"));
+    });
+    it("uses user.display_name when present", () => {
+        const entry = { user: { display_name: "Charlie Z" } };
+        const out = formatRegistrationEntry(entry, 2);
+        assert.ok(out.includes("3. Charlie Z"));
+    });
+    it("uses user first_name and last_name when present", () => {
+        const entry = {
+            user: { first_name: "Dana", last_name: "Smith" },
+        };
+        const out = formatRegistrationEntry(entry, 3);
+        assert.ok(out.includes("4. Dana Smith"));
+    });
+    it("includes status and registered_at when present", () => {
+        const entry = {
+            display_name: "Eve",
+            status: "confirmed",
+            registered_at: "2025-01-15T10:00:00Z",
+        };
+        const out = formatRegistrationEntry(entry, 4);
+        assert.ok(out.includes("Status: confirmed"));
+        assert.ok(out.includes("Registered:"));
+    });
+});

package/dist/test/standings.test.d.ts

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

package/dist/test/standings.test.js

@@ -0,0 +1,43 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { formatStandingEntry } from "../lib/formatters.js";
+describe("formatStandingEntry", () => {
+    it("formats entry with rank and player_name", () => {
+        const entry = { rank: 1, player_name: "Alice" };
+        const out = formatStandingEntry(entry, 0);
+        assert.ok(out.startsWith("1. Alice"));
+    });
+    it("falls back to placement and display_name", () => {
+        const entry = { placement: 2, display_name: "Bob" };
+        const out = formatStandingEntry(entry, 1);
+        assert.ok(out.includes("2. Bob"));
+    });
+    it("uses index when rank/placement missing", () => {
+        const entry = { player_name: "Charlie" };
+        const out = formatStandingEntry(entry, 2);
+        assert.ok(out.startsWith("3. Charlie"));
+    });
+    it("includes record when wins/losses present", () => {
+        const entry = {
+            rank: 1,
+            player_name: "Dana",
+            wins: 3,
+            losses: 1,
+        };
+        const out = formatStandingEntry(entry, 0);
+        assert.ok(out.includes("Record: 3-1"));
+    });
+    it("includes match_points and percentages when present", () => {
+        const entry = {
+            rank: 1,
+            player_name: "Eve",
+            match_points: 9,
+            opponent_match_win_pct: 0.6,
+            game_win_pct: 0.75,
+        };
+        const out = formatStandingEntry(entry, 0);
+        assert.ok(out.includes("Match points: 9"));
+        assert.ok(out.includes("OMWP: 60.0%"));
+        assert.ok(out.includes("GWP: 75.0%"));
+    });
+});

package/dist/tools/events.d.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP tools for event search, details, registrations, and tournament standings.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerEventTools(server: McpServer): void;