pob-mcp

pob-mcp es un servidor MCP. Permite a un LLM cargar, inspeccionar, modificar y mejorar builds de Path of Exile 2. Utiliza el motor de cálculo real de Path of Building Community (fork de PoE2). No reimplementa ese motor.

pob-mcp ejecuta una copia real y sin interfaz gráfica de PoB (un programa Lua) como proceso en segundo plano. Se comunica con ese proceso mediante un pequeño protocolo JSON-RPC. Cada estadística que obtienes es un número que el propio PoB ha calculado.

Cómo 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 es un fork de src/HeadlessWrapper.lua de PoB, que PoB utiliza para su suite de pruebas. pob-mcp no depende directamente de ese archivo. Las copias instaladas de PoB omiten HeadlessWrapper.lua (consulta manifest.cfg), por lo que pob-mcp incluye su propia versión. Esto significa que pob-mcp funciona de la misma manera tanto con un checkout de git de PathOfBuilding-PoE2 como con una versión de lanzamiento instalada.

Antes de empezar

Necesitas cuatro cosas:

1. uv. Úsalo para instalar y ejecutar pob-mcp.

2. LuaJIT, una compilación compatible con 5.1. Ponlo en tu PATH como luajit, o apunta a él con POB_MCP_LUAJIT. Lo necesitas por separado de PoB: el runtime de PoB solo incluye lua51.dll/SimpleGraphic.dll para su aplicación gráfica. No incluye un intérprete de línea de comandos que puedas ejecutar por sí solo.

   • Windows: instálalo con Scoop (scoop install luajit), Chocolatey (choco install luajit), o una compilación portátil.

   • macOS: brew install luajit.

   • Linux: apt install luajit, el equivalente para tu distribución, o compílalo desde el código fuente.

3. Una instalación de Path of Building - PoE2. Puede ser un checkout de git (este repositorio, o tu propio clon) o una versión de lanzamiento instalada. Consulta "Apuntar pob-mcp a una instalación de PoB" más abajo.

4. zlib. pob-mcp lo necesita para leer y escribir códigos de build, y para calcular datos de Joyas Atemporales. En Windows ya lo tienes: PoB incluye zlib1.dll (en runtime/ para un checkout, o junto a todo lo demás para una versión de lanzamiento instalada). En Linux y macOS, instala el paquete zlib/libz de tu sistema si aún no lo tienes (la mayoría de los sistemas lo tienen). Si pob-mcp no encuentra zlib, todo sigue funcionando excepto los códigos de build pegados o compartidos y los cálculos de Joyas Atemporales. Carga y exporta builds como archivos .xml en su lugar.

Apuntar pob-mcp a una instalación de PoB

pob-mcp necesita saber dónde tu instalación de Path of Building - PoE2 guarda su código fuente Lua, porque es contra lo que se ejecuta el proceso puente. Hay dos formas de indicarlo. Ten en cuenta que las dos tienen diseños diferentes en disco — pob-mcp detecta automáticamente cuál estás usando.

• Modo de checkout de desarrollo. Establece POB_MCP_SOURCE_DIR en un checkout de git de PathOfBuilding-PoE2 — ya sea su carpeta raíz, o su carpeta src directamente. Este diseño mantiene el código fuente Lua en src/, y el runtime nativo (DLLs de LuaJIT, zlib, las librerías Lua incluidas) en una carpeta runtime/ separada al lado.

• Modo de lanzamiento. Establece POB_MCP_INSTALL_DIR en la carpeta raíz de una versión de lanzamiento instalada. En Windows, suele ser %APPDATA%\Path of Building Community (PoE2). Una versión de lanzamiento instalada pone todo en una sola carpeta — Launch.lua, Modules/, zlib1.dll, las librerías lua/ incluidas — en lugar de dividirlo. (Lo comprobamos con una instalación real. No lo adivinamos solo a partir de la configuración de empaquetado del repositorio).

Si no estableces ninguna variable, pob-mcp comprueba algunas ubicaciones de instalación comunes para tu sistema operativo, y te da un error claro si no encuentra ninguna. En Windows, esto ya encuentra una copia instalada con el instalador normal sin ninguna configuración de tu parte.

Instalar pob-mcp

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

Ejecutarlo por sí solo (para pruebas)

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

Esto inicia el servidor MCP sobre stdio. No verás mucho — los servidores MCP se comunican con clientes MCP, no directamente contigo. Consulta "Comprobar que funciona", más abajo, para una forma de probarlo sin un cliente completo.

Usarlo con Claude Desktop, Cursor u otro cliente MCP

Añade una entrada a la configuración del servidor MCP de tu cliente. Para Claude Desktop, es claude_desktop_config.json. Para Cursor, es 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 el modo de lanzamiento, usa POB_MCP_INSTALL_DIR en su lugar. Apúntalo a la carpeta raíz de tu versión de lanzamiento instalada — en Windows, normalmente %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)"
      }
    }
  }
}

Reinicia tu cliente después de editar su configuración. No necesitas cerrar Path of Building. pob-mcp solo lee datos del juego de la carpeta de instalación. Nunca escribe en ella, por lo que funciona bien junto a la aplicación.

Variables de entorno

Qué puedes hacer con ello

Una vez que tu cliente esté conectado, empieza con load_build. Luego usa las otras herramientas para inspeccionar, modificar y mejorar la build:

• Cargar una build: load_build (acepta un código de exportación de PoB, un enlace pobb.in/Maxroll/poe.ninja pob-link/poe2db.tw/Pastebin.com/Rentry.co, una ruta de archivo .xml local, o texto XML sin procesar), new_build, list_local_builds.

• Inspeccionar una build: get_stats, list_stat_keys, get_character, list_classes, get_tree_state, node_info, search_tree, get_items, get_skills, list_gems, get_config, list_config_options, sanity_check.

• Modificar una build: alloc_node/dealloc_node, node_path_cost, select_class, equip_item_raw/unequip_item, add_socket_group, set_main_skill, add_gem/remove_gem/set_gem, list_valid_supports, set_config.

  Una nota sobre las gemas: cada gema tiene un id interno, y ese id no es el mismo que su nombre mostrado. El id de Bola de Fuego, por ejemplo, es "Metadata/Items/Gems/SkillGemFireball". Usa list_gems para buscar el id correcto — no lo adivines. Una suposición incorrecta no genera un error. Simplemente falla silenciosamente al resolver, por lo que la gema no hace nada. Lo mismo ocurre con las clases: select_class toma un id de clase interno, no un índice simple basado en 0. Usa list_classes para encontrarlo.

• Mejorar una build: optimize_build(goal="damage"|"defence"|"balanced", scope=[...]) ejecuta una búsqueda dirigida por objetivos sobre el árbol pasivo, las gemas de apoyo y los objetos únicos locales. Comprueba cada cambio candidato contra el motor real de PoB. Consulta su propia descripción en tu cliente MCP para obtener todos los detalles, incluyendo lo que deliberadamente deja intacto.

• Comparar o exportar: compare_builds, export_build.

Cada herramienta que modifica la build también devuelve sus stats actualizados. No necesitas una llamada separada a get_stats para ver el efecto de un cambio.

Lo que esto no hace (a propósito)

Son elecciones, no errores:

• El optimizador nunca cambia las opciones de configuración (buffs, maldiciones, estadísticas de enemigos, modificadores de mapa). Si pudiera, podría aumentar su propia puntuación asumiendo un escenario poco realista. Llama a set_config tú mismo primero si quieres optimizar para un escenario específico.

• La búsqueda de objetos y joyas solo usa la base de datos local de PoB. El ámbito items de optimize_build prueba objetos de la propia base de datos de únicos incluida de PoB, para la misma ranura. No comprueba precios de sitios de comercio, ni busca opciones de crafteo de objetos raros.

• El optimizador no busca joyas por sí mismo. Emparejar una joya con el socket correcto aún no es lo suficientemente fiable. Aún puedes probar una joya específica manualmente: usa list_uniques_for_slot, luego equip_item_raw.

• El optimizador es una búsqueda voraz, no un solucionador perfecto. Solo añade nodos del árbol — nunca elimina ni reemplaza los existentes — y solo intercambia una gema o un objeto a la vez. Puede quedarse atascado en una respuesta buena pero no óptima que una búsqueda más amplia podría superar.

• pob-mcp no puede importar un perfil de personaje en vivo de poe.ninja. Puede importar un pob-link de poe.ninja como cualquier otro sitio compatible, pero un perfil de personaje en vivo es diferente: necesita la API oficial de personajes, y esta versión aún no se comunica con esa API. Exporta el personaje a un código o enlace de PoB primero, y usa eso en su lugar.

• pob-mcp no vigila tu carpeta de Builds para detectar cambios. list_local_builds lista lo que hay cuando lo llamas. No envía actualizaciones cuando algo cambia. Para una sesión impulsada por LLM, volver a llamar a la herramienta es más simple y funciona igual de bien.

Comprobar que funciona

Las pruebas automatizadas (ejecutadas con uv run pytest) vienen en dos grupos:

• Pruebas que no tocan PoB en absoluto (test_importers.py, test_optimizer_goals.py, test_optimizer_moves.py, test_locate.py). Estas se ejecutan en cualquier lugar — no necesitas LuaJIT ni una instalación de PoB.

• test_bridge_protocol.py ejecuta un proceso puente real de principio a fin: inicia una nueva build, busca en el árbol, asigna y desasigna nodos, guarda y recarga, lista opciones de configuración, y ejecuta una comprobación de cordura. Si no encuentra POB_MCP_SOURCE_DIR, POB_MCP_INSTALL_DIR, o un ejecutable luajit, se omite a sí mismo y te dice por qué. Establece esas variables de entorno para ejecutarlo realmente.

Para probar el puente manualmente, sin un cliente MCP completo:

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

Luego escribe (o pasa por tubería) solicitudes JSON-RPC, una por línea:

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

Cada una debería imprimir una línea {"id": ..., "result": {...}}.

Dónde están las cosas

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/