pob2 MCP

构建PoE2的路径-API和MCP服务器

用于建筑物路径PoE2计算引擎的REST API和MCP（模型上下文协议）服务器。允许您以编程方式创建构建、分配被动节点、装备物品、添加技能和读取计算统计数据。

先决条件

• LuaJIT：需要作为独立解释器（请参阅下面特定于平台的说明）
• Python 3.10+：需要 mcp 软件开发工具包
• Python依赖关系: pip install -r api/requirements.txt

安装LuaJIT

PoB Windows应用程序将LuaJIT捆绑在其GUI可执行文件中(runtime/Path of Building-PoE2.exe)，但API需要一个独立的 luajit 口译员。

macOS：

brew install luajit

窗户：

scoop install luajit

或

choco install luajit

或从下载二进制文件https://luajit.org/download.html.确保 luajit.exe 在您的路径上，或设置 LUAJIT_PATH 环境变量。

Linux：

sudo apt install luajit    # Debian/Ubuntu
sudo pacman -S luajit      # Arch

快速开始

REST API

python api/run_api.py

服务器启动于 http://127.0.0.1:8000.测试它：

# Health check
curl http://localhost:8000/health

# Create a new build
curl -X POST http://localhost:8000/build/new

# Get build info
curl http://localhost:8000/build/info

# Search for passive nodes
curl 'http://localhost:8000/tree/search?q=life&max_results=5'

# Add a skill
curl -X POST http://localhost:8000/skills/add \
  -H 'Content-Type: application/json' \
  -d '{"skill_text": "Lightning Arrow 20/0 1"}'

# Get calculated stats
curl http://localhost:8000/calc

# Get specific stats
curl 'http://localhost:8000/calc/stats?keys=Life,Mana,TotalDPS,FireResist'

选项：

python api/run_api.py --host 0.0.0.0 --port 9000 --log-level debug

MCP服务器（克劳德桌面）

将此添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pob-poe2": {
      "command": "python",
      "args": ["/path/to/PathOfBuilding-PoE2/api/run_mcp.py"],
      "env": {
        "POB_PATH": "/path/to/PathOfBuilding-PoE2"
      }
    }
  }
}

替换 /path/to/PathOfBuilding-PoE2 带有克隆的实际路径。

Windows示例：

{
  "mcpServers": {
    "pob-poe2": {
      "command": "python",
      "args": ["C:\\Users\\you\\PathOfBuilding-PoE2\\api\\run_mcp.py"],
      "env": {
        "POB_PATH": "C:\\Users\\you\\PathOfBuilding-PoE2",
        "LUAJIT_PATH": "C:\\tools\\luajit\\luajit.exe"
      }
    }
  }
}

集 LUAJIT_PATH 如果 luajit 不在您的系统PATH中。

使用conda环境或特定的Python路径：

{
  "mcpServers": {
    "pob-poe2": {
      "command": "/path/to/conda/envs/py313env/bin/python",
      "args": ["/path/to/PathOfBuilding-PoE2/api/run_mcp.py"],
      "env": {
        "POB_PATH": "/path/to/PathOfBuilding-PoE2"
      }
    }
  }
}

编辑配置后重新启动Claude Desktop。然后，您可以要求克劳德：

• “创建新的Ranger构建并分配一些生命节点”
• “添加闪电箭并向我显示DPS”
• “我目前的电阻是多少？”
• “搜索提供攻击速度的节点”

Lua Bridge（独立）

用于无需Python的直接测试。

macOS/Linux：

cd src
echo '{"command":"ping"}' | \
  LUA_PATH="../runtime/lua/?.lua;../runtime/lua/?/init.lua;;" \
  luajit ../api/lua/bridge.lua

多命令会话（每行一个JSON对象）：

cd src
LUA_PATH="../runtime/lua/?.lua;../runtime/lua/?/init.lua;;" \
  luajit ../api/lua/bridge.lua <<'EOF'
{"command":"new_build"}
{"command":"add_skill","params":{"skill_text":"Lightning Arrow 20/0 1"}}
{"command":"get_output","params":{"stats":["TotalDPS","Life","Mana"]}}
{"command":"shutdown"}
EOF

Windows（cmd）：

cd src
set LUA_PATH=../runtime/lua/?.lua;../runtime/lua/?/init.lua;;
set LUA_CPATH=../runtime/?.dll;;
echo {"command":"ping"} | luajit ..\api\lua\bridge.lua

Windows（PowerShell）：

cd src
$env:LUA_PATH = "../runtime/lua/?.lua;../runtime/lua/?/init.lua;;"
$env:LUA_CPATH = "../runtime/?.dll;;"
echo '{"command":"ping"}' | luajit ..\api\lua\bridge.lua

在Windows上，设置 LUA_CPATH 让LuaJIT在中查找本机DLL runtime/ （比如 lua-utf8.dll)，因此您可以获得完整的功能，而不是回退存根。

环境变量

REST API参考

构建

被动技能树

物品

技能

计算

配置

健康

MCP工具参考

Claude Desktop提供的所有20个工具：

技能文本格式

当通过添加技能时 add_skill 或 /skills/add，使用以下格式：

Label: My Attack Setup
Slot: Weapon 1
Lightning Arrow 20/0 1
Added Lightning Damage Support 20/0 1

每条宝石线： GemName level/quality count

• GemName：宝石名称（允许空格）
• level/quality：宝石级别和质量由 /
• count：宝石数量（通常为1）

项目文本格式

通过添加项目时 add_item 或 /items/add，使用游戏的复制粘贴格式：

Item Class: Bows
Rarity: Rare
Havoc Fletch
Recurve Bow
--------
Physical Damage: 25-65
Critical Hit Chance: 5.00%
Attacks per Second: 1.40
--------
Requirements:
Level: 18
Dex: 65
--------
+10% to Fire Resistance
Adds 5 to 10 Physical Damage
10% increased Attack Speed

故障排除

“找不到模块'xml'”或类似的Lua错误

LuaJIT找不到纯Lua模块。确保 LUA_PATH 已设置。Python桥会自动设置此值。独立使用：

export LUA_PATH="../runtime/lua/?.lua;../runtime/lua/?/init.lua;;"

网桥启动超时

增加超时时间：

export POB_BRIDGE_STARTUP_TIMEOUT=60

“没有名为'mcp'的模块”或Python导入错误

使用Python 3.10+安装依赖项：

pip install -r api/requirements.txt

Claude Desktop不显示PoB工具

1. 检查配置JSON是否有效
2. 验证 python 路径指向Python 3.10+
3. 检查一下 POB_PATH 是正确的
4. 完全重新启动克劳德桌面
5. 检查Claude Desktop的MCP日志是否有错误

Windows：无法识别“luajit”

LuaJIT不在你的路径上。要么：

• 添加包含以下内容的目录 luajit.exe 到您的系统PATH
• 设置 LUAJIT_PATH 环境变量到完整路径 luajit.exe （在您的Claude Desktop配置或系统环境中）

Windows：无法将PoB的捆绑exe用作LuaJIT

捆绑 runtime/Path of Building-PoE2.exe 是一个嵌入LuaJIT的GUI应用程序——它不是一个独立的Lua解释器，不能运行桥接脚本。您需要单独安装LuaJIT（请参阅上面的先决条件）。