luxare-retail-mcp

An MCP (Model Context Protocol) server that exposes three Diaspark (diasparkonline.com) reporting/lookup APIs as tools an MCP-compatible client (e.g. Claude Desktop, Claude Code) can call.

Tools

Tool	Endpoint	Purpose
list_customers	POST /terminal/terminal/list_customers_all	Search the customer list by name, city, email, phone, etc.
sales_history_report	POST /pos/point_of_sale_report/sales_receipt_with_item_report	Sales receipt / item sales history report over a date range.
inventory_search	POST /inventory/inventory_report/on_hand_report_by_style	On-hand inventory report, filterable by SKU, serial #, brand, category, vendor, store, location, etc.

All requests are sent as Content-Type: application/xml POST bodies. No authentication is required against the demo environment currently configured (https://diasparkdemo.rw.diasparkonline.com).

How it works

Each Diaspark endpoint expects a large, mostly-static XML payload (see src/templates.ts, copied verbatim from the sample requests). Rather than generating XML from scratch, each tool takes a known-good template and only overwrites the specific <tag> values relevant to the fields you pass in — every other default/hidden field the API depends on is left untouched.

• list_customers — nearly every field maps 1:1 to a tag (first_name, last_name, city, ...).
• sales_history_report — exposes company_id, user_id, document_id, start_date (→ dt1), end_date (→ dt2), plus a raw_overrides object for any other criteria field (str1-str60, all1-all30, dec1-dec10, multiselect1-30, etc).
• inventory_search — exposes friendly names (sku, serial, brand, category, vendor, store, location, department, subcategory, group, group_code, classification, collection, designer, vendor_style, rmsa, upc) that are mapped to the underlying strN/strN+1 "from/to" tag pairs (derived from the report's column definitions), plus raw_overrides for anything else.

Passing a friendly inventory field sets both the "from" and "to" tag to that value, i.e. an exact-match filter. If a filter doesn't seem to take effect, the report may also require its corresponding allN "select all" checkbox flag to be turned off — pass that via raw_overrides (e.g. { "all5": "N" }). The full column-to-tag mapping is documented in the original OnHandStockReportBySerialCriteriaStru.xml column definitions file if you need to extend this further.

applyOverrides (in src/xmlUtils.ts) throws if you reference a tag name that doesn't exist anywhere in the template, so typos in raw_overrides fail loudly instead of being silently ignored.

Setup

npm install
npm run build

Configuration

By default the server targets the demo environment:

https://diasparkdemo.rw.diasparkonline.com

To point at a different environment (e.g. production), set the DIASPARK_BASE_URL environment variable.

Claude Desktop / Claude Code MCP config

Add to your MCP config file (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "luxare-retail": {
      "command": "node",
      "args": ["/absolute/path/to/luxare-retail-mcp/build/index.js"],
      "env": {
        "DIASPARK_BASE_URL": "https://diasparkdemo.rw.diasparkonline.com"
      }
    }
  }
}

Restart Claude Desktop / Claude Code after editing the config.

Running as a remote HTTP server

The tools are defined once in src/server.ts and exposed over two entrypoints:

• src/index.ts (npm start) — stdio transport, for a local MCP client (Claude Desktop/Code) that spawns the process directly, as above.
• src/http.ts (npm run start:http) — MCP Streamable HTTP transport, for a remote client connecting over the network. Listens on PORT (defaults to 3000), exposes a health check at / and the MCP endpoint at POST /mcp.

Deploying to Render

This repo includes a render.yaml Blueprint that deploys the HTTP entrypoint as a Node web service:

• Build: npm install && npm run build
• Start: npm run start:http
• Health check: /
• DIASPARK_BASE_URL defaults to the demo environment; override it in the Render dashboard for a different environment.

In the Render dashboard, use New > Blueprint and point it at this repo/branch — Render will read render.yaml and provision the service. Once deployed, remote MCP clients connect to https://<your-service>.onrender.com/mcp.

Adding more endpoints

To add another Diaspark API as a tool:

1. Add its sample request body as a new exported template string in src/templates.ts.
2. Add a new server.tool(...) block in src/index.ts, listing the fields you want to expose as friendly parameters (map them to the underlying tag names), plus a raw_overrides escape hatch.
3. npm run build and restart your MCP client.

Example tool calls

// list_customers
{ "first_name": "david", "company_id": 3 }

// sales_history_report
{ "company_id": 7, "start_date": "2026/07/01", "end_date": "2026/07/10" }

// inventory_search
{ "company_id": 7, "sku": "ABC123" }