Skip to main content
Glama
akshayadeodiaspark

luxare-retail-mcp

by akshayadeodiaspark
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

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).

Related MCP server: GigAPI MCP Server

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" }

Available Tools

3 tools
list_customersA

Search the Diaspark customer list (terminal/terminal/list_customers_all). All fields are optional filters; leave a field out to not filter on it.

ParametersJSON Schema
NameRequiredDescriptionDefault
zipNo
cityNo
emailNo
phoneNo
stateNo
addressNo
billto_idNo
last_nameNo
company_idNoDefaults to 3
first_nameNo
search_valueNoGeneric/free-text search term
salesperson_codeNo

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden for behavioral disclosure. The term 'Search' implies a read-only operation, but it does not explicitly state idempotency, side effects, authentication requirements, or pagination behavior. This is adequate but not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the tool's purpose and usage pattern. It includes the endpoint in parentheses for context without any superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 12 optional parameters, no output schema, and no annotations, the description is minimal. It lacks details about result format, pagination, rate limits, or other typical behaviors for a search tool. The description does not fully equip an AI agent to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at only 17% (2 out of 12 parameters have descriptions), the description should compensate but only adds a general statement about optional filtering. It does not elaborate on the meaning or format of individual parameters beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search the Diaspark customer list', identifying the verb (search) and resource (customer list). It also includes the specific endpoint for reference. The siblings are inventory_search and sales_history_report, so this tool is distinct in its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states 'All fields are optional filters; leave a field out to not filter on it', providing clear guidance on how to use the parameters. Although it doesn't discuss when not to use the tool or compare to siblings, the optional filter behavior is well-explained.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

sales_history_reportA

Run the Diaspark sales receipt / item sales history report (pos/point_of_sale_report/sales_receipt_with_item_report). Dates use YYYY/MM/DD format. Use raw_overrides for any of the report's other criteria fields (str1-str60, all1-all30, multiselect1-30, dec1-10, list1-10, etc).

ParametersJSON Schema
NameRequiredDescriptionDefault
user_idNoDefaults to 1
end_dateNoTransaction date range end (dt2), format YYYY/MM/DD
company_idNoDefaults to 7
start_dateNoTransaction date range start (dt1), format YYYY/MM/DD
document_idNoReport definition id, defaults to 2679
raw_overridesNoAdvanced: map of any other <tag> names in the criteria XML to raw values

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the behavioral disclosure burden. It mentions date format and raw_overrides but does not state if the tool is read-only, what happens with defaults, or any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the tool's purpose, no unnecessary words. Each sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, 6 parameters with nested raw_overrides. The description covers date format and raw_overrides but lacks guidance on usage context or expected output, making it minimally viable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds value by emphasizing the date format and explaining raw_overrides with examples (str1-str60, etc.), which helps the agent understand dynamic usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it runs the Diaspark sales receipt/item sales history report, specifying the report path. It distinguishes from sibling tools (inventory_search, list_customers) which are unrelated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. No prerequisites or when-not-to-use instructions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedinventory_search
    • First observedlist_customers
    • First observedsales_history_report
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct domain: inventory, customers, and sales. There is no overlap in purpose or output, making it easy for an agent to select the correct tool.

Naming Consistency4/5

All tool names use snake_case and are readable, but the pattern is not uniform: inventory_search is noun_verb, list_customers is verb_noun, and sales_history_report is a compound noun. Minor inconsistency but still clear.

Tool Count3/5

Three tools is at the lower end of the typical range. For a server focused on running specific reports from Diaspark, the count is acceptable but feels thin, potentially limiting agent capabilities.

Completeness3/5

The tools cover key reporting domains (inventory, customers, sales) but lack write operations or drill-down details. As a read-only reporting surface, it is adequate, but gaps exist for full retail lifecycle management.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • GigAPI MCP Server

    gigapi
    A
    license
    C
    quality
    D
    maintenance
    An MCP server that provides seamless integration with Claude Desktop for querying and managing timeseries data in GigAPI Timeseries Lake.
    7
    6
    Apache 2.0

  • Business Central MCP Workshop

    javiarmesto
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server that integrates with Microsoft Dynamics 365 Business Central, enabling querying of customers, items, and sales orders through natural language commands in Claude Desktop.
    10
    -

  • teradata-gcfr-mcp-server

    Pibbers
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that connects Claude to Teradata GCFR operational reporting, enabling natural-language queries about stream status, process history, loads, transforms, errors, SLA, and data lineage without writing SQL.
    MIT