pob-mcp

pob-mcp 是一个 MCP 服务器。它允许 LLM 加载、检查、修改和改进 流放之路 2 的构建。它使用来自 Path of Building Community (PoE2 分支) 的真实计算引擎，而不是重新实现该引擎。

pob-mcp 运行一个真实的、无头版本的 PoB（一个 Lua 程序）作为后台进程。它通过一个小型的 JSON-RPC 协议与该进程通信。你拿到的每一个统计数据都是 PoB 自身计算出的数字。

工作原理

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 是 PoB 自身 src/HeadlessWrapper.lua 的一个分支，PoB 在其测试套件中使用该文件。pob-mcp 并不直接依赖该文件。已安装的 PoB 副本会排除 HeadlessWrapper.lua（参见 manifest.cfg），因此 pob-mcp 自带了自己的版本。这意味着 pob-mcp 对 PathOfBuilding-PoE2 的 git 检出和已安装的发布版本都能以相同的方式工作。

开始之前

你需要四样东西：

1. uv。用它来安装和运行 pob-mcp。

2. LuaJIT，一个兼容 5.1 的构建版本。将其放在 PATH 中，命名为 luajit，或者通过 POB_MCP_LUAJIT 指向它。你需要单独安装它，因为 PoB 自身的运行时仅提供 lua51.dll/SimpleGraphic.dll 用于其图形应用程序，并未提供可独立运行的命令行解释器。

   • Windows：通过 Scoop（scoop install luajit）、Chocolatey（choco install luajit）或便携版安装。

   • macOS：brew install luajit。

   • Linux：apt install luajit，或使用你发行版对应的命令，或者从源码编译。

3. Path of Building - PoE2 安装。可以是 git 检出（此仓库或你自己的克隆），也可以是已安装的发布版本。请参见下方“将 pob-mcp 指向 PoB 安装目录”。

4. zlib。pob-mcp 需要它来读取和写入构建代码，以及计算永恒珠宝数据。在 Windows 上，你已拥有它：PoB 捆绑了 zlib1.dll（对于检出版本在 runtime/ 中，对于已安装的发布版本则与其他文件放在一起）。在 Linux 和 macOS 上，如果尚未安装，请安装你系统的 zlib/libz 包（大多数系统已安装）。如果 pob-mcp 找不到 zlib，除了粘贴或共享的构建代码以及永恒珠宝计算外，其他所有功能仍能正常工作。请使用 .xml 文件加载和导出构建。

将 pob-mcp 指向 PoB 安装目录

pob-mcp 需要知道你的 Path of Building - PoE2 安装目录存放 Lua 源码的位置，因为桥接进程就是针对这些源码运行的。有两种方式可以指向它。请注意，这两种方式在磁盘上的布局不同——pob-mcp 会自动检测你使用的是哪一种。

• 开发检出模式。将 POB_MCP_SOURCE_DIR 设置为 PathOfBuilding-PoE2 git 检出的根目录或其 src 目录。这种布局将 Lua 源码放在 src/ 下，并将原生运行时（LuaJIT DLL、zlib、捆绑的 Lua 库）放在一个单独的 runtime/ 文件夹中。

• 发布版本模式。将 POB_MCP_INSTALL_DIR 设置为已安装发布版本的根目录。在 Windows 上，通常是 %APPDATA%\Path of Building Community (PoE2)。已安装的发布版本将所有内容放在一个文件夹中——Launch.lua、Modules/、zlib1.dll、捆绑的 lua/ 库——而不是分散放置。（我们已根据真实安装进行了验证，并非仅凭仓库的打包配置猜测。）

如果你未设置这两个变量中的任何一个，pob-mcp 会检查操作系统上的几个常见安装位置，如果找不到，则会给出明确的错误信息。在 Windows 上，这通常无需任何设置即可找到通过普通安装程序安装的副本。

安装 pob-mcp

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

独立运行（用于测试）

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

这将通过 stdio 启动 MCP 服务器。你不会看到太多输出——MCP 服务器与 MCP 客户端通信，而不是直接与你交互。请参见下方“检查是否正常工作”以了解无需完整客户端即可尝试的方法。

在 Claude Desktop、Cursor 或其他 MCP 客户端中使用

在客户端的 MCP 服务器配置中添加一个条目。对于 Claude Desktop，这是 claude_desktop_config.json。对于 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"
      }
    }
  }
}

对于发布版本模式，使用 POB_MCP_INSTALL_DIR 代替。将其指向已安装发布版本的根目录——在 Windows 上，通常是 %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)"
      }
    }
  }
}

编辑配置后重新启动客户端。你无需关闭 Path of Building 本身。pob-mcp 仅从安装目录读取游戏数据，从不写入，因此它可以与应用程序并行运行。

环境变量

你可以用它做什么

客户端连接后，从 load_build 开始。然后使用其他工具检查、修改和改进构建：

• 加载构建：load_build（接受 PoB 导出代码、pobb.in/Maxroll/poe.ninja pob-link/poe2db.tw/Pastebin.com/Rentry.co 链接、本地 .xml 文件路径或原始 XML 文本）、new_build、list_local_builds。

• 检查构建：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。

• 修改构建：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。

  关于宝石的说明：每个宝石都有一个内部 ID，该 ID 与其显示名称不同。例如，火球的 ID 是 "Metadata/Items/Gems/SkillGemFireball"。使用 list_gems 查找正确的 ID——不要猜测。错误的猜测不会引发错误，只会静默解析失败，因此宝石不生效。职业也是如此：select_class 接受一个内部职业 ID，而不是简单的从 0 开始的索引。使用 list_classes 查找它。

• 改进构建：optimize_build(goal="damage"|"defence"|"balanced", scope=[...]) 在被动天赋树、辅助宝石和本地暗金物品上运行目标导向搜索。它会对每个候选改动使用 PoB 的真实引擎进行检查。请在你的 MCP 客户端中查看其完整描述，包括它有意不修改的部分。

• 比较或导出：compare_builds、export_build。

每个修改构建的工具也会返回更新后的 stats。你无需单独调用 get_stats 来查看修改效果。

此工具不做什么（有意为之）

这些是设计选择，而非缺陷：

• 优化器从不更改配置选项（增益、诅咒、敌人属性、地图词缀）。如果它可以更改，它可能会通过假设不现实的场景来提高自身分数。如果你想针对某个特定场景进行优化，请先自行调用 set_config。

• 物品和珠宝搜索仅使用 PoB 的本地数据库。 optimize_build 的 items 范围会尝试 PoB 自身捆绑的暗金数据库中的物品（针对同一位置）。它不检查交易网站价格，也不搜索稀有物品的工艺选项。

• 优化器不会自行搜索珠宝。 将珠宝匹配到正确的插槽目前还不够可靠。你仍然可以手动尝试特定的珠宝：使用 list_uniques_for_slot，然后使用 equip_item_raw。

• 优化器是贪心搜索，而非完美求解器。 它只添加天赋节点——从不移除或替换现有节点——并且一次只替换一个宝石或物品。它可能会卡在一个不错但不是最佳的答案上，而更广泛的搜索可能会击败它。

• pob-mcp 无法导入实时 poe.ninja 角色档案。 它可以像其他受支持的网站一样导入 poe.ninja pob-link，但实时角色档案不同：它需要官方角色 API，而此版本尚未与该 API 通信。请先将角色导出为 PoB 代码或链接，然后使用该代码或链接。

• pob-mcp 不会监视你的 Builds 文件夹的变化。 list_local_builds 会列出你调用时文件夹中的内容。当有变化时，它不会推送更新。对于 LLM 驱动的会话，再次调用该工具更简单，效果也一样好。

检查是否正常工作

自动化测试（使用 uv run pytest 运行）分为两组：

• 完全不涉及 PoB 的测试（test_importers.py、test_optimizer_goals.py、test_optimizer_moves.py、test_locate.py）。这些测试在任何地方都可以运行——你不需要 LuaJIT 或 PoB 安装。

• test_bridge_protocol.py 从开始到结束运行一个真实的桥接进程：它启动一个新构建，搜索天赋树，分配和取消分配节点，保存并重新加载，列出配置选项，并运行一个健全性检查。如果找不到 POB_MCP_SOURCE_DIR、POB_MCP_INSTALL_DIR 或 luajit 可执行文件，它会跳过自身并告诉你原因。设置这些环境变量以实际运行它。

要手动尝试桥接（无需完整 MCP 客户端）：

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

然后输入（或通过管道输入）JSON-RPC 请求，每行一个：

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

每个请求都应打印回一行 {"id": ..., "result": {...}}。

文件位置

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/