# CLI — run directly from terminal
cob-shopify products list --limit 5
cob-shopify products list --limit 5 --fields id,title,status
cob-shopify orders get --id gid://shopify/Order/123 --json

# MCP — connect to Claude and let AI use the same tools
claude mcp add cob-shopify-mcp -- cob-shopify-mcp start

Before (default):   59 tool schemas → ~19,000 tokens per prompt
After (activate):   1 meta-tool     → ~300 tokens per prompt
On-demand:          AI activates 1 domain → +2,000-3,000 tokens only when needed

# cob-shopify-mcp.config.yaml
tools:
  advertise_and_activate: true

COB_SHOPIFY_ADVERTISE_AND_ACTIVATE=true

# AI agent runs this via its Bash tool — zero setup
cob-shopify products list --limit 5 --json
cob-shopify orders get-by-name --name "#1001" --json
cob-shopify analytics sales-summary --start_date 2026-01-01 --end_date 2026-03-15 --json

cob-shopify products list --schema   # AI reads the schema, knows what flags to pass

flowchart LR
    subgraph AGENTS["Your AI Layer"]
        direction TB
        SALES["Sales Assistant"]
        SUPPORT["Customer Support Bot"]
        WAREHOUSE["Warehouse Manager"]
        SHIPPING["Shipping Tracker"]
        BI["Business Intelligence"]
        AUTO["Automation Workflows"]
    end

    MCP["cob-shopify-mcp\n59 tools · 4 resources · 4 prompts\nAdvertise-and-Activate: 82% less context"]

    SHOPIFY["Shopify Store"]

    AGENTS --> MCP --> SHOPIFY

AI Agent → MCP Protocol → cob-shopify-mcp → Shopify API

User → Your App → Agent Layer (LangChain, CrewAI, etc.) → MCP Client → cob-shopify-mcp → Shopify API

User → Your App → RAG (product docs, policies, FAQs) + MCP (live store data) → Response

Sales Agent    ─┐
Support Agent  ─┤→ cob-shopify-mcp (HTTP transport) → Shopify API
Warehouse Agent─┘

npm install -g cob-shopify-mcp

claude mcp add cob-shopify-mcp \
  -e SHOPIFY_CLIENT_ID=your_client_id \
  -e SHOPIFY_CLIENT_SECRET=shpss_your_secret \
  -e SHOPIFY_STORE_DOMAIN=your-store.myshopify.com \
  -- cob-shopify-mcp start

claude mcp list
# cob-shopify-mcp: ... - ✓ Connected

claude mcp add cob-shopify-mcp \
  -e SHOPIFY_CLIENT_ID=your_client_id \
  -e SHOPIFY_CLIENT_SECRET=shpss_your_secret \
  -e SHOPIFY_STORE_DOMAIN=your-store.myshopify.com \
  -- npx cob-shopify-mcp start

{
  "mcpServers": {
    "cob-shopify-mcp": {
      "command": "cob-shopify-mcp",
      "args": ["start"],
      "env": {
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "shpss_your_secret",
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

git clone https://github.com/svinpeace/cob-shopify-mcp.git
cd cob-shopify-mcp
pnpm install
pnpm build

claude mcp add cob-shopify-mcp \
  -e SHOPIFY_CLIENT_ID=your_client_id \
  -e SHOPIFY_CLIENT_SECRET=shpss_your_secret \
  -e SHOPIFY_STORE_DOMAIN=your-store.myshopify.com \
  -- node /absolute/path/to/cob-shopify-mcp/dist/cli/index.js start

claude mcp list
# cob-shopify-mcp: ... - ✓ Connected

{
  "mcpServers": {
    "cob-shopify-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cob-shopify-mcp/dist/cli/index.js", "start"],
      "env": {
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "shpss_your_secret",
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

git clone https://github.com/svinpeace/cob-shopify-mcp.git
cd cob-shopify-mcp
cp .env.example .env

SHOPIFY_CLIENT_ID=your_client_id
SHOPIFY_CLIENT_SECRET=shpss_your_secret
SHOPIFY_STORE_DOMAIN=your-store.myshopify.com

docker compose up --build
# Server starts at http://127.0.0.1:3000

curl http://127.0.0.1:3000/health
# {"status":"ok"}

claude mcp add --transport http shopify http://127.0.0.1:3000

# Verify
claude mcp list
# cob-shopify-mcp: http://127.0.0.1:3000 (HTTP) - ✓ Connected

{
  "mcpServers": {
    "cob-shopify-mcp": {
      "url": "http://127.0.0.1:3000"
    }
  }
}

read_products, write_products, read_orders, write_orders, read_all_orders, read_draft_orders, write_draft_orders, read_order_edits, write_order_edits, read_customers, write_customers, read_inventory, write_inventory, read_locations, read_fulfillments, write_fulfillments, read_assigned_fulfillment_orders, write_assigned_fulfillment_orders, read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders, read_third_party_fulfillment_orders, write_third_party_fulfillment_orders, read_shipping, read_reports, read_legal_policies

cp .env.example .env

SHOPIFY_CLIENT_ID=your_client_id_here
SHOPIFY_CLIENT_SECRET=shpss_your_secret_here
SHOPIFY_STORE_DOMAIN=my-dev-store.myshopify.com
SHOPIFY_API_VERSION=2025-01

auth:
  method: token                    # token | client-credentials | authorization-code
  store_domain: ${SHOPIFY_STORE_DOMAIN}
  access_token: ${SHOPIFY_ACCESS_TOKEN}

shopify:
  api_version: "2026-01"
  cache:
    read_ttl: 30                   # seconds
    search_ttl: 10
    analytics_ttl: 300

tools:
  read_only: false                 # disable all mutations
  disable: []                      # tool names to disable
  enable: []                       # tool names to force-enable (even tier 2)
  advertise_and_activate: false    # lazy tool loading — 82% less context tokens

transport:
  type: stdio                      # stdio | http
  port: 3000
  host: "0.0.0.0"

storage:
  backend: json                    # json | sqlite
  path: "~/.cob-shopify-mcp/"

observability:
  log_level: info                  # debug | info | warn | error
  audit_log: true

rate_limit:
  respect_shopify_cost: true
  max_concurrent: 10

# Natural commands — cob-shopify <domain> <action> [flags]
cob-shopify products list --limit 5
cob-shopify products list --limit 5 --fields id,title,status
cob-shopify products get --id gid://shopify/Product/123
cob-shopify products search --query "snowboard" --limit 10
cob-shopify orders list --limit 10 --json
cob-shopify orders get --id gid://shopify/Order/456 --fields id,name
cob-shopify customers search --query "email:john@example.com"
cob-shopify inventory low-stock-report --threshold 10
cob-shopify analytics sales-summary --start_date 2025-01-01 --end_date 2025-12-31

# Global flags (available on every command)
--json              # Force JSON output (auto when piped)
--fields <f1,f2>    # Select specific response fields
--jq <expr>         # Filter JSON with jq expression
--schema            # Show command schema, don't execute
--dry-run           # Preview mutations without executing
--yes               # Skip confirmation prompts

# Schema introspection (for AI agents)
cob-shopify products list --schema

# Mutation safety
cob-shopify products create --title "New Widget" --dry-run
cob-shopify products delete --id gid://shopify/Product/123  # prompts for confirmation

# Server commands
cob-shopify-mcp start              # Start the MCP server
cob-shopify-mcp start --transport http --port 8080
cob-shopify connect --store my-store.myshopify.com
cob-shopify config show

# Legacy commands (deprecated, will be removed in v1.0)
cob-shopify tools list
cob-shopify tools info list_products

{
  "mcpServers": {
    "cob-shopify-mcp": {
      "command": "npx",
      "args": ["-y", "cob-shopify-mcp", "start"],
      "env": {
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "shpss_your_secret",
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

pnpm install
pnpm test           # Unit tests
pnpm test:integration  # Integration tests (requires Shopify credentials)
pnpm lint           # Biome linter
pnpm typecheck      # TypeScript type checking
pnpm build          # Build with tsup

flowchart TB
    subgraph ENTRY["Entry Points"]
        direction LR
        CLI["CLI\nproducts · orders · customers\ninventory · analytics"]
        STDIO["MCP Server\nstdio transport"]
        HTTP["HTTP Server\nStreamable HTTP"]
    end

    subgraph CORE["Core Engine (API-Agnostic)"]
        direction TB

        subgraph REGISTRY["Registry & Discovery"]
            direction LR
            AD["Auto-Discover\n*.tool.ts"]
            REG["Tool Registry\nregister · list · filter"]
            CF["Config Filter\nenable · disable · tiers"]
        end

        subgraph ENGINES["MCP Engines"]
            direction LR
            TE["Tool Engine\nschema gen · execute"]
            RE["Resource Engine\nread-only data"]
            PE["Prompt Engine\ntemplates · workflows"]
        end

        subgraph INFRA["Infrastructure"]
            direction LR
            AUTH["Auth Manager\nstatic · client-creds · OAuth"]
            OBS["Observability\nlogs · metrics · audit"]
            STORE["Storage\nJSON · SQLite+encryption"]
        end

        DT["defineTool() Helper"]
    end

    subgraph SHOPIFY["Shopify Shell"]
        direction TB

        subgraph CLIENT["Shopify GraphQL Client"]
            direction LR
            GQL["GraphQL Client\n@shopify/admin-api-client"]
            RL["Rate Limiter"]
            CACHE["Cache Layer"]
        end

        subgraph TOOLS["59 Tool Definitions"]
            direction LR
            PROD["Products\n15 tools"]
            ORD["Orders\n12 tools"]
            CUST["Customers\n9 tools"]
            INV["Inventory\n7 tools"]
            ANAL["Analytics\n16 tools"]
        end

        subgraph MCPPRIM["MCP Primitives"]
            direction LR
            RES["Resources\nshop info · locations"]
            PROMPT["Prompts\nstore health · reports"]
        end
    end

    SHOPIFY_API["Shopify Admin GraphQL API"]

    CLI --> CORE
    STDIO --> CORE
    HTTP --> CORE

    AD --> REG
    REG --> CF
    CF --> TE
    CF --> RE
    CF --> PE

    DT -.-> REG

    TE --> CLIENT
    RE --> CLIENT
    PE --> CLIENT

    AUTH --> CLIENT
    OBS -.-> TE
    STORE -.-> AUTH

    GQL --> RL
    RL --> CACHE

    TOOLS --> DT
    MCPPRIM --> RE
    MCPPRIM --> PE

    CACHE --> SHOPIFY_API

src/
├── core/               # API-agnostic MCP server core
│   ├── config/         # Zod config schema, multi-source loader
│   ├── auth/           # Static token, client credentials, OAuth
│   ├── engine/         # Tool, Resource, Prompt execution engines
│   ├── registry/       # Tool registry with config filtering
│   ├── storage/        # JSON + SQLite backends with encryption
│   ├── transport/      # stdio + HTTP transports
│   ├── observability/  # pino logger, cost tracker, audit log
│   └── helpers/        # defineTool, defineResource, definePrompt
├── shopify/            # Shopify-specific implementation
│   ├── client/         # GraphQL client, rate limiter, cache, retry
│   ├── tools/          # 59 tools across 5 domains
│   ├── resources/      # 4 MCP resources
│   └── prompts/        # 4 MCP prompts
├── server/             # Server bootstrap and registration bridges
└── cli/                # CLI commands (Commander + consola)

# my-tools/get-metafields.yaml
name: get_shop_metafields
domain: shop
description: Get shop metafields by namespace
scopes: [read_metafields]
input:
  namespace:
    type: string
    description: Metafield namespace
    required: true
graphql: |
  query($namespace: String!) {
    shop {
      metafields(first: 10, namespace: $namespace) {
        edges { node { key value } }
      }
    }
  }
response:
  mapping: shop.metafields.edges

tools:
  custom_paths: ["./my-tools/"]

# Via environment variables
COB_SHOPIFY_CUSTOM_TOOLS=./custom-tools    # Load custom YAML tools from directory
COB_SHOPIFY_DISABLE=cancel_order,tool2     # Disable specific tools
COB_SHOPIFY_ENABLE=some_tier2_tool         # Enable specific Tier 2 tools
COB_SHOPIFY_READ_ONLY=true                 # Disable ALL write operations