shagghiesuperstar/medusa-commerce
Let Grok Bot manage a Medusa v2 store as an agent. Golden Rule: read the official Medusa docs before any action (built-in medusa_docs tool). Fail-loud health, read-only catalog, inventory and PII-minimal orders, draft-only products by default, and opt-in publishing (MEDUSA_ALLOW_PUBLISH plus confirm=true). Includes an mcloud CLI setup, read-only observability dashboard, event stream, audit trail, remediation hooks (off by default), and rate-limit awareness.
Use for catalog audits: categories, tags, handles, sales-channel links, missing images/prices, drafts piling up, and storefront visibility. Read-only first; fixes go through draft-only, dry-run tools.
Use after any Medusa incident, surprise, or fix. Turn the lesson into a skill rule plus a regression test, cite the official doc (or mark UNVERIFIED), and log it in docs/LESSONS.md and CHANGELOG.
Use when turning product photos or a spreadsheet row into a Medusa product. Images go to a DRAFT product only; a human reviews and publishes in Medusa Admin. Never auto-publish.
Use on first install or when the Medusa connection looks wrong. Configure MEDUSA_BACKEND_URL, a secret admin API key and optional publishable key, then run store_health and a read-only tour.
Use before ANY Medusa action or answer. Read the official Medusa docs (docs.medusajs.com) first via medusa_docs, cite the page, and label anything the docs do not cover as "not in official docs".
Use when syncing stock from an external inventory system (ERP or warehouse) into Medusa, or debugging stock that looks wrong on the storefront.
Use when the operator wants Grok Bot to publish products or change live products, prices or stock. Off by default; requires MEDUSA_ALLOW_PUBLISH=true plus confirm=true per call, one product at a time, with read-back.
Use when the Medusa Admin Locations list crashes (e.g. "null is not an object (evaluating 'a.name')") because a sales channel was hard-deleted and left orphaned stock-location ↔ sales-channel link rows.
Use when cart tax lines are missing or stale, or when deciding when a storefront must call the Calculate Cart Taxes route.
Use to install, restore, or use Medusa Cloud's official CLI (mcloud) on the Grok Bot computer, and to connect the official Medusa Docs MCP and Cloud MCP as optional connectors. mcloud is a CLI, not an MCP.
Use when deleting or cleaning up Medusa Cloud environments, previews, storefronts or projects, or when finding an environment's current backend/admin URL and domains.
Use when designing a two-way ERP integration (e.g. Zoho Inventory) with Medusa v2: ERP-to-Medusa stock via webhooks, Medusa-to-ERP orders, locking, idempotency, reconciliation and cart-time stock checks.
Forward real Medusa backend events (order.placed, inventory-level.updated) to the plugin's optional events webhook. Docs-first: store events need a backend subscriber; the plugin only emits its own in-process observability events.
Use when planning Medusa for several legal entities or brands, or B2C plus B2B, on Medusa Cloud: instance boundaries, B2B pricing, branches/environments and deploy freezes.