POB-MCP

Carregue, inspecione e otimize builds de Path of Exile 2 usando o mecanismo de cálculo real do Path of Building.

GitHub
3
Experimente este MCPPatrocinado

Documentação

pob-mcp

License: MIT Python 3.12+ PRs welcome Support on Ko-fi

pob-mcp é um servidor MCP. Ele permite que um LLM carregue, inspecione, altere e melhore builds de Path of Exile 2. Ele usa o motor de cálculo real do Path of Building Community (fork PoE2). Ele não reimplementa esse motor.

pob-mcp executa uma cópia real e headless do PoB (um programa Lua) como um processo em segundo plano. Ele se comunica com esse processo por meio de um pequeno protocolo JSON-RPC. Cada estatística que você recebe é um número que o próprio PoB calculou.

Como funciona

MCP client (Claude Desktop, Cursor, ...)
        |  MCP over stdio
        v
   pob-mcp (Python)  -- tools_*.py, optimizer/
        |  JSON-RPC over stdio
        v
   lua/pob_bridge.lua  (running under `luajit`)
        |  dofile()
        v
   Path of Building - PoE2's own Lua source (Launch.lua, Main.lua, ...)

lua/pob_bridge.lua é um fork do próprio src/HeadlessWrapper.lua do PoB, que o PoB usa em sua suíte de testes. O pob-mcp não depende desse arquivo diretamente. Cópias instaladas do PoB deixam HeadlessWrapper.lua de fora (veja manifest.cfg), então o pob-mcp traz sua própria versão. Isso significa que o pob-mcp funciona da mesma forma tanto com um checkout git do PathOfBuilding-PoE2 quanto com uma versão de lançamento instalada.

Antes de começar

Você precisa de quatro coisas:

  1. Uma forma de instalar um pacote Python. Recomendamos uv — é o caminho mais rápido e o que o restante deste README mostra primeiro. Não quer outra ferramenta na sua máquina? Um pip simples e um ambiente virtual funcionam bem também; veja os comandos alternativos abaixo.
  2. LuaJIT, uma build compatível com 5.1. Coloque-o no seu PATH como luajit, ou aponte para ele com POB_MCP_LUAJIT. Você precisa disso separadamente do próprio PoB: o runtime do PoB só inclui lua51.dll/SimpleGraphic.dll para seu aplicativo gráfico. Ele não inclui um interpretador de linha de comando que você possa executar sozinho.
    • Windows: instale com Scoop (scoop install luajit), Chocolatey (choco install luajit), ou uma build portátil.
    • macOS: brew install luajit.
    • Linux: apt install luajit, o equivalente para sua distribuição, ou compile a partir do código-fonte.
  3. Uma instalação do Path of Building - PoE2. Pode ser um checkout git (este repositório, ou seu próprio clone) ou uma versão de lançamento instalada. Veja "Aponte o pob-mcp para uma instalação do PoB" abaixo.
  4. zlib. O pob-mcp precisa disso para ler e escrever códigos de build, e para calcular dados de Joias Atemporais. No Windows, você já tem isso: o PoB inclui zlib1.dll (em runtime/ para um checkout, ou junto com todo o resto para uma versão de lançamento instalada). No Linux e macOS, instale o pacote zlib/libz do seu sistema se você ainda não tiver (a maioria dos sistemas já tem). Se o pob-mcp não encontrar o zlib, tudo continua funcionando, exceto códigos de build colados ou compartilhados e cálculos de Joias Atemporais. Carregue e exporte builds como arquivos .xml.

Aponte o pob-mcp para uma instalação do PoB

O pob-mcp precisa saber onde sua instalação do Path of Building - PoE2 mantém o código-fonte Lua, porque é contra isso que o processo de ponte executa. Existem duas formas de apontar para lá. Observe que as duas têm layouts diferentes em disco — o pob-mcp detecta automaticamente qual você está usando.

  • Modo checkout de desenvolvimento. Defina POB_MCP_SOURCE_DIR para um checkout git do PathOfBuilding-PoE2 — seja sua pasta raiz, ou sua pasta src diretamente. Esse layout mantém o código-fonte Lua em src/, e mantém o runtime nativo (DLLs do LuaJIT, zlib, as bibliotecas Lua incluídas) em uma pasta runtime/ separada ao lado.
  • Modo de lançamento. Defina POB_MCP_INSTALL_DIR para a pasta raiz de uma versão de lançamento instalada. No Windows, isso geralmente é %APPDATA%\Path of Building Community (PoE2). Uma versão de lançamento instalada coloca tudo em uma pasta — Launch.lua, Modules/, zlib1.dll, as bibliotecas lua/ incluídas — em vez de dividir. (Verificamos isso contra uma instalação real. Não apenas adivinhamos a partir da configuração de empacotamento do repositório.)

Se você não definir nenhuma das variáveis, o pob-mcp verifica alguns locais de instalação comuns para seu sistema operacional e mostra um erro claro se não encontrar nenhum. No Windows, isso já encontra uma cópia instalada normalmente sem nenhuma configuração da sua parte.

Instale o pob-mcp

git clone <this repo, or wherever you put pob-mcp> pob-mcp
cd pob-mcp
uv sync

Não quer usar uv? Você não precisa. O pob-mcp é um pacote Python normal — um pip simples também funciona:

git clone <this repo, or wherever you put pob-mcp> pob-mcp
cd pob-mcp
python -m venv .venv
.venv/bin/pip install -e .        # Windows: .venv\Scripts\pip install -e .

Execute sozinho (para testes)

POB_MCP_SOURCE_DIR=/path/to/PathOfBuilding-PoE2 uv run pob-mcp
# or, against an installed release:
POB_MCP_INSTALL_DIR="C:\Users\you\AppData\Roaming\Path of Building Community (PoE2)" uv run pob-mcp

Com uma instalação pip simples, a mesma coisa fica assim:

POB_MCP_SOURCE_DIR=/path/to/PathOfBuilding-PoE2 .venv/bin/pob-mcp   # Windows: .venv\Scripts\pob-mcp.exe

Isso inicia o servidor MCP via stdio. Você não verá muita coisa acontecer — servidores MCP conversam com clientes MCP, não diretamente com você. Veja "Verifique se funciona," abaixo, para uma forma de testar sem um cliente completo.

Use com Claude Desktop, Cursor ou outro cliente MCP

Adicione uma entrada à configuração do servidor MCP do seu cliente. Para Claude Desktop, isso é claude_desktop_config.json. Para Cursor, é mcp.json.

{
  "mcpServers": {
    "pob-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/pob-mcp", "run", "pob-mcp"],
      "env": {
        "POB_MCP_SOURCE_DIR": "/absolute/path/to/PathOfBuilding-PoE2"
      }
    }
  }
}

Para o modo de lançamento, use POB_MCP_INSTALL_DIR em vez disso. Aponte para a pasta raiz da sua versão de lançamento instalada — no Windows, geralmente %APPDATA%\Path of Building Community (PoE2):

{
  "mcpServers": {
    "pob-mcp": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\pob-mcp", "run", "pob-mcp"],
      "env": {
        "POB_MCP_INSTALL_DIR": "C:\\Users\\you\\AppData\\Roaming\\Path of Building Community (PoE2)"
      }
    }
  }
}

Reinicie seu cliente depois de editar a configuração. Você não precisa fechar o Path of Building em si. O pob-mcp apenas lê dados do jogo da pasta de instalação. Ele nunca escreve nela, então funciona bem junto com o aplicativo.

Com uma instalação pip simples (sem uv), aponte command diretamente para o executável que o pip criou no seu ambiente virtual — sem precisar de args:

{
  "mcpServers": {
    "pob-mcp": {
      "command": "C:\\path\\to\\pob-mcp\\.venv\\Scripts\\pob-mcp.exe",
      "env": {
        "POB_MCP_INSTALL_DIR": "C:\\Users\\you\\AppData\\Roaming\\Path of Building Community (PoE2)"
      }
    }
  }
}

(No macOS/Linux, isso é /path/to/pob-mcp/.venv/bin/pob-mcp.)

Variáveis de ambiente

VariávelO que faz
POB_MCP_SOURCE_DIRCaminho para um checkout git do PathOfBuilding-PoE2 (sua pasta raiz ou src/)
POB_MCP_INSTALL_DIRCaminho para a pasta raiz de uma versão de lançamento instalada
POB_MCP_LUAJITCaminho para um executável luajit, se não estiver no PATH
POB_MCP_ZLIB_PATHCaminho ou nome para carregar o zlib, se o pob-mcp não conseguir encontrá-lo sozinho
POB_MCP_BUILDS_DIRCaminho para sua pasta de Builds do PoB, para list_local_builds
POB_MCP_LOG_LEVELNível de log para o lado Python (padrão INFO); a saída da ponte é registrada em DEBUG

O que você pode fazer com ele

Assim que seu cliente estiver conectado, comece com load_build. Depois use as outras ferramentas para inspecionar, alterar e melhorar o build. Toda ferramenta que altera o build também retorna seu stats atualizado, então você não precisa de uma chamada separada de get_stats para ver o efeito de uma mudança. A descrição completa de cada ferramenta (parâmetros, comportamento, casos extremos) aparece no seu cliente MCP — as listas abaixo são apenas nomes e um resumo de uma linha, para ajudar você a encontrar a certa.

Uma nota sobre ids: gems e classes são identificadas por um id interno, não pelo nome de exibição. O id da gem da Fireball, por exemplo, é "Metadata/Items/Gems/SkillGemFireball", e select_class recebe um id de classe interno, não um índice simples baseado em 0. Use list_gems e list_classes para consultar esses valores em vez de adivinhar — um id de gem errado não gera erro, apenas falha silenciosamente ao resolver, então a gem não faz nada.

Carregar um build (3 ferramentas)
FerramentaO que faz
load_buildCarrega um build a partir de um código de exportação do PoB, um link pobb.in/Maxroll/poe.ninja/poe2db.tw/Pastebin.com/Rentry.co, um caminho local de .xml ou texto XML bruto
new_buildInicia um build novo e em branco (classe padrão, sem itens ou habilidades)
list_local_buildsLista arquivos .xml na sua pasta de Builds do PoB
Inspecionar um build (13 ferramentas)
FerramentaO que faz
get_statsObtém estatísticas calculadas (vida, ES, mana, resistências, DPS, EHP, etc.) do motor real do PoB
list_stat_keysLista todas as chaves de estatísticas disponíveis em get_stats para este build
get_characterObtém classe, ascendência e nível
list_classesLista todas as classes e suas ascendências, para uso com select_class
get_tree_stateObtém os ids dos nós da árvore passiva alocados e a contagem
node_infoObtém detalhes de um nó da árvore passiva
search_treePesquisa a árvore passiva por nome, texto de estatística, tipo ou ascendência
get_itemsLista todos os slots de equipamento/joia e o que há neles
get_skillsLista grupos de habilidades/encaixes e suas gems
list_gemsConsulta o id interno de uma gem, para uso com add_gem
get_configObtém os valores atuais das opções de configuração
list_config_optionsLista todas as opções de configuração que o PoB suporta
sanity_checkExecuta verificações defensivas de sanidade (resistências sem limite, vida baixa, etc.)
Alterar um build (13 ferramentas)
FerramentaO que faz
alloc_node / dealloc_nodeAloca ou desaloca um nó da árvore passiva (caminho calculado automaticamente)
node_path_costObtém o custo em pontos para alcançar um nó, sem alocá-lo
select_classAltera classe e/ou ascendência
equip_item_raw / unequip_itemEquipa texto bruto de item do jogo em um slot, ou remove o que está lá
add_socket_groupCria um novo grupo de habilidades/encaixes vazio
set_main_skillDefine qual grupo de encaixes é usado para cálculos de DPS
add_gem / remove_gem / set_gemAdiciona, remove ou edita o nível/qualidade/estado ativo de uma gem
list_valid_supportsLista gems de suporte que o PoB considera válidas para uma habilidade
set_configDefine uma opção de configuração
Gerenciar especificações de árvore e conjuntos de equipamento (12 ferramentas)

Um build pode conter várias especificações de árvore passiva nomeadas e vários conjuntos de equipamento nomeados, e alternar entre eles. Depois que você alterna um, toda outra ferramenta (get_tree_state, get_items e assim por diante) age sobre aquele para o qual você alternou.

FerramentaO que faz
list_specsLista as especificações de árvore passiva do build
select_specAlterna a especificação de árvore passiva ativa
create_specCria uma nova especificação de árvore passiva em branco
copy_specDuplica uma especificação de árvore passiva
rename_specRenomeia uma especificação de árvore passiva
delete_specExclui uma especificação de árvore passiva (um build sempre precisa de pelo menos uma)
list_item_setsLista os conjuntos de equipamento do build
select_item_setAlterna o conjunto de equipamento ativo
create_item_setCria um novo conjunto de equipamento vazio
copy_item_setDuplica um conjunto de equipamento
rename_item_setRenomeia um conjunto de equipamento
delete_item_setExclui um conjunto de equipamento (um build sempre precisa de pelo menos um)
Melhorar um build (1 ferramenta)
FerramentaO que faz
optimize_buildExecuta uma busca orientada a objetivos (damage/defence/balanced) pela árvore passiva, gems de suporte e itens únicos locais, pontuando cada mudança candidata contra o motor real do PoB
Comparar ou exportar (2 ferramentas)
FerramentaO que faz
compare_buildsCompara dois builds lado a lado, sem tocar no build carregado nesta sessão
export_buildExporta o build carregado como XML ou um código compartilhável

O que isso não faz (de propósito)

Estas são escolhas, não bugs:

  • O otimizador nunca altera opções de configuração (buffs, maldições, estatísticas de inimigos, mods de mapa). Se pudesse, poderia aumentar sua própria pontuação assumindo um cenário irrealista. Chame set_config você mesmo primeiro se quiser otimizar para um cenário específico.
  • A busca por itens e joias usa apenas o banco de dados local do PoB. O escopo items do optimize_build tenta itens do banco de dados exclusivo do próprio PoB, para o mesmo slot. Não verifica preços em sites de trade e não busca opções de crafting de itens raros.
  • O otimizador não busca joias por conta própria. Combinar uma joia ao soquete certo ainda não é confiável o suficiente. Você ainda pode tentar uma joia específica manualmente: use list_uniques_for_slot e depois equip_item_raw.
  • O otimizador é uma busca gulosa, não um solucionador perfeito. Ele apenas adiciona nós da árvore — nunca remove ou substitui os existentes — e só troca uma gema ou item por vez. Ele pode ficar preso em uma resposta boa-mas-não-melhor que uma busca mais ampla poderia superar.
  • pob-mcp não consegue importar um perfil de personagem ao vivo do poe.ninja. Ele pode importar um pob-link do poe.ninja como qualquer outro site suportado, mas um perfil de personagem ao vivo é diferente: ele precisa da API oficial de personagens, e esta versão ainda não fala com essa API. Exporte o personagem para um código ou link do PoB primeiro e use isso em vez disso.
  • pob-mcp não monitora sua pasta Builds em busca de alterações. list_local_builds lista o que está lá quando você o chama. Ele não envia atualizações quando algo muda. Para uma sessão orientada por LLM, chamar a ferramenta novamente é mais simples e funciona igualmente bem.

Verifique se funciona

Testes automatizados (executados com uv run pytest) vêm em dois grupos:

  • Testes que não tocam no PoB (test_importers.py, test_optimizer_goals.py, test_optimizer_moves.py, test_locate.py). Eles rodam em qualquer lugar — você não precisa de LuaJIT ou de uma instalação do PoB.
  • test_bridge_protocol.py executa um processo de ponte real do início ao fim: inicia um novo build, busca na árvore, aloca e desaloca nós, salva e recarrega, lista opções de configuração e executa uma verificação de sanidade. Se não conseguir encontrar POB_MCP_SOURCE_DIR, POB_MCP_INSTALL_DIR ou um executável luajit, ele se pula e informa o motivo. Defina essas variáveis de ambiente para realmente executá-lo.

Para testar a ponte manualmente, sem um cliente MCP completo:

cd /path/to/PathOfBuilding-PoE2/src
luajit /absolute/path/to/pob-mcp/lua/pob_bridge.lua

Depois digite (ou envie via pipe) solicitações JSON-RPC, uma por linha:

{"id": 1, "method": "new_build", "params": {}}
{"id": 2, "method": "get_stats", "params": {}}

Cada uma deve imprimir de volta uma linha {"id": ..., "result": {...}}.

Onde as coisas ficam

pob-mcp/
  lua/
    json.lua          # self-contained JSON codec for the bridge protocol
    pob_bridge.lua     # the headless PoB bridge + JSON-RPC loop
  src/pob_mcp/
    server.py          # MCP server entrypoint, tool registration
    bridge.py           # subprocess + JSON-RPC client for pob_bridge.lua
    locate.py           # finds a PoB install + luajit
    sites.py            # pobb.in/Maxroll/poe.ninja/etc. URL -> build code
    importers.py         # unifies code/URL/file/XML into one load_build path
    tools_*.py            # MCP tool definitions, grouped by area
    optimizer/             # goal-directed build search
  tests/