# Unofficial Ninja MCP

MCP server for AI agents working with the Ninja/AnaNinja API.

This project exposes the Ninja/AnaNinja API as a small operational MCP:

- auth with reusable local `deviceId/authKey`
- saved addresses
- vertical/store discovery for retail, pharmacy, beauty, and restaurants
- retail/pharmacy/beauty product search, detail lookup, and product image URLs
- restaurant branch search, menu lookup, variant IDs, and topping metadata
- draft order validation for product verticals and restaurants
- guarded checkout creation
- payment-method inspection plus saved-card, wallet, and STC Pay helpers

Live checkout/payment tools use explicit execution flags and keep state in local `0600` files.

## Install

```bash
npm install
npm run build
```

Run locally:

```bash
npm start
```

MCP client config example:

```json
{
  "mcpServers": {
    "ninja": {
      "command": "node",
      "args": ["/absolute/path/to/ninja-mcp/dist/index.js"],
      "env": {
        "NINJA_MCP_STATE_FILE": "/Users/you/.ninja-mcp/state.json"
      }
    }
  }
}
```

## First Login

1. Call `ninja_auth_start_login` with the account phone number. This registers a device session and sends an OTP.
2. Call `ninja_auth_verify_otp` with the OTP.
3. Future calls reuse the saved auth key. This MCP does not use an OAuth refresh-token flow.

The default state path is:

```text
~/.ninja-mcp/state.json
```

Override with:

```bash
NINJA_MCP_STATE_FILE=/secure/path/state.json
```

State files contain auth material.

## Current Coverage

Implemented:

- auth/device session reuse
- saved address listing
- vertical discovery for `RETAIL`, `PHARMACY`, `BEAUTY`, and `RESTAURANT`
- product search and detail lookup for retail/pharmacy/beauty through the Fahras products endpoint
- product image URL extraction from product and restaurant menu media
- restaurant branch search and restaurant menu lookup through GraphQL
- draft order validation for retail, pharmacy OTC, beauty, and restaurant carts
- checkout creation for pending unpaid orders/payment requests
- payment-method inspection for a pending checkout
- account-level saved payment option inspection
- payment helpers for saved card and wallet
- STC Pay initiate + OTP helper flow

MCP request-shape support:

- saved-card payment request shape: `savedCard.cardId` with optional `savedCard.cvv`
- wallet payment request shape: `includeWallet: true`
- restaurant checkout request shape: `OrderRequest.restaurant` with `branchId` and `menuId`, plus restaurant variant IDs in `lineItems[].itemId`

Not implemented by this MCP:

- Tabby/Tamara and other redirect/token-based methods
- Apple Pay, Samsung Pay, Google Pay, QPay, KNET, Benefit, Daftar
- prescription/consultation pharmacy handling beyond `request.pharmacy` passthrough

## Agent Workflow

Read `ninja://agent-guide` or call `ninja_agent_guide` first.

Typical product-vertical call sequence:

1. `ninja_saved_addresses`
2. `ninja_search_products` with `vertical: "RETAIL"`, `"PHARMACY"`, or `"BEAUTY"`
3. `ninja_create_draft_order`
4. Review the exact cart, total, delivery location, and payment method.
5. `ninja_create_checkout` with `confirmCreateOrder: true`
6. `ninja_pending_payment_methods`
7. Choose from the available payment methods.
8. Use a method-specific helper if this MCP implements that method.

Typical restaurant call sequence:

1. `ninja_saved_addresses`
2. `ninja_search_restaurants`
3. `ninja_restaurant_menu`
4. `ninja_create_draft_order` with `vertical: "RESTAURANT"`, `restaurant.branchId`, `restaurant.menuId`, and restaurant variant IDs in `lineItems[].itemId`
5. Review the draft, then continue through checkout/payment if the cart is correct.

Implemented method-specific helpers:

- saved card: call `ninja_pending_payment_methods`, choose a `cardIndex`, then call `ninja_pay_saved_card`
- wallet: call `ninja_pay_wallet` if wallet is available for the pending checkout
- STC Pay: use `ninja_initiate_stc_pay`, collect the fresh OTP, then call `ninja_submit_stc_otp`

Card setup: card registration is outside this MCP. Add a saved card to the account, then refresh `ninja_saved_payment_options` or `ninja_pending_payment_methods`. Once the card appears as saved, use `ninja_pay_saved_card`.

## API Notes

- The bearer token is a short-lived HS256 JWT signed locally with `authKey`.
- Saved addresses are backend GraphQL data, not only local client memory.
- Product search uses vertical discovery to find the store/search context, then the Fahras products endpoint.
- Product image URLs come from `medias`; search/menu tools return them as `imageUrls`.
- Retail/pharmacy/beauty product search returns both `id` and `productId`. Use `productId`, exposed as `orderItemId`, for `lineItems[].itemId`. The `id` field is store-scoped and should not be used as the cart item id.
- Restaurant carts use menu variant IDs. Use `variant.orderItemId` / `variantId` from `ninja_restaurant_menu` for `lineItems[].itemId`.
- Restaurant toppings use `toppingId` and `toppingOptionId` from the menu response.
- `createDraftOrder.paymentMethods` is a direct list, not a `{ data: [...] }` wrapper.
- Always draft before checkout/payment.
- `createOrder` can recover the same pending payment request for the same cart.
- Payment methods are returned per payment request; availability can vary by account, cart, location, and time.
- `ninja_pending_payment_methods` labels each method with `apiCapability` and `mcpCapability`.
- Saved cards expose `requiresCvv`; saved-card payment accepts `cardIndex` or `cardId`, plus optional `cvv`.
- `ninja_saved_payment_options` lists account-level saved cards and wallets; for an actual checkout, prefer `ninja_pending_payment_methods`.
- STC Pay initiate expects `mobileNumber` in `9665XXXXXXXX` form; the MCP normalizes common Saudi formats.
- Payment calls can return `PENDING`; poll `paymentStatus` and then inspect `showOrder`.
- Totals are read from known payment-summary keys. If the upstream shape changes, the MCP reports candidate keys instead of guessing from an arbitrary amount.

## State And Side Effects

- Tool outputs redact full auth/payment IDs.
- Auth state and pending payment context are written with mode `0600`.
- Live mutation tools use execution flags, such as `confirmCreateOrder`, `confirmSendOtp`, `confirmSubmitOtp`, and `confirmSubmitPayment`.
- Failed payment attempts keep pending context so callers can try another available method.
- Successful payment clears pending checkout context.

## Environment

```bash
NINJA_MCP_STATE_FILE=/secure/path/state.json
NINJA_FIREBASE_CHECK_TOKEN=optional_firebase_check_token
NINJA_CLIENT_VERSION=optional_api_client_version_override
NINJA_CLIENT_USER_AGENT=optional_api_user_agent_override
```