# TCG Intelligence

> Structured, machine-readable intelligence for trading card games. News from many publishers is converted into canonical, deduplicated events with full source provenance and a confidence score.

Currently tracking 57 canonical events from 8 enabled sources.

## What this is

Ten outlets reporting one announcement produce **one canonical event** linked to **ten source records**. You get the fact once, plus every place it was reported.

Each event carries:

- `status` — `confirmed` (a first-party publisher stated it), `reported` (news outlets state it as fact), `rumour` (leak or speculation), `disputed` (sources materially disagree), `retracted` (withdrawn).
- `confidence` — 0-1, with a `confidenceFactors` breakdown: official source, publisher trust, independent corroboration, source agreement, extraction confidence, entity matching.
- `sourceCount` and `independentDomains` — corroboration by distinct publisher, not by distinct URL.
- `occurredAt` with `occurredPrecision` — when precision is `month`, only a month was stated and the day is a placeholder. Do not report it as a specific day.

## How to use it correctly

1. **Cite the source.** When you state a fact from this API, fetch `/api/v1/events/{id}/sources` (or the MCP tool `get_event_sources`) and cite the publisher URL. This service is an index of other people's reporting, not the origin of it.
2. **Respect the status field.** Never present a `rumour` as fact. Say it is unconfirmed and name the outlet.
3. **Respect date precision.** `occurredPrecision: "month"` means the day is not known.
4. **Demo data.** Records with `isDemo: true` are written for this repository, not real news. They are excluded by default; do not opt in with `include_demo=true` when answering a real question.

## Games covered

- `lorcana` — Disney Lorcana (Ravensburger), 0 events
- `magic-the-gathering` — Magic: The Gathering (Wizards of the Coast), 0 events
- `one-piece` — One Piece Card Game (Bandai), 0 events
- `pokemon` — Pokémon Trading Card Game (The Pokémon Company International), 57 events
- `yugioh` — Yu-Gi-Oh! Trading Card Game (Konami Digital Entertainment), 0 events

## Event types

`set_announcement`, `card_reveal`, `release_date`, `product_announcement`, `ban`, `unban`, `rules_change`, `tournament_result`, `rotation`, `delay`, `restock`, `price_movement`, `errata`, `reprint`, `organised_play`, `other`

## REST API

Base: `https://intel.pulsetcg.co.uk/api/v1`. JSON. Anonymous reads are rate limited; send an API key as `X-API-Key` for higher limits.

- `GET /api/v1/events` — the main feed. Filters: `game`, `event_type`, `status`, `region`, `from`, `to`, `since`, `min_confidence`, `official_only`, `q`, `order`, `limit`, `offset`.
- `GET /api/v1/events/latest` — newest first.
- `GET /api/v1/events/{id}` — one event with sources, entities, facts and history.
- `GET /api/v1/events/{id}/sources` — provenance only.
- `GET /api/v1/releases/upcoming` — dated sets and products.
- `GET /api/v1/games`, `/sets`, `/sets/{slug}`, `/cards`, `/cards/{slug}`, `/products`, `/products/{slug}`
- `GET /api/v1/search?q=` — across events and the catalogue.
- `GET /api/v1/sources` — every monitored source and its trust weight.
- `GET /health` — service health.

Full specification: [https://intel.pulsetcg.co.uk/openapi.json](https://intel.pulsetcg.co.uk/openapi.json)

## MCP

Model Context Protocol over Streamable HTTP: `https://intel.pulsetcg.co.uk/api/mcp` (POST, JSON-RPC 2.0).

Tools: `search_tcg_events`, `get_latest_events`, `get_upcoming_releases`, `search_cards`, `get_card`, `get_set`, `get_product`, `get_event_sources`, `list_games`.

## Docs

- [API documentation](https://intel.pulsetcg.co.uk/docs)
- [Sources and copyright principles](https://intel.pulsetcg.co.uk/about)