{
  "markdown": "# AllOurThings\n\n> Your things, understood by AI.\n\nAllOurThings is an inventory system that works the way you do. Catalog anything you like from your home appliances to your Pokémon cards — then ask plain-English questions and get instant answers.\n\n**Website:** [allourthings.io](https://allourthings.io)\n\n## Packages\n\n| Package | npm | Description |\n|---|---|---|\n| [`packages/mcp-server`](./packages/mcp-server) | [`@allourthings/mcp-server`](https://www.npmjs.com/package/@allourthings/mcp-server) | MCP server — connects your inventory to Claude Desktop and other MCP clients |\n| [`packages/cli`](./packages/cli) | [`@allourthings/cli`](https://www.npmjs.com/package/@allourthings/cli) | CLI — manage your inventory from the terminal |\n\n---\n\n## Quick start\n\n> **Desktop only.** Requires macOS, Windows, or Linux with [Claude Desktop](https://claude.ai/download) or another MCP-compatible client.\n\n### 1. Add to Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"allourthings\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@allourthings/mcp-server\", \"--data-dir\", \"~/Documents/AllOurThings\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Your inventory vault will be created automatically on first use.\n\n### 2. Start asking questions\n\n- *\"Add my Bosch washing machine, bought from John Lewis for £649 in January 2024 with a 2-year warranty\"*\n- *\"What appliances do I own?\"*\n- *\"What's in the kitchen?\"*\n- *\"When does my TV warranty expire?\"*\n- *\"Search for anything Samsung\"*\n- *\"How much have I spent on electronics?\"*\n\n---\n\n## How it works\n\nThe MCP server exposes your inventory to any MCP-compatible AI client via 10 tools:\n\n| Tool | Description |\n|---|---|\n| `add_item` | Add a new item to your inventory |\n| `get_item` | Retrieve an item by ID or name |\n| `list_items` | List all items, optionally filtered by category, location, or tags |\n| `update_item` | Update fields on an existing item |\n| `delete_item` | Delete an item by ID |\n| `search_items` | Full-text search across all item fields |\n| `add_attachment` | Attach a file (manual, receipt, photo, warranty) to an item |\n| `get_attachment` | Retrieve an attachment as base64 |\n| `delete_attachment` | Remove an attachment from an item |\n| `attach_from_url` | Download a file from a URL and attach it to an item |\n\n---\n\n## Data\n\n### Vault structure\n\nYour inventory lives in a **vault** — a plain directory on your filesystem. Each item gets its own folder:\n\n```\n~/Documents/AllOurThings/\n  items/\n    dyson-v15-detect-a1b2c3d4/\n      item.json\n      manual.pdf\n      receipt.jpg\n    samsung-65-qled-tv-b5c6d7e8/\n      item.json\n      warranty.pdf\n```\n\nAttachments (manuals, receipts, photos) sit alongside the item JSON. You can browse and edit the vault directly in Finder or File Explorer.\n\n### Item schema\n\nEvery item has required fields (`id`, `name`, `created_at`, `updated_at`) and well-known optional fields:\n\n`category` `brand` `model` `purchase_date` `purchase_price` `currency` `warranty_expires` `retailer` `location` `features` `notes` `tags` `attachments`\n\nThe `attachments` field links PDFs and images stored in the item's folder:\n\n```json\n{\n  \"attachments\": [\n    { \"filename\": \"manual.pdf\",  \"type\": \"manual\"   },\n    { \"filename\": \"receipt.jpg\", \"type\": \"receipt\"  },\n    { \"filename\": \"photo.jpg\",   \"type\": \"photo\"    }\n  ]\n}\n```\n\nYou can also add any custom fields you like — they are preserved as-is.\n\n\n---\n\n## CLI\n\nA standalone terminal tool for power users and scripting. Works on macOS, Windows, and Linux. No AI client required.\n\n```bash\n# Run without installing\nnpx @allourthings/cli list\n\n# Or install globally\nnpm install -g @allourthings/cli\n```\n\n\n### Commands\n\n```bash\nallourthings search <query>                          # full-text search across all fields\nallourthings list [--category <c>] [-l <loc>] [-t <tag>]  # list items, optionally filtered\nallourthings get <id-or-name>                        # show full item detail\nallourthings add <name> [options]                    # add a new item\nallourthings update <id> [options]                   # update item fields\nallourthings delete <id>                             # delete an item (prompts for confirmation)\n```\n\n**Attachment management:**\n\n```bash\nallourthings attach add <item-id> <file>             # attach a local file to an item\nallourthings attach url <item-id> <url>              # download a file and attach it\nallourthings attach get <item-id> <filename>         # save an attachment to disk\nallourthings attach rm  <item-id> <filename>         # delete an attachment\n```\n\n**`add` and `update` options:**\n\n```\n-c, --category <category>\n-b, --brand <brand>\n-m, --model <model>\n    --purchase-date <date>    ISO date, e.g. 2024-01-15\n    --price <price>\n    --currency <currency>     e.g. GBP, USD\n    --warranty <date>         warranty expiry ISO date\n    --retailer <retailer>\n-l, --location <location>\n    --serial <serial>\n-t, --tag <tag...>            repeatable\n-n, --notes <notes>\n    --set key=value           custom/extra fields (update only, repeatable)\n```\n\n**Global options:**\n\n```\n--data-dir <path>    path to inventory data directory (default: ~/Documents/AllOurThings)\n--json               output raw JSON — useful for scripting and agent use\n```\n\n**Data directory:** defaults to `~/Documents/AllOurThings` on all platforms. To avoid passing `--data-dir` every time, set it once in your shell profile:\n\n```sh\nexport ALLOURTHINGS_DATA_DIR=~/Dropbox/AllOurThings\n```\n\nThe directory is created automatically on first write. Read commands (`list`, `search`, `get`) return empty results against a missing directory rather than erroring.\n\n### Examples\n\n```bash\n# Add an item\nallourthings add \"Bosch Washing Machine\" --brand Bosch --model \"WGG244A9GB\" \\\n  --category appliance --location kitchen \\\n  --purchase-date 2024-01-15 --price 649 --currency GBP \\\n  --warranty 2026-01-15 --retailer \"John Lewis\"\n\n# Search and pipe to jq\nallourthings search \"warranty\" --json | jq '[.[] | {name, warranty_expires}]'\n\n# Attach a manual\nallourthings attach add 6164c373 ~/Downloads/bosch-manual.pdf --label \"User manual\"\n\n# Update a field\nallourthings update 6164c373 --warranty 2027-01-15\n\n# Use a custom data directory\nallourthings --data-dir ~/Dropbox/AllOurThings list\n```\n\n---\n\n## Development\n\n### Prerequisites\n\n- [Bun](https://bun.sh) — `brew install bun`\n- [Task](https://taskfile.dev) — `brew install go-task`\n\n### Install dependencies\n\n```bash\nbun install\n```\n\n### Tasks\n\n| Task | Description |\n|---|---|\n| `task dev` | Seed vault + open MCP Inspector — fastest way to test |\n| `task dev:mcp` | Start MCP server in watch mode (stdio) |\n| `task test:run` | Run automated tests |\n| `task seed` | Append test items to dev vault |\n| `task seed:reset` | Clear dev vault and re-seed |\n| `task inspect` | Open MCP Inspector (dev mode, no build required) |\n| `task inspect:prod` | Build, then open MCP Inspector against compiled dist |\n| `task build` | Compile MCP server to dist/ |\n| `task build:cli` | Compile CLI to dist/ |\n| `task cli -- <args>` | Run CLI from source against dev vault, e.g. `task cli -- list` |\n| `task typecheck` | Run TypeScript type checking |\n| `task clean` | Remove dist/ |\n| `task clean:vault` | Delete local dev vault |\n\nAll tasks use `./dev-vault` by default. Override with `DATA_DIR=/your/path task <command>`.\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 7490,
  "sha": "d5a8700d01185e4eeb50921913cba8abaae2db97c749d25431d8b2fd1adfbd94",
  "repo_slug": "matt-harding/allourthings-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_allourthings_mcp_server_544df56e/readme"
}