# pashpashpash/shopify-mcp-server architecture

> Architecture diagram of the GitHub repository pashpashpash/shopify-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pashpashpash/shopify-mcp-server
- Repository: https://github.com/pashpashpash/shopify-mcp-server

## Overview

##### Project type and purpose
- This is a TypeScript-based Node.js “MCP Server” that implements the Model Context Protocol (MCP) to expose Shopify Admin GraphQL functionality as a set of command-style tools.
- It’s consumed by an external client (e.g., Claude Desktop) over a stdio-based RPC channel, and in turn calls Shopify’s GraphQL Admin API.

##### File structure
- Top level:
- package.json / tsconfig.json / jest.config.js – build, test, and dependency metadata
- src/index.ts – entry point, sets up the MCP server
- src/ShopifyClient/ShopifyClient.ts – concrete implementation of the “port” to Shopify
- src/ShopifyClient/ShopifyClientPort.ts – interface/port definition to decouple the MCP server from Shopify calls
- src/__tests__ – Jest tests to validate the ShopifyClient behavior
- Build artifacts (dist/) are produced by `npm run build`.
- Config: environment variables for SHOPIFY_ACCESS_TOKEN and MYSHOPIFY_DOMAIN.

##### Key README insights
- The server supports a dozen “tools” (get-products, get-orders, create-discount, etc.)
- Uses `@modelcontextprotocol/sdk` to handle MCP messages
- Uses `graphql-request` to call Shopify, and `zod` for runtime validation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Claude Desktop"]:::external

    %% Protocol Layer
    subgraph "Protocol Layer"
        EntryPoint["src/index.ts\n(MCP Server Entry Point)"]:::infra
        Router["MCP Router\n(@modelcontextprotocol/sdk)"]:::infra
    end

    %% Domain Layer
    subgraph "Domain Layer"
        Handlers["Command Handlers\n(get-products, get-orders, etc.)"]:::domain
    end

    %% Interface Layer
    subgraph "Ports & Interfaces"
        Port["ShopifyClientPort Interface"]:::interface
    end

    %% Adapter Layer
    subgraph "Adapter & HTTP Layer"
        Adapter["ShopifyClient Adapter\n(graphql-request, zod)"]:::infra
        GraphQLRequest["graphql-request\n(HTTP Client)"]:::infra
    end

    %% External Services
    subgraph "External Services"
        ShopifyAPI[(Shopify Admin API)]:::external
    end

    %% Configuration & Build
    subgraph "Config & Build Metadata"
        Env[".env\n(SHOPIFY_ACCESS_TOKEN, MYSHOPIFY_DOMAIN)"]:::config
        PKG["package.json"]:::config
        TSConfig["tsconfig.json"]:::config
        JestCfg["jest.config.js"]:::config
    end

    %% Optional Tests
    Tests["Jest Tests\nShopifyClient.test.ts"]:::domain

    %% Connections
    Client -->|"MCP JSON Message"| EntryPoint
    EntryPoint -->|"initialize"| Router
    Router -->|"dispatch message"| Handlers
    Handlers -->|"invoke port"| Port
    Port -->|"uses adapter"| Adapter
    Adapter -->|"executes GraphQL"| GraphQLRequest
    GraphQLRequest -->|"sends HTTP Query"| ShopifyAPI
    ShopifyAPI -->|"returns GraphQL Response"| GraphQLRequest
    GraphQLRequest -->|"response"| Adapter
    Adapter -->|"returns data"| Port
    Port -->|"returns result"| Handlers
    Handlers -->|"MCP JSON Response"| Router
    Router -->|"send response"| EntryPoint
    EntryPoint -->|"stdout JSON"| Client

    Env -->|"provides tokens"| Adapter
    PKG --> EntryPoint
    TSConfig --> EntryPoint
    JestCfg --> Tests
    Tests --> Adapter

    %% Click Events
    click EntryPoint "https://github.com/pashpashpash/shopify-mcp-server/blob/main/src/index.ts"
    click Router "https://github.com/pashpashpash/shopify-mcp-server/blob/main/src/index.ts"
    click Port "https://github.com/pashpashpash/shopify-mcp-server/blob/main/src/ShopifyClient/ShopifyClientPort.ts"
    click Adapter "https://github.com/pashpashpash/shopify-mcp-server/blob/main/src/ShopifyClient/ShopifyClient.ts"
    click Tests "https://github.com/pashpashpash/shopify-mcp-server/blob/main/src/__tests__/ShopifyClient.test.ts"
    click PKG "https://github.com/pashpashpash/shopify-mcp-server/blob/main/package.json"
    click TSConfig "https://github.com/pashpashpash/shopify-mcp-server/blob/main/tsconfig.json"
    click JestCfg "https://github.com/pashpashpash/shopify-mcp-server/blob/main/jest.config.js"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef infra fill:#90EE90,stroke:#000,stroke-width:1px
    classDef domain fill:#FFFACD,stroke:#000,stroke-width:1px
    classDef interface fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef config fill:#F5F5F5,stroke:#000,stroke-width:1px
```
