unofficial-ravensburger-playhub-mcp 1.0.0

package/dist/tools/events.js

@@ -0,0 +1,326 @@
+/**
+ * MCP tools for event search, details, registrations, and tournament standings.
+ */
+import { z } from "zod";
+import { fetchEventDetails, fetchEventRegistrations, fetchEvents, fetchTournamentRoundStandings, resolveCategoryIds, resolveFormatIds, STATUSES, } from "../lib/api.js";
+import { formatEvent, formatRegistrationEntry, formatStandingEntry, } from "../lib/formatters.js";
+export function registerEventTools(server) {
+    // Tool: Search Events
+    server.registerTool("search_events", {
+        description: "Search for Disney Lorcana TCG events near a location by latitude/longitude. Use this when you have coordinates (e.g. from a map or device). For city names like 'Seattle' or 'Austin, TX', use search_events_by_city instead. Optional: call list_filters first to get format/category names for the formats and categories parameters.",
+        inputSchema: {
+            latitude: z.number().describe("Latitude of the search center (e.g. 42.33)"),
+            longitude: z.number().describe("Longitude of the search center (e.g. -83.05)"),
+            radius_miles: z.number().default(25).describe("Search radius in miles (default: 25)"),
+            start_date: z.string().optional().describe("Only show events starting after this date (YYYY-MM-DD)"),
+            formats: z.array(z.string()).optional().describe("Filter by format names; get exact names from list_filters (e.g. ['Constructed'])"),
+            categories: z.array(z.string()).optional().describe("Filter by category names; get exact names from list_filters"),
+            statuses: z.array(z.enum(STATUSES)).default(["upcoming", "inProgress"]).describe("Include: upcoming, inProgress (live), past"),
+            featured_only: z.boolean().default(false).describe("If true, only featured/headlining events"),
+            text_search: z.string().optional().describe("Search event names by keyword"),
+            store_id: z.number().optional().describe("Limit to events at this store (ID from search_stores)"),
+            page: z.number().default(1).describe("Page number (default: 1)"),
+            page_size: z.number().default(25).describe("Results per page, max 100 (default: 25)"),
+        },
+    }, async (args) => {
+        const params = {
+            game_slug: "disney-lorcana",
+            latitude: args.latitude.toString(),
+            longitude: args.longitude.toString(),
+            num_miles: args.radius_miles.toString(),
+            page: args.page.toString(),
+            page_size: Math.min(args.page_size, 100).toString(),
+        };
+        params.display_statuses = args.statuses;
+        if (args.start_date) {
+            params.start_date_after = new Date(args.start_date).toISOString();
+        }
+        else {
+            params.start_date_after = new Date().toISOString();
+        }
+        if (args.formats && args.formats.length > 0) {
+            const formatIds = resolveFormatIds(args.formats);
+            if (formatIds.length > 0) {
+                params.gameplay_format_id = formatIds;
+            }
+        }
+        if (args.categories && args.categories.length > 0) {
+            const categoryIds = resolveCategoryIds(args.categories);
+            if (categoryIds.length > 0) {
+                params.event_configuration_template_id = categoryIds;
+            }
+        }
+        if (args.featured_only) {
+            params.is_headlining_event = "true";
+        }
+        if (args.text_search) {
+            params.name = args.text_search;
+        }
+        if (args.store_id) {
+            params.store = args.store_id.toString();
+        }
+        try {
+            const response = await fetchEvents(params);
+            if (response.results.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No events found matching your criteria. Try expanding your search radius or adjusting filters.",
+                        },
+                    ],
+                };
+            }
+            const formattedEvents = response.results.map(formatEvent).join("\n\n---\n\n");
+            const summary = `Found ${response.count} event(s). Showing ${response.results.length} (page ${args.page} of ${Math.ceil(response.count / args.page_size)}).`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${summary}\n\n${formattedEvents}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error searching events: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool: Get Event Details
+    server.registerTool("get_event_details", {
+        description: "Get full details for one Disney Lorcana event by ID. Use after search_events or search_events_by_city when the user asks for more info about a specific event, or when you have an event ID (e.g. from a previous search).",
+        inputSchema: {
+            event_id: z.number().describe("Event ID (e.g. from search results)"),
+        },
+    }, async (args) => {
+        try {
+            const event = await fetchEventDetails(args.event_id);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatEvent(event),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching event details: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool: Get Tournament Round Standings
+    server.registerTool("get_tournament_round_standings", {
+        description: "Get standings (leaderboard) for a tournament round. Use when the user asks who is winning, standings, or results for a round. You need the round ID (sometimes in event context or from get_event_details).",
+        inputSchema: {
+            round_id: z.number().describe("Tournament round ID (e.g. 414976)"),
+            page: z.number().default(1).describe("Page number (default: 1)"),
+            page_size: z.number().default(25).describe("Results per page (default: 25)"),
+        },
+    }, async (args) => {
+        try {
+            const response = await fetchTournamentRoundStandings(args.round_id, args.page, args.page_size);
+            if (response.results.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No standings found for round ${args.round_id}. The round may not exist or may not have standings yet.`,
+                        },
+                    ],
+                };
+            }
+            const formatted = response.results.map((e, i) => formatStandingEntry(e, (args.page - 1) * args.page_size + i)).join("\n\n");
+            const summary = `Round ${args.round_id} standings: ${response.count} shown (page ${args.page} of ${Math.ceil(response.total / args.page_size)}). Total: ${response.total}.\n\n${formatted}`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: summary,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching round standings: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool: Get Event Registrations
+    server.registerTool("get_event_registrations", {
+        description: "Get the list of players registered for an event. Use when the user asks who is signed up, the registration list, or how many spots are taken. You need the event ID (from search_events, search_events_by_city, or get_event_details).",
+        inputSchema: {
+            event_id: z.number().describe("Event ID (e.g. from search or get_event_details)"),
+            page: z.number().default(1).describe("Page number (default: 1)"),
+            page_size: z.number().default(25).describe("Results per page (default: 25)"),
+        },
+    }, async (args) => {
+        try {
+            const response = await fetchEventRegistrations(args.event_id, args.page, args.page_size);
+            if (response.results.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No registrations found for event ${args.event_id}. The event may not exist or may not have registrations yet.`,
+                        },
+                    ],
+                };
+            }
+            const formatted = response.results
+                .map((e, i) => formatRegistrationEntry(e, (args.page - 1) * args.page_size + i))
+                .join("\n\n");
+            const summary = `Event ${args.event_id} registrations: ${response.count} shown (page ${args.page} of ${Math.ceil(response.total / args.page_size)}). Total: ${response.total}.\n\n${formatted}`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: summary,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching event registrations: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool: Search by City Name
+    server.registerTool("search_events_by_city", {
+        description: "Search for Disney Lorcana TCG events by city name (geocoded). Use this when the user says a city, e.g. 'events in Seattle' or 'Austin, TX'. For coordinates use search_events instead. Optional: call list_filters for format/category names.",
+        inputSchema: {
+            city: z.string().describe("City name, ideally with state/country (e.g. 'Detroit, MI' or 'New York, NY')"),
+            radius_miles: z.number().default(25).describe("Search radius in miles (default: 25)"),
+            start_date: z.string().optional().describe("Only events starting after this date (YYYY-MM-DD)"),
+            formats: z.array(z.string()).optional().describe("Filter by format names from list_filters (e.g. ['Constructed'])"),
+            categories: z.array(z.string()).optional().describe("Filter by category names from list_filters"),
+            statuses: z.array(z.enum(STATUSES)).default(["upcoming", "inProgress"]).describe("Include: upcoming, inProgress, past"),
+            featured_only: z.boolean().default(false).describe("If true, only featured events"),
+            text_search: z.string().optional().describe("Search event names by keyword"),
+            store_id: z.number().optional().describe("Limit to events at this store (ID from search_stores)"),
+            page: z.number().default(1).describe("Page number (default: 1)"),
+            page_size: z.number().default(25).describe("Results per page, max 100 (default: 25)"),
+        },
+    }, async (args) => {
+        const geocodeUrl = `https://nominatim.openstreetmap.org/search?q=${encodeURIComponent(args.city)}&format=json&limit=1`;
+        try {
+            const geoResponse = await fetch(geocodeUrl, {
+                headers: {
+                    "User-Agent": "lorcana-event-finder/1.0",
+                },
+            });
+            if (!geoResponse.ok) {
+                throw new Error("Geocoding failed");
+            }
+            const geoData = (await geoResponse.json());
+            if (!geoData || geoData.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Could not find location: ${args.city}. Try being more specific (e.g., "Detroit, MI, USA").`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const location = geoData[0];
+            const latitude = parseFloat(location.lat);
+            const longitude = parseFloat(location.lon);
+            const params = {
+                game_slug: "disney-lorcana",
+                latitude: latitude.toString(),
+                longitude: longitude.toString(),
+                num_miles: args.radius_miles.toString(),
+                display_statuses: args.statuses,
+                page: args.page.toString(),
+                page_size: Math.min(args.page_size, 100).toString(),
+                start_date_after: args.start_date
+                    ? new Date(args.start_date).toISOString()
+                    : new Date().toISOString(),
+            };
+            if (args.formats && args.formats.length > 0) {
+                const formatIds = resolveFormatIds(args.formats);
+                if (formatIds.length > 0) {
+                    params.gameplay_format_id = formatIds;
+                }
+            }
+            if (args.categories && args.categories.length > 0) {
+                const categoryIds = resolveCategoryIds(args.categories);
+                if (categoryIds.length > 0) {
+                    params.event_configuration_template_id = categoryIds;
+                }
+            }
+            if (args.featured_only) {
+                params.is_headlining_event = "true";
+            }
+            if (args.text_search) {
+                params.name = args.text_search;
+            }
+            if (args.store_id) {
+                params.store = args.store_id.toString();
+            }
+            const response = await fetchEvents(params);
+            if (response.results.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No events found near ${location.display_name} within ${args.radius_miles} miles. Try expanding your search radius or adjusting filters.`,
+                        },
+                    ],
+                };
+            }
+            const formattedEvents = response.results.map(formatEvent).join("\n\n---\n\n");
+            const summary = `Found ${response.count} event(s) near ${location.display_name}. Showing ${response.results.length} (page ${args.page} of ${Math.ceil(response.count / args.page_size)}).`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${summary}\n\n${formattedEvents}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/filters.d.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP tools for listing filters (formats, categories) and server capabilities (for LLM discovery).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFilterTools(server: McpServer): void;

package/dist/tools/filters.js

@@ -0,0 +1,87 @@
+/**
+ * MCP tools for listing filters (formats, categories) and server capabilities (for LLM discovery).
+ */
+import { fetchCategories, fetchGameplayFormats, updateFilterMaps } from "../lib/api.js";
+const CAPABILITIES_TEXT = `# Lorcana Event Finder – Tool Guide
+
+Use this to choose the right tool. All tools return plain text.
+
+| Tool | When to use |
+|------|-------------|
+| **list_filters** | User wants to filter events by format (e.g. Constructed) or category; call first to get exact names for \`formats\` / \`categories\` parameters. |
+| **search_events** | You have latitude and longitude (e.g. from a map or device). |
+| **search_events_by_city** | User says a city name, e.g. "events in Seattle" or "Austin, TX". |
+| **get_event_details** | User asks for more info about a specific event; you have an event ID (from search). |
+| **get_event_registrations** | User asks who is signed up or the registration list; you need event ID. |
+| **get_tournament_round_standings** | User asks who is winning or standings for a round; you need round ID. |
+| **search_stores** | User asks for stores, venues, or places to play; optional: name (\`search\`) and/or location (lat/long + \`radius_miles\`). |
+| **search_stores_by_city** | User says a city for stores, e.g. "stores in Seattle". |
+
+**Typical flow:** For "events near Seattle" → \`search_events_by_city\` with \`city: "Seattle, WA"\`. For "who's signed up for that event?" → \`get_event_registrations\` with the event ID from the previous search.
+`;
+export function registerFilterTools(server) {
+    // Tool: List Capabilities (for LLM discovery)
+    server.registerTool("list_capabilities", {
+        description: "List all tools and when to use each. Call this first if you are unsure which tool to use (e.g. search_events vs search_events_by_city, or how to get event IDs).",
+        inputSchema: {},
+    }, async () => ({
+        content: [{ type: "text", text: CAPABILITIES_TEXT }],
+    }));
+    // Tool: List Available Filters
+    server.registerTool("list_filters", {
+        description: "List format and category names you can use when searching events. Call before search_events or search_events_by_city if the user wants to filter by format (e.g. Constructed) or category. Use the exact names shown in the formats and categories array parameters.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const [formats, categories] = await Promise.all([
+                fetchGameplayFormats(),
+                fetchCategories(),
+            ]);
+            updateFilterMaps(formats, categories);
+            const formatList = formats.map((f) => `- ${f.name}${f.description ? ` - ${f.description}` : ""}`).join("\n");
+            const categoryList = categories.map((c) => `- ${c.name}`).join("\n");
+            const filterInfo = `# Event Search Filters (use exact names in parameters)
+
+## Formats (use in \`formats\` array)
+${formatList}
+
+## Categories (use in \`categories\` array)
+${categoryList}
+
+## Statuses (use in \`statuses\` array)
+- upcoming - Not started yet
+- inProgress - Live now
+- past - Completed
+
+## Example
+To filter by format and category in search_events or search_events_by_city, pass arrays of the exact names above, e.g. \`formats: ["Constructed"]\`, \`categories: ["League"]\`.
+
+## Other optional parameters
+- featured_only (boolean): Only featured events
+- text_search (string): Search event names
+- store_id (number): Limit to one store (IDs from search_stores)
+- radius_miles (number): Search radius, default 25
+- start_date (string): YYYY-MM-DD, events starting after this date
+`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: filterInfo,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching filter options: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/stores.d.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP tools for store search (by name, location, or city).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerStoreTools(server: McpServer): void;

package/dist/tools/stores.js

@@ -0,0 +1,142 @@
+/**
+ * MCP tools for store search (by name, location, or city).
+ */
+import { z } from "zod";
+import { fetchStores } from "../lib/api.js";
+import { formatStore } from "../lib/formatters.js";
+export function registerStoreTools(server) {
+    // Tool: Search Stores
+    server.registerTool("search_stores", {
+        description: "Search for game stores that host Disney Lorcana events. Use when the user asks for stores, venues, or places to play. Pass search (name) and/or latitude+longitude+radius_miles; you can pass both. No location = first page of all stores.",
+        inputSchema: {
+            search: z.string().optional().describe("Search by store name (e.g. 'game' or store name)"),
+            latitude: z.number().optional().describe("Latitude for location search (use with longitude and radius_miles)"),
+            longitude: z.number().optional().describe("Longitude for location search (use with latitude and radius_miles)"),
+            radius_miles: z.number().default(25).describe("Radius in miles when using lat/long (default: 25)"),
+            page: z.number().default(1).describe("Page number (default: 1)"),
+            page_size: z.number().default(25).describe("Results per page, max 100 (default: 25)"),
+        },
+    }, async (args) => {
+        const params = {
+            page: args.page.toString(),
+            page_size: Math.min(args.page_size, 100).toString(),
+        };
+        if (args.search) {
+            params.search = args.search;
+        }
+        if (args.latitude !== undefined && args.longitude !== undefined) {
+            params.latitude = args.latitude.toString();
+            params.longitude = args.longitude.toString();
+            params.num_miles = args.radius_miles.toString();
+        }
+        try {
+            const response = await fetchStores(params);
+            if (response.results.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No stores found matching your criteria. Try a different search term or location.",
+                        },
+                    ],
+                };
+            }
+            const formattedStores = response.results.map(formatStore).join("\n\n---\n\n");
+            const summary = `Found ${response.count} store(s). Showing ${response.results.length} (page ${args.page}).`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${summary}\n\n${formattedStores}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error searching stores: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool: Search Stores by City
+    server.registerTool("search_stores_by_city", {
+        description: "Search for game stores that host Disney Lorcana events by city name (geocoded). Use when the user says a city, e.g. 'stores in Seattle' or 'where to play in Austin'. For coordinates use search_stores with latitude/longitude.",
+        inputSchema: {
+            city: z.string().describe("City name, ideally with state/country (e.g. 'Detroit, MI' or 'New York, NY')"),
+            radius_miles: z.number().default(25).describe("Radius in miles (default: 25)"),
+            page: z.number().default(1).describe("Page number (default: 1)"),
+            page_size: z.number().default(25).describe("Results per page, max 100 (default: 25)"),
+        },
+    }, async (args) => {
+        const geocodeUrl = `https://nominatim.openstreetmap.org/search?q=${encodeURIComponent(args.city)}&format=json&limit=1`;
+        try {
+            const geoResponse = await fetch(geocodeUrl, {
+                headers: { "User-Agent": "lorcana-event-finder/1.0" },
+            });
+            if (!geoResponse.ok) {
+                throw new Error("Geocoding failed");
+            }
+            const geoData = (await geoResponse.json());
+            if (!geoData || geoData.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Could not find location: ${args.city}. Try being more specific (e.g., "Detroit, MI, USA").`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const location = geoData[0];
+            const latitude = parseFloat(location.lat);
+            const longitude = parseFloat(location.lon);
+            const params = {
+                latitude: latitude.toString(),
+                longitude: longitude.toString(),
+                num_miles: args.radius_miles.toString(),
+                page: args.page.toString(),
+                page_size: Math.min(args.page_size, 100).toString(),
+            };
+            const response = await fetchStores(params);
+            if (response.results.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No stores found near ${location.display_name} within ${args.radius_miles} miles.`,
+                        },
+                    ],
+                };
+            }
+            const formattedStores = response.results.map(formatStore).join("\n\n---\n\n");
+            const totalPages = Math.ceil(response.count / args.page_size);
+            const summary = `Found ${response.count} store(s) near ${location.display_name}. Showing ${response.results.length} (page ${args.page} of ${totalPages}).`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${summary}\n\n${formattedStores}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "unofficial-ravensburger-playhub-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for finding Disney Lorcana TCG events",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "unofficial-ravensburger-playhub-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "node --test dist",
+    "test:coverage": "c8 --exclude='**/test/**' --reporter=text --reporter=lcov node --test dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "lorcana",
+    "tcg",
+    "events"
+  ],
+  "author": "",
+  "license": "Unlicense",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zammitt/unofficial-ravensburger-playhub-mcp.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "c8": "^10.1.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}