shopify-store-sync-mcp 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Youssef Idder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,578 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <img src="docs/images/hero.png" alt="shopify-store-sync-mcp: diff and sync configuration between Shopify stores from your AI assistant" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/shopify-store-sync-mcp"><img src="https://img.shields.io/npm/v/shopify-store-sync-mcp?color=cb3837" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-57c26e" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D20-6cb6ff" alt="Node 20+">
+  <img src="https://img.shields.io/badge/MCP-server-a371f7" alt="MCP server">
+  <img src="https://img.shields.io/badge/Shopify%20Admin%20API-2026--10-e3b341" alt="Shopify Admin API 2026-10">
+</p>
+
+<h3 align="center">Keep your Shopify stores in sync by asking for it.</h3>
+
+<p align="center">Compare a dev store with production, see every difference field by field, review a dry-run plan, then apply it.<br>From Claude, Cursor or any MCP client, or straight from the command line.</p>
+
+<p align="center">
+  <a href="#get-started">Get started</a> ·
+  <a href="#what-it-syncs">What it syncs</a> ·
+  <a href="#why-this-tool">Why this tool</a> ·
+  <a href="#safe-on-production">Safety</a> ·
+  <a href="#tested-on-real-stores">Tested</a> ·
+  <a href="#roadmap">Roadmap</a>
+</p>
+
+<p align="center">
+  <img src="docs/images/quickstart.png" alt="Three steps: connect your stores with npx shopify-store-sync-mcp connect, add the server to your AI client, ask in plain language" width="100%">
+</p>
+
+<p align="center">
+  <img src="docs/images/demo.png" alt="diff_stores, plan_sync and apply_plan output: 6 created, 3 updated, 1 conflict skipped, protected store refused without confirmation" width="100%">
+</p>
+
+<sub>Real output of the server's tools on two sample stores.</sub>
+
+## What it syncs
+
+The store setup that usually gets rebuilt by hand, plus the images it uses. References between items (a size guide pointing at a product, a menu linking to a page) are carried across by handle, so they land on the right item instead of a broken ID.
+
+<p align="center">
+  <img src="docs/images/what-it-syncs.png" alt="Metafield definitions, metaobject definitions and entries, collections, pages, menus, redirects, store policies, files and images, and opt-in products, metafield values and translations" width="100%">
+</p>
+
+<details>
+<summary><b>Details per resource</b></summary>
+
+| Resource | Keyed by | Notes |
+|---|---|---|
+| `metafield_definitions` | `OWNER_TYPE.namespace.key` | Name, description, pinning, storefront and customer account access, capabilities, validations. A type change is reported as a conflict, since Shopify can't change a definition's type in place. |
+| `metaobject_definitions` | `type` | Schema, access, capabilities. Fields are added or updated, never removed. Self-referencing definitions are handled. |
+| `pages` | `handle` | Title, body HTML, template, published state. |
+| `metaobjects` | `type/handle` | All field values, publish status. References to products, collections, pages and other metaobjects are remapped. |
+| `menus` | `handle` | Full item tree (3 levels), including customer account menus. Links to resources are remapped; custom URLs are kept; links to things that can't be matched are left out and reported. |
+| `redirects` | `path` | Thousands are fine. |
+| `collections` | `handle` | Title, description, sort order, template, SEO and smart-collection rules (rules on a metafield definition are remapped). Manual collections keep their own product list; sales-channel publishing is not copied. Manual versus smart is reported as a conflict. |
+| `shop_policies` | `type` | Refund, privacy, terms, shipping and contact policy text. |
+| `products` *(opt-in)* | `handle` | Title, description, vendor, type, tags, template, SEO, options, variants (matched by option values, with SKU) and images. **New products are created as drafts.** Prices only with `prices: true` (`--with-prices`); inventory and sales-channel publishing are never copied. On update, variants, images and option values that only the target has are kept, and don't count as differences. Gift cards are skipped. |
+| `metafields` *(opt-in)* | `OWNER/handle/namespace.key` | Metafield **values** on products and collections, landed on the item with the same handle. Reference values are remapped. Filter with `namespaces`. |
+| `translations` *(opt-in)* | `locale:Type/handle` | Translations of pages, collections, metaobjects, menus and policies. Registered against the target's own text, after the content itself is synced. The plan warns when a language isn't added to the target. |
+
+`products`, `metafields` and `translations` can be large, so they're read only when you ask for them (`resources: ["products"]`). When an include filter names exact product handles (or handle prefixes like `linen-*`), only those products are read. App-owned (`app--…`) and Shopify-reserved (`shopify--…`) data is skipped and listed in the report.
+
+**Files and images** referenced by any of the above are matched by file name in the target. When one is missing, the plan says so and `apply_plan` uploads it from the source store.
+
+</details>
+
+## Use cases
+
+<p align="center">
+  <img src="docs/images/use-cases.png" alt="Dev to production, multi-region brands, new market launch, drift audits" width="100%">
+</p>
+
+## Why this tool
+
+Plenty of Shopify MCP servers read and write *one* store. This one is built for the job *between* stores, where every ID is different:
+
+| | Generic Admin MCP servers | shopify-store-sync-mcp |
+|---|---|---|
+| Compare two stores | ❌ | ✅ field-level diff |
+| Cross-store ID remapping | ❌ you copy raw IDs | ✅ products, collections, pages, blogs, metaobjects, definitions, customer account pages and shop policies |
+| Dry run before writing | ❌ | ✅ every write goes through a reviewed plan |
+| Detects changes made after planning | ❌ | ✅ re-reads the target and skips anything that drifted |
+| Deletes | sometimes | **never** |
+| Production guardrails | ❌ | ✅ writes are off by default; protected stores need typed confirmation |
+| Audit trail | ❌ | ✅ JSONL log of every write |
+
+**Why not just Shopify CLI?** The CLI runs one query you wrote, on one store. This tool uses the CLI only to sign in, and does the comparing, ID remapping, ordering, uploads and safety checks for you.
+
+<p align="center">
+  <img src="docs/images/vs-shopify-cli.png" alt="Left: raw shopify store execute commands per store with manual comparison and ID rewriting. Right: diff_stores, plan_sync and apply_plan doing it with remapping, ordering, uploads and drift checks" width="100%">
+</p>
+
+## Safe on production
+
+<p align="center">
+  <img src="docs/images/safety.png" alt="Read-only by default, plan then apply, drift protection, never deletes, protected stores, conflicts not forced, audit log, no broken IDs" width="100%">
+</p>
+
+<details>
+<summary><b>How each safeguard works</b></summary>
+
+1. **Read-only by default.** `allowWrites` is `false` until you set it, per store.
+2. **Plan, then apply.** `apply_plan` only runs a plan produced by `plan_sync`. Plans expire after an hour.
+3. **Drift protection.** Before writing, the target is re-read. Any item that changed since planning is skipped, not overwritten.
+4. **No deletes.** Items that exist only in the target are listed, never removed. Fields that exist only in the target are left alone.
+5. **Protected stores.** Production needs the exact domain typed as confirmation.
+6. **Conflicts aren't forced.** A metafield definition whose type differs is reported and skipped.
+7. **Audit log.** Every write is appended to `~/.shopify-store-sync/audit.log` (override with `SYNC_AUDIT_LOG`).
+
+</details>
+
+## Get started
+
+### 1. Connect your stores
+
+Most people only need the first option: no app to create. The other two are for scheduled or unattended runs.
+
+<p align="center">
+  <img src="docs/images/connect.png" alt="connect output: browser approval, Connected, and the stores.json line to add; then the three ways to connect compared" width="100%">
+</p>
+
+```bash
+npm install -g @shopify/cli
+npx shopify-store-sync-mcp connect my-dev-store            # read-only
+npx shopify-store-sync-mcp connect my-staging-store --writes
+```
+
+<details>
+<summary><b>More about the Shopify CLI sign-in</b></summary>
+
+Each `connect` opens Shopify in your browser; click **Install** to approve. It asks for read-only scopes unless you pass `--writes` (or the store is configured with `"allowWrites": true`), then prints the line to add to `stores.json`:
+
+```json
+{ "stores": { "my-dev-store": { "domain": "my-dev-store.myshopify.com", "auth": "shopify-cli" } } }
+```
+
+Requests then run through `shopify store execute`, Shopify CLI's supported command, using the sign-in it saved. Each request starts Shopify CLI (about a second), so a full diff takes tens of seconds instead of one or two with an app. That sign-in belongs to you and expires after a while; when it does, the tool says so and you run `connect` again. Because of that, use option 2 or 3 for scheduled or unattended runs.
+
+</details>
+
+<details>
+<summary><b>Option 2: a Dev Dashboard app (automation on your own stores)</b></summary>
+
+One app covers every store in the same Shopify organization, and tokens are fetched and refreshed for you.
+
+1. Open the [Dev Dashboard](https://dev.shopify.com/dashboard), go to **Apps**, click **Create app**, then **Create app manually**.
+2. Give it a name, for example `Store Sync`. Any URL works as the App URL (it's never opened); untick **Embed app in Shopify admin**.
+3. In **Scopes**, paste the scopes from "Scopes needed per resource" below, then click **Create app** and **Release**.
+4. Install it on each store: open `https://admin.shopify.com/store/<store-handle>/oauth/install?client_id=<your client ID>` and click **Install**.
+5. Under the app's **Settings**, copy the **Client ID** and **Client secret** into environment variables (step 2 reads them from there).
+
+Adding a scope later means releasing a new version and approving the update on each store (same install link).
+
+</details>
+
+<details>
+<summary><b>Option 3: an access token from a custom app (automation on a client's store)</b></summary>
+
+Client credentials only work on stores in the app's own organization; elsewhere Shopify answers `shop_not_permitted`. For unattended runs on such a store, ask the owner to create a custom app in their admin (**Settings > Apps > Develop apps**), grant the scopes listed below, install it and share the Admin API access token (`shpat_...`). Use it as `accessToken` in step 2.
+
+</details>
+
+<details>
+<summary><b>Scopes needed per resource</b></summary>
+
+| Resource | Read scope | Write scope |
+|---|---|---|
+| metafield definitions | `read_products` (and the owner type's read scope) | `write_products` (and the owner type's write scope) |
+| metaobjects and definitions | `read_metaobjects`, `read_metaobject_definitions` | `write_metaobjects`, `write_metaobject_definitions` |
+| pages | `read_online_store_pages` | `write_online_store_pages` |
+| menus | `read_online_store_navigation` | `write_online_store_navigation` |
+| redirects | `read_online_store_navigation` | `write_online_store_navigation` |
+| collections | `read_products` | `write_products` |
+| products | `read_products` | `write_products` (plus `read_files`/`write_files` for their images) |
+| shop policies | `read_legal_policies` | `write_legal_policies` |
+| metafield values | `read_products` | `write_products` |
+| translations | `read_translations`, `read_locales` | `write_translations` |
+| files | `read_files` | `write_files` (to upload missing files) |
+| theme diff | `read_themes` | none, never writes |
+| ID remapping | `read_products`, `read_content` | none |
+
+Everything at once (the set used for the live tests), ready to paste:
+
+```text
+read_products,write_products,read_metaobjects,write_metaobjects,read_metaobject_definitions,write_metaobject_definitions,read_online_store_pages,write_online_store_pages,read_online_store_navigation,write_online_store_navigation,read_legal_policies,write_legal_policies,read_translations,write_translations,read_locales,read_files,write_files,read_themes,read_content
+```
+
+Give source stores read-only scopes when you can.
+
+</details>
+
+### 2. Describe your stores
+
+`connect` prints the line to add. A `stores.json` mixing all three ways to connect:
+
+```json
+{
+  "stores": {
+    "dev":  { "domain": "my-brand-dev.myshopify.com", "auth": "shopify-cli" },
+    "eu":   { "domain": "my-brand-eu.myshopify.com", "clientId": "env:EU_CLIENT_ID", "clientSecret": "env:EU_CLIENT_SECRET", "allowWrites": true, "protected": true },
+    "uk":   { "domain": "my-brand-uk.myshopify.com", "accessToken": "env:UK_TOKEN" }
+  }
+}
+```
+
+<details>
+<summary><b>All store options</b></summary>
+
+Create `stores.json`. Secrets can come from environment variables with `env:NAME`:
+
+```json
+{
+  "stores": {
+    "dev": {
+      "domain": "my-brand-dev.myshopify.com",
+      "accessToken": "env:DEV_TOKEN",
+      "label": "Development"
+    },
+    "eu": {
+      "domain": "my-brand-eu.myshopify.com",
+      "clientId": "env:EU_CLIENT_ID",
+      "clientSecret": "env:EU_CLIENT_SECRET",
+      "allowWrites": true,
+      "protected": true
+    }
+  }
+}
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `domain` | required | `*.myshopify.com` domain |
+| `auth` | | `"shopify-cli"`: use the sign-in saved by `connect` (no token needed), **or** |
+| `accessToken` | | Static Admin API token, **or** |
+| `clientId` + `clientSecret` | | Dev Dashboard app; tokens are fetched and refreshed automatically |
+| `apiVersion` | `2026-10` | Admin API version |
+| `allowWrites` | `false` | Must be `true` for `apply_plan` to write to this store |
+| `protected` | `false` | `apply_plan` also requires `confirm: "<domain>"` |
+
+You can also pass the whole config as JSON in `SHOPIFY_STORES`, or point `SHOPIFY_STORES_FILE` at a file elsewhere. For a single store, `SHOPIFY_STORE_DOMAIN` plus `SHOPIFY_ACCESS_TOKEN` works.
+
+</details>
+
+### 3. Add it to your AI client
+
+```json
+{
+  "mcpServers": {
+    "shopify-store-sync": {
+      "command": "npx",
+      "args": ["-y", "shopify-store-sync-mcp"],
+      "env": { "SHOPIFY_STORES_FILE": "/absolute/path/to/stores.json" }
+    }
+  }
+}
+```
+
+<details>
+<summary><b>Claude Desktop, Claude Code and Cursor</b></summary>
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "shopify-store-sync": {
+      "command": "npx",
+      "args": ["-y", "shopify-store-sync-mcp"],
+      "env": {
+        "SHOPIFY_STORES_FILE": "/absolute/path/to/stores.json",
+        "DEV_TOKEN": "shpat_...",
+        "EU_CLIENT_ID": "...",
+        "EU_CLIENT_SECRET": "..."
+      }
+    }
+  }
+}
+```
+
+**Claude Code**
+
+```bash
+claude mcp add shopify-store-sync \
+  -e SHOPIFY_STORES_FILE=/absolute/path/to/stores.json \
+  -e DEV_TOKEN=shpat_... \
+  -- npx -y shopify-store-sync-mcp
+```
+
+**Cursor** (`.cursor/mcp.json`) takes the same `command`, `args` and `env` as Claude Desktop.
+
+</details>
+
+### 4. Ask
+
+- *"Compare dev and eu. Only metaobjects and menus."*
+- *"Which product metafield definitions in namespace custom are missing from eu?"* (uses `include: ["PRODUCT.custom.*"]`)
+- *"Plan a sync of the faq and size_guide metaobjects from dev to eu."*
+- *"Apply only ops 1 to 4 of that plan."*
+- *"Copy the linen-shirt product to eu, with its prices."* (uses `resources: ["products"], include: ["linen-shirt"], prices: true`)
+- *"Copy the French translations from dev to eu."* (uses `resources: ["translations"], locales: ["fr"]`)
+- *"Export eu's configuration to ./store-config so I can commit it."*
+- *"Has eu drifted from ./store-config?"*
+- *"What's different in the theme settings between dev and eu?"*
+
+## Tools
+
+What `diff_stores` reports, field by field (real output):
+
+<p align="center">
+  <img src="docs/images/field-diff.png" alt="Field-level diff: page body, menu items, definition name, and a type conflict reported but not forced" width="100%">
+</p>
+
+<details>
+<summary><b>All 9 tools</b></summary>
+
+| Tool | Writes? | What it does |
+|---|---|---|
+| `list_stores` | no | Configured stores and their write permissions. Secrets are never returned. |
+| `list_resource_types` | no | What can be synced and how it's keyed. |
+| `snapshot_store` | no | Read one store's configuration in portable form. |
+| `diff_stores` | no | Only-in-source, changed (field by field), only-in-target. |
+| `plan_sync` | no | Dry-run plan: creates, updates, conflicts, missing references. Returns a `plan_id`. |
+| `get_plan` | no | Show a plan, or list recent ones. |
+| `apply_plan` | **yes** | Execute a plan, with every safety check below. |
+| `export_snapshot` | local files only | Write a store's configuration to a folder for git ([config as code](#config-as-code)). |
+| `diff_themes` | no | Compare theme templates and settings between two stores ([theme settings](#theme-settings-diff)). |
+
+Every tool except `apply_plan` is read-only toward Shopify and annotated as such, so clients can auto-approve them.
+
+</details>
+
+## Command line
+
+Everything also works without an AI client, and `--exit-code` turns `diff` into a scheduled drift check.
+
+<p align="center">
+  <img src="docs/images/cli.png" alt="CLI output of diff, plan and themes commands" width="100%">
+</p>
+
+<details>
+<summary><b>Commands</b></summary>
+
+Everything also works without an AI client. Run a command instead of starting the server:
+
+```bash
+npx shopify-store-sync-mcp stores
+npx shopify-store-sync-mcp diff dev eu --resources pages,menus
+npx shopify-store-sync-mcp plan dev eu
+npx shopify-store-sync-mcp apply <plan-id> --confirm eu.myshopify.com
+npx shopify-store-sync-mcp export eu ./store-config
+npx shopify-store-sync-mcp themes dev eu
+```
+
+`--json` gives machine-readable output and `--exit-code` makes `diff` and `themes` exit with 2 when they find differences, handy for a scheduled drift check. Run `npx shopify-store-sync-mcp help` for every option.
+
+</details>
+
+## Config as code
+
+Export a store's setup as small, sorted JSON files, commit it, and use the folder as a source anywhere (`dir:./store-config`) to spot drift, review changes as a pull request, or restore.
+
+<p align="center">
+  <img src="docs/images/config-as-code.png" alt="Exported store-config folder and one translation file" width="100%">
+</p>
+
+<details>
+<summary><b>How to use it</b></summary>
+
+Export a store's configuration as one small JSON file per item, with sorted keys and no store-specific IDs, then commit it:
+
+```bash
+npx shopify-store-sync-mcp export prod ./store-config
+git add store-config && git commit -m "Snapshot prod configuration"
+```
+
+Any command or tool that takes a source also takes `dir:<path>`:
+
+- **Spot drift:** `diff dir:./store-config prod` shows what changed in production since the commit.
+- **Review changes:** edit the files or re-export from staging, and review the change as a pull request.
+- **Restore or promote:** `plan dir:./store-config prod`, then `apply`, with all the usual safety checks.
+
+</details>
+
+<details>
+<summary><b>Theme settings diff (read-only)</b></summary>
+
+`diff_themes` (or `themes` on the command line) compares the published themes of two stores: JSON templates, section groups and `config/settings_data.json`, setting by setting. Pass theme ids to compare other themes, and `files` to narrow it down (for example `templates/product*.json`). It is read-only: themes are never written to.
+
+</details>
+
+## How it works
+
+<p align="center">
+  <img src="docs/images/how-it-works.png" alt="Snapshot, diff, plan, apply, with safety checks before every write" width="100%">
+</p>
+
+<p align="center">
+  <img src="docs/images/remapping.png" alt="gid://shopify/Product/101 in dev becomes shopify://Product/linen-shirt, then gid://shopify/Product/9101 in eu" width="100%">
+</p>
+
+<details>
+<summary><b>How ID remapping works</b></summary>
+
+Every Shopify ID is store-specific, so the server never compares or copies raw IDs. When it reads a store, each `gid://shopify/...` value is rewritten into a portable reference:
+
+```
+gid://shopify/Product/8123456          →  shopify://Product/linen-shirt
+gid://shopify/Metaobject/2918          →  shopify://Metaobject/faq/returns
+gid://shopify/MetaobjectDefinition/77  →  shopify://MetaobjectDefinition/faq
+gid://shopify/CustomerAccountPage/12   →  shopify://CustomerAccountPage/orders
+gid://shopify/ShopPolicy/5             →  shopify://ShopPolicy/PRIVACY_POLICY
+gid://shopify/Menu/41                  →  shopify://Menu/main-menu
+gid://shopify/MetafieldDefinition/9    →  shopify://MetafieldDefinition/PRODUCT.custom.fabric
+gid://shopify/MediaImage/730           →  shopify://File/size-chart.png
+```
+
+This covers JSON list values (`list.product_reference`) and definition validations (`metaobject_definition_id`). When it writes, references are resolved by handle in the target. A reference that doesn't exist there is flagged in the plan before anything is written.
+
+Things in the same plan can depend on each other, for example a metaobject pointing at another one being created, or a definition that references itself. These are written in two passes: first without the pending references, then complete.
+
+Files (images, generic files and videos) are matched by file name and uploaded to the target when missing. Collection rules that filter on a metafield are remapped to the target's definition.
+
+**Not remapped yet:** product variants and articles. Their values are left out of the sync and listed as warnings, never copied as broken IDs.
+
+Two references followed from the source store to the target, as the sample sync above wrote them:
+
+</details>
+
+## Tested on real stores
+
+<p align="center">
+  <img src="docs/images/tested.png" alt="68 automated tests, 52 GraphQL operations validated, 11 item types written live, 2 sign-in methods used live" width="100%">
+</p>
+
+<details>
+<summary><b>Every live test and its result</b></summary>
+
+| Feature | Live result |
+|---|---|
+| Diff of all default resource types | both stores read in about 10 seconds |
+| Create: metafield and metaobject definitions, metaobjects, smart collection, page, redirect, French translation | applied, second diff empty |
+| File reference on a metaobject | image uploaded to the target by file name and linked |
+| Update: page title and body, collection description | applied, second diff empty |
+| Shop policies | synced; a policy Shopify manages automatically is reported with how to unblock it |
+| Metafield values, including a `product_reference` | applied, reference remapped to the target's own product |
+| Values on products missing from the target | skipped up front with the reason |
+| Export to a folder, then diff that folder against the store | no differences |
+| Theme settings diff | read-only, 15 files compared in about 1 second |
+| Products (Shopify CLI sign-in, Windows) | a real product copied as a draft with its 4 images and alt text; after editing the copy and adding a variant and an image there, the update restored the title and kept both; the next diff was identical |
+| Products: reading only named handles | planning one product went from 97 to 6 seconds |
+| Safety: write to a read-only store | refused |
+| Safety: target edited after the plan was made | step skipped, nothing overwritten |
+| Shopify CLI sign-in on Windows (CLI 4.9.4), both stores | `connect` read-only and `--writes`; plan, apply (7 creates incl. file upload and translation), update and re-diff all exact; also through the MCP server over stdio |
+
+Behaviours of the live API found this way are covered by tests: `nodes` returns `null` for customer account pages (they're looked up by listing instead), `ShopPolicy.type` has to be aliased next to `Metaobject.type`, Shopify refuses edits to auto-managed policies, and a failed token request carries its reason (such as `app_not_installed`) in an HTML page.
+
+</details>
+
+## Roadmap
+
+<p align="center">
+  <img src="docs/images/roadmap.png" alt="Roadmap: shipped (syncing, safety, ways to use it, quality) and next (collection sources, variants and articles, more metafield owners, menu translations, markets, bulk mode, undo, optional deletes)" width="100%">
+</p>
+
+<details>
+<summary><b>The full list</b></summary>
+
+**Shipped**
+
+*Syncing*
+- [x] Metafield definitions, metaobject definitions and metaobject entries
+- [x] Products: content, options, variants by option values and SKU, images; new ones as drafts, prices only when asked, target-only variants and images kept
+- [x] Collections with smart-collection rules, pages, menus (3 levels, customer account menus too), redirects, store policies
+- [x] Metafield values on products and collections, translations per language (opt-in)
+- [x] Images and files matched by file name, uploaded to the target when missing
+- [x] Cross-store ID remapping by handle, including list references and rules on metafield definitions
+- [x] Two-pass writes for items that point at each other or at themselves
+- [x] Filters: resource types, include and exclude patterns, namespaces, metaobject types, owner types, languages
+
+*Safety*
+- [x] Dry-run plans that expire after an hour, applied in full or step by step (`--only`)
+- [x] Drift check before every write, never deletes, read-only by default, typed confirmation for protected stores
+- [x] Conflicts reported instead of forced (type changes, manual versus smart collections, values on items missing from the target)
+- [x] Audit log of every write
+
+*Ways to use it*
+- [x] MCP server with 9 tools, read-only tools annotated for auto-approval
+- [x] Command line with `--json` output and `--exit-code` for scheduled drift checks
+- [x] Config as code: export a store to files and use the folder as a source (`dir:`)
+- [x] Read-only theme settings diff
+- [x] Connect without creating an app (Shopify CLI sign-in), or with a Dev Dashboard app or an access token
+- [x] Published on npm, runs with `npx`
+
+*Quality*
+- [x] 68 automated tests against an in-memory Shopify, plus MCP protocol tests
+- [x] Every GraphQL operation validated against Shopify's schema for 2026-04, 2026-10 and 2027-01
+- [x] Tested live between two stores on Linux and Windows, Shopify CLI 4.9 and 5
+- [x] Parallel reads with throttle-aware retries; clear errors for missing installs, expired sign-ins and auto-managed policies
+
+**Next**
+- [ ] Move collection rules to Shopify's new `sources` model (`ruleSet` is deprecated but supported through 2027-01)
+- [ ] Product prices per market and inventory levels, as explicit opt-ins
+- [ ] Remap product variants and blog articles, so references to them sync too
+- [ ] Metafield values on variants, pages, blogs and the shop
+- [ ] Menu item (link) translations
+- [ ] Markets and market web presences
+- [ ] Bulk operations for very large stores
+- [ ] Undo: restore the previous values of an applied plan from the audit log
+- [ ] Optional deletes, behind an explicit flag
+
+</details>
+
+Ideas and PRs are welcome. Issues tagged `good first issue` are a good place to start.
+
+<details>
+<summary><b>Development</b></summary>
+
+```bash
+npm install
+npm test              # vitest: unit, sync engine against an in-memory Shopify, and MCP protocol tests
+npm run typecheck
+npm run build
+
+# Validate every GraphQL operation against Shopify's real Admin schema
+npm run validate:graphql            # defaults to 2026-10
+npm run validate:graphql -- 2027-01
+```
+
+Layout:
+
+```
+src/
+  index.ts            entrypoint: MCP server on stdio, or the CLI when given a command
+  engine.ts           everything the tools and the CLI do, in one place
+  server.ts           MCP tools
+  cli.ts              command line
+  snapshotFiles.ts    export and read snapshot folders (config as code)
+  themes.ts           read-only theme settings diff
+  config.ts           store config loading and validation
+  shopify/client.ts   Admin GraphQL client (token refresh, throttling, retries)
+  shopify/cliClient.ts  the same requests through Shopify CLI's sign-in (`shopify store execute`)
+  refs.ts             GID <-> portable reference mapping
+  snapshot.ts         read a store into portable form
+  diff.ts             field-level diff
+  plan.ts             dry-run plans and plan storage
+  apply.ts            guarded, drift-checked, two-pass writes
+  resources/          one adapter per resource type
+test/
+  fakeShop.ts         in-memory Admin API used by the tests
+```
+
+Adding a resource type means writing one adapter (`fetch`, `create`, `update`) in `src/resources/`. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+</details>
+
+<details>
+<summary><b>Related projects</b></summary>
+
+Syncing definitions between stores isn't a new idea, and these tools are worth knowing:
+
+| Project | Type | What it covers |
+|---|---|---|
+| [groupthought/metasync](https://github.com/groupthought/metasync) | CLI | Metafield and metaobject definitions plus resource data; dry run by default; has a delete mode |
+| [TeamDijon/meta-sync](https://github.com/TeamDijon/meta-sync) | CLI | Metafield and metaobject definitions and entries; manifest-based copy; bulk mode deletes the target first |
+| [shopify-metadata-migrator](https://github.com/warriorachilles/shopify-metadata-migrator) | CLI | Copies metafield and metaobject definitions |
+| MetaMaintain, Metora, Rewind Staging | Shopify apps (paid or freemium) | Definition and entry sync through an embedded app |
+
+What this project adds: it runs inside your AI client as an MCP server (or as a CLI) on your own machine, signed in as you through Shopify CLI or with your own private app, so there's no third-party app from the App Store and no data goes anywhere except Shopify. You can ask for a diff in plain language; it also covers pages, menus, redirects, collections, policies, metafield values and translations, remaps references and files across stores, keeps store configuration in git, checks for drift before writing and never deletes. If you only need a scripted one-shot copy of definitions, one of the CLIs above may be all you need.
+
+</details>
+
+## Disclaimer
+
+Not affiliated with, endorsed by or sponsored by Shopify Inc. "Shopify" is a trademark of Shopify Inc. Test on development stores first; you are responsible for what you apply to production.
+
+## License
+
+[MIT](LICENSE) © Youssef Idder