Skip to main content
Glama
ameghcoder

commerce-ops-mcp

by ameghcoder
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

Commerce Operations MCP

Status: domain/data foundation plus a working MCP server exposing four read-only investigation tools, served over both local stdio and remote Streamable HTTP (hosted on Render). No write/action tool yet — see "Current limitations".

Hosted MCP URL: https://e-commerce-mcp.onrender.com/mcp (Streamable HTTP, stateless — see "Connecting to the hosted server" below)

Working name: commerce-ops-mcp (may change before final delivery).

An AI-native commerce operations investigator focused on delayed-order investigation, exposed through a remotely hosted MCP server.

Problem

An operations specialist needs to answer, for a given order: "why is this order delayed, and what should I do about it?" Answering that well often requires checking payment status, inventory availability, and fulfillment state — but the product is that one investigation workflow, not standalone tooling for payments, inventory, or fulfillment.

Confirmed scope (client-clarified): a single, focused end-to-end workflow — delayed-order investigation — is the right level of scope. Separate coverage of all four commerce domains (orders, payments, inventory, fulfillment) as independent workflows is explicitly out of scope. The project intentionally does not provide independent workflows for payments, inventory, fulfillment, or general order management; those systems are consulted only as supporting evidence when investigating a delayed order.

Related MCP server: Fulfillment Triage MCP

Current scope

This repository implements the backend foundation plus a working MCP server on top of it:

  • Domain types and status enums

  • A synthetic, internally consistent commerce dataset (static TypeScript modules)

  • A repository layer over that dataset

  • An OrderContextService that composes operational facts (not diagnoses) for a given order

  • A DelayDiagnosisService that applies deterministic rules to those facts to identify the likely delay cause

  • A ResolutionService that maps a diagnosis to recommended next actions

  • An MCP server exposing search_orders, get_order_context, diagnose_order_delay, and recommend_resolution as tools, over two transports sharing the same tool registration (src/mcp/create-server.ts):

    • src/mcp/server.ts — stdio, for local MCP clients (Claude Desktop/Code, MCP Inspector)

    • src/mcp/http.ts — Streamable HTTP (stateless), deployed remotely on Render for AI agents to connect to without any local setup

  • Tests covering all of the above

No write/action tool (create_resolution_ticket), LLM/agent integration, database, or frontend exists yet. See CLAUDE.md for the explicit scope boundary and docs/assumptions.md / docs/decisions.md for what's decided vs. pending.

Architecture

Synthetic data (src/data/*.ts — static, typed TypeScript modules)
        ↓
Repositories (src/repositories/*.repository.ts)
        ↓
Domain services (order-context.service.ts, delay-diagnosis.service.ts,
                  resolution.service.ts)
        ↓
src/mcp/create-server.ts — search_orders, get_order_context,
                            diagnose_order_delay, recommend_resolution
        ↓                              ↓
src/mcp/server.ts (stdio)   src/mcp/http.ts (Streamable HTTP → Render)

Repositories hide the underlying data representation; services and the MCP tools depend only on repository method signatures, not on how the data is stored. See docs/decisions.md for why static TypeScript modules were chosen over PostgreSQL, why the MCP tool set stops at four read-only tools for now, and why the remote transport runs in stateless mode.

Connecting to the hosted server

No local setup is required to try the deployed workflow — point any MCP client that supports Streamable HTTP at:

https://e-commerce-mcp.onrender.com/mcp

For example, with the MCP Inspector:

npx @modelcontextprotocol/inspector
# then connect with transport "Streamable HTTP" and the URL above

The server is stateless and unauthenticated (read-only synthetic data only — see docs/decisions.md for that tradeoff, stated explicitly rather than left implicit). The /mcp endpoint is rate-limited to 60 requests per IP per minute (in-memory, per-instance — see docs/decisions.md) as a basic abuse guard given the lack of authentication.

Running locally

npm install
npm run typecheck
npm test

# stdio transport (for Claude Desktop/Code, MCP Inspector over stdio)
npm run build
npm start

# Streamable HTTP transport (what's deployed to Render)
npm run build
npm run start:http   # listens on $PORT, defaults to 3000

Point any MCP client (e.g. npx @modelcontextprotocol/inspector node dist/server.js, or Claude Desktop/Code's MCP config) at npm start (from this directory) to connect over stdio.

Testing

Tests use Vitest and live in tests/, mirroring src/:

  • tests/repositories/ — finder methods, including missing-record cases

  • tests/services/ — OrderContextService (context composition, including the ORD-1003 inventory-shortage case), DelayDiagnosisService (all seven scenario orders map to their expected category), and ResolutionService

  • tests/data/ — cross-record invariant checks (foreign keys, order totals, one-record-per-order cardinality, required scenario orders) run against the real dataset and against deliberately broken copies of it — checks TypeScript's structural typing can't express on its own

Synthetic data

src/data/ contains 18 products, 15 customers, 50 orders, and their corresponding payments/inventory/fulfillment records — all synthetic, INR-priced, .test-domain emails, MockPay as the fake payment provider. Each entity is a static, typed TypeScript module (e.g. src/data/orders.ts) rather than a JSON file; the dataset was generated once and is now finalized and hand-editable in place — see docs/decisions.md.

Seven orders (ORD-1001–ORD-1007) are deterministic, hand-crafted scenarios representing known operational situations (payment failure, inventory shortage, fulfillment delay, etc.) — see docs/test-scenarios.md for the full table.

Current limitations

  • No write/action tool (create_resolution_ticket) — read-only investigation, diagnosis, and recommendation only.

  • No persistence beyond static TypeScript modules; no database.

  • No authentication/authorization on the hosted HTTP endpoint — deliberate and disclosed, not an oversight; see docs/decisions.md. Acceptable here because the tool set is read-only and the data is synthetic; would need revisiting before any real data touched this server. Mitigated in part by a per-IP rate limit (60 req/min, in-memory) on /mcp, but that limits abuse per-instance only, not a substitute for real auth.

  • No real external integrations of any kind.

Future stages

Not yet built, and out of scope for this submission: one controlled, confirmation-gated write action (create_resolution_ticket), and authentication on the hosted endpoint if this ever handled real data. See CLAUDE.md and docs/decisions.md / docs/assumptions.md for what's confirmed vs. still open.

Available Tools

4 tools
diagnose_order_delayDiagnose order delayA

Apply deterministic rules to an order's context to identify the most likely cause of a delay (payment issue, inventory shortage, fulfillment delay/failure, cancelled, or no issue), with supporting evidence.

ParametersJSON Schema
NameRequiredDescriptionDefault
orderIdYes

TDQS

A3.9/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It discloses that the tool uses deterministic rules and returns supporting evidence, which is valuable. However, it does not explicitly state whether it is read-only, whether it fetches the context itself, or any side effects. For a diagnostic tool, this is acceptable 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, well-structured sentence that front-loads the action and provides all key details without redundancy. Every phrase earns its place, making it highly concise.

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?

The description lists the possible delay causes and mentions supporting evidence, but it does not clarify the exact input-output relationship (e.g., whether it fetches context internally) or describe the result format. Without an output schema, this ambiguity leaves room for misinterpretation, especially given the sibling get_order_context tool.

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

Parameters3/5

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

The schema has only one parameter, orderId, with 0% schema description coverage. The description mentions 'an order's context' but does not explicitly define orderId. However, the parameter name is self-explanatory, and the phrase 'to an order's context' implies its use. Thus, the description adds minimal but sufficient meaning.

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 the tool's function: applying deterministic rules to an order's context to identify the most likely cause of a delay. It enumerates the possible outcomes (payment issue, inventory shortage, fulfillment delay/failure, cancelled, or no issue) and mentions supporting evidence, which distinguishes it from sibling tools like get_order_context that merely retrieve context.

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 implies usage when an order is delayed and the user needs to determine the cause. It does not explicitly state when not to use it or compare to alternatives, but the context is clear enough for an agent to select this tool over search_orders or recommend_resolution.

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

get_order_contextGet order contextA

Gather the operational facts for one order — order, customer, payment, items+product, inventory, fulfillment — as evidence for investigating why it may be delayed. Returns facts only, no diagnosis.

ParametersJSON Schema
NameRequiredDescriptionDefault
orderIdYes

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the burden of disclosure. It clearly discloses the scope (facts only) and explicitly states what it does not do (no diagnosis), which is valuable behavioral context beyond a simple 'get' statement.

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 action and content, and ending with a clear boundary. Every word earns its place; no fluff or repetition of schema.

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

Completeness5/5

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

Given the simple tool (one parameter, no output schema), the description provides enough detail on what is returned: the operational fact categories and the no-diagnosis boundary. It is complete for an AI agent to know when and how to invoke it.

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?

The schema has only orderId with 0% coverage, but the description's 'for one order' makes the parameter's purpose self-evident. While it doesn't explicitly define orderId, the context of gathering information for a single order adequately compensates for the sparse schema.

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 uses a specific verb ('Gather') and identifies a clear resource ('operational facts for one order') with enumerated facets. It distinguishes itself from siblings by stating it returns facts only, no diagnosis, positioning it as the evidence-gathering step.

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 gives clear context: it is for investigating why an order may be delayed. It also sets an exclusion ('no diagnosis') that indirectly points to diagnosing tools, but it does not explicitly name sibling alternatives such as diagnose_order_delay.

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

recommend_resolutionRecommend resolutionA

Diagnose an order's delay and return recommended next actions for an operations specialist to take.

ParametersJSON Schema
NameRequiredDescriptionDefault
orderIdYes

TDQS

A4.2/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 transparency burden. It describes an advisory, read-only-looking operation ('return recommended next actions') without explicitly stating side effects, permissions, or whether it modifies anything. It adds some context (for an operations specialist) but does not disclose any deeper behavioral traits beyond what the name implies.

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, efficient sentence that front-loads the core verb ('Diagnose') and immediately communicates both the diagnostic and recommendation actions. Every word contributes to understanding, with no redundancy or filler.

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

Completeness4/5

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

Given the tool's simplicity—one parameter, no output schema, and a clear purpose—the description is largely complete. It covers what it does and for whom, though it could briefly mention the format of the recommendations (e.g., a list of actions). This is a minor gap, not a major omission.

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?

The schema only defines orderId as a string with zero descriptive coverage. The description ties orderId to 'an order's delay', providing meaningful context for the parameter. Although it doesn't specify format or how to obtain orderId, the single simple parameter is adequately explained by the description.

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 the tool's function: diagnose an order's delay and return recommended next actions. It uses a specific verb ('diagnose' and 'return') and resource ('order's delay', 'recommended next actions'), and it distinguishes itself from the sibling tool 'diagnose_order_delay' by adding the action recommendation component.

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 implicitly conveys when to use this tool—when you need recommended actions for an operations specialist. However, it does not explicitly contrast with alternatives like 'diagnose_order_delay', so it lacks explicit when-not guidance. The context is clear but lacks exclusions.

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

search_ordersSearch ordersA

Find candidate orders to investigate, optionally filtered by status and/or customer id. Read-only lookup — not general order management.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNo
customerIdNo

TDQS

A4/5.0
Behavior3/5

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

With no annotations, the description carries the burden and does disclose read-only behavior and the exclusion of general management. However, it does not describe return format, pagination, sorting, or any other behavioral details, leaving the agent with only a minimal safety profile.

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 two concise sentences, front-loaded with the primary function and followed by a relevant safety note. Every word earns its place, and the structure is clean.

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

Completeness4/5

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

Given no output schema, the description should ideally specify return values. 'Find candidate orders' implies a list of matching orders, but the response structure is not stated. This minor gap is acceptable for a simple search tool, making it mostly complete.

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

Parameters3/5

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

The schema has no parameter descriptions (0% coverage), so the description must compensate. It states the parameters are optional filters by status and/or customer id, which adds meaning. It does not elaborate on enum semantics beyond the schema values, but for a simple search this is adequate.

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 the tool 'Find candidate orders to investigate', using a specific verb and resource. It distinguishes itself from general order management and, combined with sibling names, implies a distinct investigative search function.

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 conveys clear usage context: it is for finding candidate orders to investigate, with optional filters. It explicitly states it is read-only and not for general management, but it does not name sibling alternatives or provide when-not-to-use guidance relative to them.

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. Dates show when Glama detected each change.

  1. 4 tool updatesv0.1.0
    • First observeddiagnose_order_delay
    • First observedget_order_context
    • First observedrecommend_resolution
    • First observedsearch_orders
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool serves a distinct stage in the investigation pipeline: search for candidates, gather context, diagnose cause, and recommend actions. Even though recommend_resolution includes diagnosis, the primary outputs are clearly different, so there is no ambiguity in selection.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (search, get, diagnose, recommend), making the operation of each tool predictable and easy to understand.

Tool Count5/5

Four tools is well-scoped for an order-delay investigation workflow, covering the essential stages without unnecessary bloat or omissions. The count fits comfortably within the ideal 3-15 range.

Completeness5/5

The tool set covers the full lifecycle of investigating an order delay: finding candidates, gathering contextual data, diagnosing the root cause, and recommending next steps. There are no obvious gaps for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessSyncing

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

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ameghcoder/e-commerce-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server