PoB2 Build Analysis

An MCP (Model Context Protocol) server that enables Claude to analyze, modify, and optimize Path of Building builds using PoB's actual calculation engine.

---

☕ If you find this project helpful, consider buying me a coffee!

---

Features

Build Analysis (Always Available)

• List & Analyze Builds: Browse builds and extract stats, skills, items, passive trees, and notes from XML
• Compare Builds: Side-by-side build comparison
• File Watching: Real-time detection of builds saved from PoB with automatic cache invalidation
• Tree Analysis: Compare passive trees, find paths to nodes, discover nearby notables, what-if allocation testing

High-Fidelity Calculations (Lua Bridge)

• Live Stats: Accurate stat calculation using PoB's own engine — identical to what PoB GUI shows
• Build Loading & Creation: Load existing builds or create new ones from scratch by class/ascendancy
• Passive Tree Editing: Set full tree allocation and see immediate stat recalculation
• Node Search: Search the passive tree for nodes by name or stat text
• Character Level: Set level and watch all stats update accordingly

Item & Skill Management (Lua Bridge)

• Items: Add items from PoE clipboard text, view all equipped gear
• Flasks: Toggle flasks active/inactive with immediate stat feedback
• Skills: Full gem management — create socket groups, add/remove/level/quality gems
• Batch Operations: setup_skill_with_gems and add_multiple_items for efficient workflows

Build Optimization (Lua Bridge)

• Defensive Analysis: 3-layer framework (avoidance / mitigation / recovery) — evaluates EHP, spell suppression, armour/PDR, evasion, block, life regen, and leech
• Node Suggestions: Archetype-aware suggestions by goal (damage, life, ES, defense, resist)
• Tree Optimization: Recommend nodes within reach of the current allocation
• Item Upgrade Analysis: Slot-by-slot upgrade recommendations based on live stats
• Skill Link Optimization: Detect missing "more" multipliers, penetration gaps, anti-synergies
• Budget Build Creation: Generate starter build plans with skill links, gearing strategy, and passive priorities

Build Validation

• Comprehensive Checks: Resistances, life pool, defensive layers, mana, flask immunities, accuracy, damage scaling
• Severity Classification: Critical / Warning / Info with actionable suggestions
• Dual Source: Uses Lua bridge stats when available, falls back to XML parsing
• Overall Score: 0–10 build health score

Configuration & Scenario Testing (Lua Bridge)

• Config State: View bandit, pantheon, enemy settings
• Toggle Conditions: Charges, buffs (Onslaught, Fortify, Leeching), boss mode
• Enemy Tuning: Set enemy level, resistances, armour, evasion for boss DPS testing

Skill Gem Analysis

• Archetype Detection: Classify builds (Elemental Bow Attack, Summoner, Critical Spell, etc.)
• Support Gem Recommendations: Ranked suggestions with DPS estimates and cost context
• Quality Validation: Identify missing quality, awakened upgrade paths, corruption targets
• Optimal Links: Auto-generate best support gem combinations for 4/5/6-link setups
• Budget Tiers: League-start, mid-league, and endgame recommendations

Build Export & Persistence

• Export: Copy builds to XML files with optional notes
• Save Tree: Write optimized passive tree back to an existing build file
• Snapshots: Versioned build history with tags, stat metadata, and one-click rollback

Currency & Market Data (poe.ninja)

• Exchange Rates: Real-time currency prices in Chaos Orb equivalent
• Arbitrage Detection: Find profitable currency trading loops
• Trade Profit Calculator: Evaluate custom trading chains

Trade API (Optional, POE_TRADE_ENABLED=true)

• Item Search: Search trade with stat filters, price range, link count
• Price Checking: Min/max/median/average from recent listings
• Upgrade Finder: Identify best item upgrade candidates for your build
• Resistance Gear: Find affordable gear to cap resistances
• Cluster Jewels: Search and analyze cluster jewel setups
• Shopping List: Generate a prioritized shopping list from build analysis

---

Installation

cd pob-mcp
npm install
npm run build

Configuration

Claude Desktop Configuration

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

XML-Only (No Lua Bridge)

{
  "mcpServers": {
    "pob": {
      "command": "node",
      "args": ["/absolute/path/to/pob-mcp-server/build/index.js"],
      "env": {
        "POB_DIRECTORY": "/path/to/your/Path of Building/Builds"
      }
    }
  }
}

Full Configuration (With Lua Bridge)

{
  "mcpServers": {
    "pob": {
      "command": "node",
      "args": ["/absolute/path/to/pob-mcp-server/build/index.js"],
      "env": {
        "POB_DIRECTORY": "/path/to/your/Path of Building/Builds",
        "POB_LUA_ENABLED": "true",
        "POB_FORK_PATH": "/path/to/PathOfBuilding/src",
        "POB_CMD": "/usr/local/bin/luajit",
        "POB_TIMEOUT_MS": "10000"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
POB_DIRECTORY	OS-default Builds dir	Path to your PoB builds directory
POB_LUA_ENABLED	false	Set "true" to enable Lua bridge
POB_FORK_PATH	~/Projects/PathOfBuilding/src	Path to PathOfBuilding/src
POB_CMD	luajit	LuaJIT binary path
POB_TIMEOUT_MS	10000	Lua request timeout (ms)
POE_TRADE_ENABLED	false	Enable Trade API tools

Setting Up the Lua Bridge (optional, advanced)

The Lua bridge is optional and off by default. Everything under "Build Analysis", "Tree Analysis", currency data, and the XML-based tools works on a fresh clone with no bridge. Only the high-fidelity calc tools (lua_*, evaluate_trade_item, live get_stats, defensive analysis, etc.) require it. Leave POB_LUA_ENABLED unset and those tools simply report that the bridge isn't enabled.

The bridge spawns a headless Path of Building under LuaJIT and talks to it over a stdio JSON-RPC API (HeadlessWrapper.lua with POB_API_STDIO=1).

Important: there is no publicly distributed PoE2 PoB build with this stdio API. A PoE1 implementation exists at ianderse/PathOfBuilding@api-stdio (PoE1 only — it computes PoE1 builds, not PoE2). Enabling the bridge for PoE2 therefore requires supplying your own local headless PoE2 PoB that exposes the same protocol — this is an advanced, self-hosted step, not something a fresh clone can do out of the box.

1. Install LuaJIT

# macOS
brew install luajit
# Ubuntu/Debian
sudo apt-get install luajit
# Windows (scoop)
scoop install luajit            # or download from https://luajit.org/ and add to PATH

2. Provide a headless PoB with the stdio API

Point POB_FORK_PATH at the src/ directory of a Path of Building checkout whose HeadlessWrapper.lua boots the stdio JSON-RPC server when POB_API_STDIO=1. For PoE1, that's the ianderse/PathOfBuilding@api-stdio branch above. For PoE2, you must supply an equivalent locally.

3. Verify

luajit -v
ls "$POB_FORK_PATH/HeadlessWrapper.lua"
# ping test (should print a ready banner, then {"ok":true,"pong":true}):
( echo '{"action":"ping"}'; echo '{"action":"quit"}' ) | POB_API_STDIO=1 luajit "$POB_FORK_PATH/HeadlessWrapper.lua"

4. Enable it

Set POB_LUA_ENABLED=true, POB_FORK_PATH, and POB_CMD (the luajit path) in your Claude config, then restart.

---

Available Tools

The server registers 91 tools across 10 categories.

XML-Based Tools (Always Available)

Tool	Description
list_builds	List all .xml build files
analyze_build	Full build summary: class, stats, skills, items, tree
compare_builds	Side-by-side build comparison
get_build_stats	Extract raw stats from build XML
get_build_notes	Get build notes from XML
set_build_notes	Set build notes in XML
start_watching	Monitor builds directory for changes
stop_watching	Stop file monitoring
watch_status	Show watching status and cache info
get_recent_changes	List recently modified builds
refresh_tree_data	Clear passive tree data cache

Tree Analysis Tools (Always Available)

Tool	Description
compare_trees	Show node differences between two builds
get_nearby_nodes	Find notables/keystones reachable from current allocation
find_path_to_node	Shortest path to a target node ID
get_passive_upgrades	Suggest passive tree upgrades
suggest_masteries	Suggest mastery choices for allocated clusters

Lua Bridge — Core (Require POB_LUA_ENABLED=true)

Tool	Description
lua_start	Start the PoB calculation engine (stdio or TCP)
lua_stop	Stop the engine and free resources
lua_new_build	Create a blank build for a given class/ascendancy
lua_load_build	Load a build file into the engine
lua_save_build	Save the current in-memory build to a .xml file
lua_reload_build	Reload the current build from disk
lua_get_build_info	Get current build metadata (class, level, etc.)
set_character_level	Set level and recalculate all stats
lua_get_stats	Get calculated stats (category: offense/defense/all)
lua_get_tree	View passive tree: class, ascendancy, all allocated node IDs
lua_set_tree	Replace passive tree allocation (preserves class if omitted)
update_tree_delta	Add/remove individual nodes without replacing entire tree
search_tree_nodes	Search passive tree by name or stat text
list_specs	List all tree specs in the current build
select_spec	Switch active tree spec
create_spec	Create a new tree spec
delete_spec	Delete a tree spec
rename_spec	Rename a tree spec
list_item_sets	List all item sets in the current build
select_item_set	Switch active item set
plan_leveling	Generate a leveling plan for a build

lua_set_tree class IDs: 0=Scion, 1=Marauder, 2=Ranger, 3=Witch, 4=Duelist, 5=Templar, 6=Shadow

Witch ascendancy IDs: 1=Occultist, 2=Elementalist, 3=Necromancer

lua_save_build is required before using file-based tools (validate_build, analyze_build, etc.) on an in-memory build.

Lua Bridge — Item & Skill Management

Tool	Description
add_item	Add item from PoE clipboard text to a slot
add_multiple_items	Add multiple items in one operation
get_equipped_items	List all equipped gear with name, base, and rarity
toggle_flask	Activate/deactivate flask 1–5; returns updated stats
get_skill_setup	Show all socket groups with gems, levels, and quality
set_main_skill	Set which group/gem is used for DPS calculations
create_socket_group	Create a new socket group (label, slot, enabled)
add_gem	Add a gem to a socket group (name, level, quality)
set_gem_level	Set gem level by group + gem index
set_gem_quality	Set gem quality (Default/Anomalous/Divergent/Phantasmal)
remove_gem	Remove a gem by group + gem index
remove_skill	Remove an entire socket group
setup_skill_with_gems	Create a socket group with active gem + supports in one call

Slot names: Weapon 1, Weapon 2, Helmet, Body Armour, Gloves, Boots, Amulet, Ring 1, Ring 2, Belt, Flask 1–Flask 5

Lua Bridge — Build Optimization

Tool	Description
analyze_defenses	3-layer defensive audit: avoidance / mitigation / recovery
suggest_optimal_nodes	Archetype-aware node suggestions by goal
optimize_tree	Recommend nearby nodes to allocate for a goal
analyze_items	Slot-by-slot item analysis with upgrade priorities
optimize_skill_links	Audit supports: "more" multipliers, penetration, anti-synergies
create_budget_build	Generate a starter build plan for a class/skill/budget
get_build_issues	Get prioritized list of build problems and suggestions
check_boss_readiness	Evaluate readiness for specific boss encounters
suggest_watchers_eye	Suggest Watcher's Eye mods for the build's auras

suggest_optimal_nodes goals: damage, defense, life, es, resist, speed

Defensive layers:

• Avoidance — evasion, spell suppression, dodge, block
• Mitigation — armour/PDR, endurance charges
• Recovery — life regen (≥1%/s), leech, ES recharge

A build with all 3 layers is considered exceptional.

Configuration & Enemy Settings

Tool	Description
get_config	View bandit, pantheon, and enemy settings
set_config	Toggle charges, buffs, conditions (e.g. usePowerCharges, enemyIsBoss)
set_enemy_stats	Set enemy level, resistances, armour, evasion for DPS scenarios
save_config_preset	Save current config as a named preset
load_config_preset	Load a saved config preset
list_config_presets	List all saved config presets

Build Validation

Tool	Description
validate_build	Check resistances, life, defensive layers, mana, immunities, accuracy, damage scaling

Returns critical issues, warnings, and info with actionable suggestions and an overall 0–10 health score. Uses Lua bridge stats when available; falls back to XML parsing. build_name is optional — omitting it validates the currently loaded Lua bridge build.

Skill Gem Analysis

Tool	Description
analyze_skill_links	Evaluate support gems and detect build archetype
suggest_support_gems	Ranked support gem recommendations with DPS estimates
validate_gem_quality	Find gems needing quality, awakened upgrades, or corruption
compare_gem_setups	Side-by-side structural comparison of gem configurations
find_optimal_links	Auto-generate best support combo for a 4/5/6-link and budget
gem_upgrade_path	Show upgrade path for a gem (awakened, quality variants)

Budget tiers: league_start, mid_league, endgame

Build Export & Persistence

Tool	Description
export_build	Copy a build to a new XML file with optional notes
save_tree	Write passive tree back to an existing build file
snapshot_build	Create a versioned snapshot with description and tag
list_snapshots	List all snapshots for a build
restore_snapshot	Restore from a snapshot (auto-backs up current state)
export_build_summary	Export a human-readable build summary

Snapshots are stored in POB_DIRECTORY/.pob-mcp/snapshots/.

Note: export_build copies from the XML file, not from the Lua bridge. Use lua_save_build first if you want to export in-memory changes.

Currency & Market Data (poe.ninja)

Tool	Description
get_currency_rates	Live exchange rates for all currencies (Chaos Orb equivalent)
find_arbitrage	Detect profitable currency trading loops
calculate_trading_profit	Evaluate a specific trading chain

Rates are updated every 5 minutes from poe.ninja. Pass the exact league name (e.g., Standard, Hardcore, Settlers).

Trade API Tools (Require POE_TRADE_ENABLED=true)

Tool	Description
search_trade_items	Search trade with stat filters, price range, link count
get_item_price	Price statistics (min/max/median/average) for an item
get_leagues	List available leagues
search_stats	Look up Trade API stat IDs
find_item_upgrades	Identify best upgrade candidates for your build
find_resistance_gear	Find affordable gear to cap specific resistances
compare_trade_items	Compare multiple trade listings side by side
search_cluster_jewels	Search for cluster jewels by notable
analyze_build_cluster_jewels	Evaluate cluster jewel setups for a build
generate_shopping_list	Generate a prioritized shopping list from build analysis

---

Typical Workflows

Analyze an existing build

1. lua_start
2. lua_load_build (build_name: "MyBuild.xml")
3. lua_get_stats (category: "defense")
4. validate_build
5. analyze_defenses (build_name: "MyBuild.xml")

Build from scratch

1. lua_start
2. lua_new_build (class_name: "Witch", ascendancy: "Necromancer")
3. setup_skill_with_gems (active_gem: "Summon Skeletons", support_gems: [...])
4. lua_set_tree (nodes: [...])
5. lua_get_stats
6. lua_save_build (build_name: "MySummoner.xml")

Optimize passive tree

1. lua_load_build (build_name: "MyBuild.xml")
2. suggest_optimal_nodes (goal: "life", points_available: 5)
3. search_tree_nodes (query: "maximum life")
4. lua_get_tree   ← copy current node list
5. lua_set_tree   ← add new nodes to the list
6. lua_get_stats  ← verify improvement
7. lua_save_build ← persist

Test DPS against Shaper

1. lua_load_build
2. set_enemy_stats (level: 84, fire_resist: 40, cold_resist: 40, lightning_resist: 40)
3. set_config (config_name: "enemyIsBoss", value: true)
4. lua_get_stats (category: "offense")

---

Troubleshooting

XML Features

No builds found

• Verify POB_DIRECTORY is correct and contains .xml files
• Check file permissions

Parse errors

• Open the build in PoB GUI to verify it isn't corrupted
• Ensure PoB is up to date

Lua Bridge

luajit command not found

brew install luajit          # macOS
sudo apt-get install luajit  # Ubuntu/Debian

Or set POB_CMD to the full path (e.g., /opt/homebrew/bin/luajit).

Failed to find valid ready banner POB_FORK_PATH must point to the directory containing HeadlessWrapper.lua:

ls "$POB_FORK_PATH/HeadlessWrapper.lua"   # must exist
ls "$POB_FORK_PATH/Modules/"              # must exist

Timed out waiting for response

• Increase POB_TIMEOUT_MS (try 20000)
• Test manually: cd "$POB_FORK_PATH" && luajit HeadlessWrapper.lua

Stats don't match PoB GUI

• Check bandit/pantheon/enemy settings with get_config
• Ensure the correct tree spec is active in the XML
• Make sure your PathOfBuilding fork is on the api-stdio branch and up to date

Bridge becomes unresponsive

lua_stop → wait a moment → lua_start

If still unresponsive, restart Claude Desktop.

Nodes dropped after lua_set_tree Nodes must form a valid connected path from the class starting node. Disconnected nodes are silently dropped by PoB. Ensure all intermediate nodes are included.

lua_save_build doesn't persist gem changes Gem modifications made via add_gem, set_gem_level, set_gem_quality are currently held in Lua memory and are not serialized back to the XML on save. This is a known limitation.

---

Development

npm run build   # compile TypeScript
npm run dev     # watch mode

Path of Building XML Structure

PoB builds are XML files with:

• <Build>: Character info and stats
• <Tree>: Passive skill tree node allocations
• <Skills>: Socket groups and gem links
• <Items>: Equipped items
• <Notes>: Build notes

Contributing

Issues and pull requests are welcome!

Contributors

Maxwell Renke

Ian

J-Gierend

License

GPL-3.0