By Adunni MCP Server

A minimal Model Context Protocol (MCP) server exposing two tools that let an AI agent look up product information and order status for the By Adunni storefront — without a human driving a UI.

Built to practice the specific skill of designing an interface for an agent to call, rather than for a human to read: structured inputs/outputs, explicit schemas, and documentation written so a model can act on it directly.

Why this exists

By Adunni is a live e-commerce brand I run. In the real store, a support agent or internal tool would need to answer questions like "is this in stock?" or "where's my order?" — today that's done by a human (me) checking Shopify manually. This project is a small proof-of-concept for how an AI agent could do that lookup directly, via two well-defined tools.

The underlying data is a static in-memory fixture (src/data.ts) standing in for the real Shopify Admin API, so this runs standalone with zero credentials or network calls.

Related MCP server: Commerce MCP Server

Tools

get_product_info

Look up a single product by ID, or list all products in a collection.

* Provide one or the other. If neither is given, all products are returned.

Returns: JSON object (single product) or JSON array (collection/all), each with id, name, collection, price, currency, stock, description.

Example call:

{ "name": "get_product_info", "arguments": { "productId": "prod_001" } }

Example response:

{
  "id": "prod_001",
  "name": "Adaeze Beaded Clutch",
  "collection": "Evening",
  "price": 85,
  "currency": "GBP",
  "stock": 12,
  "description": "Hand-beaded clutch bag with a braided strap, made in a classic evening silhouette."
}

check_order_status

Look up an order by ID. Resolves each line item into its full product object in the same call, so an agent doesn't need to chain a second lookup.

Returns: JSON object with id, customerEmail, status (processing | shipped | delivered | cancelled), items (each resolved to its full product), placedAt, shippingCountry, and trackingNumber if available.

If the order ID doesn't exist, the tool returns an error result (isError: true) with a JSON { "error": "..." } payload, rather than throwing — so an agent can handle it gracefully instead of crashing.

Running it

npm install
npm run build
npm start          # runs the compiled server on stdio

For local development without a build step:

npm run dev         # runs src/index.ts directly via tsx

Connecting it to an MCP client

Add to your client's MCP config (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "adunni-store": {
      "command": "node",
      "args": ["/absolute/path/to/adunni-mcp-server/dist/index.js"]
    }
  }
}

Testing

A smoke test drives the server with real MCP JSON-RPC messages over stdio and asserts on the results (exact lookup, collection filtering, nested order resolution, and error handling for unknown IDs):

npm run build
node test/smoke-test.mjs

Stack

TypeScript, @modelcontextprotocol/sdk, zod for schema validation. Transport: stdio.

Author

Fopefoluwa Ayo — fopeayo@hotmail.com