tabletopdb

tabletopdb

面向 Agent 的桌游工具：搜索 BGG 目录、获取游戏详情和收藏、查看热门榜单、查找交易和获取推荐——全部通过公开的 BoardGameGeek XML API2 实现。

tabletopdb 是基于文档中列出的 bgg-mcp 工具集（最初由 kkjdaniel 编写）进行的洁净室重建，完全根据其公开 README 中的工具列表重新编写。它复现了工具接口，以及针对 BGG XML API2 的请求和响应处理；未复制原项目的代码。

一个可执行文件提供两种用法：

• 小型 CLI：tabletopdb <tool-name> '<json-arguments>'
• stdio MCP 服务：tabletopdb mcp

要求

• Node.js 20 或更高版本。
• 环境中需要有 BoardGameGeek API 密钥：

export BGG_API_KEY="your-bgg-api-key"

每次调用都会发送 Authorization: Bearer $BGG_API_KEY。如果密钥缺失或为空，调用会在发出任何请求之前报错，并指出 BGG_API_KEY。

可选环境变量：

• BGG_API_URL — 覆盖 API 基础地址（默认值为 https://boardgamegeek.com/xmlapi2）。
• BGG_USERNAME — 你的 BGG 用户名；仅用于丰富 bgg-price 的身份信息输出。

CLI 用法

工具名称使用连字符，完全遵循文档中的写法：

tabletopdb bgg-search '{"query":"Catan"}'
tabletopdb bgg-details '{"id":13}'
tabletopdb bgg-collection '{"username":"someuser"}'
tabletopdb bgg-hot '{}'
tabletopdb bgg-user '{"username":"someuser"}'
tabletopdb bgg-price '{"id":13}'
tabletopdb bgg-trade-finder '{"username":"someuser","maxResults":10}'
tabletopdb bgg-recommender '{"id":13,"limit":5}'
tabletopdb bgg-rules '{"id":13}'
tabletopdb bgg-thread-details '{"threadId":123456}'
tabletopdb --version

退出代码：0 表示成功，1 表示 API／验证错误，2 表示用法错误（未知命令或 JSON 参数格式错误）。

MCP 用法

npx -y @reneturcios/tabletopdb mcp

MCP 客户端配置：

{
  "mcpServers": {
    "tabletopdb": {
      "command": "npx",
      "args": ["-y", "@reneturcios/tabletopdb", "mcp"],
      "env": { "BGG_API_KEY": "your-bgg-api-key" }
    }
  }
}

Docker：

docker run -i -e BGG_API_KEY="your-bgg-api-key" ghcr.io/cloudcorprecords/tabletopdb
docker run --rm -e BGG_API_KEY="your-bgg-api-key" ghcr.io/cloudcorprecords/tabletopdb bgg-hot '{}'

工具

BGG 以 XML 格式返回数据；内置的小型解析器会将响应转换为 JSON（属性会变为字段，重复元素会变为数组，混合内容中的元素文本会保留在 value 键下）。

工具	参数	功能
bgg-search	query（必需）、type	按名称搜索 BGG。type 默认为 boardgame。
bgg-details	id（数字，必需）、type	获取完整游戏详情和统计数据（/thing?id=&stats=1）。
bgg-collection	username（必需）	获取用户拥有的收藏（own=1&stats=1）。如果 BGG 返回 HTTP 202（正在准备收藏数据），则返回 {status: "accepted", note}，而非报错——请稍后重试。
bgg-hot	type	获取当前 BGG 热门榜单。type 默认为 boardgame。
bgg-user	username（必需）	获取 BGG 用户资料。
bgg-price	id（数字，必需）	通过 BGG 解析游戏身份信息，并返回 {id, name, price_sources: [], note}。实时价格查询需要单独的价格数据提供方；请参阅“差距”。
bgg-trade-finder	username（必需）、maxResults	获取状态标记为 fortrade 的收藏项目，返回 {username, for_trade, count}。
bgg-recommender	id（数字，必需）、limit	按类别启发式推荐：获取游戏的第一个类别，搜索该类别，并返回最多 limit 款其他游戏（默认值为 10）。请参阅“差距”。
bgg-rules	id（数字，必需）	返回 {id, name, description, bgg_url, note}——游戏的 BGG 描述和页面链接。完整规则可在 BGG 文件／维基中找到。
bgg-thread-details	threadId（数字，必需）	获取论坛主题及其解析后的文章。

差距

• bgg-price 提供的是身份信息，而非价格数据：原项目通过外部价格来源解析价格，但其 README 未说明这些来源，因此本次重建返回 BGG 解析出的身份信息、空的 price_sources 列表以及明确说明。
• 出于相同原因，bgg-rules 提供的是信息，而非完整规则：它返回游戏描述和 BGG 官方页面；完整规则位于该页面的文件和维基中。
• bgg-recommender 是基于类别的启发式推荐（共享第一个类别，排除源游戏），并非经过训练的推荐模型。
• 收藏数据的 HTTP 202 语义被简化为单个 {status: "accepted", note} 对象；调用方可通过重试来轮询。
• 构建此软件包时未调用实时 BGG；其行为仅通过 fake-fetch 测试样例验证。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx

许可证

MIT — 详见 LICENSE。