nitaiaharoni1/super-mcp

createdb super_mcp
cp .env.example .env (set DATABASE_URL and a random BASKET_CONTINUATION_SECRET >=32 bytes)
pnpm install && pnpm db:migrate && pnpm db:seed (seed writes the API key to .local/api-key.txt)
pnpm dev -> http://localhost:8787/mcp (also /health and /openapi.json)

Usage

• •Hosted endpoint: point any MCP client at it — no key needed; /v1/admin/* stays behind a master key.
• •MCP '/mcp' exposes optimize_delivery (minimizes basket + delivery/service fee over an address/city/near input).
• •REST smoke: curl -s http://localhost:8787/health; POST /v1/delivery/optimize with items + address; GET /v1/products?q=חלב.
• •Self-hosters can set SUPER_MCP_ALLOW_ANONYMOUS=0 and send Authorization: Bearer <key> from .local/api-key.txt.
• •Semantic re-index: pnpm db:semantic-index -- --backend=hasher --limit=5000, then pnpm db:benchmark-semantic.

Key features

• ✓Deterministic-first basket resolution prefers exact-name/phrase/token/ontology evidence and returns needs_confirmation rather than silently guessing wrong products.
• ✓Hebrew catalog search, line resolution, unit normalisation, promotion maths, and freshness shared between delivery and physical-basket engines.
• ✓Semantics are data-driven (semantic_term / semantic_attribute_definition / semantic_search_config in Postgres), with embedding-based fallback (active Ontology he-retail-v1).
• ✓Activation gates: vector/profile coverage, recall, p95 latency budgets, forbiddenHitRate and Herzliya BBQ tests at 0.
• ✓Hosted vs self-host split is clean — the open-source tree contains no path into the operator's cloud; Apache-2.0.

Best for

Agents that answer Israeli grocery questions — pricing for a basket, delivery optimization, promotions — with honest confirmation when input is ambiguous.

Caveats

• ⚠Hosted mode: open access without a key, but you get no cloud credentials, database access, or deploy rights.
• ⚠Needs Node 22+, pnpm 9+, and Postgres 16+ with pgvector for self-hosting.
• ⚠Basket resolution intentionally refuses rather than guesses — some lines return needs_confirmation, expecting follow-up questions.
• ⚠Embedding/semantic layers warm up on first request; benchmarks target warm wall-clock under ~8s for an 18-line call.