homebox-mcp 0.9.0__tar.gz

homebox_mcp-0.9.0/.env.example

@@ -0,0 +1,21 @@
+# Copy to .env (gitignored, chmod 600) and fill in.
+#
+# Create an API key in Homebox: Profile → API Keys, or
+#   POST /api/v1/users/self/api-keys  {"name": "homebox-mcp"}
+
+# Base URL of your Homebox instance (no trailing slash).
+HOMEBOX_URL=http://localhost:7745
+
+# Homebox API key (starts with hb_).
+HOMEBOX_TOKEN=hb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# --- Optional -------------------------------------------------------------
+
+# Name of one custom field used as a stable item identifier: tools resolve
+# items by it and field_index() defaults to it. Unset = resolve by
+# assetId/name only.
+#HOMEBOX_ALIAS_FIELD=item_id
+
+# Directory where generate_label / qrcode save PNG/JPEG output.
+# Default: current working directory.
+#HOMEBOX_LABEL_DIR=~/homebox-labels

homebox_mcp-0.9.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run tests
+        # --with . installs the package (and its deps: mcp, httpx, pillow,
+        # pillow-heif) so nothing is mocked away; --with pytest/respx add the
+        # test-only tooling.
+        run: uv run --with pytest --with respx --with . pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Ruff
+        run: uvx ruff check .

homebox_mcp-0.9.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Trusted publishing (OIDC) — no API token/secret needed.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

homebox_mcp-0.9.0/.gitignore

@@ -0,0 +1,32 @@
+# Secrets — never commit the live credential (keep the template)
+.env
+.env.local
+!.env.example
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+
+# uv
+.uv/
+
+# IDE / tooling
+.claude/
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local MCP configuration
+.mcp.json
+
+# build artifacts
+dist/
+*.egg-info/

homebox_mcp-0.9.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versioning: [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+### Changed (BREAKING)
+- `create_item`: personal named params (`item_id`, `category`, `dossier`,
+  `resale_value`, `value_asof`, `value_source`) replaced by a generic
+  `fields: dict` — each value's JSON type picks the custom-field type
+  (string → text, number → number [integer-coerced], boolean → boolean).
+- `set_value` replaced by generic `set_fields(identifier, fields)` (same typed
+  mapping, upsert semantics).
+- `existing_item_ids()` replaced by `field_index(field_name?)` — a
+  `{field_value: assetId}` index over any custom field, defaulting to
+  `$HOMEBOX_ALIAS_FIELD`.
+- Write tools (`set_warranty`, `set_fields`, `set_identity`, `set_tags`,
+  `attach_document`) now require an exact identifier (assetId, alias field, or
+  name); fuzzy matches are refused and multiple exact matches error with the
+  candidates listed, so a typo can no longer mutate the wrong item. Read tools
+  (`get_item`, `generate_label`) keep the fuzzy fallback.
+- `set_location`'s `fields` values are typed by JSON type (was text-only).
+
+### Added
+- `move_item(identifier, location)` — move an item via partial PATCH.
+- `set_item(...)` — general item editor (rename, description, notes, quantity,
+  purchase info, insured/archived, custom fields); quantity-only edits use
+  PATCH.
+- Confirm-gated delete tools: `delete_item`, `delete_location` (refuses
+  non-empty unless `confirm_nonempty=True`; sub-locations cascade, items are
+  orphaned), `delete_tag`, `delete_attachment` — `confirm` must equal the
+  target's exact name; all carry the MCP `destructiveHint` annotation.
+- Attachment management: `list_attachments` (ids/types/titles),
+  `get_attachment` (download to a local path), `rename_attachment`
+  (title/type/primary).
+- `search_items` accepts `tags` (tag names) and/or `query`.
+- MCP tool annotations (`readOnlyHint`/`idempotentHint`/`destructiveHint`) on
+  all tools.
+- `HOMEBOX_ALIAS_FIELD` env var: name one custom field as a stable item
+  identifier (items resolve by it; summaries surface it). Previously the
+  `item_id` field name was hard-coded.
+- `HOMEBOX_LABEL_DIR` env var: where `generate_label`/`qrcode` save output
+  (default: current directory; previously a hard-coded personal path).
+- `warranties_expiring`: `after` bound (defaults to today, so already-expired
+  warranties are excluded by default) and `lifetime=True` to list
+  lifetime-warranty items.
+- Locations can be referenced by `/`-separated path (e.g. `Garage/Shelf 1`)
+  everywhere a location name is accepted; ambiguous bare names now error with
+  the matching paths listed instead of silently using the first match.
+- Version guard: tools fail with a clear message against pre-0.26 Homebox.
+- `__version__` on the server module.
+- This changelog.
+- Packaging: `pyproject.toml` (PyPI name `homebox-mcp`, console script
+  `homebox-mcp`); the module renamed `server.py` → `homebox_mcp.py` with a
+  `server.py` compatibility shim so existing MCP registrations keep working.
+- Test suite (pytest + respx, fully mocked) and GitHub Actions CI
+  (tests on Python 3.10/3.13, ruff) + PyPI trusted-publishing workflow.
+- README overhauled for public release; CONTRIBUTING.md added.
+
+### Fixed
+- `location_contents` never listed sub-locations on Homebox 0.26.2:
+  `GET /entities` returns non-location entities only, so location children
+  were invisible to `parentIds` queries (latent upstream-behavior bug).
+  Sub-locations now come from the entity tree; `delete_location`'s emptiness
+  check counts both kinds.
+- `location_contents(recursive=True)` now finds items nested inside items
+  (0.26 unified entities — e.g. lenses inside a camera bag).
+- `set_tags` uses partial PATCH instead of the GET→preserve→PUT cycle.
+- Pagination: entity listings over one page (200 entities) were silently
+  truncated, breaking search/dedupe/warranty sweeps on large inventories.
+- API failures now surface as legible tool errors (HTTP status + Homebox's
+  response body) instead of raw tracebacks.
+- `create_item` date args are RFC3339-normalized like `set_warranty`'s.
+- `create_location` duplicate check is per-parent, so the same tote/shelf name
+  can exist under different parents.
+
+### Changed
+- Default branch renamed `master` → `main`.
+- `.env.example` documents all supported environment variables.

homebox_mcp-0.9.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Thanks for your interest in improving `homebox-mcp`. It's a small, single-module
+MCP server, so contributing is lightweight.
+
+## Development setup
+
+You need [`uv`](https://docs.astral.sh/uv/). The server is one module
+(`homebox_mcp.py`) with [PEP 723](https://peps.python.org/pep-0723/) inline
+dependencies, so there's nothing to install up front — `uv` resolves everything
+on demand.
+
+```bash
+git clone https://github.com/dgahagan/homebox-mcp
+cd homebox-mcp
+```
+
+## Tests
+
+Tests use `pytest` with [`respx`](https://lundberg.github.io/respx/) to mock the
+Homebox HTTP API — **no live instance is required or should be used** for the
+suite:
+
+```bash
+uv run --with pytest --with respx --with . pytest
+```
+
+## Lint
+
+Code is linted with [`ruff`](https://docs.astral.sh/ruff/) (config in
+`pyproject.toml`; line length 100):
+
+```bash
+uv run --with ruff ruff check .
+```
+
+## Pull requests
+
+- **Add tests for behavior changes.** The full-body-PUT preserve logic and the
+  typed custom-field handling are exactly the kind of thing that regresses
+  silently — cover new or changed behavior with a mocked-httpx test.
+- **Update [`CHANGELOG.md`](CHANGELOG.md)** under the `Unreleased` section
+  ([Keep a Changelog](https://keepachangelog.com/) format).
+- **Keep it lint-clean** (`ruff check .` passes).
+- **Keep tool docstrings accurate** — they are the source of truth for the tool
+  reference in the README and for how MCP clients present each tool.
+
+## Testing against a live Homebox instance
+
+If you validate a change against a real Homebox instance, **use disposable data
+only** — create clearly-marked throwaway items/locations and delete them
+afterward. Never test against inventory you care about, and never point the
+suite or ad-hoc scripts at a production instance's real data.
+
+By contributing you agree that your contributions are licensed under the
+project's [MIT License](LICENSE).

homebox_mcp-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Gahagan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

homebox_mcp-0.9.0/PKG-INFO

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: homebox-mcp
+Version: 0.9.0
+Summary: MCP server for Homebox (>= 0.26): inventory Q&A, intake, attachments, labels
+Project-URL: Homepage, https://github.com/dgahagan/homebox-mcp
+Project-URL: Changelog, https://github.com/dgahagan/homebox-mcp/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/dgahagan/homebox-mcp/issues
+Author: Dan Gahagan
+License: MIT License
+        
+        Copyright (c) 2026 Dan Gahagan
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: claude,homebox,inventory,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Home Automation
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.10
+Requires-Dist: pillow-heif>=0.16
+Requires-Dist: pillow>=10
+Description-Content-Type: text/markdown
+
+# homebox-mcp
+
+[![PyPI version](https://img.shields.io/pypi/v/homebox-mcp.svg)](https://pypi.org/project/homebox-mcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/dgahagan/homebox-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/dgahagan/homebox-mcp/actions/workflows/ci.yml)
+
+An [MCP](https://modelcontextprotocol.io) server over the
+[Homebox](https://homebox.software) REST API, so an MCP client like Claude can
+work with your home inventory in plain language: *"where is my impact driver",*
+*"what's in Tote B-3", "which warranties expire this year", "add this drill —
+here's a photo of the receipt and the model number".* It answers questions,
+performs intake (create an item, attach the manual/receipt, tag and file it),
+manages attachments, and prints QR labels for totes and shelves — no
+hand-rolled `curl`.
+
+## Quickstart
+
+You need a running Homebox instance (**0.26+**, see [Requirements](#requirements))
+and an API key from **Profile → API Keys** in the Homebox web UI.
+
+### Claude Code
+
+```bash
+claude mcp add homebox --scope user \
+  -e HOMEBOX_URL=https://homebox.example.com \
+  -e HOMEBOX_TOKEN=hb_xxxxxxxxxxxxxxxxxxxxxxxx \
+  -- uvx homebox-mcp
+claude mcp get homebox      # should show: Status ✔ Connected
+```
+
+`--scope user` makes it available from any project. `uvx` fetches and runs the
+published package in an ephemeral environment — nothing to install first.
+
+### Claude Desktop / generic MCP clients
+
+Add to your client's MCP config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "homebox": {
+      "command": "uvx",
+      "args": ["homebox-mcp"],
+      "env": {
+        "HOMEBOX_URL": "https://homebox.example.com",
+        "HOMEBOX_TOKEN": "hb_xxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### From a clone (no PyPI)
+
+The module carries [PEP 723](https://peps.python.org/pep-0723/) inline
+dependencies, so it also runs standalone with `uv run --script` — `uv` resolves
+`mcp`, `httpx`, `pillow`, and `pillow-heif` into an ephemeral venv on first run.
+Instead of env vars, drop credentials in a `.env` file next to the module:
+
+```bash
+git clone https://github.com/dgahagan/homebox-mcp
+cd homebox-mcp
+cp .env.example .env        # .env is gitignored
+chmod 600 .env
+# edit .env: HOMEBOX_URL + HOMEBOX_TOKEN
+```
+
+Then register the **absolute path** to the module (or to `server.py`, a
+compatibility shim kept for older registrations):
+
+```bash
+claude mcp add homebox --scope user -- \
+  uv run --script /path/to/homebox-mcp/homebox_mcp.py
+```
+
+The server reads config from the environment, falling back to the sibling
+`.env` (resolved relative to the script, so the absolute-path invocation still
+finds it). The credential never enters the MCP config — it stays in the
+gitignored `.env`.
+
+## Requirements
+
+- **Homebox 0.26 or newer** — the actively maintained
+  [sysadminsmedia fork](https://github.com/sysadminsmedia/homebox) at
+  [homebox.software](https://homebox.software). This server speaks the unified
+  **entities** API introduced in 0.26. Older instances use a different API
+  (`/items`, `/locations`, `/labels`) and are rejected on the first tool call
+  with a clear error rather than failing cryptically.
+- **An API key** — Homebox **Profile → API Keys** (the token starts with `hb_`).
+- **[`uv`](https://docs.astral.sh/uv/)**, or any **Python ≥ 3.10** environment
+  where you install `homebox-mcp` yourself.
+
+## Configuration
+
+All configuration is via environment variables (or the sibling `.env` for the
+clone workflow):
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `HOMEBOX_URL` | yes | Base URL of your Homebox instance (no trailing slash). |
+| `HOMEBOX_TOKEN` | yes | Homebox API key (`hb_…`). |
+| `HOMEBOX_ALIAS_FIELD` | no | Name of one custom field to treat as a stable item identifier — items can be resolved by it, summaries surface it, and `field_index` defaults to it. Unset = resolve by assetId/name only. See [Conventions](#conventions-optional). |
+| `HOMEBOX_LABEL_DIR` | no | Where `generate_label` / `qrcode` save output. Default: current working directory. |
+
+## Tools
+
+~33 tools. Reads accept a **fuzzy** identifier (assetId, alias field, exact
+name, then first keyword match). Write tools require an **exact** identifier
+(assetId, alias field, or exact name) — a typo or an ambiguous match is refused
+rather than mutating the wrong item. Locations are referenced by name or
+`/`-separated path (e.g. `Garage/Shelf 1`) to disambiguate duplicate names.
+
+### Read / Q&A
+
+| Tool | Purpose |
+|------|---------|
+| `search_items(query?, tags?, limit=20)` | Search items by keyword and/or tag names (AND of both); returns each with assetId, location, and the alias field. |
+| `get_item(identifier)` | Full detail for one item: location path, identity, purchase, warranty, custom fields, tags, attachments. |
+| `list_locations()` | The full location tree as an indented outline. |
+| `location_contents(location, recursive=False)` | Items directly in a location plus its sub-location names; `recursive=True` walks the whole subtree and returns every nested item with its full location path. |
+| `list_tags(detail=False)` | All tag (label) names; `detail=True` returns full objects (description, color, icon, parent tag). |
+| `warranties_expiring(before?, after?, lifetime=False)` | Items whose warranty expires in `after…before` (`after` defaults to today, excluding already-expired); `lifetime=True` lists lifetime-warranty items. |
+
+### Create & intake
+
+| Tool | Purpose |
+|------|---------|
+| `create_item(name, location?, quantity=1, manufacturer?, model?, serial?, purchase_price?, purchase_date?, purchase_from?, warranty_expires?, notes?, fields?, tags?)` | Create and enrich an item in one call. `fields` is a dict typed by JSON value (string→text, number→number [integer-coerced], bool→boolean); `tags` must already exist. Returns the new assetId. |
+| `import_csv(csv_text)` | Bulk-create items and locations from a Homebox CSV in one multipart request. `HB.location` **auto-creates** the path hierarchy; recognizes `HB.name`, `HB.tags`, `HB.quantity`, `HB.serial_number`, `HB.model_number`, `HB.manufacturer`, `HB.notes`, `HB.purchase_*`, `HB.warranty_expires`, `HB.field.<name>`. |
+| `create_location(name, parent?, description?)` | Create a location (tote/bin/shelf) to bootstrap a new storage spot; `description` doubles as a contents manifest. |
+| `barcode_lookup(code)` | UPC/EAN → name/manufacturer/model (optional, for boxed goods). |
+
+### Edit
+
+All write tools resolve by exact identifier and preserve everything you don't
+touch (a full-body PUT that echoes the rest of the item back — see
+[gotchas](#how-it-works-and-homebox-026-gotchas)).
+
+| Tool | Purpose |
+|------|---------|
+| `set_item(identifier, new_name?, description?, notes?, quantity?, purchase_price?, purchase_date?, purchase_from?, insured?, archived?, fields?)` | General item editor: rename, notes, quantity, purchase info, insured/archived flags, custom fields. Quantity-only edits use a partial PATCH. |
+| `move_item(identifier, location)` | Move an item to another location (partial PATCH — nothing else changes). |
+| `set_warranty(identifier, expires?, lifetime?, details?)` | Set warranty end date, lifetime flag, and terms summary. |
+| `set_identity(identifier, manufacturer?, model_number?, serial_number?)` | Set manufacturer / model / serial (e.g. after a nameplate photo reveals them). |
+| `set_fields(identifier, fields)` | Create or overwrite custom fields (upsert; typed by JSON value type). |
+| `set_tags(identifier, tags, mode="add")` | Add / remove / replace tags on an item; unknown tag names are auto-created (partial PATCH). |
+| `set_tag(name, new_name?, description?, color?, icon?, parent?, clear_parent=False)` | Edit **a tag's own** metadata (rename, color, icon, parent tag for grouping) — not what's tagged on an item. Creates the tag if new. |
+| `set_location(location, new_name?, parent?, clear_parent?, description?, notes?, tags?, tags_mode?, entity_type?, asset_id?, fields?)` | General location editor: rename, move (or `clear_parent` to root), tags, notes, entity type, assetId, custom fields. |
+| `set_location_manifest(location, description)` | Set a location's contents-manifest `description` (echoes name/parent/assetId so the PUT doesn't wipe them). |
+
+### Attachments
+
+| Tool | Purpose |
+|------|---------|
+| `attach_document(identifier, source, title, doc_type="manual", primary=False)` | Attach a file (local **path or http(s) URL**) to an item, or to a location by name as a fallback. `doc_type` e.g. manual/receipt/warranty/photo. |
+| `attach_location_photo(location, source, title?, primary=True)` | Attach a photo to a **location** as its primary "this is the spot" image for wayfinding. |
+| `list_attachments(identifier)` | List an item's or location's attachments **with their ids** (the handle the other attachment tools need). |
+| `get_attachment(identifier, attachment_id, save_to)` | Download one attachment to a local path so its content (e.g. a manual) can be read. |
+| `rename_attachment(identifier, attachment_id, title?, doc_type?, primary?)` | Update an attachment's title, type, or primary flag. |
+
+> Uploads auto-convert HEIC/HEIF (iPhone photos) to JPEG so Homebox always
+> stores a browser-renderable image, and sanitize `/` in titles (Homebox treats
+> a title as a path and would otherwise truncate it).
+
+### Deletes (confirm-gated)
+
+Every delete requires `confirm` to equal the target's exact name and carries
+the MCP `destructiveHint` annotation, so clients prompt before running them.
+
+| Tool | Purpose |
+|------|---------|
+| `delete_item(identifier, confirm)` | Permanently delete an item and its attachments. No undo. |
+| `delete_location(location, confirm, confirm_nonempty=False)` | Delete a location. A non-empty one is refused unless `confirm_nonempty=True`: **sub-locations cascade (are deleted); items are orphaned to the top level** (not deleted). |
+| `delete_tag(name, confirm)` | Delete a tag itself (removed from every tagged item; the items survive). |
+| `delete_attachment(identifier, attachment_id, confirm)` | Delete one attachment (`confirm` = its exact title). |
+
+### Labels & finalize
+
+| Tool | Purpose |
+|------|---------|
+| `generate_label(identifier, kind="location", out_dir?)` | Save a printable label **PNG** (QR + readable name) for a `location`, `item`, or `asset`. Saves to `$HOMEBOX_LABEL_DIR` (else CWD). |
+| `qrcode(data, out_dir?)` | Save a raw QR **JPEG** for arbitrary data (prefer `generate_label` for totes — it adds the name). |
+| `set_primary_photos()` | Ensure every entity with photos has a primary image (finalize after a bulk photo attach). |
+| `create_thumbnails()` | Generate any missing photo thumbnails (finalize after a bulk photo attach). |
+| `field_index(field_name?)` | `{field_value: assetId}` index over a custom field (default `$HOMEBOX_ALIAS_FIELD`) — a one-pass **dedupe** index before a bulk import, since `q` doesn't index custom fields. |
+
+## How it works (and Homebox 0.26 gotchas)
+
+The value of this server is as much in what it works *around* as in what it
+exposes. These are hard-won behaviors of the 0.26 entities API:
+
+- **Items and locations are unified "entities"** (`/v1/entities`); a location is
+  an entity whose entity-type has `isLocation=true`. A new item with no
+  entityTypeId lazily gets a default `Item` type.
+- **`GET /entities` returns non-location entities only.** Location children never
+  appear in `/entities` results, even with `parentIds` — sub-locations come from
+  the entity tree (`/entities/tree`). `location_contents` merges both sources, and
+  `delete_location`'s emptiness check counts items *and* sub-locations.
+- **Deleting a non-empty location cascades sub-locations but orphans items.**
+  Force-deleting a location (`confirm_nonempty=True`) deletes its sub-locations
+  with it, but its **items survive**, re-parented to the top level. Move items
+  out first if you don't want them loose.
+- **List/search responses are lightweight summaries** — they omit `fields` and
+  have an empty `assetId`. The server fetches full detail (`GET /entities/{id}`)
+  before returning assetId/alias, so `search_items`/`get_item` are accurate.
+- **`q` does not index custom fields.** Resolving by an alias-field value uses a
+  scan fallback (one detail fetch per item). Resolving by **assetId** (via
+  `/v1/assets/{id}`) or **name** is cheaper — prefer assetId when you have it
+  (e.g. the value `create_item` returns).
+- **PUT clears omitted fields**, including `assetId`. Every write tool rebuilds a
+  full body from a fresh GET (`_preserve_item_body`) and overrides only the
+  targeted keys. `create_item` assigns the asset ID *after* enrichment so it
+  survives.
+- **Attachment titles are basenamed on `/`.** Homebox treats a title as
+  path-like, so "front 3/4 view" silently stores as "4 view". The server
+  sanitizes `/`→`-` in attach titles.
+- **Number custom fields are integer-typed.** A float `numberValue` (e.g.
+  `17000.0`, which FastMCP produces from a `float`-typed arg) makes the API
+  **500 "Unknown Error"**. The server coerces number values to `int`; pass whole
+  numbers.
+- **Custom-field values are type-keyed** (`textValue` / `numberValue` /
+  `booleanValue`). The server rebuilds each field by its declared type —
+  coercing everything to `textValue` (an earlier bug) silently wiped
+  numeric/boolean fields on any PUT.
+- **Pagination.** Entity listings over one page (200) were silently truncated;
+  the server pages through to the reported `total`, so search, dedupe, and
+  warranty sweeps stay correct on large inventories.
+
+## Conventions (optional)
+
+Homebox's built-in `assetId` is a stable numeric handle, but it isn't something
+you'd type from memory. If you want a **human-meaningful stable identifier** —
+useful for cross-referencing items with receipts, spreadsheets, or another
+system — add a custom field (say `item_id`) holding a slug like
+`makita-xdt131` and point `HOMEBOX_ALIAS_FIELD` at it. Then:
+
+- items resolve by that slug in every read and write tool,
+- `search_items`/`get_item` summaries surface it, and
+- `field_index()` defaults to it, giving you a one-call dedupe map before a bulk
+  import.
+
+This is entirely optional — leave `HOMEBOX_ALIAS_FIELD` unset and items resolve
+by assetId or name only. Nothing about the field name is special; any single
+custom field works.
+
+## Companion scripts
+
+Two standalone helper scripts ship in the repo (not MCP tools):
+
+- **`annotate_location_photos.py`** turns one wide photo of a shelf bank into one
+  boxed/labeled image per shelf (`--rows N`), and can upload each straight to its
+  Homebox location with `--upload`. See its `--help`.
+- **`heic2jpg.py`** converts HEIC/HEIF (iPhone photos) to JPEG for ad-hoc use
+  (`./heic2jpg.py FILE...`). Note the attach tools **already auto-convert HEIC on
+  upload**, so this is only needed to feed HEIC frames to a vision step *before*
+  upload.
+
+Both rely on `pillow-heif`, which bundles libheif — there's no system package to
+install.
+
+## Security
+
+- **API key handling.** In the clone workflow the key lives in `.env`, which is
+  gitignored and should be mode `600` (`chmod 600 .env`). Never commit it. In the
+  `uvx` workflow it's passed through your MCP client's config — treat that file
+  as a secret too.
+- **Key rotation.** Rotating the Homebox `HBOX_AUTH_API_KEY_PEPPER` invalidates
+  every issued key — mint a new one and update your config.
+- **Confirm-gated deletes.** All four delete tools require `confirm` to equal the
+  target's exact name and carry the MCP `destructiveHint` annotation, so a
+  well-behaved client prompts before any destructive call.
+- **Use HTTPS** for any remote Homebox instance — the API key is sent on every
+  request in the `Authorization` header.
+
+## Development
+
+```bash
+git clone https://github.com/dgahagan/homebox-mcp
+cd homebox-mcp
+
+# Run the test suite (httpx mocked with respx — no live instance needed)
+uv run --with pytest --with respx --with . pytest
+
+# Lint
+uv run --with ruff ruff check .
+```
+
+The server is a single module (`homebox_mcp.py`) with PEP 723 inline
+dependencies. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and PR
+expectations, and [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## License
+
+[MIT](LICENSE) © Dan Gahagan