Skip to main content
Glama
mcp-commerce-server

mcp-commerce-server

mcp-commerce-server

CI MCP TypeScript License

A Model Context Protocol server that lets AI assistants (Claude, ChatGPT, Cursor, your own agents) work with an online store, without being able to do damage.

MCP makes it easy to hand a model a set of tools. The hard part is deciding what happens when the model is confused, over-eager or being manipulated. This server is built around that question.

Safety model

Control

How

Least-privilege keys

Each API key maps to a principal with explicit scopes (catalog:read, orders:read, customers:pii, inventory:write, …). Keys are stored only as SHA-256 hashes and compared in constant time.

PII minimisation

get_order masks customer email and phone (th**************om) unless the key holds customers:pii. A support bot doesn't need the full address to say "it shipped".

Preview-then-confirm writes

adjust_inventory and create_discount never act on the first call. They return a preview and a confirm_token: an HMAC over (principal, tool, exact arguments, expiry). Executing requires the same principal, the same arguments and an unexpired, unused token.

Business limits in code

Max stock change per call, max discount %, max validity. Bigger changes go to a human in the back office.

Tool annotations

readOnlyHint, destructiveHint and idempotentHint let MCP clients decide when to ask the user.

Rate limits

Per principal.

Audit log

Every call: principal, tool, outcome (ok / preview / denied / error) and a hash of the arguments, so the audit trail doesn't become a second copy of customer data.

A confused or prompt-injected model therefore can't:

  • skip the human (no token without a preview),

  • show the user one change and execute another (the token is bound to the exact arguments),

  • replay an old approval (tokens are single-use and expire after 5 minutes), or

  • reach data its key isn't scoped for.

Related MCP server: mcp-ecom-agent-layer

Tools, resources, prompts

Name

Kind

Scope

search_products

tool · read-only

catalog:read

get_order

tool · read-only (PII masked by default)

orders:read (+ customers:pii)

list_low_stock

tool · read-only

inventory:read

adjust_inventory

tool · destructive · preview/confirm

inventory:write

create_discount

tool · idempotent · preview/confirm

discounts:write

commerce://products/{sku}

resource

catalog:read

commerce://policies/returns

resource

—

restock_review

prompt

—

Read tools return both human-readable text and structuredContent for programmatic clients.

Run it

Locally with Claude Desktop (stdio):

npm ci && npm run build
node -e "console.log(require('crypto').createHash('sha256').update('sk_local_demo').digest('hex'))"
{
  "mcpServers": {
    "commerce": {
      "command": "node",
      "args": ["/path/to/mcp-commerce-server/dist/stdio.js"],
      "env": {
        "MCP_KEYS": "desktop:<sha256-from-above>:catalog:read,orders:read,inventory:read,inventory:write",
        "MCP_API_KEY": "sk_local_demo"
      }
    }
  }
}

Remotely (Streamable HTTP, stateless): MCP_KEYS=... npm run http. Clients send Authorization: Bearer <key> to POST /mcp. Each request authenticates independently; the store, confirmation service and audit log are shared.

Audit records go to stderr in stdio mode, because stdout is the protocol channel.

Tests

The tests connect a real MCP Client to the server over the SDK's in-memory transport, the same protocol path a production client uses. They cover discovery and annotations, structured output, PII masking per scope, scope denials (audited without raw arguments), schema rejection, rate limiting, and the full preview → tamper → confirm → replay cycle. They also caught a real bug: scope names contain :, which the key parser originally split on.

npm ci
npm run ci      # typecheck + tests + build

The store is an in-memory adapter behind a small interface. Point it at Shopify's Admin API (see commerce-ops-agent) or any backend.


Built by Admire T. Ndaneta. MIT licensed.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to securely call enterprise MCP tools with tenant-scoped RBAC, human approvals, audit logging, and multi-tool workflows across customer, order, document, and ticket data.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to manage Magento 2 / Adobe Commerce products, stock, orders, and customers through 12 read/write MCP tools with secure, audited access.
      AGPL 3.0