<p align="center">
  <img src="assets/MCP-Banner.png" alt="Destiny Codex" width="100%">
</p>

# Destiny Codex

> Version **0.5.1.0** (02.07.2026)
>
> Turn the Destiny 2 Manifest (gibberish hash-reference JSON) into clean, AI-readable text — with full relationship traversal, structured filtering, item comparison, and weapon perk-roll extraction.

Destiny Codex is a CLI tool **and** an MCP server. It works for **100% of the manifest** — every definition table is supported generically. Hash references are resolved into human-readable names automatically, in both directions.

## Changelog

### 0.5.1.0 (02.07.2026)

**Features:**
- **Offline mode** — The remote manifest version is only checked when the cache is missing or the last check is older than 1 hour. If Bungie is unreachable, the cached manifest is used with a warning. Commands are faster and work without internet.
- **Fast reverse perk search** — `codex perksearch` now uses a precomputed `weapon_perks` table in the index DB instead of scanning all ~40k items per query. Run `codex index --rebuild` once to upgrade an existing index cache (older caches fall back to the full scan automatically).
- **`--json` output** — `search`, `filter`, `browse`, `rolls`, and `perksearch` accept `--json` for raw structured output (scripting without the REST server).
- **Per-language manifest metadata** — Switching languages back and forth no longer re-downloads the manifest if the cached DB is still current.
- **Network hardening** — All Bungie calls now have timeouts (15 s metadata, 120 s download); the manifest download retries up to 3× and verifies the SQLite header before replacing the cache.
- **CI** — GitHub Actions workflow (build + tests on every push/PR).

**Bug Fixes:**
- **Stat name filters** — Stat names (`--stat "Swing Speed:50"`, `statsByName`) are now resolved against the manifest's own `DestinyStatDefinition` table instead of a hardcoded list that contained wrong hashes for Accuracy, Charge Rate, Swing Speed, Guard Endurance, and others. This also makes stat filters work in every manifest language.
- **`itemSubType` labels** — The formatter used a wrong enum (e.g. `1: Helmet`); replaced with the correct `DestinyItemSubType` values (Hand Cannon, Sword, Glaive, ...).
- **Type declarations** — `dist/api.d.ts` is now actually emitted (`declaration: true`); library consumers get TypeScript types.
- **`zod` dependency** — Declared explicitly instead of relying on the MCP SDK's transitive copy.
- **Filter completeness** — `filter` no longer stops scanning early (`limit * 3`), which could silently drop matching items depending on table order.
- **Table name validation** — Table names from CLI/MCP/REST input are validated against the manifest before being used in SQL. The REST server returns 400 for unknown tables.

**Improvements:**
- **Shared socket logic** — `rolls`, `perksearch`, and the `weapon_perks` index build now share one `sockets.ts` perk-extraction implementation instead of three copies that could drift apart.
- Prepared-statement cache for definition lookups (hot paths like `rolls`, `browse`, `graph` no longer re-prepare identical SQL thousands of times).
- The API query cache now covers `search`, `get`, `resolve`, `relationships`, `graph`, and `compare` (previously only `filter`/`browse`/`rolls`/`perksearch`).
- Central `enums.ts` for class/damage names; `filter` output now shows `class=Titan`/`dmg=Solar` instead of numeric codes; REST `class`/`damage` params are case-insensitive.
- **Tests** — Expanded from 50 to 74, including a fixture in-memory manifest DB that covers `filter`, `rolls`, `perksearch`, `sockets`, `relationships`, and the table-validation guard. Version consistency between `package.json` and `src/version.ts` is enforced by a test.

---

### 0.5.0.0 (07.01.2026)

**Features:**
- **`browse` MCP tool + CLI command** — Browse items with full display data: icons, stats, sockets, damage type, watermarks, flavor text. Like `filter` but enriched for visual/display use.
- **`compare` MCP tool** — Compare 2-6 items side-by-side via MCP (stats, perks, properties in aligned columns). Previously only available in CLI and REST.
- **`item` MCP tool** — Look up an item by name and get its full readable definition in one step. Replaces the search+get two-call pattern.
- **AGENTS.md updated** — `browse.ts` and `compare.ts` now documented in the architecture section.

**Bug Fixes:**
- **`resolve` MCP tool** — Removed unnecessary database query that loaded a definition only to discard it (`void def`).

---

## Quick Start

```bash
# 1. Install dependencies + build
npm install
npm run build

# 2. Install the `codex` command globally (links this repo)
npm link            # or: npm install -g .

# 3. Add your Bungie API key (get one at https://www.bungie.net/en/Application)
codex config set-key your_key_here

# 4. (Optional) Set your preferred language (default: en)
codex config set-language de    # German, French, Spanish, Japanese, etc.

# 5. Download the manifest + build indexes
codex sync
codex index

# 6. Use it
codex item Gjallarhorn
```

> All commands below use the global `codex` command. If you'd rather not install
> it globally, you can always run it in-place with `node dist/index.js <command>`
> from the repo root (e.g. `node dist/index.js item Gjallarhorn`).

Instead of `config set-key`, you can also provide the key via a `.env` file
(`cp .env.example .env`, then set `BUNGIE_API_KEY=...`) or the `BUNGIE_API_KEY`
environment variable.

## CLI Commands

### Lookup & Search

| Command | Description |
|---|---|
| `codex item <name>` | Look up an item by name, show full readable definition. Picks best match automatically. |
| `codex search <query>` | Search by name (substring, case-insensitive). `-t <table>` to filter, `-l <n>` for limit. |
| `codex filter [options]` | Structured filter: `--tier`, `--type`, `--class`, `--damage`, `--bucket`, `--stat`. |
| `codex browse [options]` | Browse items with full display data (icons, stats, sockets, damage, flavor text). Same filters as `filter` but enriched. |
| `codex rolls <name>` | Show all possible perk rolls for a weapon (barrel, mag, traits, mods, catalyst). Answers "what can this weapon roll?" |
| `codex perksearch <perk>` | Reverse perk search: find all weapons that can roll a given perk. Alias: `perks`. |
| `codex get <table> <hash>` | Full readable definition by table + hash (all refs resolved inline). |
| `codex resolve <hash>` | Bare hash → short summary (auto-detects table). |
| `codex raw <table> <hash>` | Raw JSON of a definition. |

### Relationships & Graph

| Command | Description |
|---|---|
| `codex relationships <table> <hash>` | Show outgoing + incoming references. Alias: `codex rels`. |
| `codex graph <table> <hash>` | Traverse the reference graph as a tree. Alias: `codex tree`. |
| `codex compare <name1> <name2> [name3...]` | Compare 2+ items side-by-side (stats, perks, properties). |

### Management

| Command | Description |
|---|---|
| `codex sync` | Download/refresh the manifest. `--force` to re-download. |
| `codex index` | Build search indexes (speeds up everything ~10x). `--rebuild` to force. |
| `codex info` | Show manifest version + table list. |
| `codex tables` | List all definition tables. |
| `codex mcp` | Start the MCP server (for AI tool integration). |
| `codex serve` | Start REST API HTTP server for app integration. `--port`, `--host`. |
| `codex config set-key <key>` | Save your Bungie API key. |
| `codex config set-language <lang>` | Save preferred manifest language (`de`, `fr`, `es`, `ja`, ...). Run `sync` after. |
| `codex config get-language` | Show currently saved language. |

## Examples

### Look up an item
```bash
codex item Gjallarhorn
codex item "Last Wish" --table DestinyActivityDefinition
```

### Search
```bash
codex search Gjallarhorn
codex search "Wolfpack Rounds" -t DestinySandboxPerkDefinition
codex find "Last Wish" -l 5
```

### Filter
```bash
# All Exotic Rocket Launchers
codex filter --tier Exotic --type "Rocket Launcher"

# All Legendary Titan helmets
codex filter --tier Legendary --class Titan --bucket Helmet

# Rocket Launchers with Blast Radius >= 90
codex filter --type "Rocket Launcher" --stat "Blast Radius:90"

# Solar Sidearms, max 10 results
codex filter --damage Solar --type "Sidearm" --limit 10
```

### Browse (enriched item data)
```bash
# Exotic Rocket Launchers with icons, stats, sockets, flavor text
codex browse --tier Exotic --type "Rocket Launcher"

# Legendary Titan helmets with full display data
codex browse --tier Legendary --class Titan --bucket Helmet --limit 10

# Solar Sidearms with icons and stats
codex browse --damage Solar --type "Sidearm" --limit 10
```

### Relationships (how things connect)
```bash
# What does Gjallarhorn reference? (outgoing)
codex rels DestinyInventoryItemDefinition 1363886209 -d outgoing

# Who uses the "Wolfpack Rounds" perk? (incoming)
codex rels DestinySandboxPerkDefinition 2447763556 -d incoming

# Both directions
codex rels DestinyInventoryItemDefinition 1363886209
```

### Graph traversal
```bash
codex graph DestinyInventoryItemDefinition 1363886209 --depth 3
codex tree DestinyInventoryItemDefinition 1363886209 --depth 2 --branch 10
```

### Compare items
```bash
codex compare Gjallarhorn "Hezen Vengeance"
codex compare "Deathbringer" "Two-Tailed Fox" "Eyes of Tomorrow"
```

### Weapon perk rolls
```bash
# What can Code Duello roll?
codex rolls "Code Duello"

# Exotic perks + catalyst
codex rolls Gjallarhorn

# Raid weapon rolls
codex rolls "Hezen Vengeance"
```

### Reverse perk search
```bash
# Which weapons can roll Incandescent?
codex perksearch Incandescent

# Which weapons can roll Bait and Switch?
codex perks "Bait and Switch"

# Which weapons can roll Vorpal Weapon?
codex perksearch "Vorpal Weapon"
```

### Multi-language support
```bash
# Switch to German
codex config set-language de
codex sync
codex index --rebuild

# Now everything is in German
codex item Gjallarhorn          # "Raketenwerfer (Exotisch)"
codex filter --tier Exotisch --type "Raketenwerfer"
codex rolls "Code Duello"       # "INTRINSISCHE EIGENSCHAFTEN", "WAFFEN-PERKS"

# One-off language for sync (without saving)
codex sync --language fr
codex sync -l ja

# Supported languages
en, de, es, es-mx, fr, fr-ca, it, ja, ko, pl, pt-br, ru, zh-chs, zh-cht
```

## MCP Server (for AI tools)

Destiny Codex runs as an [MCP server](https://modelcontextprotocol.io/) over stdio. AI assistants like Devin, Claude, and others can call it directly.

### Start the server
```bash
codex mcp
```

### Configure in an MCP client

If you installed the `codex` command globally (`npm link` / `npm install -g .`),
point your MCP client at it directly:

```json
{
  "mcpServers": {
    "destiny-codex": {
      "command": "codex",
      "args": ["mcp"]
    }
  }
}
```

If you did **not** install it globally, run it from the built output instead:

```json
{
  "mcpServers": {
    "destiny-codex": {
      "command": "node",
      "args": ["/path/to/destiny-codex/dist/index.js", "mcp"]
    }
  }
}
```

### MCP Tools

| Tool | Description |
|---|---|
| `manifest_info` | Manifest version, language, table list with row counts. Auto-syncs. |
| `list_tables` | All definition tables. |
| `search` | Name search with optional table filter. |
| `filter` | Structured query: itemType, tierType, classType, damageType, bucket, stat ranges. |
| `browse` | Enriched item data: icons, stats, sockets, damage, flavor text. Same filters as `filter`. |
| `rolls` | All possible perk rolls for a weapon (barrel, mag, traits, mods, catalyst). |
| `perk_search` | Reverse perk search: which weapons can roll a given perk? |
| `item` | Look up item by name → full readable definition in one step (fuzzy-matched). |
| `compare` | Compare 2-6 items side-by-side (stats, perks, properties in columns). |
| `get` | Readable text rendering of a definition (all hash refs resolved inline). |
| `resolve` | Bare hash → short summary. |
| `relationships` | Outgoing + incoming references (how things connect). |
| `graph` | Traverse the reference graph N hops deep as a tree. |
| `raw` | Raw JSON of a definition. |

## App Integration

Destiny Codex can be used as a backend in your own app — without AI, without the CLI.

### Programmatic API (Node.js)

```ts
import { DestinyCodex } from "destiny-codex";

const codex = new DestinyCodex({ apiKey: "your-bungie-key" });
await codex.sync();    // download manifest
await codex.index();   // build indexes

// Search
const hits = await codex.search("Gjallarhorn");

// Weapon perk rolls
const rolls = await codex.getRolls("Code Duello");

// Reverse perk search
const weapons = await codex.findWeaponsWithPerk("Incandescent");

// Filter
const exotics = await codex.filter({ tierTypeName: "Exotic", itemTypeDisplayName: "Rocket Launcher" });

// Browse (enriched: icons, stats, sockets, flavor text)
const browseResults = await codex.browse({ tierTypeName: "Exotic", itemTypeDisplayName: "Rocket Launcher" });

// Compare
const comparison = await codex.compare(["Gjallarhorn", "Hezen Vengeance"]);

// Relationships
const rels = await codex.relationships("DestinyInventoryItemDefinition", 1363886209);

// Raw JSON
const raw = await codex.raw("DestinyInventoryItemDefinition", 1363886209);

codex.close();
```

### REST API Server (for web apps / frontends)

```bash
codex serve --port 3000
```

All endpoints return JSON with CORS enabled:

| Endpoint | Description |
|---|---|
| `GET /health` | Health check |
| `GET /api/info` | Manifest version, language, tables |
| `GET /api/tables` | All definition tables |
| `GET /api/search?q=<name>&table=<t>&limit=<n>` | Search by name |
| `GET /api/filter?tier=<t>&type=<t>&class=<c>&damage=<d>` | Structured filter |
| `GET /api/browse?tier=<t>&type=<t>&class=<c>&damage=<d>` | Browse items with full display data (icons, stats, sockets) |
| `GET /api/get/<table>/<hash>` | Readable definition |
| `GET /api/resolve/<hash>` | Bare hash → summary |
| `GET /api/rolls/<name-or-hash>` | Weapon perk rolls |
| `GET /api/perksearch/<perk-name-or-hash>` | Weapons that can roll a perk |
| `GET /api/compare?items=<n1,n2,n3>` | Compare items |
| `GET /api/relationships/<table>/<hash>?direction=<both\|outgoing\|incoming>` | References |
| `GET /api/graph/<table>/<hash>?depth=<n>&branch=<n>` | Graph traversal |
| `GET /api/raw/<table>/<hash>` | Raw JSON |

```bash
# Examples
curl http://localhost:3000/api/search?q=Gjallarhorn
curl http://localhost:3000/api/rolls/Code%20Duello
curl http://localhost:3000/api/perksearch/Incandescent
curl "http://localhost:3000/api/filter?tier=Exotic&type=Rocket%20Launcher&limit=5"
curl "http://localhost:3000/api/browse?tier=Exotic&type=Rocket%20Launcher&limit=5"
```

## How It Works

The Destiny 2 Manifest is a SQLite database with ~83 tables of JSON definitions. Every definition is full of hash references — `itemHash: 1363886209`, `statHash: 155624089`, etc. — that are meaningless without looking up the target.

Destiny Codex:

1. **Downloads** the manifest from Bungie's API and caches it locally as SQLite.
2. **Builds indexes** (forward hash→table, name index, reverse reference index) stored as a versioned SQLite DB.
3. **Resolves** hash references two ways:
   - **Field-name heuristic**: `itemHash` → `DestinyInventoryItemDefinition` (fast, no lookup needed)
   - **Reverse index fallback**: any hash → its table (handles unknown field names)
4. **Formats** definitions as clean, indented text with hash refs replaced by `"Gjallarhorn" (hash 1363886209, DestinyInventoryItemDefinition)` inline.
5. **Traverses** the reference graph in both directions: outgoing (what does X reference?) and incoming (who references X?).

## Performance

| Operation | Time |
|---|---|
| Manifest download | ~10s (37 MB compressed) |
| Index build | ~15s (one-time per manifest version) |
| `codex search` (with index) | ~1.3s |
| `codex rels` (with index) | ~1.2s |
| `codex graph` (with index) | ~1.2s |
| `codex filter` | ~0.3s |
| `codex perksearch` (with index) | ~1s |

## Requirements

- Node.js **22.5+** (uses built-in `node:sqlite`). On Node 22/23 it may require the `--experimental-sqlite` flag; on Node 24+ it is stable.
- A Bungie.net API key (free, get one at https://www.bungie.net/en/Application)

```

## License

PolyForm Noncommercial 1.0.0 — see [LICENSE](LICENSE).

This software may **never** be used for commercial purposes. Personal use,
research, education, charitable organizations, and government institutions
are permitted. See the [full license text](https://polyformproject.org/licenses/noncommercial/1.0.0)
for details.