Destiny - Codex

Destiny Codex

Versão 0.5.1.0 (02.07.2026)

Transforme o Manifest do Destiny 2 (JSON de referências por hash ilegível) em texto limpo e legível por IA — com travessia completa de relacionamentos, filtragem estruturada, comparação de itens e extração de rolls de perks de armas.

Destiny Codex é uma ferramenta de CLI e um servidor MCP. Funciona para 100% do manifest — toda tabela de definição é suportada genericamente. Referências por hash são resolvidas automaticamente em nomes legíveis, em ambas as direções.

Changelog

0.5.1.0 (02.07.2026)

Recursos:

• Modo offline — A versão remota do manifest só é verificada quando o cache está ausente ou a última verificação tem mais de 1 hora. Se a Bungie estiver inacessível, o manifest em cache é usado com um aviso. Os comandos ficam mais rápidos e funcionam sem internet.
• Busca reversa rápida de perks — codex perksearch agora usa uma tabela weapon_perks pré-computada no banco de índices em vez de escanear todos os ~40 mil itens por consulta. Execute codex index --rebuild uma vez para atualizar um cache de índices existente (caches mais antigos voltam automaticamente para a varredura completa).
• Saída --json — search, filter, browse, rolls e perksearch aceitam --json para saída estruturada bruta (scripting sem o servidor REST).
• Metadados do manifest por idioma — Alternar idiomas de um lado para o outro não baixa mais o manifest novamente se o banco em cache ainda estiver atualizado.
• Robustez de rede — Todas as chamadas à Bungie agora têm timeouts (15 s para metadados, 120 s para download); o download do manifest tenta novamente até 3× e verifica o cabeçalho do SQLite antes de substituir o cache.
• CI — Workflow do GitHub Actions (build + testes em todo push/PR).

Correções de bugs:

• Filtros por nome de stat — Nomes de stats (--stat "Swing Speed:50", statsByName) agora são resolvidos contra a tabela DestinyStatDefinition do próprio manifest em vez de uma lista fixa que continha hashes errados para Precisão, Taxa de Carregamento, Velocidade de Balanço, Resistência de Guarda e outros. Isso também faz os filtros de stats funcionarem em todos os idiomas do manifest.
• Rótulos itemSubType — O formatador usava um enum errado (ex.: 1: Helmet); substituído pelos valores corretos de DestinyItemSubType (Canhão de Mão, Espada, Glaive, ...).
• Declarações de tipo — dist/api.d.ts agora é realmente emitido (declaration: true); consumidores de biblioteca recebem tipos TypeScript.
• Dependência zod — Declarada explicitamente em vez de depender da cópia transitiva do SDK MCP.
• Completude do filtro — filter não para mais de escanear cedo (limit * 3), o que podia descartar silenciosamente itens correspondentes dependendo da ordem da tabela.
• Validação de nome de tabela — Nomes de tabela vindos de entrada CLI/MCP/REST são validados contra o manifest antes de serem usados em SQL. O servidor REST retorna 400 para tabelas desconhecidas.

Melhorias:

• Lógica de socket compartilhada — rolls, perksearch e a construção do índice weapon_perks agora compartilham uma única implementação de extração de perks sockets.ts em vez de três cópias que podiam divergir.
• Cache de declarações preparadas para consultas de definição (caminhos quentes como rolls, browse, graph não preparam mais o mesmo SQL milhares de vezes).
• O cache de consultas da API agora cobre search, get, resolve, relationships, graph e compare (antes apenas filter/browse/rolls/perksearch).
• enums.ts central para nomes de classe/dano; a saída filter agora mostra class=Titan/dmg=Solar em vez de códigos numéricos; os parâmetros REST class/damage são insensíveis a maiúsculas/minúsculas.
• Testes — Expandidos de 50 para 74, incluindo um banco de dados de manifest em memória de fixture que cobre filter, rolls, perksearch, sockets, relationships e a proteção de validação de tabela. A consistência de versão entre package.json e src/version.ts é garantida por um teste.

---

0.5.0.0 (07.01.2026)

Recursos:

• Ferramenta MCP browse + comando CLI — Navegue por itens com dados de exibição completos: ícones, stats, sockets, tipo de dano, marcas d'água, texto de sabor. Como filter, mas enriquecido para uso visual/exibição.
• Ferramenta MCP compare — Compare 2-6 itens lado a lado via MCP (stats, perks, propriedades em colunas alinhadas). Antes disponível apenas em CLI e REST.
• Ferramenta MCP item — Consulte um item pelo nome e obtenha sua definição legível completa em uma única etapa. Substitui o padrão de duas chamadas busca+obtenção.
• AGENTS.md atualizado — browse.ts e compare.ts agora documentados na seção de arquitetura.

Correções de bugs:

• Ferramenta MCP resolve — Removida consulta desnecessária ao banco de dados que carregava uma definição apenas para descartá-la (void def).

---

Início 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 os comandos abaixo usam o comando global codex. Se preferir não instalá-lo globalmente, você pode sempre executá-lo no local com node dist/index.js <command> a partir da raiz do repositório (ex.: node dist/index.js item Gjallarhorn).

Em vez de config set-key, você também pode fornecer a chave via um arquivo .env (cp .env.example .env, depois defina BUNGIE_API_KEY=...) ou a variável de ambiente BUNGIE_API_KEY.

Comandos CLI

Consulta e Busca

Comando	Descrição
codex item <name>	Consulta um item pelo nome, mostra definição legível completa. Escolhe automaticamente a melhor correspondência.
codex search <query>	Busca por nome (substring, insensível a maiúsculas/minúsculas). -t <table> para filtrar, -l <n> para limite.
codex filter [options]	Filtro estruturado: --tier, --type, --class, --damage, --bucket, --stat.
codex browse [options]	Navegue por itens com dados de exibição completos (ícones, stats, sockets, dano, texto de sabor). Mesmos filtros de filter, mas enriquecido.
codex rolls <name>	Mostra todos os rolls de perks possíveis para uma arma (cano, carregador, traços, mods, catalisador). Responde "o que essa arma pode rolar?"
codex perksearch <perk>	Busca reversa de perks: encontra todas as armas que podem rolar um determinado perk. Alias: perks.
codex get <table> <hash>	Definição legível completa por tabela + hash (todas as referências resolvidas inline).
codex resolve <hash>	Hash puro → resumo curto (detecta tabela automaticamente).
codex raw <table> <hash>	JSON bruto de uma definição.

Relacionamentos e Grafo

Comando	Descrição
codex relationships <table> <hash>	Mostra referências de saída + entrada. Alias: codex rels.
codex graph <table> <hash>	Percorre o grafo de referências como uma árvore. Alias: codex tree.
codex compare <name1> <name2> [name3...]	Compara 2+ itens lado a lado (stats, perks, propriedades).

Gerenciamento

Comando	Descrição
codex sync	Baixa/atualiza o manifest. --force para rebaixar.
codex index	Constrói índices de busca (acelera tudo ~10x). --rebuild para forçar.
codex info	Mostra versão do manifest + lista de tabelas.
codex tables	Lista todas as tabelas de definição.
codex mcp	Inicia o servidor MCP (para integração com ferramentas de IA).
codex serve	Inicia o servidor HTTP da API REST para integração de aplicativos. --port, --host.
codex config set-key <key>	Salva sua chave de API da Bungie.
codex config set-language <lang>	Salva o idioma preferido do manifest (de, fr, es, ja, ...). Execute sync depois.
codex config get-language	Mostra o idioma atualmente salvo.

Exemplos

Consultar um item

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

Navegar (dados de item 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

Relacionamentos (como as coisas se conectam)

# 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

Travessia de grafo

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

Comparar itens

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"

Busca reversa 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"

Suporte a múltiplos idiomas

# 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 ferramentas de IA)

Destiny Codex roda como um servidor MCP via stdio. Assistentes de IA como Devin, Claude e outros podem chamá-lo diretamente.

Iniciar o servidor

codex mcp

Configurar em um cliente MCP

Se você instalou o comando codex globalmente (npm link / npm install -g .), aponte seu cliente MCP diretamente para ele:

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

Se você não o instalou globalmente, execute-o a partir da saída compilada:

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

Ferramentas MCP

Ferramenta	Descrição
manifest_info	Versão do manifest, idioma, lista de tabelas com contagens de linhas. Sincroniza automaticamente.
list_tables	Todas as tabelas de definição.
search	Busca por nome com filtro opcional de tabela.
filter	Consulta estruturada: itemType, tierType, classType, damageType, bucket, faixas de stats.
browse	Dados de item enriquecidos: ícones, stats, sockets, dano, texto de sabor. Mesmos filtros de filter.
rolls	Todos os rolls de perks possíveis para uma arma (cano, carregador, traços, mods, catalisador).
perk_search	Busca reversa de perks: quais armas podem rolar um determinado perk?
item	Consulta item por nome → definição legível completa em uma etapa (correspondência difusa).
compare	Compara 2-6 itens lado a lado (stats, perks, propriedades em colunas).
get	Renderização de texto legível de uma definição (todas as referências de hash resolvidas inline).
resolve	Hash puro → resumo curto.
relationships	Referências de saída + entrada (como as coisas se conectam).
graph	Percorre o grafo de referências N níveis de profundidade como uma árvore.
raw	JSON bruto de uma definição.

Integração de Aplicativos

Destiny Codex pode ser usado como backend no seu próprio aplicativo — sem IA, sem 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 aplicativos web / frontends)

codex serve --port 3000

Todos os endpoints retornam JSON com CORS habilitado:

Endpoint	Descrição
GET /health	Verificação de saúde
GET /api/info	Versão do manifest, idioma, tabelas
GET /api/tables	Todas as tabelas de definição
GET /api/search?q=<name>&table=<t>&limit=<n>	Busca por nome
GET /api/filter?tier=<t>&type=<t>&class=<c>&damage=<d>	Filtro estruturado
GET /api/browse?tier=<t>&type=<t>&class=<c>&damage=<d>	Navegue por itens com dados de exibição completos (ícones, stats, sockets)
GET /api/get/<table>/<hash>	Definição legível
GET /api/resolve/<hash>	Hash puro → resumo
GET /api/rolls/<name-or-hash>	Rolls de perks de armas
GET /api/perksearch/<perk-name-or-hash>	Armas que podem rolar um perk
GET /api/compare?items=<n1,n2,n3>	Comparar itens
GET /api/relationships/<table>/<hash>?direction=<both|outgoing|incoming>	Referências
GET /api/graph/<table>/<hash>?depth=<n>&branch=<n>	Travessia de grafo
GET /api/raw/<table>/<hash>	JSON bruto

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

Como Funciona

O Manifest do Destiny 2 é um banco de dados SQLite com ~83 tabelas de definições JSON. Cada definição está cheia de referências por hash — itemHash: 1363886209, statHash: 155624089, etc. — que são sem sentido sem consultar o destino.

Destiny Codex:

1. Baixa o manifest da API da Bungie e o armazena em cache localmente como SQLite.
2. Constrói índices (hash→tabela direto, índice de nomes, índice de referências reversas) armazenados como um banco SQLite versionado.
3. Resolve referências por hash de duas maneiras:
   • Heurística de nome de campo: itemHash → DestinyInventoryItemDefinition (rápido, sem necessidade de consulta)
   • Fallback de índice reverso: qualquer hash → sua tabela (lida com nomes de campo desconhecidos)
4. Formata definições como texto limpo e indentado com referências de hash substituídas por "Gjallarhorn" (hash 1363886209, DestinyInventoryItemDefinition) inline.
5. Percorre o grafo de referências em ambas as direções: saída (o que X referencia?) e entrada (quem referencia X?).

Desempenho

Operação	Tempo
Download do manifest	~10s (37 MB compactado)
Construção de índices	~15s (uma vez por versão do manifest)
codex search (com índice)	~1.3s
codex rels (com índice)	~1.2s
codex graph (com índice)	~1.2s
codex filter	~0.3s
codex perksearch (com índice)	~1s

Requisitos

• Node.js 22.5+ (usa node:sqlite integrado). No Node 22/23 pode exigir a flag --experimental-sqlite; no Node 24+ é estável.
• Uma chave de API da Bungie.net (gratuita, obtenha uma em https://www.bungie.net/en/Application)

## Licença

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

Este software **nunca** pode ser usado para fins comerciais. Uso pessoal,
pesquisa, educação, organizações de caridade e instituições governamentais
são permitidos. Veja o [texto completo da licença](https://polyformproject.org/licenses/noncommercial/1.0.0)
para detalhes.