# tabletopdb

BoardGameGeek tools for agents: search the BGG catalogue, pull game
details and collections, check the hot list, find trades, and get
recommendations — all through the public BoardGameGeek XML API2.

`tabletopdb` is a clean-room rebuild of the documented `bgg-mcp` tool
set (originally by kkjdaniel), written fresh from its public README
tool list. It reproduces the tool surface and the request/response
handling against the BGG XML API2; it does not copy the original
project's code.

One bin serves two faces:

- a small CLI: `tabletopdb <tool-name> '<json-arguments>'`
- a stdio MCP server: `tabletopdb mcp`

## Requirements

- Node.js 20 or newer.
- A BoardGameGeek API key in the environment:

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

Every call sends `Authorization: Bearer $BGG_API_KEY`. When the key is
missing or blank, calls fail with an error naming `BGG_API_KEY` before
any request is made.

Optional environment variables:

- `BGG_API_URL` — override the API base (default
  `https://boardgamegeek.com/xmlapi2`).
- `BGG_USERNAME` — your BGG username; enriches `bgg-price` identity
  output only.

## CLI usage

Tool names are hyphenated, exactly as documented:

```bash
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
```

Exit codes: `0` success, `1` API/validation error, `2` usage error
(unknown command or malformed JSON arguments).

## MCP usage

```bash
npx -y @reneturcios/tabletopdb mcp
```

MCP client config:

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

Docker:

```bash
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 '{}'
```

## Tools

BGG answers in XML; responses are converted to JSON by a small
built-in parser (attributes become fields, repeated elements become
arrays, element text is kept under a `value` key where mixed).

| Tool | Arguments | What it does |
|---|---|---|
| `bgg-search` | `query` (required), `type` | Search BGG by name. `type` defaults to `boardgame`. |
| `bgg-details` | `id` (number, required), `type` | Full thing details with stats (`/thing?id=&stats=1`). |
| `bgg-collection` | `username` (required) | A user's owned collection (`own=1&stats=1`). If BGG answers HTTP 202 (collection being prepared), returns `{status: "accepted", note}` instead of an error — retry shortly. |
| `bgg-hot` | `type` | The current BGG hot list. `type` defaults to `boardgame`. |
| `bgg-user` | `username` (required) | A BGG user profile. |
| `bgg-price` | `id` (number, required) | Resolves the game's identity via BGG and returns `{id, name, price_sources: [], note}`. Live price lookup needs a separate price-data provider; see Gaps. |
| `bgg-trade-finder` | `username` (required), `maxResults` | Collection items whose status is marked `fortrade`, as `{username, for_trade, count}`. |
| `bgg-recommender` | `id` (number, required), `limit` | Category heuristic: takes the game's first category, searches it, and returns up to `limit` other games (default 10). See Gaps. |
| `bgg-rules` | `id` (number, required) | `{id, name, description, bgg_url, note}` — the game's BGG description and page link. Full rules live in BGG files/wiki. |
| `bgg-thread-details` | `threadId` (number, required) | A forum thread with its parsed articles. |

## Gaps

- `bgg-price` is an identity shaping, not a price feed: the original
  project resolves prices through external price sources that its
  README does not specify, so this rebuild returns the BGG-resolved
  identity with an empty `price_sources` list and an explicit note.
- `bgg-rules` is an info shaping for the same reason: it returns the
  game's description and canonical BGG page; the full rules live in
  the files and wiki on that page.
- `bgg-recommender` is a labelled category heuristic (shared first
  category, source game excluded), not a learned recommendation model.
- The collection HTTP 202 semantics are simplified to a single
  `{status: "accepted", note}` object; callers poll by retrying.
- No live BGG call was made while building this package; behaviour is
  verified against fake-fetch fixtures only.

## Development

```bash
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
```

## License

MIT — see `LICENSE`.