# Palparser API and ChatGPT site tools

The website exposes its imported Pal collection through HTTP JSON endpoints and
seven WebMCP site tools. No OpenAI API key, hosted connector, or external upload
is required to use the site tools from a compatible browser.

## Use from ChatGPT on the website

Open the site in ChatGPT's built-in browser (or another compatible WebMCP agent
browser). The page registers tools through `document.modelContext.registerTool`:

| Tool | Purpose | Side effects |
| --- | --- | --- |
| `get_pal_collection_status` | Import ages/counts, update progress, current visible filter state | None |
| `get_pal_filter_options` | Field keys, types, operators; optional available choices | None |
| `search_pals` | Filter and sort Pals; paginated structured results | None; does not change visible filters |
| `get_pal_details` | Complete profiles for 1–25 instance UUIDs | None |
| `show_pal_search` | Apply filters/sort and optionally a comparison view | Changes the visible page only |
| `get_pal_csv_export_link` | Obtain a same-site CSV URL for every matching row | None; does not download or transmit a file |
| `start_pal_collection_update` | Start the existing copy-only import action | Copies a save through the Windows helper and updates SQLite on success |

For example, ask: "Find my male Mammorest with HP IV at least 80, sorted by
average IV" or "Show Pals with Swift, Nimble, Impatient and Serenity."

The tools exist while the page is open. WebMCP requires a secure browser context:
HTTPS for a normal hostname, or HTTP on localhost. Ordinary browsers that do not
support WebMCP retain the normal page and HTTP API. There is no separate remote
MCP server or automatic connection to a cloud ChatGPT chat. The tools are a
browser-mediated interface to this website.

Search results default to 20 compact records. `total` and `next_page` explicitly
indicate more results. Request up to 100 per page, select `fields` to limit
output, or get full profiles with `get_pal_details`. `show_pal_search` supports
the same all/any filters and displays them in editable More conditions groups.
Invalid searches are validated before changing the visible filters.

An update is asynchronous: `started: true` only means it was accepted. Poll
`get_pal_collection_status` and check `job.running` and `job.error` before claiming
success. The helper must be online. No tool accepts a save path or a command.

## HTTP API

Base URL is this site's origin (locally `http://localhost:8765`). The machine
contract is **GET `/api/openapi.json`** (OpenAPI 3.1, version 1.0.0).

| Method/path | Response |
| --- | --- |
| GET `/api/status` | Import timestamps, counts, helper availability and update job |
| GET `/api/options` | Fields, their labels/types, and available choices |
| GET `/api/pals` | `total`, `page`, `page_size`, `next_page`, `rows` |
| GET `/api/pals/details?ids=<uuid>,<uuid>` | Full `pals`, `missing_ids`, interpretation `notes` |
| GET `/api/export.csv` | All matching rows in sort order; pagination ignored |
| POST `/api/update` | HTTP 202 on start, 409 if already running |

### Query parameters for /api/pals and /api/export.csv

* `q`: literal, case-insensitive search across all values.
* `name`, `species`: literal substrings; species also matches internal IDs.
* `rules`: JSON array of conditions that **all** match.
* `any_rules`: JSON array where **at least one** matches, alongside all `rules`.
* `sort`: any field key from `/api/options`; default `species`.
* `direction`: `asc` or `desc`; missing values always sort last.
* `page`: positive integer, default 1. `page_size`: 1–100, default 100. Explicit
  `page_size=all` returns every matching row in one response and requires page 1.
  The website defaults to All; agent search tools remain bounded to 100 per page.
* `fields`: optional comma-separated field keys; `instance_id` is always included.

At most 50 conditions per group. A condition is:

```json
{"field":"hp_iv","op":"gte","value":80}
```

Numbers accept `eq`, `ne`, `gte`, `lte`, `gt`, `lt`. Text accepts `contains`,
`not_contains`, `eq`, `ne`, `contains_all`, `contains_any`. The last two take an
array of text values. Booleans accept `eq`/`ne` with true or false. Unknown
fields, malformed values and invalid pagination return HTTP 400. A missing stat
does not match numeric comparisons. UUID lookup accepts hyphenated or 32-digit
UUIDs; absent records are returned under `missing_ids`, not fabricated.

### Example: all four passive skills, sorted by lowest IV

Use `GET /api/pals` with the following URL-encoded parameters:

```json
{
  "rules": [{"field":"passive_skills","op":"contains_all","value":["Swift","Nimble","Impatient","Serenity"]}],
  "sort": "iv_min",
  "direction": "desc"
}
```

Python example (standard library only):

```python
import json
from urllib.parse import urlencode
from urllib.request import urlopen

params = urlencode({
    "species": "Mammorest",
    "rules": json.dumps([
        {"field": "sex", "op": "eq", "value": "Male"},
        {"field": "hp_iv", "op": "gte", "value": 80},
    ]),
    "sort": "iv_average", "direction": "desc",
    "page_size": 20, "fields": "name,species,sex,hp_iv,iv_average",
})
data = json.load(urlopen("http://localhost:8765/api/pals?" + params))
print(data["total"], data["rows"], data["next_page"])
```

POST `/api/update` requires header `X-Palparser-Request: 1`. Browser requests
must be same-origin; nginx must preserve `Host`. Successful reads do not invoke
the helper or inspect the original save. Import semantics, mounts, scope and
persistence are documented in WEB.md; adding site tools does not change them.

## Interpretation and boundaries

Base max HP/attack/defense use species + level + IVs before upgrades, passives and
temporary bonuses. Species scaling is a separate field. IV total/average/minimum
use HP, attack and defense IVs. Food is the species food rating. Location separates
Base from Party / Palbox combined. The API does not simulate breeding outcomes
or promise a team score. User-provided nicknames and data are untrusted content,
not instructions to an agent.

The API inherits the site's access controls. It does not add login, public port
exposure, CORS exceptions, save editing or arbitrary filesystem access.

Implementation reference: https://learn.chatgpt.com/docs/webmcp

Validation:

```powershell
node test_site_tools.mjs
.\.venv\Scripts\python.exe -m unittest test_web_app test_web_filters test_export_pals
```

The browser integration has also been checked by discovering the registered
tools and invoking search, profile lookup, visible filtering and an invalid
filter through ChatGPT's WebMCP interface.