Skip to main content
Glama
FopeA6

By Adunni MCP Server

by FopeA6
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

Input

Type

Required

Description

productId

string

no*

Exact product ID, e.g. prod_001

collection

string

no*

Collection name, e.g. Evening

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

Input

Type

Required

Description

orderId

string

yes

Exact order ID, e.g. order_1001

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

Available Tools

2 tools
check_order_statusCheck order statusA

Look up a By Adunni order by order ID. Returns status (processing/shipped/delivered/cancelled), shipping country, tracking number if available, and the full product details for each line item.

ParametersJSON Schema
NameRequiredDescriptionDefault
orderIdYesExact order ID, e.g. 'order_1001'.

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations, the description carries the full behavioral burden, and it does meaningful work by enumerating the return payload: status enum values, shipping country, optional tracking number, and line-item product details. It does not state permission requirements, rate limits, or error behavior (e.g. what happens for an unknown order ID), which keeps it short of a 5.

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, zero filler, and the lookup action plus required key is front-loaded before the return-value detail. Every clause earns its place.

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?

For a one-parameter read tool with no output schema, the description fully compensates by describing the returned fields, including the enumerated statuses and the conditional tracking number. Nothing an agent needs to invoke or interpret the call is missing.

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?

Schema description coverage is 100% and the single orderId parameter is already documented with a concrete example ('order_1001'), so the schema does the heavy lifting. The description only restates 'by order ID' without adding format or validation nuance, matching the baseline 3.

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?

States a specific verb and resource ('Look up a By Adunni order by order ID') and scopes it to the order domain, which cleanly separates it from the sibling get_product_info. An agent can pick the right tool without opening either schema.

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

Usage Guidelines3/5

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

Usage is implied by the name and description — you call it when you have an order ID and need order status — but there is no explicit when-to-use/when-not guidance and no mention of the sibling get_product_info as the alternative for product-level lookups. Adequate but leaves routing to inference.

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

get_product_infoGet product infoA

Look up By Adunni product details by product ID, or list all products in a given collection (e.g. 'Evening', 'Everyday'). Returns price, currency, stock level and description as structured JSON. Provide either productId OR collection, not both.

ParametersJSON Schema
NameRequiredDescriptionDefault
productIdNoExact product ID, e.g. 'prod_001'.
collectionNoCollection name to list, e.g. 'Evening'.

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses the returned fields (price, currency, stock level, description) and the format (structured JSON). It omits auth needs, rate limits, and error behavior on invalid IDs, keeping it out of the top band.

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?

Three tight sentences, front-loaded with the core action and each carrying distinct information (modes, return shape, mutual-exclusivity rule). Nothing is redundant.

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?

With no output schema, the description usefully enumerates return fields and format, and covers the parameter contract. It lacks pagination/limit guidance for the collection-listing mode, which is the only notable gap for a 2-param tool.

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%, so baseline is 3, but the description adds a genuinely new constraint the schema does not encode: the two parameters are mutually exclusive ('not both'). That is real meaning beyond the schema's example strings.

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?

States a specific verb+resource ('Look up By Adunni product details') and clearly presents the two operating modes: single-product by ID or full-collection listing. The resource (products) is unmistakably distinct from the sole sibling check_order_status, which concerns orders.

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?

Explicitly tells the caller to 'Provide either productId OR collection, not both', which governs parameter selection between the two modes. It stops short of naming the sibling tool or stating hard exclusions, but the usage context is clear.

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. 2 tool updatesv1.0.0
    • First observedcheck_order_status
    • First observedget_product_info
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools target completely different resources: product catalog lookup vs. order tracking by order ID. There is no plausible scenario where an agent would confuse the two, and the product tool's dual-mode (productId or collection) is explicitly constrained.

Naming Consistency4/5

Both names follow a verb_noun pattern (get_product_info, check_order_status), which is predictable and readable. The only minor deviation is the differing verb choice ('get' vs 'check') for what are both fundamentally read/lookup operations.

Tool Count3/5

Two tools is thin for an e-commerce storefront surface, even a read-only one. It is not absurdly under-scoped for a simple brand assistant, but agents will quickly hit the edge of what they can do.

Completeness3/5

The surface covers the two most common read paths (product details and order status) but omits obvious operations like searching products by name, listing a customer's orders, or checking availability across collections. Read-only coverage is coherent but has notable dead ends for anything beyond a known ID.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Merchant Web MCP

    Redser06
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI shopping agents to search products, check stock, apply promotions, manage cart sessions, and create cryptographically signed checkout sessions on e-commerce storefronts, while giving merchants analytics into agent intent and catalog demand gaps.
    MIT

  • ro.autoid/autoid-support

    AutoID-Alex
    F
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to search enterprise Auto-ID products and exact SKUs, read live stock and current pricing, and explore variants, accessories, consumables and support relationships through a public read-only endpoint. It also surfaces manuals, firmware, drivers and other verified technical resources from the vendor's support center.
    -