Skip to content

Add character import API handlers#1

Draft
mcagnion wants to merge 1 commit into
ianderse:devfrom
mcagnion:feature/import-poe-character
Draft

Add character import API handlers#1
mcagnion wants to merge 1 commit into
ianderse:devfrom
mcagnion:feature/import-poe-character

Conversation

@mcagnion

@mcagnion mcagnion commented Apr 25, 2026

Copy link
Copy Markdown

Summary

  • add JSON-RPC handlers for importing passive tree/jewels and items/skills from official PoE API JSON
  • add save_build support so MCP can persist the in-memory build after import
  • return ok=false when ImportTab reports a non-throwing import failure via charImportStatus

Validation

  • git diff --check
  • luajit -bl src/API/Handlers.lua
  • luajit -bl src/API/BuildOps.lua
  • pob-mcp npm run build
  • pob-mcp TMPDIR=/tmp npm test -- --runTestsByPath tests/unit/toolSchemas.test.ts tests/unit/pobLuaBridge.test.ts tests/unit/importHandlers.test.ts --runInBand
  • real bridge smoke: start, ping, new_build, save_build, invalid import_passive_tree, invalid import_items_skills

Companion change for pob-mcp live character import support.

@mcagnion mcagnion mentioned this pull request Apr 25, 2026
Closed
5 tasks
mcagnion added a commit to mcagnion/pob-mcp that referenced this pull request Apr 25, 2026
@mcagnion @claude
feat: add lua_list_characters and lua_import_character with PoE API i…
e0256d6 
…ntegration

Adds two new MCP tools that import a live PoE character into the loaded
build via the official PoE character-window API.

- lua_list_characters: HTTP-only listing (no Lua bridge required), sorted
  by lastLoginTime, displays class/ascendancy/league/realm/last login.
- lua_import_character: replaces the active spec's tree, jewels, items,
  and skill gems with the in-game state. Returns a before/after diff
  (stats, items per slot, skill groups, tree node count) so callers can
  verify the import result.

The feature works against the JSON-RPC handlers added on the matching
PoB branch (see ianderse/PathOfBuilding#1). Configuration, build notes,
other tree specs, and other item sets are preserved.

Includes 41 unit tests covering the HTTP client, the handler flow
(critical regression test for sequential bridge calls), and a schema
guard against duplicate tool registration. POE_SESSION_ID env var
documented for private profiles.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@mcagnion
mcagnion force-pushed the feature/import-poe-character branch from 3064947 to 0134cfe Compare April 25, 2026 12:51
@mcagnion
mcagnion changed the base branch from api-stdio to dev April 25, 2026 12:51
@mcagnion

mcagnion commented Apr 25, 2026

Copy link
Copy Markdown
Author

Rebased onto dev (current PR PathOfBuildingCommunity#9505 head). The original branch was on api-stdio which is stale (last upstream sync 2025-11-01, missing the 3.28 tree data).

Diagnostic for posterity in case anyone hits the same wall:

  • On api-stdio, lua_load_build of any 3.28 build leaves treeTab.specList empty because TreeTabClass:Load early-returns when treeVersions["3_28"] is nil. build.spec still points to the constructor's default spec, but it's no longer in specList — silent state mismatch.
  • Then import_passive_tree calls treeTab:SetActiveSpec(treeTab.activeSpec) and crashes at Classes/TreeTab.lua:499 (curSpec is nil) because m_min(activeSpec, #specList) returns 0 against the empty list.
  • Reproduced on Hiero (cluster jewels), MickaMirageRanger (lvl 2, no clusters), and a fresh lua_new_build followed by import. Always crashes on api-stdio.
  • Smoke test on the new base (dev w/ JSON-RPC API): import succeeds, before/after diff renders, block 75% preserved across import (that fix lives in the handler — I force useSecondWeaponSet=false after ImportItemsAndSkills so PoB calc reads from the slots the API just populated, unless ignore_weapon_swap=true).

Companion pob-mcp PR is ianderse/pob-mcp#8.

🤖 Generated with Claude Code

mcagnion added a commit to mcagnion/pob-mcp that referenced this pull request Apr 25, 2026
@mcagnion @claude
feat: add lua_list_characters and lua_import_character with PoE API i…
4990121 
…ntegration

Adds two new MCP tools that import a live PoE character into the loaded
build via the official PoE character-window API.

- lua_list_characters: HTTP-only listing (no Lua bridge required), sorted
  by lastLoginTime, displays class/ascendancy/league/realm/last login.
- lua_import_character: replaces the active spec's tree, jewels, items,
  and skill gems with the in-game state. Returns a before/after diff
  (stats, items per slot, skill groups, tree node count) so callers can
  verify the import result.

The feature works against the JSON-RPC handlers added on the matching
PoB branch (see ianderse/PathOfBuilding#1). Configuration, build notes,
other tree specs, and other item sets are preserved.

Includes 41 unit tests covering the HTTP client, the handler flow
(critical regression test for sequential bridge calls), and a schema
guard against duplicate tool registration. POE_SESSION_ID env var
documented for private profiles.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
charleslucas added a commit to charleslucas/PathOfBuilding that referenced this pull request Jul 9, 2026
@charleslucas @claude
fix(api): create_spec builds a real PassiveSpec, not a fabricated table
62dc37d 
create_spec hand-rolled a plain Lua table with only a few fields, omitting
jewels/nodes/allocNodes/etc. that a genuine PassiveSpec has. Native code
that iterates every spec then crashed on the fake one — ItemsTab:DeleteItem
does pairs(spec.jewels) during lua_import_character's clear-items step and
threw 'bad argument ianderse#1 to pairs (table expected, got nil)', corrupting the
import into a partial state (new tree, old items) that made every defensive
stat wrong. Root-caused 2026-07-09 during a tree audit.

Now uses PoB's own constructor + copy pattern (TreeTab.lua:599-602):
new('PassiveSpec', build, treeVersion), copyTable(jewels), and
RestoreUndoState(src:CreateUndoState(), version). The copy now also
correctly preserves class/ascendancy (was dropping them: a Scavenger copy
showed 'Scion/None, 77 nodes'; now 'Scion/Scavenger, 101 nodes').

Verified live: with a create_spec backup present, lua_import_character now
completes fully (items included) instead of crashing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mcagnion