inventory-mcp

MCP server for Inventory (whereiput.it) — search your stuff, do full CRUD, and run the AI photo-assist flow from Claude Desktop, Claude Code, Codex, or any MCP-compatible client.

It is a thin scope-enforced proxy over the Inventory token API (/api/v1/inventory/*). It makes no auth decision: it forwards your inv_ bearer unchanged as an Authorization: Bearer header over HTTPS, and the API's 403/404 is the real boundary. The token is never placed in a URL and never logged.

Setup

npm install
npm run build

Get a token

Mint a personal API token in the SPA at https://whereiput.it/settings?tab=integrations (name + scopes read/write/ai). The raw inv_… secret is shown once — copy it into the installer.

Tool visibility is gated by the token's scopes: a read-only token never sees write/ai tools.

Install (curl | bash)

Interactive (prompts for token + client):

curl -fsSL https://mcp.whereiput.it | bash

Non-interactive, Codex:

curl -fsSL https://mcp.whereiput.it | bash -s -- inv_your_token_here codex

The installer gates on the inv_ prefix, configures Claude Code (claude mcp add) and/or Codex (codex mcp add + an idempotent managed-block shell export), and never embeds the token in a URL.

Transports & client config

Claude Code (remote HTTP)

claude mcp add inventory --transport http https://mcp.whereiput.it/mcp -H "Authorization: Bearer inv_…"

Codex (~/.codex/config.toml)

[mcp_servers.inventory]
url = "https://mcp.whereiput.it/mcp"
bearer_token_env_var = "INVENTORY_TOKEN"

Then set the token before starting Codex:

export INVENTORY_TOKEN="inv_your_token_here"   # fish: set -gx INVENTORY_TOKEN inv_your_token_here

Claude Desktop (local stdio — zero infra)

{
  "mcpServers": {
    "inventory": {
      "command": "node",
      "args": ["/path/to/inventory-mcp/dist/stdio.js"],
      "env": {
        "INVENTORY_API_URL": "https://whereiput.it",
        "INVENTORY_API_TOKEN": "inv_your_token_here"
      }
    }
  }
}

Generic HTTP client

{ "type": "http", "url": "https://mcp.whereiput.it/mcp", "headers": { "Authorization": "Bearer inv_…" } }

Environment variables

Variable	Default	Purpose
INVENTORY_API_URL	https://whereiput.it	Inventory token API base URL. Deploy override: https://api.whereiput.it — the /api/v1/inventory/* routes are served by the Laravel backend on api., not the SPA host.
INVENTORY_API_TOKEN	—	The inv_ bearer (stdio only; HTTP takes it per-request)
INVENTORY_MCP_PORT	3100	HTTP transport listen port (the mcp.whereiput.it deploy uses 3119)

INVENTORY_API_URL defaults to https://whereiput.it, but the production mcp.whereiput.it deploy overrides it to https://api.whereiput.it (the host that actually serves /api/v1/inventory/*).

Tools

Tool	Scope	API call
list_areas, get_area	read	GET areas[/{id}]
list_locations, get_location	read	GET areas/{id}/locations, locations/{id}
search_items, get_item	read	GET items/search?q=, items/{id}
create_area / update_area / delete_area	write	POST/PUT/DELETE areas
create_location / update_location / delete_location	write	POST areas/{id}/locations, PUT/DELETE locations/{id}
create_item / update_item / delete_item	write	POST locations/{id}/items, PUT/DELETE items/{id}
create_category, create_tag	write	POST categories / tags
recognize_photo	ai	POST items/recognize
save_recognized	ai	POST locations/{id}/items/bulk

A user-invoked catalog_from_photo prompt walks the recognize → review → save flow.

AI photo-assist caveat (Phase 7 follow-up)

recognize_photo passes text-friendly args (image_base64 + mime + area_id). The Phase 7 recognize endpoint is multipart-only today. For the remote HTTP transport, the recognize endpoint likely needs a base64/JSON input-adapter branch (an input adapter only — no logic change). The ai tools + client methods ship now; the live end-to-end recognize call lights up once that input adapter lands. This is a documented sequencing acceptance, not a blocker.

Remote deploy (the heavier infra lift)

The remote Streamable HTTP transport (mcp.whereiput.it) is an operator task, not automatable from this repo:

1. Run node dist/http.js continuously under a process manager (this box uses supervisor: whereiput-mcp, port 3119).
2. TLS-terminate + reverse-proxy mcp.whereiput.it → the Node process (the SDK speaks plain HTTP; HTTPS is the front).
3. Add a DNS A/AAAA record for mcp.whereiput.it.
4. Set INVENTORY_API_URL to the Inventory token API host (https://api.whereiput.it).

Sessions are tracked in an in-memory Map (single instance is adequate for v1; a multi-instance deploy would need sticky sessions).

stdio-local needs zero hosting — the Claude Desktop config above works entirely on the local machine with no remote endpoint.

Development

npm run dev        # HTTP transport with tsx (no build step)
npm run dev:stdio  # stdio transport with tsx
npm test           # vitest