# Boxes MCP

An unofficial, local-first [Model Context Protocol](https://modelcontextprotocol.io/) server for inventory data exported from **Boxes: Storage made simple**.

Boxes MCP turns your spaces, containers, nested items, values, custom fields, and downloaded photos into a private mirror that an MCP client can search and analyze. Boxes remains the capture app and source of truth.

> This project is not affiliated with, endorsed by, or sponsored by StackTracks, LLC. “Boxes” is used only to identify compatibility with the Boxes app. No Boxes logos or proprietary code are included.

## Status

Early preview. The server, format-tolerant CSV/ZIP importer, signed webhook verifier, and export-request adapter are implemented. Exact field mapping will be tightened against a sanitized real export.

The package is named `boxes-home-inventory-mcp` because the npm name `boxes-mcp` is already used by an unrelated GNOME virtualization project.

## Quick start

Requires Node.js 20 or newer.

```bash
npm install
npm run build
node dist/src/cli.js import /path/to/boxes-export.zip
node dist/src/cli.js serve
```

Add the local server to an MCP client:

```json
{
  "mcpServers": {
    "boxes": {
      "command": "node",
      "args": ["/absolute/path/to/boxes-mcp/dist/src/cli.js", "serve"],
      "env": {
        "BOXES_MCP_DATA_FILE": "/absolute/private/path/inventory.json",
        "BOXES_MCP_MEDIA_DIR": "/absolute/private/path/media"
      }
    }
  }
}
```

Inventory data and images are ignored by Git. Do not commit real exports or your `data/` directory.

## Tools

- `search_inventory` — search names, notes, locations, tags, and custom fields.
- `get_inventory_object` — fetch a record by stable ID.
- `list_contents` — list the objects directly inside a space or container.
- `inventory_totals` — summarize counts, quantity, and declared value.
- `documentation_audit` — find items missing photos, values, receipts, or other requested evidence.
- `get_sync_status` — inspect import/webhook freshness.
- `request_export` — call a Boxes-approved export endpoint when one is configured.

## Importing exports and images

Request an export in Boxes from **Dashboard → Manage Data → Export Data**. Import the downloaded CSV, a directory of CSVs, or a ZIP containing CSVs:

```bash
boxes-mcp import ~/Downloads/boxes-export.zip
```

If your image ZIP is separate, import it too. Image files are copied into the private media directory with SHA-256 filenames so duplicates are stored once.

The importer preserves every original column in `raw`, even when it does not recognize the field yet.

## Export-request automation

Boxes currently documents export requests through its iOS interface, not a public API. Its terms prohibit reverse-engineering and unauthorized automated access. For that reason, this project does not embed private mobile endpoints or ask for your Boxes password.

The MCP tool is ready for an approved endpoint. Once Boxes provides an export URL and authentication method, configure:

```bash
BOXES_EXPORT_REQUEST_URL=https://approved.example/export
BOXES_EXPORT_REQUEST_TOKEN=...
BOXES_EXPORT_ALLOWED_HOSTS=approved.example
```

Until then, `request_export` returns a clear `not_configured` result instead of pretending an export was requested.

## Event notifications

Pro accounts can send signed HTTPS event notifications to Boxes MCP:

```bash
BOXES_WEBHOOK_SECRET=... boxes-mcp webhooks
```

The receiver listens on `POST /webhooks/boxes`, verifies the `X-Boxes-Signature` HMAC over `timestamp.raw_body`, rejects stale requests, and deduplicates event UUIDs. It stores the entity snapshot while discarding actor email and device metadata by default.

Webhooks are an incremental signal, not a complete backup. Use periodic full exports to reconcile missed events and photos.

## Privacy and security

- Local storage by default; no analytics or telemetry.
- Raw exports, photos, secrets, and the mirror database are Git-ignored.
- Actor email/device metadata from webhooks is not retained.
- Export endpoints require HTTPS and an explicit hostname allowlist.
- Read tools are marked read-only in their MCP annotations.

See [SECURITY.md](SECURITY.md) before exposing the HTTP receiver to the internet.

## Development

```bash
npm run typecheck
npm test
```

Contributions are welcome. Synthetic fixtures only—never attach a real household export to a public issue or pull request.

## License

Apache-2.0.