Metadata-Version: 2.4
Name: pob-mcp
Version: 0.3.0
Summary: MCP server giving AI agents real programmatic control of Path of Building Community (Path of Exile 1)
Author: MudcrabWarrior
License-Expression: MIT
Project-URL: Homepage, https://github.com/MudcrabWarrior/pob-mcp
Project-URL: Repository, https://github.com/MudcrabWarrior/pob-mcp
Project-URL: Issues, https://github.com/MudcrabWarrior/pob-mcp/issues
Keywords: mcp,path-of-exile,path-of-building,poe,llm,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: mcp>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

<div align="center">

# pob-mcp

**Give any AI assistant real, verifiable control of Path of Building.**

For **Path of Exile 1**, via [Path of Building Community](https://github.com/PathOfBuildingCommunity/PathOfBuilding).

Paste a build link. Get a slot-by-slot upgrade analysis where every single number
came out of Path of Building's own calculation engine — not a language model's guesswork.

[![tests](https://github.com/MudcrabWarrior/pob-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MudcrabWarrior/pob-mcp/actions/workflows/ci.yml)
[![licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
[![uses your Path of Building](https://img.shields.io/badge/uses-your%20PoB%20install-238636)](https://github.com/PathOfBuildingCommunity/PathOfBuilding)
[![no account required](https://img.shields.io/badge/auth-none%20required-brightgreen)](#do-i-need-an-account-api-key-or-login)

</div>

---

## The problem

Ask any AI about your Path of Exile build and it will confidently invent numbers.
It has read a lot of forum posts, so the answers *sound* right — "that's about
40% more DPS" — but nothing was calculated. There's no way to tell a good answer
from a plausible-looking wrong one.

**pob-mcp removes the guessing.** It runs a real, unmodified Path of Building
headlessly and lets the assistant drive it. When it says a swap is worth
+8,722,100 DPS, that figure came from the same engine as PoB's own item tooltips,
and you can paste the resulting build into the desktop GUI to check it yourself.

The project has exactly one rule, and everything else follows from it:

> **Never fabricate a number.** If a stat didn't come out of a real PoB
> calculation, it doesn't get reported. "Not computed" beats a confident guess.

---

## What it looks like

> **You:** Load `https://pobb.in/xcACDMM2fFR6` and tell me what's actually holding this build back.

```
Trickster (Shadow), level 94 — Reap mines, tree 3_29

  Combined DPS   59,549,948        Life  3,708 (2,432 unreserved)
  Total EHP          24,247        ES    2,011      Evasion  50,859
  Resists     F 75 (+15)  C 80 (+58)  L 75 (+3)  Chaos 38
  Spell Suppression 97%             Block 25%

  _meta: enemy Pinnacle lvl 84 · Frenzy charges ON · Power charges ON
```

> **You:** Is that DPS honest, or is it assuming perfect conditions?

```
pob_config_sensitivity()  →  what the headline number depends on

  useFrenzyCharges  ON → OFF      DPS −24,357,212      EHP    −208
  enemyIsBoss       Pinnacle→None DPS +15,659,402      EHP −12,962
  usePowerCharges   ON → OFF      DPS −12,678,059      EHP       0
```

**41% of this build's advertised DPS evaporates without Frenzy charges.** That's
the kind of thing a headline number hides, and it's the first thing worth knowing.

*(The same conversation can rank every support gem's measured contribution —
on this build, levelling the **active** gem turns out to be worth six times the
best support upgrade. Every figure is a real calculation with that gem removed
or levelled.)*

> **You:** Find me upgrades — and tell me what gets worse, not just what improves.

```
pob_find_upgrades()  →  1,478 real calculations in 6.0s, 0 failed
                        ranked by combined score, verbatim output

   1. Flask    Replica Rumi's Concoction   DPS          +0    EHP  +17,900
   2. Flask    Vorana's Preparation        DPS  +6,616,661    EHP   +1,093
   3. Boots    Legacy of Fury              DPS  +8,722,100    EHP     −972
   4. Ring 2   Kalandra's Touch            DPS  +6,287,099    EHP     −131
   5. Flask    Progenesis                  DPS          +0    EHP   +4,426
   6. Flask    Starlight Chalice           DPS  +3,783,608    EHP   +1,093
   7. Flask    Rumi's Concoction           DPS          +0    EHP   +3,965
   8. Ring 2   The Taming                  DPS  +4,783,763    EHP     −131
   9. Weapon 2 Replica Mistwall            DPS −13,316,941    EHP  +14,330
  10. Belt     The Arkhon's Tools          DPS +14,607,821    EHP   −8,841
```

Look at rows 9 and 10. **The Arkhon's Tools is the single biggest DPS gain in
the run — and it costs 8,841 EHP.** Replica Mistwall is the mirror image: a
third of your damage traded away for a third more effective health. Neither is
"the answer"; both are decisions, and you can only make them if the cost is on
the table.

That's why the top of the list is a flask that adds no damage whatsoever. The
ranking weighs offence and defence together rather than sorting by DPS and
hoping you notice the footnotes.

<div align="center">
  <img src="docs/assets/workflow.svg" alt="A build review, end to end: load, check assumptions, find weak points, simulate and shop" width="880">
</div>

---

## Why this and not a chatbot

|  | Asking an AI directly | **pob-mcp** |
|---|---|---|
| Where numbers come from | The model's training data | Path of Building's calc engine |
| Can you verify a claim? | No | Yes — `pob_export()` → paste into the GUI |
| Knows *your* gear and tree | Only what you paste | Loads your actual build |
| Handles your league's tree | Assumes whatever it saw | Uses the build's own tree version |
| Defensive trade-offs | Usually ignored | Reported on every recommendation |
| Hidden assumptions | Invisible | Surfaced by `pob_config_sensitivity()` |

---

## Install

### 1. You need Path of Building

**Path of Building Community** — [download the latest][pobdl]. Installer or
portable zip, either works. If you play Path of Exile you already have it.

**LuaJIT** — the interpreter that runs PoB's calculation engine. The `.mcpb`
extension (Claude Desktop / Cowork) **ships its own copy — skip this**. For the
command-line route it's one command:

```powershell
winget install DEVCOM.LuaJIT          # Windows
brew install luajit                   # macOS
sudo apt install luajit               # Debian/Ubuntu
```

That's the whole prerequisite list. No Python install, no clone, no build step.

### 2. Add it to your AI client

<table>
<tr><td width="50%" valign="top">

**Claude Desktop or Cowork** — one click

Download the **`.mcpb` bundle** (e.g. `pob-mcp-0.3.0.mcpb`) from the
[latest release][rel], then:

*Settings → Extensions → Advanced settings → Extension Developer → select the file*

You'll get a settings form where you can point it at your Path of Building
folder if it isn't found automatically. Nothing else to install — Claude
supplies Python and the dependencies itself, and the bundle ships its own
LuaJIT.

</td><td width="50%" valign="top">

**Claude Code, Cursor, Zed, Continue…** — one command

```bash
claude mcp add pob --scope user -- \
  uvx --from git+https://github.com/MudcrabWarrior/pob-mcp pob-mcp
```

See below for the JSON-config form.

</td></tr>
</table>

[rel]: https://github.com/MudcrabWarrior/pob-mcp/releases/latest

### 3. Try it

Whichever route you took, **start a new session** — registration doesn't affect
one already running — and ask:

> Load https://pobb.in/xcACDMM2fFR6 and give me the headline DPS and EHP.

You should get about 59.5M Combined DPS and 24,247 EHP. Done. (The first call
takes a few seconds while Path of Building loads its data; after that,
calculations are fast. If anything looks wrong, ask it to *"run pob_status"* —
that reports exactly what was found and what wasn't.)

#### Command-line clients in detail

**Claude Code** — one command. [uv][uv] fetches the server, its dependencies and
a Python runtime on first run:

```bash
claude mcp add pob --scope user -- uvx --from git+https://github.com/MudcrabWarrior/pob-mcp pob-mcp
```

**Cursor, Zed, Continue, or any other MCP client** — add this to its MCP
config. (Claude Desktop works this way too, but the `.mcpb` extension above is
easier and is the only route that also covers Cowork.)

```json
{
  "mcpServers": {
    "pob": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/MudcrabWarrior/pob-mcp", "pob-mcp"]
    }
  }
}
```

Don't have `uv`? [Install it][uv] — one command on every platform — or use the
pip route below.

[pobdl]: https://github.com/PathOfBuildingCommunity/PathOfBuilding/releases/latest
[uv]: https://docs.astral.sh/uv/

<details>
<summary><b>Prefer pip?</b></summary>

```bash
pip install git+https://github.com/MudcrabWarrior/pob-mcp
claude mcp add pob --scope user -- pob-mcp
```

Needs Python 3.10+ already installed. `uvx` is the easier route mainly because
it supplies Python itself and keeps the install isolated.
</details>

<details>
<summary><b>Why the long git URL?</b></summary>

pob-mcp hasn't been published to PyPI yet, so `uvx` is pointed straight at the
repository. Once the first release lands, the command shortens to:

```bash
claude mcp add pob --scope user -- uvx pob-mcp
```

Everything else stays the same.
</details>

<details>
<summary><b>"LuaJIT not found"</b> — even though you just installed it</summary>

On Windows, `winget` only updates `PATH` for shells started *afterwards*, and
your MCP client may have inherited the old one. pob-mcp checks the winget
install directory directly, so this usually resolves itself — but if not:

1. **Restart your MCP client** (not just the terminal).
2. Or point at it explicitly:
   ```bash
   claude mcp add pob --scope user -e POB_LUAJIT="C:\path\to\luajit.exe" -- uvx --from git+https://github.com/MudcrabWarrior/pob-mcp pob-mcp
   ```
3. Or drop a `luajit.exe` at `%USERPROFILE%\.pob-mcp\luajit\luajit.exe` and it
   will be found with no configuration at all.

The `.mcpb` extension bundles its own LuaJIT (Windows build), so this only
applies to the `uvx`/pip route — those install from source and don't ship a
native binary, so LuaJIT comes from your platform's package manager.
</details>

<details>
<summary><b>"Path of Building not found"</b> — tell it where yours is</summary>

pob-mcp searches the usual install locations and any folder named
`Path of Building*`. If yours is somewhere unusual, say so. `POB_SRC` is **the
folder containing `Launch.lua`**:

```bash
claude mcp add pob --scope user -e POB_SRC="D:\Games\Path of Building Community" -- uvx --from git+https://github.com/MudcrabWarrior/pob-mcp pob-mcp
```

The error message lists every location it checked.
</details>

<details>
<summary><b>Linux / macOS</b> — one extra build step</summary>

Path of Building only ships a Windows build of the small `lua-utf8` native
module, so compile it once (upstream PoB's own test suite does the same):

```bash
git clone --depth 1 https://github.com/starwing/luautf8.git /tmp/luautf8
mkdir -p ~/.pob-mcp/lib
gcc -O2 -fPIC -shared $(pkg-config --cflags luajit) \
    /tmp/luautf8/lutf8lib.c -o ~/.pob-mcp/lib/lua-utf8.so
```

Then register with the extra paths — MCP clients don't inherit your shell:

```bash
claude mcp add pob --scope user \
  -e POB_ZLIB=/lib/x86_64-linux-gnu/libz.so.1 \
  -e POB_LUA_CPATH="$HOME/.pob-mcp/lib" \
  -e POB_SRC="/path/to/your/PathOfBuilding" \
  -- uvx --from git+https://github.com/MudcrabWarrior/pob-mcp pob-mcp
```

Can't find zlib? `ldconfig -p | grep libz`. Running PoB under Wine works too.

Linux is tested and covered by CI. macOS should work identically but nobody has
confirmed it — reports welcome.
</details>

<details>
<summary><b>All settings</b> — every option is optional</summary>

| Variable | What it's for |
|---|---|
| `POB_SRC` | Your Path of Building folder (the one with `Launch.lua`). Set if auto-detection fails. |
| `POB_LUAJIT` | Path to `luajit`, if it isn't on your `PATH` |
| `POB_ZLIB` | Path to zlib. Automatic on Windows; required on Linux/macOS. |
| `POB_LUA_CPATH` | Extra directories to search for native Lua modules |
| `POB_MCP_CACHE` | Where fetched builds are cached. Default `~/.pob-mcp/cache`, 1-hour TTL. |
| `POB_MCP_TIMEOUT` | Seconds before a call gives up. Default 180; the slow analysis tools always get at least 600. |
| `POB_MCP_USER_AGENT` | Override the `User-Agent` sent to pobb.in / pastebin |

Full walkthrough and every error explained: [`docs/SETUP.md`](docs/SETUP.md).
</details>


pob-mcp is strictly additive. It reads PoB's own files and injects what it needs
at runtime — it never writes into your installation, and CI proves the folder is
byte-identical after a full test run.

Path of Building itself writes `Data/TimelessJewelData/*.bin` caches on first
use, exactly as the desktop app does. That's upstream behaviour, not ours.

## Using it

Just talk normally — there's no syntax to learn and no need to name the tools.
Paste a build link and ask. The assistant picks the right calls itself.

### Start here

> Load `https://pobb.in/YOUR_BUILD` and give me a health check.

That gets you the headline numbers, and it's the fastest way to confirm
everything is wired up.

Want the whole review in one go? The server ships a **`review_build` prompt** —
in clients that support MCP prompts it shows up as a slash command (type `/`
and look for `review_build`) and runs the full workflow: honest-numbers check
first, then gems, tree, upgrades, trade links, and a share code to verify. The
four questions it automates are worth knowing on their own:

### The four questions worth asking

**1. Are my numbers honest?**

> Is my DPS assuming perfect conditions? What does it depend on?

Most build exports quietly assume full charges and a specific enemy. On the
example build above, 41% of the advertised DPS disappears without Frenzy
charges. Ask this *first* — it changes how you read everything else.

**2. What should I upgrade?**

> What are my best upgrades? Rank them by measured delta, and tell me what gets
> worse, not just what improves.

Searches every unique that fits, ranked by real calculation. The "what gets
worse" phrasing matters — it's how you find the +14.6M DPS belt that costs you
8,841 EHP, instead of being told it's simply "the best".

**3. What's dead weight?**

> Which support gem in my main link contributes least? Any allocated tree nodes
> doing nothing?

Frequently finds a gem worth less than levelling your active skill, or passives
you pathed through and forgot.

**4. What do I actually buy?**

> Generate a trade search for better boots for this build.

Weights the search by *your* build's calculated mod values and anchors the
minimums to what you're already wearing.

### Try things before committing to them

> What if I swapped Legacy of Fury in, dropped Increased Critical Damage for
> Elemental Focus, and took the two nodes near Flash Freeze? Show me the deltas.

Batch what-ifs are the workhorse. Nothing changes until you say so, and
`pob_reset()` puts everything back.

### The one habit worth forming

> Export that and give me the share code.

Paste it into desktop Path of Building and check the number yourself. The whole
design assumes you'll want to — and if the GUI ever disagrees with what you were
told, that's a bug worth [reporting](https://github.com/MudcrabWarrior/pob-mcp/issues).

### If a recommendation looks wrong

Two things catch most surprises:

- **Wrong main skill.** Exports are often saved with a utility skill selected
  (an item-granted effect, a curse, a movement skill), which zeroes the damage
  numbers. Ask *"what's my main socket group?"* — and if it's wrong, *"set my
  main skill to X"*.
- **Zero delta isn't the same as useless.** Stun thresholds, ailment immunity
  and flask masteries don't show up in DPS or EHP. A change measuring 0/0 may
  still be doing something the metrics can't see.

---

## Common questions

### Does this work with any AI model, or just Claude?

**Any client that speaks MCP.** The server is a plain stdio MCP server — Claude
Code, Claude Desktop, Cursor, Zed, Continue, and anything else implementing the
protocol. The command is the same everywhere; the JSON-config form is in the
[install section](#command-line-clients-in-detail) above.

One honest caveat: the *numbers* are identical whatever model you use, because
Path of Building computes them. The model only affects the quality of the
reasoning wrapped around those numbers — which combinations it thinks to try,
and how well it explains the trade-offs.

### Do I need an account, API key, or login?

**No. None.** No sign-up, no API key, no OAuth, no telemetry. The server runs
locally as a subprocess and talks to your client over stdin/stdout.

It makes exactly two kinds of outbound request, neither authenticated:

- **Fetching a build** you asked for, from pobb.in, pastebin, or poe.ninja, via
  their public read endpoints — cached on disk for an hour, with a descriptive `User-Agent`
  as [pobb.in's API docs request](https://github.com/Dav1dde/pasteofexile).
- **The current league name**, once a day, from GGG's public
  `api.pathofexile.com/leagues` endpoint.

It never touches the unofficial trade search API, never sends your build
anywhere, and works fully offline if you hand it a local XML file.

### Is it safe to point at my real Path of Building?

Yes. pob-mcp is strictly additive — it loads PoB's own files and injects what it
needs at runtime. It never writes to your installation, and CI asserts the PoB
directory is byte-for-byte unchanged after a full test run.

*(PoB itself writes `Data/TimelessJewelData/*.bin` decompression caches on first
use, exactly as the desktop app does. That's upstream behaviour, not ours.)*

---

## The 17 tools

<div align="center">
  <img src="docs/assets/architecture.svg" alt="pob-mcp architecture: MCP client to pob-mcp to Path of Building, returning verified calculations" width="860">
</div>

**Loading and reading**

| Tool | What it does | Read-only |
|---|---|---|
| `pob_load_build(source)` | pobb.in / pastebin / poe.ninja link, share code, XML file, raw XML — or the name of a build saved in your own PoB | — |
| `pob_list_builds()` | The builds saved in your own PoB, any of which loads by name | ✓ |
| `pob_get_stats(sections?)` | Computed stats — offence, defence, resistances, charges, attributes | ✓ |
| `pob_get_build_detail(section)` | Items by slot, skill groups and links, allocated tree, config flags | ✓ |
| `pob_status()` | Health check: which PoB, LuaJIT and build are in use — works with nothing loaded | ✓ |

**Changing things**

| Tool | What it does | Read-only |
|---|---|---|
| `pob_simulate(scenarios)` | **The workhorse.** Batch what-ifs — items, gems, tree nodes, config, flasks — without committing. Returns every changed stat with better/worse semantics. | ✓ |
| `pob_apply(changes)` | Commit changes to the session | — |
| `pob_reset()` | Restore the build as loaded | — |
| `pob_export()` | Share code for the current state — paste into the GUI to verify | ✓ |

**Analysis**

| Tool | What it does | Read-only |
|---|---|---|
| `pob_find_upgrades(slot?)` | Every unique that fits, ranked by measured delta, defensive cost attached | ✓ |
| `pob_anoint()` | Every anointable notable enchanted onto your amulet, ranked by real delta, oil recipe attached | ✓ |
| `pob_watchers_eye()` | Watcher's Eye mods for *your* active auras, each simulated in your jewel socket | ✓ |
| `pob_analyze_gems()` | Per-support contribution, and +1 level / +quality upside | ✓ |
| `pob_analyze_tree()` | Weakest allocated nodes, best adjacent pickups, mastery-choice check, per-jewel contribution | ✓ |
| `pob_config_sensitivity()` | Which assumptions the headline numbers secretly rest on | ✓ |
| `pob_search_nodes(keyword)` | Search the build's own passive tree version | ✓ |
| `pob_trade_links(...)` | Weighted trade searches and direct unique/gem links | ✓ |

Every tool carries honest [MCP annotations](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#tool-annotations),
so clients can bulk-approve the read-only set instead of prompting on every
call. Nothing here is destructive — "not read-only" means it changes the
in-memory session, which `pob_reset()` undoes. Only `pob_load_build` and
`pob_trade_links` ever touch the network. There's also one **MCP prompt**,
`review_build`, which packages the whole workflow.

Every numeric response carries `_meta` — PoB version, tree version, main skill,
charge and boss configuration. Numbers without their assumptions are a trap.

### Trade links that mean something

`pob_trade_links()` doesn't just search for an item name. For an equipment slot
it drives **Path of Building's own Trade Query Generator**: every candidate mod
is scored through your build's real calculator, and the search minimums are
anchored to the item you're already wearing — so results should actually beat
what you have.

```
pob_trade_links(slots=["Gloves"])

  league        Allflame   (example — the current league is auto-detected, 24h cache)
  stat weights  CombinedDPS ×1.0 · TotalEHP ×0.5   (override with stat_weights)
  → https://www.pathofexile.com/trade/search/…?q=…
```

Want a purely defensive search? `stat_weights=[{"stat":"TotalEHP","weight":1.0}]`.

This builds **URLs only**. It opens nothing, buys nothing, and never queries the
unofficial trade API — you click the link and shop yourself.

---

## Accuracy, stated honestly

Simulation deltas run through `calcs.getMiscCalculator` — the same machinery
behind PoB's own item-hover tooltips. That's the engine; pob-mcp only drives it.

- **Verified against external ground truth.** The primary test build reproduces
  **91 of 91** stats that its author's desktop GUI embedded in the export —
  resistances, EHP, and 59,549,948 Combined DPS, all exact — and this one *is*
  enforced by the test suite. Two older-league minion builds were additionally
  measured by hand at 76/87 and 70/85, every mismatch consistent with
  cross-league balance changes; those two figures are a one-off measurement,
  not a standing assertion.
- **Your numbers come from your Path of Building.** Whatever version you have
  installed is the version used, and every response reports it in `_meta`, so
  a figure is never ambiguous about which PoB produced it. The published
  examples above were measured on 2.66.2.
- **High confidence** for anything the 78 tests cover.
- **Medium confidence** for exotic archetypes outside the test corpus —
  self-trigger loops, aura stacking. Simulation state restoration had one nasty
  class of bug (cross-gem `srcInstance` writes) caught only because a test
  spotted a 12.4M discrepancy. Comparable latent cases may exist.
- **When it matters, check it.** `pob_export()` then import into the GUI. That
  path is deliberately first-class.

### Known limits

- **Keystone and ascendancy *removal*** can't be measured — PoB's quick
  calculator silently ignores it, and the GUI's own hover has the same blind
  spot. We exclude those from rankings rather than report a misleading zero.
- **No prices or availability.** Upgrade results are numeric, not shopping advice.
- **Jewels that rewrite tree nodes** (timeless jewels and kin) are reported
  "not computed" in the jewel scan rather than guessed. Ordinary masteries and
  jewels *are* auto-evaluated by `pob_analyze_tree()`.
- **Unmet attribute requirements are flagged, not priced in.** PoB computes
  every number as if the gear were wearable; results that would break your
  Str/Dex/Int carry an `attrWarning` saying exactly what's missing.
- **A zero DPS/EHP delta doesn't mean useless** — stun tech, ailment immunity and
  flask masteries are invisible to those two metrics.
- **No live GUI sync.** Headless by design.

---

## Tests

You don't need these to *use* pob-mcp — they're here so you can check the claims
above rather than take them on trust. From a clone of this repo:

```bash
python -m pytest tests/
```

78 tests, about a minute:

- **unit** — share-code decode, URL parsing, tool registration, saved-build
  name resolution (incl. path-traversal attempts)
- **external truth** — a real build's GUI-exported stats, reproduced 91/91
- **regression** — 7 archetypes incl. two minion builds, pinned to one PoB version;
  anoint, Watcher's Eye, mastery/jewel analysis and attribute warnings against real calcs
- **adversarial** — corrupt XML, dead links, bogus slots, killing the engine mid-session
- **trade** — link construction and the PoB-driven weighted query generator

CI runs the suite on Ubuntu **and Windows**, against both PoB layouts on each,
and asserts the Path of Building directory is unmodified afterwards.

---

## Credits

**This project is a thin layer on other people's excellent work.** It would not
exist without any of the following, and I'm grateful to all of them.

### Path of Building Community

[**@PathOfBuildingCommunity**](https://github.com/PathOfBuildingCommunity/PathOfBuilding)
— everything here is a remote control for *their* calculation engine. Years of
meticulous, unglamorous work reverse-engineering and maintaining Path of Exile's
damage formulas. Every number pob-mcp reports is theirs; the hard part was
already done. Originally created by **Openarl**, and carried forward since by the
community fork's maintainers and contributors. MIT licensed.

If you find this tool useful, go
[star Path of Building](https://github.com/PathOfBuildingCommunity/PathOfBuilding)
and consider contributing there — it helps far more players than this ever will.

### The headless API groundwork

[**@ianderse**](https://github.com/ianderse) — author of
[PR #9505, *"Add headless JSON-RPC API for programmatic PoB access"*](https://github.com/PathOfBuildingCommunity/PathOfBuilding/pull/9505),
and of [ianderse/pob-mcp](https://github.com/ianderse/pob-mcp). `pob_mcp/bridge/pob_ops.lua`
is adapted directly from that PR's `BuildOps.lua` (MIT, unchanged apart from an
attribution header). He worked out the build-operation layer first; this project
started from it rather than reinventing it.

**Please go support [PR #9505](https://github.com/PathOfBuildingCommunity/PathOfBuilding/pull/9505).**
A merged upstream headless API would benefit every tool in this space, and it's
been open a long time.

*(Note on licensing: ianderse also maintains a `pob-mcp` repository under GPL-3.
This project takes only the **MIT-licensed upstream PR #9505**, not that
repository. [`NOTICE.md`](NOTICE.md#relationship-to-ianderspob-mcp-gpl-30) sets
out exactly what the two codebases share, how that was measured, and a
correction to an earlier claim that was measured wrongly.)*

### Everyone else

- [**@Dav1dde**](https://github.com/Dav1dde) — [pobb.in / pasteofexile](https://github.com/Dav1dde/pasteofexile),
  where most build links live, and one of the few community services with a
  properly documented public API. Build loading leans on it.
- [**Mike Pall**](https://luajit.org/) — LuaJIT, which runs the whole engine, fast.
- [**@starwing**](https://github.com/starwing/luautf8) — `luautf8`, the native
  module PoB needs and that Linux/macOS users build from source.
- [**@atty303**](https://github.com/atty303/pob-web) — [pob-web](https://github.com/atty303/pob-web)
  runs unmodified PoB in the browser via WebAssembly. Studying how it hosts PoB
  without forking it shaped this project's "never modify the install" approach.
- [**@brather1ng** and the RePoE maintainers](https://github.com/repoe-fork/repoe)
  — game data extraction the whole third-party ecosystem depends on.
- **Grinding Gear Games** — for Path of Exile, and for tolerating a rich
  third-party tool ecosystem around it.

### Disclaimer

> This product isn't affiliated with or endorsed by Grinding Gear Games in any way.

Path of Exile is a trademark of Grinding Gear Games.

---

## Contributing

Bug reports, archetype coverage, and macOS confirmation are all genuinely
useful. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) first — especially the
"never fabricate a number" rule, which is enforced in review.

Further reading: [`docs/SETUP.md`](docs/SETUP.md) ·
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) ·
[`docs/pob-internals.md`](docs/pob-internals.md) ·
[`docs/DECISIONS.md`](docs/DECISIONS.md) ·
[`docs/KNOWN_UNKNOWNS.md`](docs/KNOWN_UNKNOWNS.md)

## Licence

MIT — see [`LICENSE`](LICENSE). Third-party notices in [`NOTICE.md`](NOTICE.md).
