流放之路配装分析MCP服务

Path of Building MCP Server

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

Works against a stock PathOfBuildingCommunity checkout — no fork, no patches. The server ships its own stdio adapter that loads PoB's HeadlessWrapper.lua as a library and drives the real calculation engine directly.

PoE 3.29 compatibility: This release targets Path of Building data and builds for the 3.29 league. Use a current PoB checkout for the matching tree, skills, and item data. Trade calls should always use get_leagues instead of hard-coding a challenge-league name.

☕ 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
• Tree Specs: List, switch, create, copy, rename, and delete passive tree specs
• Node Search: Search the passive tree for nodes by name or stat text
• Character Level: Set level and watch all stats update accordingly
• Anointment Ranking: Simulate every anointable notable through PoB's live calculator and rank by DPS/EHP impact

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; restoring the active source also reloads the engine

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
• Weighted BIS Search: Build-specific best-in-slot listings using PoB's native TradeQueryGenerator stat weights (requires POE_SESSION_ID)
• 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"
      }
    }
  }
}

With the Lua Bridge

If PoB is installed (macOS), this is the whole configuration. POB_PATH, POB_DIRECTORY and POB_CMD are detected from the installed app.

{
  "mcpServers": {
    "pob": {
      "command": "node",
      "args": ["/absolute/path/to/pob-mcp-server/build/index.js"],
      "env": {
        "POB_LUA_ENABLED": "true"
      }
    }
  }
}

Set POB_PATH explicitly only when driving a PathOfBuilding git checkout instead of an installed app, or when the app lives somewhere unusual:

        "POB_PATH": "/path/to/PathOfBuilding/src",
        "POB_CMD": "/opt/homebrew/bin/luajit"

Environment Variables

Saving and restoring builds

lua_save_build writes atomically. Saving back to the file loaded into the bridge is allowed. To replace a different existing file, pass overwrite: true explicitly; otherwise choose a new name. Saved-file stats are invalidated immediately, and names with or without .xml share the same cache entry.

save_tree preserves unrelated XML elements and writes mastery selections in PoB's native format. Snapshot restore reloads the engine when that exact source file is active. If the reload fails, the response states that the file was restored but live stats are not yet synchronized. Another active build is left untouched.

Affix tools support both current Data/ModExplicit.lua and legacy Data/ModItem.lua installations. Unmatched or ambiguous explicit lines leave remaining slots unknown.

Setting Up the Lua Bridge

The Lua bridge uses PoB's actual calculation engine for accurate stats.

If you already have Path of Building installed (macOS)

Install LuaJIT and you are done:

brew install luajit

The server locates the engine inside the installed app, so there is no checkout to clone and no Lua modules to install. It uses the writable src/ copy the app maintains under ~/Library/Application Support/PathOfBuildingMac, which means the engine always matches the PoB you actually run, and the app's own C modules, which are the ones PoB ships no non-Windows build of in the repo.

Skip to step 4 to verify.

Working from a PathOfBuilding checkout instead

1. Install LuaJIT

# macOS
brew install luajit

# Ubuntu/Debian
sudo apt-get install luajit

# Windows: download from https://luajit.org/ and add to PATH

2. Install PoB's Lua C modules (macOS and Linux)

PoB commits its C modules to runtime/ as Windows .dll builds only, so a checkout cannot supply them anywhere else. Without this the bridge appears to hang and then times out, because PoB reports module 'lua-utf8' not found and waits for a keypress that never comes.

luarocks --lua-version=5.1 --local install luautf8

# Homebrew LuaJIT needs to be pointed at explicitly:
luarocks --lua-version=5.1 --lua-dir=$(brew --prefix luajit) --local install luautf8

The bridge searches ~/.luarocks/lib/lua/5.1, so --local is enough. Windows users can skip this: the bundled DLLs are used.

3. Clone PathOfBuilding

git clone https://github.com/PathOfBuildingCommunity/PathOfBuilding.git

Note the full path to the src/ directory — that's your POB_PATH.

No fork or patches are required. The server ships its own stdio adapter (lua/vanilla_stdio_bridge.lua + lua/pob_ops.lua) that loads the stock HeadlessWrapper.lua as a library and drives PoB's real calculation engine directly. Every Lua-bridge tool — stats, tree editing, gems, items, config, specs, save/export, anointments, weighted trade queries — works against an unmodified checkout. Call lua_get_capabilities at runtime for the authoritative action list.

To verify locally after building this project:

npm run test:smoke

The smoke tests resolve the engine the same way the server does, so an installed PoB needs no configuration. Set POB_PATH only to point them at a checkout.

This runs both the adapter contract and MCP stdio transport checks: tool discovery, capabilities, build load, snapshot, stats, items, skills, reversible tree mutation, config, anointment ranking, and build info.

For the deep end-to-end workflow suite:

npm run test:smoke:full

This verifies blank-build gem editing, build discovery and file persistence, loading, character-level mutation and restoration, tree search, build validation, configuration/snapshot save-and-restore, and defensive/boss-readiness analysis.

For persistence regression checks against the real engine:

npm run test:smoke:persistence

This checks overwrite protection, cache refresh, snapshot reload, XML notes and mastery preservation, and rejection of incomplete native imports.

To exercise the live Trade API integration (requires network access):

npm run test:smoke:trade

This verifies MCP discovery plus live league, stat, item-search, price-check, resistance-gear recommendation, currency-rate, and trading-profit requests against the Standard league.

To also exercise the authenticated weighted BIS search (requires your POESESSID):

POE_SESSION_ID=<your POESESSID> npm run test:smoke:weighted

To verify live crafting-data integration (requires network access):

npm run test:smoke:crafting

This verifies that the crafting advisor obtains current currency rates and base-mod data for a known item base through MCP.

4. Verify

luajit -v
ls /path/to/PathOfBuilding/src/HeadlessWrapper.lua

5. Update Claude Desktop config and restart Claude Desktop

Available Tools

With every optional integration enabled, the server registers 99 tools across 10 categories.

XML-Based Tools (Always Available)

Tree Analysis Tools (Always Available)

Lua Bridge — Core (Require POB_LUA_ENABLED=true)

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

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

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

Build Validation

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

Budget tiers: league_start, mid_league, endgame

Build Export & Persistence

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)

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)

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")

Find the best anointment and shop for upgrades

1. lua_load_build (build_name: "MyBuild.xml")
2. find_best_anointment (slot: "Amulet", focus: "both")
3. find_weighted_trade_items (league: "Standard", slot: "Amulet")   ← requires POE_TRADE_ENABLED + POE_SESSION_ID

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_PATH must point to the directory containing HeadlessWrapper.lua:

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

Timed out waiting for response

• Increase POB_TIMEOUT_MS (try 20000)
• Test manually: cd "$POB_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 checkout is 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.

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

License

GPL-3.0