{"_id":"@iflow-mcp/ramakay-shopify-mcp-proxy","name":"@iflow-mcp/ramakay-shopify-mcp-proxy","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@iflow-mcp/ramakay-shopify-mcp-proxy","version":"0.1.0","description":"MCP Server providing proxy access to Shopify Storefront/Admin APIs with mock.shop support.","main":"dist/server.js","type":"module","bin":{"iflow-mcp-ramakay-shopify-mcp-proxy":"dist/server.js"},"scripts":{"build":"tsc","start":"node dist/server.js","dev":"tsc --watch & node --watch dist/server.js","prepublishOnly":"npm run build","inspect":"npx @modelcontextprotocol/inspector node dist/server.js"},"repository":{"type":"git","url":"git+https://github.com/ramakay/ShopifyMockMCP.git"},"keywords":["mcp","modelcontextprotocol","shopify","proxy","mock.shop"],"author":{"name":"ramakay"},"license":"MIT","bugs":{"url":"https://github.com/ramakay/ShopifyMockMCP/issues"},"homepage":"https://github.com/ramakay/ShopifyMockMCP#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.6.1","axios":"^1.8.4","graphql":"^16.10.0","zod":"^3.24.2"},"devDependencies":{"@mermaid-js/mermaid-cli":"^11.6.0","@types/node":"^20","typescript":"^5"},"_id":"@iflow-mcp/ramakay-shopify-mcp-proxy@0.1.0","_integrity":"sha512-Xp+KIn4QpEFl13156B+ZQnP7BmQdn9zVB82AWhHobaVvoOQYe9U+W2wNVTvlMqpitNxuu9maTI9Zbr/Ab4mjSg==","_resolved":"/app/auto-mcp-upload/data/8682/iflow-mcp-ramakay-shopify-mcp-proxy-0.1.0.tgz","_from":"file:/app/auto-mcp-upload/data/8682/iflow-mcp-ramakay-shopify-mcp-proxy-0.1.0.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Xp+KIn4QpEFl13156B+ZQnP7BmQdn9zVB82AWhHobaVvoOQYe9U+W2wNVTvlMqpitNxuu9maTI9Zbr/Ab4mjSg==","shasum":"7345ce33fc1e2224db2a92ff880a8d2177fb156a","tarball":"https://registry.npmjs.org/@iflow-mcp/ramakay-shopify-mcp-proxy/-/ramakay-shopify-mcp-proxy-0.1.0.tgz","fileCount":8,"unpackedSize":59531,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFTkb4tZeLlyfn9Ir2SYtuDHUnAqEW+tE22ER8JXFAv3AiB8NgEEpI3JhRU511Gc79VmQGrkwGbbA55JMQ5mh8s3iA=="}]},"_npmUser":{"name":"chatflowdev","email":"chatflowdev@gmail.com"},"directories":{},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ramakay-shopify-mcp-proxy_0.1.0_1770899514820_0.4875831679441598"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-12T12:31:54.719Z","0.1.0":"2026-02-12T12:31:55.147Z","modified":"2026-02-12T12:31:55.379Z"},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"description":"MCP Server providing proxy access to Shopify Storefront/Admin APIs with mock.shop support.","homepage":"https://github.com/ramakay/ShopifyMockMCP#readme","keywords":["mcp","modelcontextprotocol","shopify","proxy","mock.shop"],"repository":{"type":"git","url":"git+https://github.com/ramakay/ShopifyMockMCP.git"},"author":{"name":"ramakay"},"bugs":{"url":"https://github.com/ramakay/ShopifyMockMCP/issues"},"license":"MIT","readme":"# Shopify MCP Proxy & Mock Server (ShopifyMCPMockShop)\n\nThis project implements a Model Context Protocol (MCP) server that acts as an intelligent bridge and proxy to Shopify's Storefront API. It uniquely supports `mock.shop` for safe development and testing without requiring real store credentials.\n\nThe server communicates via **Standard Input/Output (stdio)**, making it suitable for local integration with clients like Claude Desktop and Cursor.\n## Motivation\n \nGeneric AI developer tools and off-the-shelf MCP servers often promise much but can lack the transparency, safety mechanisms (like explicit `ToolAnnotations`), stability, or specific features needed for controlled development and testing, especially against rapidly evolving APIs like Shopify's.\n \nThis project was born from the need for a reliable, open-source Shopify MCP server that:\n \n*   **Prioritizes Safety:** Integrates deeply with `mock.shop` to provide a crucial sandbox for risk-free development and accurate testing without impacting live stores.\n*   **Emphasizes Transparency & Control:** Allows developers (and their AI partners) to understand exactly how interactions with the Shopify API occur, including which API versions are used and the potential impact of actions (via `ToolAnnotations` like `readonly`, `destructive`, etc.).\n*   **Addresses Specific Needs:** Fills the gap left by purely informational tools or closed-source commercial offerings by providing a *safe execution engine* tailored for Shopify development workflows.\n \nThe goal is to enable developers to confidently leverage AI assistance for Shopify tasks, knowing they have a tool built with intentional guardrails and clear operational context.\n\n## Architecture\n\n### System Overview\nThe ShopifyMCPMockShop server follows a layered architecture that provides clean separation between MCP protocol handling and Shopify API integration:\n\n![System Architecture](architecture.png)\n\n### Data Flow\nThis sequence diagram illustrates how a typical request flows through the system, from user interaction to API response:\n\n![Data Flow Diagram](dataflow.png)\n\n### Tool Hierarchy\nThe MCP server exposes a comprehensive set of tools organized by Shopify resource type:\n\n![Tool Hierarchy](tools-hierarchy.png)\n\n## Setup & Running Locally\n\nThis server is a standalone Node.js script.\n\n1.  **Clone the repository:**\n    ```bash\n    git clone https://github.com/ramakay/ShopifyMockMCP.git\n    cd ShopifyMCPMockShop\n    ```\n2.  **Install dependencies:**\n    ```bash\n    npm install\n    ```\n3.  **Build the server:**\n    ```bash\n    npm run build\n    ```\n    This compiles the TypeScript code into JavaScript in the `dist` directory (`dist/server.js`).\n4.  **Configure Environment (Optional - for Real Store):**\n    *   If you want to connect to a **real Shopify store** instead of `mock.shop`, set the following environment variables before running the server (e.g., via export or a `.env` file loaded by your client):\n        *   `SHOPIFY_STORE`: Your store domain (e.g., `your-store.myshopify.com`). **Required** for real store usage.\n        *   `SHOPIFY_ACCESS_TOKEN`: Your Storefront API access token. **Required** for real store usage.\n        *   `SHOPIFY_VERSION`: Optional specific Storefront API version (e.g., `2025-04`). Defaults to latest stable.\n    *   **Note:** Using `mock.shop` (default when `SHOPIFY_STORE` is not set) requires no environment variables.\n    *   **Note:** Admin API functionality is currently disabled but planned for future updates. Configuration variables (`USE_ADMIN_API`, `ADMIN_ACCESS_TOKEN`, `ADMIN_VERSION`) are not currently used.\n\n5.  **Running:** The server is intended to be launched automatically by MCP clients (like Claude Desktop or Cursor) using the stdio configuration. You do not need to run `npm run start` manually. See the \"Usage\" section below.\n\n## Usage with Cursor or Claude Desktop\n\nConfigure your MCP client (Cursor, Claude Desktop) to launch this server via stdio. Add an entry like the following to the respective configuration file:\n\n*   **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n*   **Cursor:** `~/.cursor/mcp.json` (or similar)\n\n```json\n{\n  \"mcpServers\": {\n    // ... other servers ...\n    \"shopify-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/full/path/to/ShopifyMCPMockShop/dist/server.js\"\n      ],\n      \"env\": {\n        // Only needed if connecting to a REAL store:\n        // \"SHOPIFY_STORE\": \"your-store.myshopify.com\",\n        // \"SHOPIFY_ACCESS_TOKEN\": \"your-storefront-token\",\n        // \"SHOPIFY_VERSION\": \"2025-04\"\n      },\n      \"disabled\": false,\n      \"alwaysAllow\": []\n    }\n    // ... other servers ...\n  }\n}\n```\n\n**Important:**\n*   Replace `/full/path/to/ShopifyMCPMockShop` with the **absolute path** to where you cloned the repository.\n*   Only include the `env` variables if you are connecting to a real store.\n*   Restart your client (Cursor/Claude Desktop) after modifying the configuration.\n\n## Available Tools\n\nThis MCP server currently provides tools for interacting with the Shopify Storefront API.\n\n| Tool Name           | Description                                                                                   | API        |\n| :------------------ | :-------------------------------------------------------------------------------------------- | :--------- |\n| `getShopInfo`       | Fetches basic shop details (name, description, currency).                                     | Storefront |\n| `getProductById`    | Fetches a specific product by ID. If `includeImages` is true, returns JSON details and the first image (75px) as a base64 `ImageContentBlock`. | Storefront |\n| `findProducts`      | Searches/filters products with pagination/sorting.                                            | Storefront |\n| `getCollectionById` | Fetches a specific collection by ID, optionally including products.                           | Storefront |\n| `findCollections`   | Searches/filters collections with pagination/sorting.                                         | Storefront |\n| `cartCreate`        | Creates a new shopping cart.                                                                  | Storefront |\n| `cartLinesAdd`      | Adds line items to an existing shopping cart.                                                 | Storefront |\n| `cartLinesUpdate`   | Updates line items (e.g., quantity) in an existing shopping cart.                             | Storefront |\n| `cartLinesRemove`   | Removes line items from an existing shopping cart.                                            | Storefront |\n| `getCart`           | Fetches the details of an existing shopping cart by ID.                                       | Storefront |\n\n*(Note: Admin API tools like `getCustomerById` and `createProduct` are planned for future updates and are currently disabled.)*\n\n## Inspecting Server Capabilities\n\nTo verify the server is built correctly and see the exact capabilities it advertises to MCP clients, you can use the `inspect` script defined in `package.json`:\n\n```bash\n# Ensure you have run 'npm install' and 'npm run build' first\n# Run this from the project root directory\nnpm run inspect\n```\n\nThis command executes the compiled server (`node dist/server.js`) and sends the standard `mcp/capabilities` request via its standard input. The server processes this request and prints its capabilities (including available tools, resource templates, and server information) as a JSON response to its standard output, which you will see in your terminal. This is useful for debugging and confirming the server's advertised functionality.\n\n## Known Issues\n\n*   **Inline Image Rendering:** Clients like Claude Desktop and Cursor currently render `ImageContentBlock`s (used by `getProductById` when `includeImages` is true) in a separate UI block below the main text response, rather than inline. Attempts to use Markdown or HTML image tags within text blocks also failed to render inline in these clients.\n\n## Future Plans\n\n*   Re-integrate and test Admin API tools (`getCustomerById`, `createProduct`, etc.).\n*   Add configuration options for Admin API credentials (`USE_ADMIN_API`, `ADMIN_ACCESS_TOKEN`, `ADMIN_VERSION`).\n*   Implement a testing framework.\n*   Explore resource handling if client support improves.\n\n## License\n\nMIT License","readmeFilename":"README.md","_rev":"1-3d9fd326305ff20b5cf04053c9099e7b"}