Destiny - Codex

Destiny Codex

Versión 0.5.1.0 (02.07.2026)

Convierte el Manifest de Destiny 2 (JSON de referencias hash incomprensibles) en texto limpio y legible para IA — con recorrido completo de relaciones, filtrado estructurado, comparación de objetos y extracción de rolls de perks de armas.

Destiny Codex es una herramienta CLI y un servidor MCP. Funciona con el 100% del manifest — cada tabla de definiciones está soportada de forma genérica. Las referencias hash se resuelven automáticamente en nombres legibles, en ambas direcciones.

Registro de cambios

0.5.1.0 (02.07.2026)

Características:

• Modo sin conexión — La versión remota del manifest solo se comprueba cuando la caché falta o la última comprobación tiene más de 1 hora. Si Bungie no está disponible, se usa el manifest en caché con una advertencia. Los comandos son más rápidos y funcionan sin internet.
• Búsqueda inversa rápida de perks — codex perksearch ahora usa una tabla weapon_perks precalculada en la base de datos de índices en lugar de escanear los ~40k objetos por consulta. Ejecuta codex index --rebuild una vez para actualizar una caché de índices existente (las cachés antiguas recurren automáticamente al escaneo completo).
• Salida --json — search, filter, browse, rolls y perksearch aceptan --json para salida estructurada sin procesar (scripting sin el servidor REST).
• Metadatos del manifest por idioma — Cambiar de idioma de un lado a otro ya no vuelve a descargar el manifest si la base de datos en caché sigue siendo actual.
• Refuerzo de red — Todas las llamadas a Bungie ahora tienen tiempos de espera (15 s para metadatos, 120 s para descargas); la descarga del manifest se reintenta hasta 3 veces y verifica el encabezado SQLite antes de reemplazar la caché.
• CI — Flujo de trabajo de GitHub Actions (compilación + pruebas en cada push/PR).

Correcciones de errores:

• Filtros de nombres de estadísticas — Los nombres de estadísticas (--stat "Swing Speed:50", statsByName) ahora se resuelven contra la propia tabla DestinyStatDefinition del manifest en lugar de una lista fija que contenía hashes incorrectos para Precisión, Cadencia de disparo, Velocidad de balanceo, Resistencia de guardia y otros. Esto también hace que los filtros de estadísticas funcionen en todos los idiomas del manifest.
• Etiquetas itemSubType — El formateador usaba una enumeración incorrecta (p. ej. 1: Helmet); se reemplazó con los valores correctos de DestinyItemSubType (Cañón de mano, Espada, Glaive, ...).
• Declaraciones de tipos — dist/api.d.ts ahora se emite realmente (declaration: true); los consumidores de la biblioteca obtienen tipos de TypeScript.
• Dependencia zod — Declarada explícitamente en lugar de depender de la copia transitiva del SDK de MCP.
• Completitud del filtro — filter ya no detiene el escaneo antes de tiempo (limit * 3), lo que podía descartar silenciosamente objetos coincidentes según el orden de la tabla.
• Validación de nombres de tablas — Los nombres de tablas de entrada CLI/MCP/REST se validan contra el manifest antes de usarse en SQL. El servidor REST devuelve 400 para tablas desconocidas.

Mejoras:

• Lógica de sockets compartida — rolls, perksearch y la construcción del índice weapon_perks ahora comparten una implementación de extracción de perks sockets.ts en lugar de tres copias que podían divergir.
• Caché de sentencias preparadas para búsquedas de definiciones (rutas calientes como rolls, browse, graph ya no re-preparan SQL idéntico miles de veces).
• La caché de consultas de API ahora cubre search, get, resolve, relationships, graph y compare (anteriormente solo filter/browse/rolls/perksearch).
• enums.ts central para nombres de clase/daño; la salida filter ahora muestra class=Titan/dmg=Solar en lugar de códigos numéricos; los parámetros REST class/damage no distinguen entre mayúsculas y minúsculas.
• Pruebas — Ampliadas de 50 a 74, incluida una base de datos de manifest en memoria de prueba que cubre filter, rolls, perksearch, sockets, relationships y la protección de validación de tablas. La consistencia de versión entre package.json y src/version.ts está garantizada por una prueba.

---

0.5.0.0 (07.01.2026)

Características:

• Herramienta MCP browse + comando CLI — Explora objetos con datos de visualización completos: iconos, estadísticas, sockets, tipo de daño, marcas de agua, texto de sabor. Como filter pero enriquecido para uso visual/display.
• Herramienta MCP compare — Compara 2-6 objetos lado a lado vía MCP (estadísticas, perks, propiedades en columnas alineadas). Anteriormente solo disponible en CLI y REST.
• Herramienta MCP item — Busca un objeto por nombre y obtén su definición legible completa en un solo paso. Reemplaza el patrón de dos llamadas buscar+obtener.
• AGENTS.md actualizado — browse.ts y compare.ts ahora documentados en la sección de arquitectura.

Correcciones de errores:

• Herramienta MCP resolve — Se eliminó una consulta innecesaria a la base de datos que cargaba una definición solo para descartarla (void def).

---

Inicio rápido

# 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

Todos los comandos a continuación usan el comando global codex. Si prefieres no instalarlo globalmente, siempre puedes ejecutarlo en el lugar con node dist/index.js <command> desde la raíz del repositorio (p. ej. node dist/index.js item Gjallarhorn).

En lugar de config set-key, también puedes proporcionar la clave mediante un archivo .env (cp .env.example .env, luego establece BUNGIE_API_KEY=...) o la variable de entorno BUNGIE_API_KEY.

Comandos CLI

Búsqueda y consulta

Comando	Descripción
codex item <name>	Busca un objeto por nombre, muestra la definición legible completa. Selecciona automáticamente la mejor coincidencia.
codex search <query>	Busca por nombre (subcadena, sin distinguir mayúsculas). -t <table> para filtrar, -l <n> para límite.
codex filter [options]	Filtro estructurado: --tier, --type, --class, --damage, --bucket, --stat.
codex browse [options]	Explora objetos con datos de visualización completos (iconos, estadísticas, sockets, daño, texto de sabor). Mismos filtros que filter pero enriquecido.
codex rolls <name>	Muestra todos los rolls de perks posibles para un arma (cañón, cargador, rasgos, mods, catalizador). Responde "¿qué puede tener este arma?"
codex perksearch <perk>	Búsqueda inversa de perks: encuentra todas las armas que pueden tener un perk dado. Alias: perks.
codex get <table> <hash>	Definición legible completa por tabla + hash (todas las referencias resueltas en línea).
codex resolve <hash>	Hash simple → resumen breve (detecta la tabla automáticamente).
codex raw <table> <hash>	JSON sin procesar de una definición.

Relaciones y grafo

Comando	Descripción
codex relationships <table> <hash>	Muestra referencias salientes + entrantes. Alias: codex rels.
codex graph <table> <hash>	Recorre el grafo de referencias como un árbol. Alias: codex tree.
codex compare <name1> <name2> [name3...]	Compara 2+ objetos lado a lado (estadísticas, perks, propiedades).

Gestión

Comando	Descripción
codex sync	Descarga/actualiza el manifest. --force para volver a descargar.
codex index	Construye índices de búsqueda (acelera todo ~10x). --rebuild para forzar.
codex info	Muestra la versión del manifest + lista de tablas.
codex tables	Lista todas las tablas de definiciones.
codex mcp	Inicia el servidor MCP (para integración con herramientas de IA).
codex serve	Inicia el servidor HTTP de API REST para integración de aplicaciones. --port, --host.
codex config set-key <key>	Guarda tu clave de API de Bungie.
codex config set-language <lang>	Guarda el idioma preferido del manifest (de, fr, es, ja, ...). Ejecuta sync después.
codex config get-language	Muestra el idioma guardado actualmente.

Ejemplos

Buscar un objeto

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

Buscar

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

Filtrar

# 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

Explorar (datos de objeto enriquecidos)

# 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

Relaciones (cómo se conectan las cosas)

# 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

Recorrido del grafo

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

Comparar objetos

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

Rolls de perks de armas

# What can Code Duello roll?
codex rolls "Code Duello"

# Exotic perks + catalyst
codex rolls Gjallarhorn

# Raid weapon rolls
codex rolls "Hezen Vengeance"

Búsqueda inversa de perks

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

Soporte multilingüe

# 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

Servidor MCP (para herramientas de IA)

Destiny Codex se ejecuta como un servidor MCP sobre stdio. Asistentes de IA como Devin, Claude y otros pueden llamarlo directamente.

Iniciar el servidor

codex mcp

Configurar en un cliente MCP

Si instalaste el comando codex globalmente (npm link / npm install -g .), apunta tu cliente MCP directamente a él:

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

Si no lo instalaste globalmente, ejecútalo desde la salida compilada en su lugar:

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

Herramientas MCP

Herramienta	Descripción
manifest_info	Versión del manifest, idioma, lista de tablas con recuentos de filas. Sincronización automática.
list_tables	Todas las tablas de definiciones.
search	Búsqueda por nombre con filtro de tabla opcional.
filter	Consulta estructurada: itemType, tierType, classType, damageType, bucket, rangos de estadísticas.
browse	Datos de objeto enriquecidos: iconos, estadísticas, sockets, daño, texto de sabor. Mismos filtros que filter.
rolls	Todos los rolls de perks posibles para un arma (cañón, cargador, rasgos, mods, catalizador).
perk_search	Búsqueda inversa de perks: ¿qué armas pueden tener un perk dado?
item	Busca objeto por nombre → definición legible completa en un solo paso (coincidencia difusa).
compare	Compara 2-6 objetos lado a lado (estadísticas, perks, propiedades en columnas).
get	Representación de texto legible de una definición (todas las referencias hash resueltas en línea).
resolve	Hash simple → resumen breve.
relationships	Referencias salientes + entrantes (cómo se conectan las cosas).
graph	Recorre el grafo de referencias N niveles de profundidad como un árbol.
raw	JSON sin procesar de una definición.

Integración de aplicaciones

Destiny Codex se puede usar como backend en tu propia aplicación — sin IA, sin CLI.

API programática (Node.js)

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();

Servidor de API REST (para aplicaciones web / frontends)

codex serve --port 3000

Todos los endpoints devuelven JSON con CORS habilitado:

Endpoint	Descripción
GET /health	Comprobación de salud
GET /api/info	Versión del manifest, idioma, tablas
GET /api/tables	Todas las tablas de definiciones
GET /api/search?q=<name>&table=<t>&limit=<n>	Búsqueda por nombre
GET /api/filter?tier=<t>&type=<t>&class=<c>&damage=<d>	Filtro estructurado
GET /api/browse?tier=<t>&type=<t>&class=<c>&damage=<d>	Explora objetos con datos de visualización completos (iconos, estadísticas, sockets)
GET /api/get/<table>/<hash>	Definición legible
GET /api/resolve/<hash>	Hash simple → resumen
GET /api/rolls/<name-or-hash>	Rolls de perks de armas
GET /api/perksearch/<perk-name-or-hash>	Armas que pueden tener un perk
GET /api/compare?items=<n1,n2,n3>	Comparar objetos
GET /api/relationships/<table>/<hash>?direction=<both|outgoing|incoming>	Referencias
GET /api/graph/<table>/<hash>?depth=<n>&branch=<n>	Recorrido del grafo
GET /api/raw/<table>/<hash>	JSON sin procesar

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

Cómo funciona

El Manifest de Destiny 2 es una base de datos SQLite con ~83 tablas de definiciones JSON. Cada definición está llena de referencias hash — itemHash: 1363886209, statHash: 155624089, etc. — que no tienen sentido sin buscar el destino.

Destiny Codex:

1. Descarga el manifest de la API de Bungie y lo almacena en caché localmente como SQLite.
2. Construye índices (hash→tabla directo, índice de nombres, índice de referencias inversas) almacenados como una base de datos SQLite versionada.
3. Resuelve referencias hash de dos maneras:
   • Heurística de nombre de campo: itemHash → DestinyInventoryItemDefinition (rápido, sin necesidad de búsqueda)
   • Respaldo de índice inverso: cualquier hash → su tabla (maneja nombres de campo desconocidos)
4. Formatea definiciones como texto limpio e indentado con referencias hash reemplazadas por "Gjallarhorn" (hash 1363886209, DestinyInventoryItemDefinition) en línea.
5. Recorre el grafo de referencias en ambas direcciones: salientes (¿a qué referencia X?) y entrantes (¿quién referencia a X?).

Rendimiento

Operación	Tiempo
Descarga del manifest	~10s (37 MB comprimido)
Construcción de índices	~15s (una vez por versión del manifest)
codex search (con índice)	~1.3s
codex rels (con índice)	~1.2s
codex graph (con índice)	~1.2s
codex filter	~0.3s
codex perksearch (con índice)	~1s

Requisitos

• Node.js 22.5+ (usa node:sqlite integrado). En Node 22/23 puede requerir la bandera --experimental-sqlite; en Node 24+ es estable.
• Una clave de API de Bungie.net (gratuita, obtén una en https://www.bungie.net/en/Application)

## Licencia

PolyForm Noncommercial 1.0.0 — consulte [LICENCIA](LICENSE).

Este software **nunca** podrá utilizarse con fines comerciales. Se permiten el uso personal, la investigación, la educación, las organizaciones benéficas y las instituciones gubernamentales. Consulte el [texto completo de la licencia](https://polyformproject.org/licenses/noncommercial/1.0.0) para obtener más detalles.