Destiny - Codex

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 toolandan MCP server. It works for100% of the manifest— every definition table is supported generically. Hash references are resolved into human-readable names automatically, in both directions.

- 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 perksearchnow uses a precomputedweapon_perkstable in the index DB instead of scanning all ~40k items per query. Runcodex index --rebuildonce to upgrade an existing index cache (older caches fall back to the full scan automatically).
- --jsonoutput—search,filter,browse,rolls, andperksearchaccept--jsonfor 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).

- Stat name filters— Stat names (--stat "Swing Speed:50",statsByName) are now resolved against the manifest's ownDestinyStatDefinitiontable 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.
- itemSubTypelabels— The formatter used a wrong enum (e.g.1: Helmet); replaced with the correctDestinyItemSubTypevalues (Hand Cannon, Sword, Glaive, ...).
- Type declarations—dist/api.d.tsis now actually emitted (declaration: true); library consumers get TypeScript types.
- zoddependency— Declared explicitly instead of relying on the MCP SDK's transitive copy.
- Filter completeness—filterno 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.

- Shared socket logic—rolls,perksearch, and theweapon_perksindex build now share onesockets.tsperk-extraction implementation instead of three copies that could drift apart.
- Prepared-statement cache for definition lookups (hot paths likerolls,browse,graphno longer re-prepare identical SQL thousands of times).
- The API query cache now coverssearch,get,resolve,relationships,graph, andcompare(previously onlyfilter/browse/rolls/perksearch).
- Centralenums.tsfor class/damage names;filteroutput now showsclass=Titan/dmg=Solarinstead of numeric codes; RESTclass/damageparams are case-insensitive.
- Tests— Expanded from 50 to 74, including a fixture in-memory manifest DB that coversfilter,rolls,perksearch,sockets,relationships, and the table-validation guard. Version consistency betweenpackage.jsonandsrc/version.tsis enforced by a test.

- browseMCP tool + CLI command— Browse items with full display data: icons, stats, sockets, damage type, watermarks, flavor text. Likefilterbut enriched for visual/display use.
- compareMCP tool— Compare 2-6 items side-by-side via MCP (stats, perks, properties in aligned columns). Previously only available in CLI and REST.
- itemMCP 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.tsandcompare.tsnow documented in the architecture section.

- resolveMCP tool— Removed unnecessary database query that loaded a definition only to discard it (void def).

# 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 globalcodexcommand. If you'd rather not install it globally, you can always run it in-place withnode dist/index.js <command>from the repo root (e.g.node dist/index.js item Gjallarhorn).

Instead ofconfig set-key, you can also provide the key via a.envfile (cp .env.example .env, then setBUNGIE_API_KEY=...) or theBUNGIE_API_KEYenvironment variable.

codex item Gjallarhorn codex item "Last Wish" --table DestinyActivityDefinition

codex search Gjallarhorn codex search "Wolfpack Rounds" -t DestinySandboxPerkDefinition codex find "Last Wish" -l 5

# 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

# 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

# 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

codex graph DestinyInventoryItemDefinition 1363886209 --depth 3 codex tree DestinyInventoryItemDefinition 1363886209 --depth 2 --branch 10

codex compare Gjallarhorn "Hezen Vengeance" codex compare "Deathbringer" "Two-Tailed Fox" "Eyes of Tomorrow"

# What can Code Duello roll? codex rolls "Code Duello" # Exotic perks + catalyst codex rolls Gjallarhorn # Raid weapon rolls codex rolls "Hezen Vengeance"

# 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"

# 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

Destiny Codex runs as anMCP serverover stdio. AI assistants like Devin, Claude, and others can call it directly.

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

If you didnotinstall it globally, run it from the built output instead:

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

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

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)

All endpoints return JSON with CORS enabled:

# 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"

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.
- Downloadsthe manifest from Bungie's API and caches it locally as SQLite.
- Builds indexes(forward hash→table, name index, reverse reference index) stored as a versioned SQLite DB.
- Resolveshash references two ways:

- Field-name heuristic:itemHash→DestinyInventoryItemDefinition(fast, no lookup needed)
- Reverse index fallback: any hash → its table (handles unknown field names)

- Node.js22.5+(uses built-innode:sqlite). On Node 22/23 it may require the--experimental-sqliteflag; on Node 24+ it is stable.
- A Bungie.net API key (free, get one athttps://www.bungie.net/en/Application)

## License PolyForm Noncommercial 1.0.0 — see 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 for details.

Semantic search through Dickens' classic tale. Find passages by meaning, theme, or concept - not just keywords.

MCP server for the AI Dev Jobs board - 8,400+ open AI/ML engineering roles at 489 companies. Search by role, location, salary, experience level. Live MCP endpoint aidevboard.com/mcp with 4 tools.

API for AI agents to search, license, and download b-roll video clips and voiceovers. Pay-per-request, no human interaction required.

Keyless remote MCP connector to search flights, hotels, and experiences at all-in prices (every mandatory tax and fee included) and book on breckenwander.com.

EU legal research for AI agents: semantic + full-text search over ~48,000 EUR-Lex acts including consolidated versions, daily drift monitoring, answers with verifiable CELEX citations. German, English, French. Remote MCP server at https://conformi.eu/api/mcp — free tier, no key required for article and timeline tools.

Corpus search and linguistic analysis for AI Agents

Security intelligence MCP server — 20 tools: CVE lookup (EPSS/KEV), domain recon, SSL, IP reputation, IOC, exploit search, code security. Free, no API key.

Server that connects Claude/Cursor to the FatSecret Platform API. Search foods, track your diet, manage recipes, and monitor weight directly from your AI assistant.

Open-source Node.js FHIR MCP server with SMART Backend Services, metadata-aware search/CRUD tools, compact responses, FHIRPath filtering, safe pagination, audit events, and terminology lookup.

Geospatial data for AI agents via OpenStreetMap — geocoding, reverse geocoding, POI search, routing, and area statistics. No API key required.