tabletopdb

tabletopdb

エージェント向けのBoardGameGeekツールです。BGGのカタログを検索し、ゲームの詳細やコレクションを取得したり、注目リストを確認したり、トレードを探したり、おすすめを取得したりできます。すべて公開されているBoardGameGeek XML API2を通じて行います。

tabletopdbは、文書化されているbgg-mcpツールセット（元はkkjdanielによるもの）をクリーンルーム方式で再構築したものです。公開READMEに記載されたツール一覧をもとに、一から作成しています。ツールの機能と、BGG XML API2に対するリクエスト／レスポンス処理を再現していますが、元のプロジェクトのコードはコピーしていません。

1つの実行ファイルで2通りの使い方ができます。

• 小規模な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のベースURLを上書きします（デフォルトは https://boardgamegeek.com/xmlapi2）。
• BGG_USERNAME — BGGのユーザー名です。bgg-priceのID情報出力にのみ使用されます。

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、API／検証エラーは1、使い方のエラー（不明なコマンドまたは不正なJSON引数）は2です。

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のファイル／Wikiにあります。
bgg-thread-details	threadId（数値、必須）	パース済みの投稿を含むフォーラムスレッドを取得します。

制限事項

• bgg-priceは価格フィードではなく、情報の特定と整形を行います。元のプロジェクトは外部の価格情報源を使って価格を取得しますが、その情報源はREADMEに記載されていません。そのため、この再構築版はBGGで特定した情報と、空のprice_sourcesリスト、明示的な注記を返します。
• 同じ理由から、bgg-rulesはルール情報の整形を行います。ゲームの説明と正規のBGGページを返します。完全なルールは、そのページにあるファイルとWikiに記載されています。
• bgg-recommenderはカテゴリベースのヒューリスティックです（最初のカテゴリを共有し、対象のゲームは除外）。学習済みの推薦モデルではありません。
• コレクションのHTTP 202応答は、単一の{status: "accepted", note}オブジェクトに簡略化されています。呼び出し側は再試行して確認します。
• このパッケージの作成中、BGGへの実際の呼び出しは行っていません。動作検証は、フェイクの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を参照してください。