CraveUp MCP Server

<div align="center">

A Model Context Protocol (MCP) server that lets AI agents onboard restaurant brands and manage Crave menus, storefronts, and mobile releases — entirely from natural language in chat

Quick Start | Available Tools | Authentication | Documentation

</div>

---

Overview

This MCP server provides Crave platform integration for Claude Code, Cursor, and other MCP-compatible clients. It covers the full merchant lifecycle: creating an organization, wiring a repo, importing menus, configuring locations, going live with subscriptions and payments, managing discounts, and dispatching guarded Expo/EAS mobile releases.

Key Features

• 34 Tools in 8 Categories — onboarding, go-live, location settings, menus, discounts, readiness checks, mobile releases, sandbox data
• Natural-Language Onboarding — "hook up this repo for Demo Bistro" → login → create org → wire .env → import menu → run iOS
• Idempotent Writes — menu imports, discount creation, and sandbox seeding are safe to re-run
• Guarded Mobile Releases — internal TestFlight only; paid EAS work requires a scoped Expo token plus explicit confirmation, and public App Store release remains human-controlled
• TypeScript — full type safety with Zod validation
• Tested — Vitest suite (53 tests) covering tools, clients, config, and readiness logic

Note: this is a local MCP server. It runs as a stdio subprocess on the developer's machine and authenticates to Crave with either your craveup login CLI session or a merchant API key. See Authentication.

After rebuilding packages/mcp/dist, restart the MCP server in your client (or reload the window) so new tools appear.

---

Quick Start

Installation

# From npm (published package)
npx -y @craveup/mcp

# Or from the monorepo
pnpm --filter @craveup/mcp build   # compiles to dist/

Configuration

Option A — Full NL onboarding (recommended for new brands). Run craveup login once in a terminal, then register the MCP server without an API key:

{
  "mcpServers": {
    "craveup": {
      "command": "node",
      "args": ["/path/to/craveup-turborepo/packages/mcp/dist/cli.js"]
    }
  }
}

The server reads your CLI session from the macOS keychain (or ~/.config/craveup/credentials.json). Alternatively set CRAVEUP_ACCESS_TOKEN in the MCP env.

Option B — Menu-only (existing location + API key). Create a merchant API key in Crave Business Manager → Settings → Developer → API Keys:

{
  "mcpServers": {
    "craveup": {
      "command": "npx",
      "args": ["-y", "@craveup/mcp"],
      "env": {
        "CRAVEUP_API_KEY": "crv_test_…",
        "CRAVEUP_LOCATION_ID": "<default location id>",
        "CRAVEUP_BASE_URL": "https://api.craveup.com"
      }
    }
  }
}

CRAVEUP_LOCATION_ID and CRAVEUP_BASE_URL are optional; every menu tool also accepts an explicit locationId.

Mobile releases. To dispatch mobile release workflows, also set a scoped Expo robot-user token in the MCP env:

{
  "env": {
    "EXPO_TOKEN": "<scoped Expo robot-user token>"
  }
}

Example chat flow

"This demo-bistro repo — hook it up to Crave for Demo Bistro. Login if you need to, create the org, import the menu, and run it on the iOS simulator."

Agent sequence:

1. whoami — confirm session (or ask user to run craveup login)
2. create_organization({ name: "Demo Bistro", mintApiKey: true })
3. connect_project({ projectPath: "…/demo-bistro", apiKey, locationId })
4. import_menu(…) from e2e/demo-menu.json
5. check_storefront_readiness — menu + ordering + payments
6. If not ready → open_location_for_orders and/or craveup integrations add stripe
7. Re-run readiness until ready: true
8. npx expo start --ios

---

Available Tools

Entities

CRUD-style operations are available for the following entity types:

Entity	Create	Get	Update	Delete	List
Organization	✅	-	-	-	-
Location	✅	-	✅	✅	✅
Store Settings	-	✅	✅	-	-
Menu	✅	-	✅	-	✅
Product	✅¹	✅	✅	✅	-
Discount	✅	-	-	-	✅
Order	-	-	-	-	✅
Customer	-	-	-	-	✅
Subscription	✅²	-	-	-	✅
Mobile Release	✅³	✅	-	-	-

¹ Products are created in bulk via import_menu. ² start_subscription_checkout opens a Stripe Checkout session; plans themselves are read-only. ³ start_mobile_release dispatches an EAS workflow run; deletion/cancellation stays in EAS.

Checks & Guides

Check	Tool Name	Description
Go-live Status	get_onboarding_status	The dashboard's 6 go-live steps with completion state + next actions
Storefront Readiness	check_storefront_readiness	Go/no-go gate: menu, ordering session, Stripe chargesEnabled
Mobile Release Readiness	check_mobile_release_readiness	Read-only Expo/EAS preflight for internal releases
Onboarding Flow	get_onboarding_flow	NL checklist: login → create org → connect repo → import menu → run
Session	whoami	Verify the craveup login session is readable
Integration Guide	get_integration_guide	Crave.js implementation guidance: storefront, menu display, checkout

---

Tool Reference

<details> <summary><strong>Onboarding Tools</strong></summary>

Tool	Description
get_onboarding_flow	NL checklist: login → create org → connect repo → import menu → run
whoami	Verify the craveup login session is readable
create_organization	Create merchant + location; mintApiKey: true returns a storefront key
connect_project	Write EXPO_PUBLIC_CRAVEUP_* into an Expo app's .env (validates the project path is a real directory)

</details>

<details> <summary><strong>Go-live Tools</strong></summary>

Tool	Description
get_onboarding_status	The dashboard's 6 go-live steps with completion state + next actions
create_location	Create a location (restaurantDisplayName + optional address PATCH)
delete_location	Soft-archive a location (frees slug; hides from dashboard)
list_locations	Dashboard locations-stats for the merchant
get_location_orders	Active orders for a location
list_customers	Customers page for a location
set_location_address	Set the street address; the server geocodes (no lat/lng needed)
set_fulfillment_methods	Enable pickup / table service / delivery / room service
list_subscription_plans	Plans with price, interval, and trial info
start_subscription_checkout	Stripe Checkout URL for the user to pay in the browser

</details>

<details> <summary><strong>Location Settings Tools</strong></summary>

Tool	Description
get_location_settings	Read store hours, scheduled-order flag, tax, takeout
update_store_hours	Set hours (always_open, business_9am_10pm, or custom 7-day schedule)
set_scheduled_orders_enabled	Toggle order-ahead when closed
set_takeout_enabled	Enable/disable takeout pickup
open_location_for_orders	One-shot fix for "Restaurant is closed. Scheduled orders are not allowed."

</details>

<details> <summary><strong>Menu & Storefront Tools</strong></summary>

Tool	Description
import_menu	Idempotent full menu import; forces menu.isActive=true by default
set_menu_active	Explicitly activate/deactivate a menu (use when list_menus shows inactive)
list_menus	Read back menus exactly as the storefront API serves them
get_product	Fetch one product with its modifier group ids
update_product	Partial edits: name, description, price, availability
set_product_availability	Sold-out toggles
delete_product	Remove a product (category references cleaned up)
get_integration_guide	Implementation guidance: storefront setup, menu display, checkout, import format

</details>

<details> <summary><strong>Discount Tools</strong></summary>

Tool	Description
list_discounts	List location promo codes and their current configuration
create_order_discount	Idempotently create an order-level fixed or percentage promo code (percentage capped at 100)

</details>

<details> <summary><strong>Readiness Tools</strong></summary>

Tool	Description
check_storefront_readiness	Hybrid wizard gate: menu, ordering session, Stripe chargesEnabled

</details>

<details> <summary><strong>Mobile Release Tools</strong></summary>

Run craveup apps configure in the Expo/React Native project and commit the generated workflows before using these tools. EAS builds consume plan minutes.

Tool	Description
check_mobile_release_readiness	Read-only local preflight for EAS project identity, workflow, credentials, and internal target
start_mobile_release	Dispatch the fixed internal TestFlight workflow after exact confirmation
get_mobile_release_status	Read the EAS workflow run, build jobs, and submission jobs

start_mobile_release cannot publish publicly. iOS always goes to internal TestFlight first; public App Store review remains an explicit App Store Connect action. Use craveup apps publish play-internal for Android; the CLI blocks submission unless the local EAS submit profile targets Google Play's internal track.

</details>

<details> <summary><strong>Sandbox Tools</strong></summary>

Tool	Description
seed_sandbox_analytics	Idempotently create customers, orders, ratings, and funnel events for the dev test organization. Requires CRAVEUP_SANDBOX_MODE=true, a non-production CRAVEUP_ADMIN_BASE_URL, and a dev Clerk session.

</details>

---

Authentication

This server authenticates to Crave with a merchant API key (menu, discount, and readiness tools), a CLI session from craveup login (onboarding, go-live, and location-settings tools), and optionally an Expo token (mobile release tools). No OAuth app registration or redirect URIs are needed — keys are minted directly in Crave Business Manager.

Important: Test vs Live

Mode	When to use	API key prefix	Setup difficulty
Test	Development, demos, integration tests	crv_test_…	Easy — mint a key and go
Live	Real storefront orders with real payments	crv_live_…	Requires a live location: go-live checklist complete, subscription active, Stripe chargesEnabled

The server validates the prefix at startup — anything not starting with crv_ is rejected before a single request is made. Point CRAVEUP_BASE_URL at a local API (e.g. http://localhost:8000) to develop fully offline from production.

Test Setup (recommended for first run)

1. Sign in to Crave Business Manager → Settings → Developer → API Keys
2. Create a key for the location you want to work with — copy the crv_test_… value
3. Set CRAVEUP_API_KEY (and optionally CRAVEUP_LOCATION_ID) in the MCP server env
4. For session-authenticated tools (onboarding, go-live, location settings), run craveup login once in a terminal — the server reads the session from the macOS keychain or ~/.config/craveup/credentials.json

Live Setup

1. Complete the go-live checklist — get_onboarding_status shows the six steps and what's missing
2. Verify payments with check_storefront_readiness — it gates on menu, ordering session, and Stripe chargesEnabled
3. Mint a crv_live_… key in Business Manager and swap it into the MCP env

Once you have credentials

CRAVEUP_API_KEY=crv_test_…            # merchant API key (test or live)
CRAVEUP_LOCATION_ID=<location id>     # optional default; every tool also accepts locationId
CRAVEUP_BASE_URL=https://api.craveup.com   # optional; defaults to production API

CRAVEUP_ACCESS_TOKEN=<session token>  # optional alternative to the keychain session
EXPO_TOKEN=<scoped robot-user token>  # only for mobile release tools

Credential safety

Do not paste Apple passwords, 2FA codes, App Store Connect keys, or Google service-account JSON into chat. Bootstrap interactive credentials in a visible terminal; EAS stores the reusable submission credentials. EXPO_TOKEN must be a scoped Expo robot-user token, never a personal account token.

Common pitfalls

• New tools not appearing. After rebuilding packages/mcp/dist, restart the MCP server in your client (or reload the window) — clients cache the tool list per process.
• Keys are location-scoped. The API rejects requests for locations the key cannot access; use the key minted for the location you're targeting, or pass an explicit locationId.
• Session tools failing while key tools work. The two auth modes are independent — a valid CRAVEUP_API_KEY does not log you in. Run craveup login in a terminal (the MCP process cannot open a browser).
• "Restaurant is closed. Scheduled orders are not allowed." Not an auth problem: run open_location_for_orders({ locationId }) for the one-shot fix, then retry.
• Sandbox seeding refuses to run. seed_sandbox_analytics is guarded by design: it requires CRAVEUP_SANDBOX_MODE=true and a non-production CRAVEUP_ADMIN_BASE_URL — there is no override for production.

---

Development

Building

pnpm --filter @craveup/mcp build   # compile to dist/

Testing

pnpm --filter @craveup/mcp test    # vitest — 53 tests across 5 files

Project Structure

src/
├── clients/         # Crave + Expo/EAS API clients
├── tools/           # MCP tool definitions (7 categories)
├── handlers/        # Business logic (readiness, onboarding, guides)
├── helpers/         # Zod schemas, session, env config
├── cli.ts           # stdio entry point (craveup-mcp bin)
└── index.ts         # Server assembly + tool registration

tests/
└── unit/            # Vitest suites (53 tests)

docs/
├── ARCHITECTURE.md  # Layers, auth modes & design decisions
└── TESTING.md       # Testing patterns & conventions

---

Documentation

Document	Description
CHANGELOG.md	Version history and all changes
docs/ARCHITECTURE.md	Layers, authentication modes, and design decisions
docs/TESTING.md	Testing strategy, in-memory MCP transport pattern, conventions
docs.cravejs.com	Hosted CraveUp MCP server guide + Crave.js integration docs (also served at runtime via get_integration_guide)
modelcontextprotocol.io	MCP specification

---

Error Handling

Tools return structured MCP error results (isError: true) rather than throwing: missing or invalid auth reports which credential is needed (session vs API key vs EXPO_TOKEN), and the API rejects keys that cannot access the requested location. Paid EAS dispatch requires an exact confirmation phrase, location deletion is a recoverable soft-archive, and sandbox seeding refuses to run unless all dev-environment guards are set.

---

Contributing

Note: development happens in the private CraveUp monorepo; the public craveup/craveup-mcp repo is a read-only mirror synced automatically from packages/mcp. Bug reports and feature requests are welcome as issues on the mirror; direct pushes and PRs there will be overwritten by the next sync.

Tool naming convention

• get_* / list_* / check_* — read-only
• create_* / update_* / set_* / delete_* — writes, idempotent where possible
• start_* — kicks off an external process (checkout, EAS workflow) and returns a handle

Add tests in tests/unit/ for every new tool; pnpm --filter @craveup/mcp test must pass before publishing (prepublishOnly runs build + tests).

---

License

MIT — see LICENSE.