@unclick/bgg-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+Apache License 2.0
+
+Copyright (c) 2026 UnClick / malamutemayhem
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,37 @@
+# BoardGameGeek MCP by UnClick
+
+BoardGameGeek search, game details, rankings, and collections.
+
+> By UnClick. 180+ tools plus persistent agent memory in one install: https://unclick.world
+
+## Install
+
+Installs straight from GitHub, no npm account needed.
+
+```json
+{
+  "mcpServers": {
+    "bgg": {
+      "command": "npx",
+      "args": ["-y", "https://github.com/malamutemayhem/unclick/releases/download/standalone-mcps-latest/bgg.tgz"]
+    }
+  }
+}
+```
+
+## Tools
+
+- `bgg_search`
+- `bgg_game_details`
+- `bgg_user_collection`
+- `bgg_top_games`
+- `bgg_game_reviews`
+
+## Want the rest?
+
+This is one connector. [UnClick](https://unclick.world) bundles 180+ tools plus
+persistent cross-session agent memory in a single install.
+
+## License
+
+Apache-2.0

package/dist/bgg-tool.js

@@ -0,0 +1,249 @@
+// BoardGameGeek XML API2 integration.
+// Docs: https://boardgamegeek.com/wiki/page/BGG_XML_API2
+// No authentication required.
+// Base URL: https://boardgamegeek.com/xmlapi2
+import { XMLParser } from "fast-xml-parser";
+const BGG_BASE = "https://boardgamegeek.com/xmlapi2";
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+});
+// ─── helpers ──────────────────────────────────────────────────────────────────
+async function bggFetch(path) {
+    const res = await fetch(`${BGG_BASE}${path}`, {
+        headers: { "User-Agent": "UnClickMCP/1.0 (https://unclick.io)" },
+    });
+    if (!res.ok)
+        throw new Error(`BGG API HTTP ${res.status}`);
+    const xml = await res.text();
+    return parser.parse(xml);
+}
+/** BGG collection endpoints return 202 while the data is being prepared. Retry. */
+async function bggFetchWithRetry(path, maxRetries = 5, delayMs = 2000) {
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        const res = await fetch(`${BGG_BASE}${path}`, {
+            headers: { "User-Agent": "UnClickMCP/1.0 (https://unclick.io)" },
+        });
+        if (res.status === 202) {
+            if (attempt < maxRetries - 1) {
+                await new Promise((r) => setTimeout(r, delayMs));
+                continue;
+            }
+            throw new Error("BGG collection is still being prepared. Please try again in a few seconds.");
+        }
+        if (!res.ok)
+            throw new Error(`BGG API HTTP ${res.status}`);
+        const xml = await res.text();
+        return parser.parse(xml);
+    }
+    throw new Error("BGG collection request timed out after retries.");
+}
+function attr(obj, key) {
+    if (obj && typeof obj === "object") {
+        return String(obj[`@_${key}`] ?? "");
+    }
+    return "";
+}
+function val(obj) {
+    return attr(obj, "value");
+}
+function primaryName(names) {
+    if (!Array.isArray(names)) {
+        return val(names);
+    }
+    const primary = names.find((n) => attr(n, "type") === "primary");
+    return val(primary ?? names[0]);
+}
+// ─── bgg_search ───────────────────────────────────────────────────────────────
+// GET /search?query=<name>&type=boardgame[,boardgameexpansion]
+export async function bggSearch(args) {
+    const query = String(args.query ?? "").trim();
+    if (!query)
+        return { error: "query is required." };
+    const type = String(args.type ?? "boardgame").trim();
+    const allowed = ["boardgame", "boardgameexpansion"];
+    const safeType = allowed.includes(type) ? type : "boardgame";
+    const data = await bggFetch(`/search?query=${encodeURIComponent(query)}&type=${encodeURIComponent(safeType)}`);
+    const root = (data.items ?? {});
+    const items = root.item ?? [];
+    return {
+        total: Number(attr(root, "total") ?? items.length),
+        results: items.slice(0, 20).map((item) => ({
+            id: attr(item, "id"),
+            type: attr(item, "type"),
+            name: primaryName(item.name),
+            year_published: val(item.yearpublished) || null,
+        })),
+    };
+}
+// ─── bgg_game_details ─────────────────────────────────────────────────────────
+// GET /thing?id=<id>&stats=1
+export async function bggGameDetails(args) {
+    const gameId = String(args.gameId ?? "").trim();
+    if (!gameId)
+        return { error: "gameId is required." };
+    const data = await bggFetch(`/thing?id=${encodeURIComponent(gameId)}&stats=1`);
+    const root = (data.items ?? {});
+    const items = root.item ?? [];
+    const item = items[0];
+    if (!item)
+        return { error: `No game found with id ${gameId}` };
+    const stats = item.statistics ?? {};
+    const ratings = stats.ratings ?? {};
+    const links = (item.link ?? []);
+    const categories = links
+        .filter((l) => attr(l, "type") === "boardgamecategory")
+        .map((l) => val(l));
+    const mechanics = links
+        .filter((l) => attr(l, "type") === "boardgamemechanic")
+        .map((l) => val(l));
+    const designers = links
+        .filter((l) => attr(l, "type") === "boardgamedesigner")
+        .map((l) => val(l));
+    const publishers = links
+        .filter((l) => attr(l, "type") === "boardgamepublisher")
+        .map((l) => val(l));
+    // Strip HTML tags from description
+    const rawDesc = String(item.description ?? "");
+    const description = rawDesc.replace(/&#10;/g, "\n").replace(/<[^>]+>/g, "").trim();
+    return {
+        id: attr(item, "id"),
+        type: attr(item, "type"),
+        name: primaryName(item.name),
+        year_published: val(item.yearpublished) || null,
+        description: description.slice(0, 1000) + (description.length > 1000 ? "…" : ""),
+        image: String(item.image ?? "").trim() || null,
+        min_players: val(item.minplayers) || null,
+        max_players: val(item.maxplayers) || null,
+        playing_time: val(item.playingtime) || null,
+        min_play_time: val(item.minplaytime) || null,
+        max_play_time: val(item.maxplaytime) || null,
+        min_age: val(item.minage) || null,
+        complexity_weight: val(ratings.averageweight) || null,
+        average_rating: val(ratings.average) || null,
+        bayes_average: val(ratings.bayesaverage) || null,
+        rank: (() => {
+            const ranks = ratings.ranks ?? {};
+            const rankItems = Array.isArray(ranks.rank) ? ranks.rank : ranks.rank ? [ranks.rank] : [];
+            const overall = rankItems.find((r) => attr(r, "name") === "boardgame");
+            return overall ? val(overall) : null;
+        })(),
+        num_ratings: val(ratings.usersrated) || null,
+        num_owned: val(ratings.owned) || null,
+        categories,
+        mechanics,
+        designers,
+        publishers: publishers.slice(0, 5),
+    };
+}
+// ─── bgg_user_collection ──────────────────────────────────────────────────────
+// GET /collection?username=<username>&own=1 (or wishlist=1, played=1)
+export async function bggUserCollection(args) {
+    const username = String(args.username ?? "").trim();
+    if (!username)
+        return { error: "username is required." };
+    const status = String(args.status ?? "owned").trim();
+    const statusMap = {
+        owned: "own=1",
+        wishlist: "wishlist=1",
+        played: "played=1",
+    };
+    const statusParam = statusMap[status] ?? "own=1";
+    const data = await bggFetchWithRetry(`/collection?username=${encodeURIComponent(username)}&${statusParam}&stats=1`);
+    const root = (data.items ?? {});
+    const rawItems = root.item;
+    const items = Array.isArray(rawItems)
+        ? rawItems
+        : rawItems
+            ? [rawItems]
+            : [];
+    return {
+        username,
+        status,
+        total: items.length,
+        games: items.slice(0, 50).map((item) => {
+            const stats = item.stats ?? {};
+            const rating = (item.stats
+                ? stats.rating ?? {}
+                : {});
+            return {
+                id: attr(item, "objectid"),
+                name: String(item.name?.["#text"] ?? ""),
+                year_published: attr(item.yearpublished ?? {}, ""),
+                image: String(item.image ?? "").trim() || null,
+                num_plays: attr(item, "numplays") || String(item.numplays ?? ""),
+                user_rating: val(rating) || null,
+                average_rating: val(stats.rating?.average ?? {}) || null,
+                rank: (() => {
+                    const r = stats.ranks;
+                    if (!r)
+                        return null;
+                    const rankItems = Array.isArray(r.rank) ? r.rank : r.rank ? [r.rank] : [];
+                    const overall = rankItems.find((x) => attr(x, "name") === "boardgame");
+                    return overall ? attr(overall, "value") : null;
+                })(),
+            };
+        }),
+    };
+}
+// ─── bgg_top_games ────────────────────────────────────────────────────────────
+// GET /hot?type=boardgame - returns BGG's "Hotness" list (top 50)
+export async function bggTopGames(args) {
+    const limit = Math.min(Number(args.limit ?? 20), 50);
+    const data = await bggFetch("/hot?type=boardgame");
+    const root = (data.items ?? {});
+    const rawItems = root.item;
+    const items = Array.isArray(rawItems)
+        ? rawItems
+        : rawItems
+            ? [rawItems]
+            : [];
+    return {
+        list: "BGG Hotness (most discussed/active games right now)",
+        total: items.length,
+        games: items.slice(0, limit).map((item, i) => ({
+            rank: i + 1,
+            id: attr(item, "id"),
+            name: val(item.name),
+            year_published: val(item.yearpublished) || null,
+            thumbnail: val(item.thumbnail) || null,
+        })),
+    };
+}
+// ─── bgg_game_reviews ─────────────────────────────────────────────────────────
+// GET /thing?id=<id>&comments=1&page=<page>
+export async function bggGameReviews(args) {
+    const gameId = String(args.gameId ?? "").trim();
+    if (!gameId)
+        return { error: "gameId is required." };
+    const page = Math.max(1, Number(args.page ?? 1));
+    const data = await bggFetch(`/thing?id=${encodeURIComponent(gameId)}&comments=1&page=${page}&pagesize=25`);
+    const root = (data.items ?? {});
+    const rawItems = root.item;
+    const items = Array.isArray(rawItems)
+        ? rawItems
+        : rawItems
+            ? [rawItems]
+            : [];
+    const item = items[0];
+    if (!item)
+        return { error: `No game found with id ${gameId}` };
+    const comments = item.comments ?? {};
+    const rawComments = comments.comment;
+    const commentList = Array.isArray(rawComments)
+        ? rawComments
+        : rawComments
+            ? [rawComments]
+            : [];
+    return {
+        game_id: gameId,
+        game_name: primaryName(item.name),
+        page,
+        total_comments: Number(attr(comments, "totalitems") ?? 0),
+        comments: commentList.map((c) => ({
+            username: attr(c, "username"),
+            rating: attr(c, "rating") || null,
+            comment: String(c["#text"] ?? attr(c, "value") ?? "").trim(),
+        })),
+    };
+}

package/dist/index.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// BoardGameGeek MCP. Standalone MCP server by UnClick.
+// By UnClick. 180+ tools plus persistent agent memory in one install: https://unclick.world
+//
+// Generated from the UnClick connector by scripts/generate-standalone-mcp.mjs.
+// Edit the connector in the UnClick monorepo, not here.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { bggSearch, bggGameDetails, bggUserCollection, bggTopGames, bggGameReviews, } from "./bgg-tool.js";
+const TOOLS = [
+    {
+        name: "bgg_search",
+        description: "Search BoardGameGeek for board games by name.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                query: { type: "string", description: "Game name to search for" },
+                type: { type: "string", enum: ["boardgame", "boardgameexpansion"], description: "Type of item to search for (default: boardgame)" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "bgg_game_details",
+        description: "Get full details for a board game by its BGG ID - name, year, rating, players, playtime, description, categories, and mechanics.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                gameId: { type: "string", description: "BoardGameGeek game ID" },
+            },
+            required: ["gameId"],
+        },
+    },
+    {
+        name: "bgg_user_collection",
+        description: "Get a BGG user's game collection filtered by status (owned, wishlist, or played).",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                username: { type: "string", description: "BGG username" },
+                status: { type: "string", enum: ["owned", "wishlist", "played"], description: "Collection filter (default: owned)" },
+            },
+            required: ["username"],
+        },
+    },
+    {
+        name: "bgg_top_games",
+        description: "Get the BGG Hotness list - the most discussed and active board games right now.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                limit: { type: "number", description: "Number of games to return (max 50, default 20)" },
+            },
+        },
+    },
+    {
+        name: "bgg_game_reviews",
+        description: "Get user comments and ratings for a board game on BGG.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                gameId: { type: "string", description: "BoardGameGeek game ID" },
+                page: { type: "number", description: "Page number (default 1, 25 comments per page)" },
+            },
+            required: ["gameId"],
+        },
+    }
+];
+const HANDLERS = {
+    bgg_search: (args) => bggSearch(args),
+    bgg_game_details: (args) => bggGameDetails(args),
+    bgg_user_collection: (args) => bggUserCollection(args),
+    bgg_top_games: (args) => bggTopGames(args),
+    bgg_game_reviews: (args) => bggGameReviews(args),
+};
+const server = new Server({ name: "io.github.malamutemayhem/bgg", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const handler = HANDLERS[req.params.name];
+    if (!handler) {
+        return { content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }], isError: true };
+    }
+    try {
+        const result = await handler((req.params.arguments ?? {}));
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: message }], isError: true };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`[bgg-mcp] fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@unclick/bgg-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.malamutemayhem/bgg",
+  "description": "BoardGameGeek search, game details, rankings, and collections. By UnClick (https://unclick.world).",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "unclick",
+    "boardgamegeek",
+    "bgg",
+    "board-games"
+  ],
+  "author": "UnClick (https://unclick.world)",
+  "type": "module",
+  "bin": {
+    "bgg-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.15.1",
+    "fast-xml-parser": "^5.8.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/malamutemayhem/unclick.git",
+    "directory": "packages/standalone/bgg-mcp"
+  },
+  "homepage": "https://unclick.world"
+}

package/server.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.malamutemayhem/bgg",
+  "title": "BoardGameGeek MCP by UnClick",
+  "description": "BoardGameGeek search, game details, rankings, and collections. By UnClick.",
+  "version": "0.1.0",
+  "websiteUrl": "https://unclick.world",
+  "icons": [
+    {
+      "src": "https://unclick.world/favicon.png",
+      "mimeType": "image/png",
+      "sizes": [
+        "512x512"
+      ]
+    }
+  ],
+  "repository": {
+    "url": "https://github.com/malamutemayhem/unclick.git",
+    "source": "github",
+    "subfolder": "packages/standalone/bgg-mcp"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@unclick/bgg-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}