cob-shopify-mcp — Architecture

01 — Entry Points

How Requests Get In

Use as an MCP server (stdio or HTTP) for AI agents, or as a standalone CLI tool for direct Shopify management — no MCP required.

▶

CLI

Natural domain commands powered by Commander. cob-shopify products list --limit 5. Auto-discovers built-in + custom YAML tools.

products orders customers inventory analytics Commander

⇄

stdio Transport

Standard MCP transport via StdioServerTransport. Process-level piping for local agents, IDE integrations, and Claude Desktop.

StdioServerTransport local pipe

🌐

HTTP Transport

Streamable HTTP transport for remote clients. Enables multi-agent deployments, web dashboards, and cloud-hosted servers.

StreamableHTTPServerTransport remote port config

flowchart LR
    CLI["CLI · Commander
products · orders · customers
inventory · analytics"]
    STDIO["stdio Transport
StdioServerTransport"]
    HTTP["HTTP Transport
StreamableHTTPServerTransport"]

    MCP["MCP Server
@modelcontextprotocol/sdk"]

    CLI --> MCP
    STDIO --> MCP
    HTTP --> MCP

    MCP --> CORE["Core Engine"]

    style CLI fill:#2d1b69,stroke:#8b5cf6,stroke-width:2px,color:#e0e0e0
    style STDIO fill:#162d50,stroke:#3b82f6,stroke-width:2px,color:#e0e0e0
    style HTTP fill:#0f3425,stroke:#10b981,stroke-width:2px,color:#e0e0e0
    style MCP fill:#1a1a2e,stroke:#6c63ff,stroke-width:2px,color:#e0e0e0
    style CORE fill:#1a1a2e,stroke:#a78bfa,stroke-width:2px,color:#e0e0e0

02 — Core Engine

The Brain

API-agnostic MCP engine. Discovers tools, manages configuration, executes requests, and handles all cross-cutting concerns.

🔎

Registry & Discovery

Auto-discovers definitions via glob (*.tool.ts, *.tool.yaml), registers into the Tool Registry, and applies config-driven filtering via tiers and enable/disable rules.

auto-discover tool registry config filter tiers

⚙

Execution Engines

Three MCP primitive engines. The Tool Engine validates input, executes against the API, and maps responses. Resource and Prompt engines serve read-only data and templates.

Tool Engine Resource Engine Prompt Engine

🛡

Infrastructure

Auth Manager (static token, client credentials, OAuth), structured logging via pino, cost tracking, audit trails, and pluggable storage (JSON or SQLite with encryption).

auth manager pino logger cost tracker audit JSON storage SQLite + encryption

flowchart TB
    subgraph REG["Registry & Discovery"]
        direction LR
        AD["Auto-Discover
*.tool.ts · *.tool.yaml"]
        TREG["Tool Registry
register · list · filter"]
        CF["Config Filter
enable · disable · tiers"]
    end

    subgraph ENG["Execution Engines"]
        direction LR
        TE["Tool Engine
schema → execute → map"]
        RE["Resource Engine
read-only data"]
        PE["Prompt Engine
templates & workflows"]
    end

    subgraph INF["Infrastructure"]
        direction LR
        AUTH["Auth Manager
static · credentials · OAuth"]
        OBS["Observability
pino · cost tracker · audit"]
        STR["Storage
JSON · SQLite + encryption"]
    end

    DT["defineTool() · defineResource() · definePrompt()"]

    AD --> TREG --> CF
    CF --> TE
    CF --> RE
    CF --> PE
    DT -.-> TREG
    AUTH -.-> TE
    OBS -.-> TE
    STR -.-> AUTH

    style REG fill:#162d50,stroke:#3b82f6,stroke-width:2px,color:#e0e0e0
    style ENG fill:#162d50,stroke:#3b82f6,stroke-width:2px,color:#e0e0e0
    style INF fill:#162d50,stroke:#3b82f6,stroke-width:2px,color:#e0e0e0
    style DT fill:#7c2d12,stroke:#f97316,stroke-width:2px,color:#e0e0e0

03 — Shopify Shell

The Implementation

Shopify-specific layer: GraphQL client with rate limiting and caching, 49 built-in + 5 example custom tools across 5 domains, 4 resources, and 4 prompts.

🔗

GraphQL Client

Built on @shopify/admin-api-client with a middleware pipeline: Rate Limiter (cost-based throttling) → Cache Layer (TTL-based) → Retry (exponential backoff).

@shopify/admin-api-client rate limiter cache retry

49 Tools — 5 Domains

Type-safe, co-located tool definitions with Zod v4 schemas.

15

Products

list · get · search · create · update · variants · collections · tags · status

12

Orders

list · search · get · timeline · fulfillment · draft · notes · tags · mark paid

9

Customers

list · search · get · orders · LTV · create · update · tags

7

Inventory

item · SKU · levels · location · low stock · adjust · set

6

Analytics

sales · top products · orders · refunds · repeat rate · risk

Resources & Prompts

📋

Shop Info

Resource — store details

📍

Locations

Resource — all locations

💰

Currencies

Resource — enabled currencies

📜

Policies

Resource — store policies

💡

Store Health Check

Prompt — comprehensive audit

📈

Daily Sales Report

Prompt — revenue summary

📦

Inventory Risk Analysis

Prompt — stock alerts

💬

Customer Support Summary

Prompt — CS insights

flowchart TB
    subgraph CLIENT["GraphQL Client Pipeline"]
        direction LR
        CL["@shopify/admin-api-client
createAdminApiClient()"]
        RL["Rate Limiter
cost-based throttling"]
        CA["Cache Layer
TTL-based"]
        RT["Retry
exponential backoff"]
    end

    subgraph TOOLS["49 Tools — 5 Domains"]
        direction LR
        P["Products
15 tools"]
        O["Orders
12 tools"]
        C["Customers
9 tools"]
        I["Inventory
7 tools"]
        A["Analytics
6 tools"]
    end

    subgraph PRIM["MCP Primitives"]
        direction LR
        RES["4 Resources
shop · locations · currencies · policies"]
        PRM["4 Prompts
health · sales · risk · support"]
    end

    API["Shopify Admin GraphQL API
v2026-01"]

    CL --> RL --> CA --> RT
    TOOLS --> CL
    PRIM --> CL
    RT --> API

    style CLIENT fill:#1a4731,stroke:#10b981,stroke-width:2px,color:#e0e0e0
    style TOOLS fill:#1a4731,stroke:#10b981,stroke-width:2px,color:#e0e0e0
    style PRIM fill:#1a4731,stroke:#10b981,stroke-width:2px,color:#e0e0e0
    style API fill:#5b21b6,stroke:#a78bfa,stroke-width:3px,color:#ffffff

04 — Data Flow

Request to Response

The complete journey of an MCP tool call, from input validation through GraphQL execution to the final cached response.

1

MCP Tool Call

Client invokes a tool, e.g. list_products({ limit: 10 })

2

Zod Input Validation

Parameters validated against the tool's Zod v4 schema. Invalid input rejected immediately.

3

Config / Tier Check

Verify the tool is enabled in the current configuration and the tier allows execution.

4

Cache Lookup

Check TTL-based cache for a matching query. On hit, skip the rest and return cached data immediately.

5

Rate Limit Gate

Cost-based throttling respecting Shopify's 1000-point budget with 50/s restore rate.

6

Auth Token

Auth Manager resolves token from the configured provider (static, client-credentials, or OAuth).

7

GraphQL Execute + Retry

POST the query to Shopify Admin GraphQL API. Retry with exponential backoff on 429/5xx errors.

8

Response Mapping

Extract, normalize, and transform the raw GraphQL response into the tool's output schema.

9

Cache Store

Store the successful response in the TTL cache for subsequent identical queries.

10

Audit Log

Record tool name, duration, status, parameters, and cost to the audit trail.

11

MCP Response Returned

Return { content: [{ type: "text", text: "..." }] } to the MCP client.

flowchart LR
    USER["AI Agent / Client"]

    subgraph REQ["Request Pipeline"]
        direction TB
        R1["1. MCP Tool Call"]
        R2["2. Zod Validation"]
        R3["3. Config/Tier Check"]
        R4["4. Cache Lookup"]
        R5["5. Rate Limit Gate"]
        R6["6. Auth Token"]
        R7["7. GraphQL Execute + Retry"]
    end

    API["Shopify API"]

    subgraph RESP["Response Pipeline"]
        direction TB
        S1["8. Response Mapping"]
        S2["9. Cache Store"]
        S3["10. Audit Log"]
        S4["11. MCP Response"]
    end

    USER --> R1 --> R2 --> R3 --> R4 --> R5 --> R6 --> R7 --> API
    API --> S1 --> S2 --> S3 --> S4 --> USER

    style REQ fill:#162d50,stroke:#3b82f6,stroke-width:2px,color:#e0e0e0
    style RESP fill:#0f3425,stroke:#10b981,stroke-width:2px,color:#e0e0e0
    style API fill:#5b21b6,stroke:#a78bfa,stroke-width:3px,color:#ffffff
    style USER fill:#2d1b69,stroke:#8b5cf6,stroke-width:2px,color:#e0e0e0

05 — Tier System

Config-Driven Tool Tiers

Three-tier architecture for safe, flexible tool management. Enable what you need, disable what you don't, extend with custom YAML.

Tier 1 Enabled by Default

49 built-in tools ship ready to use, plus 5 example custom YAML tools. Safe, read-first operations with well-defined scopes. No config needed to get started.

list_products get_product search_products list_orders get_order search_orders list_customers get_customer inventory_levels sales_summary create_product update_product + 37 more

Tier 2 Disabled by Default — Opt-in via Config

Sensitive or destructive operations that require explicit opt-in. Safety boundary: no billing, payments, payouts, financial reports, or admin config changes unless deliberately enabled.

billing payments themes discounts marketing metafields store config payouts ... extensible

Tier 3 Custom YAML Tools — Enabled by Default

Define your own tools via *.tool.yaml files. Auto-discovered, schema-validated, and registered alongside built-in tools. Ship domain-specific tooling without writing TypeScript.

*.tool.yaml auto-discovered Zod validated custom GraphQL no code required

flowchart LR
    subgraph T1["Tier 1 — Enabled by Default"]
        direction TB
        T1A["49 Built-in Tools"]
        T1B["Products · Orders · Customers
Inventory · Analytics"]
    end

    subgraph T2["Tier 2 — Disabled by Default"]
        direction TB
        T2A["Opt-in via Config"]
        T2B["Billing · Payments · Themes
Discounts · Store Config"]
    end

    subgraph T3["Tier 3 — Custom YAML"]
        direction TB
        T3A["*.tool.yaml"]
        T3B["Auto-discovered
Zod validated · Custom GraphQL"]
    end

    CF["Config Filter
enable · disable · tiers"]
    REG["Tool Registry"]

    T1 --> CF
    T2 -.->|opt-in| CF
    T3 --> CF
    CF --> REG

    style T1 fill:#0f3425,stroke:#10b981,stroke-width:2px,color:#e0e0e0
    style T2 fill:#3a1515,stroke:#ef4444,stroke-width:2px,color:#e0e0e0
    style T3 fill:#162d50,stroke:#3b82f6,stroke-width:2px,color:#e0e0e0
    style CF fill:#1a1a2e,stroke:#a78bfa,stroke-width:2px,color:#e0e0e0
    style REG fill:#1a1a2e,stroke:#6c63ff,stroke-width:2px,color:#e0e0e0

06 — Advertise & Activate

82% Context Token Reduction

Instead of injecting all 49 tool schemas into AI context (~16,000 tokens), register one meta-tool with domain summaries (~300 tokens). AI activates only what it needs.

❌

Before (Default MCP)

Every MCP server dumps all tool schemas on connect. 49 tools = ~16,000 tokens consumed before the user asks a question. 95% wasted on tools never called.

            49 schemas → ~16,000 tokens/prompt
          

✅

After (Advertise & Activate)

One meta-tool activate_tools with domain summaries. AI calls activate_tools("analytics") to load only the 6 tools it needs.

            1 meta-tool → ~300 tokens + on-demand
          

⚡

How It Works

1. Connect — AI sees activate_tools with 5 domain summaries
2. Activate — AI calls activate_tools("analytics")
3. Execute — 6 analytics tools registered, AI calls top_products

            82% reduction · No competitor has this
          

Available Domains

Products

15 tools — list, search, get, create, update, variants, collections

Orders

12 tools — list, search, get, fulfillments, draft orders, tracking

Customers

9 tools — list, search, get, create, lifetime value, tags

Inventory

7 tools — stock levels, adjustments, SKU lookup, low-stock

Analytics

6 tools — sales summary, top products, refund rates, trends

Enable It

Config: tools.advertise_and_activate: true
Env var: COB_SHOPIFY_ADVERTISE_AND_ACTIVATE=true

07 — Use Cases

Who Uses This & How

From AI chatbots to multi-agent orchestration — every team in an ecommerce business can leverage cob-shopify-mcp as their Shopify brain.

🛒

Sales Assistant

AI agent that helps sales reps answer product questions, check real-time inventory, create draft orders, and pull customer lifetime value — all through natural conversation.

search_products list_inventory_levels create_draft_order get_customer_lifetime_value

🎧

Customer Support Bot

Look up orders by name or number, track fulfillment status, view order timeline, pull customer details and order history — resolve tickets faster with live data.

get_order_by_name get_order_fulfillment_status get_customer_orders

📦

Warehouse Manager

Monitor stock levels across locations, get low-stock alerts, adjust quantities, and generate inventory risk reports — keep the warehouse running smoothly.

low_stock_report adjust_inventory get_location_inventory

🚚

Shipping Executive

Track fulfillment across orders, update order notes and tags for logistics workflows, monitor delivery status at scale.

get_order_fulfillment_status add_order_note update_order_tags

📊

Business Intelligence

Sales summaries, top-selling products, refund rate analysis, repeat customer metrics, and inventory risk — all accessible to AI agents for automated reporting.

sales_summary top_products repeat_customer_rate

⚡

Automation Pipelines

Bulk product updates, tag management, order processing, customer segmentation — trigger from webhooks, cron jobs, or multi-agent workflows.

update_product manage_product_tags create_product

Integration Patterns

flowchart TB
    subgraph DIRECT["Pattern 1: Direct MCP"]
        direction LR
        D1["Claude / Cursor / Windsurf"] --> D2["MCP Protocol"] --> D3["cob-shopify-mcp"] --> D4["Shopify API"]
    end

    subgraph AGENT["Pattern 2: Agent Orchestration"]
        direction LR
        A1["Your App"] --> A2["Agent Layer\nLangChain · CrewAI · AutoGen"] --> A3["MCP Client"] --> A4["cob-shopify-mcp"] --> A5["Shopify API"]
    end

    subgraph RAG["Pattern 3: RAG + Live Data"]
        direction LR
        R1["User Query"] --> R2["Your App"]
        R2 --> R3["RAG\nProduct docs · FAQs · Policies"]
        R2 --> R4["MCP\nLive store data"]
        R3 --> R5["Combined Response"]
        R4 --> R5
    end

    subgraph MULTI["Pattern 4: Multi-Agent System"]
        direction LR
        M1["Sales Agent"] --> M4["cob-shopify-mcp\nHTTP transport"]
        M2["Support Agent"] --> M4
        M3["Warehouse Agent"] --> M4
        M4 --> M5["Shopify API"]
    end

    style DIRECT fill:#0f3425,stroke:#10b981,stroke-width:2px,color:#e0e0e0
    style AGENT fill:#162d50,stroke:#3b82f6,stroke-width:2px,color:#e0e0e0
    style RAG fill:#2d1b40,stroke:#8b5cf6,stroke-width:2px,color:#e0e0e0
    style MULTI fill:#1a2540,stroke:#06b6d4,stroke-width:2px,color:#e0e0e0