The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
Feat/ai discoverability (#835)
Jakub Sieradzki019017771be2
diff --git a/.claude/skills/migration-guide/SKILL.md b/.claude/skills/migration-guide/SKILL.mdindex 0709a8cfc..d59988c3e 100644--- a/.claude/skills/migration-guide/SKILL.md+++ b/.claude/skills/migration-guide/SKILL.md@@ -44,7 +44,7 @@ Based on classification, read from `docs/migrations/mercur-1.x-to-2.0/`:1. Set up fresh 2.0 project (see README.md)2. Update `medusa-config.ts` (plugins, modules, providers)-3. Add registry blocks (`mercurjs add <block>`)+3. Add registry blocks (`bunx @mercurjs/cli@latest add <block>`)4. Port custom backend code in order: providers → modules → workflows → links → subscribers → API routes → middlewares5. Port dashboard code (if applicable)6. Verify at each checkpointdiff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 000000000..8aadcdc73--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,93 @@+# Mercur++**Open-source AI-native marketplace framework built on MedusaJS v2.**++Mercur provides reusable building blocks for multi-vendor marketplaces: seller management, commissions, payouts, order splitting, vendor portals, and admin dashboards. Code is copied into your project for full ownership — no black-box dependencies.++## Architecture++- **Foundation**: MedusaJS v2 (headless commerce)+- **Language**: TypeScript (strict)+- **Monorepo**: Turborepo with bun+- **Pattern**: Block-based — modules, workflows, API routes, and UI extensions installed via CLI++### Project Structure++```+mercur/+├── apps/docs/ # Documentation site (Mintlify)+├── packages/admin/ # Admin dashboard UI+├── packages/cli/ # @mercurjs/cli — scaffolding, blocks, codegen+├── packages/client/ # @mercurjs/client — typed API client+├── packages/core-plugin/ # @mercurjs/core-plugin — core Medusa plugin+├── packages/dashboard-sdk/ # Vite plugin for dashboard apps+├── packages/registry/ # Official block registry+├── packages/types/ # @mercurjs/types — shared type definitions+├── packages/vendor/ # Vendor portal UI framework+└── templates/basic/ # Starter project template+```++## Documentation++- **Docs**: https://docs.mercurjs.com+- **MCP Server**: https://docs.mercurjs.com/mcp — use with AI agents for documentation search+- **llms.txt**: https://docs.mercurjs.com/llms.txt — machine-readable project summary++## CLI Commands++```bash+# Create a new marketplace project+bunx @mercurjs/cli@latest create my-marketplace++# Add blocks from registry+bunx @mercurjs/cli@latest add <block-name>++# Generate TypeScript types from API routes+bunx @mercurjs/cli@latest codegen++# Search available blocks+bunx @mercurjs/cli@latest search -q "commission"++# View block details+bunx @mercurjs/cli@latest view <block-name>+```++## Block System++Mercur uses a block-based architecture where reusable pieces of functionality are installed into your project:++- **Modules** — data models and business logic (sellers, commissions, offers, reviews)+- **Links** — relationships between modules (e.g., linking sellers to products)+- **Workflows** — multi-step business processes (order splitting, payout calculation)+- **API Routes** — HTTP endpoints for admin, vendor, and storefront APIs+- **Admin Extensions** — UI components for the admin dashboard+- **Vendor Extensions** — UI components for the vendor portal++Install blocks with `mercurjs add`:++```bash+bunx @mercurjs/cli@latest add seller commission payout+```++## Skills++Mercur ships `.claude/skills/` with project templates. Skills provide AI agents with domain-specific patterns for admin UI, forms, tabs, compound components, and code review. They are auto-loaded by Claude Code.++## Configuration Files++- `blocks.json` — project block configuration and path aliases+- `mercur.config.ts` — dashboard/vendor app configuration+- `medusa-config.ts` — MedusaJS configuration++## Getting Started++```bash+bunx @mercurjs/cli@latest create my-marketplace+cd my-marketplace+bun run dev+```++This starts:+- Backend API at `http://localhost:9000`+- Admin Panel at `http://localhost:7000`+- Vendor Panel at `http://localhost:7001`diff --git a/README.md b/README.mdindex 9cd364218..b515e741a 100644--- a/README.md+++ b/README.md@@ -45,6 +45,16 @@ technology stack.- **CLI** — `@mercurjs/cli` for scaffolding projects, adding blocks, and managing registries- **Full code ownership** — code is copied into your project, no black-box dependencies+## Using with AI Agents++Mercur is built to be AI-agent friendly. Your AI coding assistant can use these resources to understand and work with Mercur projects:++- **MCP Server**: `https://docs.mercurjs.com/mcp` — connect your agent for documentation search+- **llms.txt**: `https://docs.mercurjs.com/llms.txt` — machine-readable project summary+- **AGENTS.md**: included in every project created with `mercurjs create` — gives agents instant project context+- **Skills**: `.claude/skills/` shipped with templates — domain-specific patterns for Claude Code+- **AI Development Guide**: [docs.mercurjs.com/v2/ai-development/mcp](https://docs.mercurjs.com/v2/ai-development/mcp)+## Why Choose Mercur?- Full Ownership: Unlike SaaS platforms, you own yourdiff --git a/apps/docs/docs.json b/apps/docs/docs.jsonindex fe0942625..2d82d6776 100644--- a/apps/docs/docs.json+++ b/apps/docs/docs.json@@ -2,6 +2,7 @@"$schema": "https://mintlify.com/docs.json","theme": "mint","name": "MercurJS documentation",+ "description": "Mercur is an open-source AI-native marketplace framework built on MedusaJS v2. It provides block-based architecture for building multi-vendor marketplaces with seller management, commissions, order splitting, payouts, admin panel, and vendor portal. Code is copied directly into your project — full ownership, no black-box dependencies.","logo": {"dark": "/logo.svg","light": "/logo_dark.svg"diff --git a/apps/docs/v2/blocks.mdx b/apps/docs/v2/blocks.mdxindex f638f9ce3..83e79901f 100644--- a/apps/docs/v2/blocks.mdx+++ b/apps/docs/v2/blocks.mdx@@ -149,4 +149,46 @@ mode: "custom"</p></div>+ <div className="mt-12 mb-4">+ <h2 className="text-2xl font-bold tracking-tight mb-4">Quick Start</h2>++ <h3 className="text-lg font-semibold mb-2">Install a block</h3>++```bash+bunx @mercurjs/cli@latest add reviews+```++This copies the block source code into your project:++```+src/+├── modules/reviews/ # Data model and service+│ ├── models/+│ ├── service.ts+│ └── index.ts+├── workflows/reviews/ # Business logic+│ ├── create-review.ts+│ └── index.ts+├── api/+│ ├── admin/reviews/ # Admin API routes+│ ├── vendor/reviews/ # Vendor API routes+│ └── store/reviews/ # Storefront API routes+└── admin/+ └── routes/reviews/ # Admin dashboard pages+```++ <h3 className="text-lg font-semibold mt-6 mb-2">Search blocks</h3>++```bash+bunx @mercurjs/cli@latest search -q "reviews"+```++ <h3 className="text-lg font-semibold mt-6 mb-2">Compare local changes against registry</h3>++```bash+bunx @mercurjs/cli@latest diff reviews+```++ </div>+</div>diff --git a/apps/docs/v2/core-concepts/commission.mdx b/apps/docs/v2/core-concepts/commission.mdxindex 5d508f9de..257c26faf 100644--- a/apps/docs/v2/core-concepts/commission.mdx+++ b/apps/docs/v2/core-concepts/commission.mdx@@ -83,6 +83,53 @@ The `getCommissionLines` method calculates commissions for a given cart or orderAll commission calculations use `BigNumber` arithmetic for precision. This is critical for financial accuracy — standard floating-point math can introduce rounding errors.</Info>+## API examples++### Create a commission rate (Admin API)++```bash+curl -X POST http://localhost:9000/admin/commission-rates \+ -H "Authorization: Bearer <admin-token>" \+ -H "Content-Type: application/json" \+ -d '{+ "name": "Default Product Commission",+ "code": "default-product",+ "type": "percentage",+ "target": "item",+ "value": 15,+ "priority": 0+ }'+```++### Create a rate with rules (Admin API)++```bash+curl -X POST http://localhost:9000/admin/commission-rates \+ -H "Authorization: Bearer <admin-token>" \+ -H "Content-Type: application/json" \+ -d '{+ "name": "Electronics Commission",+ "code": "electronics",+ "type": "percentage",+ "target": "item",+ "value": 12,+ "priority": 10,+ "rules": [+ {+ "reference": "product_category",+ "reference_id": "pcat_electronics"+ }+ ]+ }'+```++### List commission rates++```bash+curl http://localhost:9000/admin/commission-rates \+ -H "Authorization: Bearer <admin-token>"+```+## Commission linesA **CommissionLine** is the calculated commission for a single line item or shipping method. It stores:diff --git a/apps/docs/v2/core-concepts/payout.mdx b/apps/docs/v2/core-concepts/payout.mdxindex bc67ab81d..0cb1e1912 100644--- a/apps/docs/v2/core-concepts/payout.mdx+++ b/apps/docs/v2/core-concepts/payout.mdx@@ -115,6 +115,59 @@ PayoutAccount└── Payout (one-to-many, per-order transfers)```+## Configuration example++```typescript+// medusa-config.ts+{+ resolve: "./modules/payout",+ options: {+ // How long payment authorizations are valid+ authorizationWindowMs: 7 * 24 * 60 * 60 * 1000, // 7 days++ // Time for seller to fulfill before capture+ sellerActionWindowMs: 72 * 60 * 60 * 1000, // 72 hours++ // Safety margin before authorization expiry+ captureSafetyBufferMs: 24 * 60 * 60 * 1000, // 24 hours++ // Minimum fulfillment status before capture+ requiredFulfillmentStatus: "fulfilled",+ },+}+```++## API examples++### Get seller's payout account (Vendor API)++```bash+curl http://localhost:9000/vendor/payout-accounts/<account-id> \+ -H "Authorization: Bearer <seller-token>"+```++### Create payout onboarding (Vendor API)++Initiates provider onboarding (e.g. Stripe Connect account setup). The `data` and `context` fields are passed to the payout provider:++```bash+curl -X POST http://localhost:9000/vendor/payout-accounts/<account-id>/onboarding \+ -H "Authorization: Bearer <seller-token>" \+ -H "Content-Type: application/json" \+ -d '{+ "context": {+ "return_url": "https://my-store.com/settings/payouts"+ }+ }'+```++### List payouts (Admin API)++```bash+curl http://localhost:9000/admin/payouts \+ -H "Authorization: Bearer <admin-token>"+```+## Provider abstractionThe payout module is **provider-agnostic**. A `PayoutProviderService` acts as a bridge to the external payment processor. It delegates all external operations — creating accounts, processing payouts, parsing webhooks — to a pluggable provider implementation.diff --git a/apps/docs/v2/core-concepts/seller.mdx b/apps/docs/v2/core-concepts/seller.mdxindex b6c9e60f8..871b543c3 100644--- a/apps/docs/v2/core-concepts/seller.mdx+++ b/apps/docs/v2/core-concepts/seller.mdx@@ -115,6 +115,64 @@ A seller is linked to many entities across the system:| Promotions | One-to-many | Seller-created promotions and discounts || Price Lists | One-to-many | Custom pricing rules |+## API examples++### Register a seller (Vendor API)++The seller registration endpoint allows unauthenticated users to create a new seller account. The seller starts in `PENDING_APPROVAL` status.++```bash+curl -X POST http://localhost:9000/vendor/sellers \+ -H "Content-Type: application/json" \+ -d '{+ "name": "Acme Electronics",+ "email": "[email protected]",+ "member_email": "[email protected]",+ "currency_code": "eur",+ "address": {+ "company": "Acme Electronics Ltd",+ "address_1": "123 Market Street",+ "city": "Berlin",+ "country_code": "de",+ "postal_code": "10115"+ }+ }'+```++### Create a seller (Admin API)++Admins can create sellers directly with a specified status and send a member invite:++```bash+curl -X POST http://localhost:9000/admin/sellers \+ -H "Authorization: Bearer <admin-token>" \+ -H "Content-Type: application/json" \+ -d '{+ "name": "Acme Electronics",+ "email": "[email protected]",+ "currency_code": "eur",+ "member": {+ "email": "[email protected]"+ }+ }'+```++### List sellers (Admin API)++```bash+curl http://localhost:9000/admin/sellers \+ -H "Authorization: Bearer <admin-token>"+```++### Approve a seller (Admin API)++Approves a seller in `PENDING_APPROVAL` status, changing it to `OPEN`:++```bash+curl -X POST http://localhost:9000/admin/sellers/slr_abc123/approve \+ -H "Authorization: Bearer <admin-token>"+```+## Extension pointsThe order completion workflow provides hooks for custom logic:diff --git a/apps/docs/v2/developer-guide/overview.mdx b/apps/docs/v2/developer-guide/overview.mdxindex b48eaffa2..286c7a6e9 100644--- a/apps/docs/v2/developer-guide/overview.mdx+++ b/apps/docs/v2/developer-guide/overview.mdx@@ -160,6 +160,45 @@ This means:The CLI (`@mercurjs/cli@latest`) manages this process: scaffolding projects, installing blocks, searching the registry, and comparing local changes against upstream versions.+## Workflow example++Here is a simplified example of how a Mercur workflow is structured. Workflows coordinate multi-step operations with automatic rollback on failure:++```typescript+import {+ createWorkflow,+ createStep,+ StepResponse,+ WorkflowResponse,+} from "@medusajs/framework/workflows-sdk"+import { MercurModules } from "@mercurjs/types"++const validateSellerStep = createStep(+ "validate-seller",+ async ({ seller_id }: { seller_id: string }, { container }) => {+ const sellerService = container.resolve(MercurModules.SELLER)+ const seller = await sellerService.retrieveSeller(seller_id)++ if (seller.status !== "open") {+ throw new Error("Seller is not active")+ }++ return new StepResponse(seller)+ }+)++const createProductForSellerWorkflow = createWorkflow(+ "create-product-for-seller",+ (input: { seller_id: string }) => {+ const seller = validateSellerStep({ seller_id: input.seller_id })++ // Additional steps: create product, link to seller, etc.++ return new WorkflowResponse({ seller })+ }+)+```+## Design principles**Modular over monolithic** — Each marketplace feature is a separate module that can be installed, modified, or replaced independently. You don't need to use all of Mercur to benefit from it.diff --git a/context7.json b/context7.jsonnew file mode 100644index 000000000..68fb245e5--- /dev/null+++ b/context7.json@@ -0,0 +1,21 @@+{+ "$schema": "https://context7.com/schema/context7.json",+ "projectTitle": "Mercur",+ "description": "Open-source AI-native marketplace framework built on MedusaJS v2. Provides blocks for seller management, commissions, payouts, order splitting, and vendor portals.",+ "folders": [+ "apps/docs/v2/"+ ],+ "excludeFolders": [+ "apps/docs/v2/changelog",+ "apps/docs/api-reference"+ ],+ "rules": [+ "Mercur extends MedusaJS v2 — do not confuse with Medusa v1 patterns.",+ "Use the block-based CLI (mercurjs add) to install features, not npm packages.",+ "Modules are resolved via MercurModules enum, not string service names.",+ "Seller statuses are: pending_approval, open, suspended, terminated."+ ],+ "url": "https://context7.com/mercurjs/mercur",+ "public_key": "pk_mIfToseksi2vDdrKBjkFu"++}diff --git a/packages/cli/package.json b/packages/cli/package.jsonindex 35cd33254..26cc6950a 100644--- a/packages/cli/package.json+++ b/packages/cli/package.json@@ -9,6 +9,16 @@"type": "module","description": "Mercur CLI","author": "MercurJS (https://github.com/mercurjs)",+ "keywords": [+ "marketplace",+ "multi-vendor",+ "medusajs",+ "ecommerce",+ "open-source-marketplace",+ "headless-commerce",+ "ai-ready",+ "marketplace-framework"+ ],"publishConfig": {"access": "public"},diff --git a/packages/client/package.json b/packages/client/package.jsonindex 4d8b7a128..3c9bff951 100644--- a/packages/client/package.json+++ b/packages/client/package.json@@ -9,6 +9,14 @@"type": "commonjs","author": "MercurJS (https://github.com/mercurjs)","license": "MIT",+ "keywords": [+ "marketplace",+ "multi-vendor",+ "medusajs",+ "ecommerce",+ "marketplace-client",+ "api-client"+ ],"publishConfig": {"access": "public"},diff --git a/packages/core-plugin/package.json b/packages/core-plugin/package.jsonindex 519dba7be..38603b5f4 100644--- a/packages/core-plugin/package.json+++ b/packages/core-plugin/package.json@@ -27,9 +27,14 @@"./*": "./.medusa/server/src/*.js"},"keywords": [- "medusa",- "plugin",- "medusa-plugin-other",+ "marketplace",+ "multi-vendor",+ "medusajs",+ "ecommerce",+ "open-source-marketplace",+ "headless-commerce",+ "ai-ready",+ "marketplace-framework","medusa-plugin","medusa-v2"],diff --git a/packages/types/package.json b/packages/types/package.jsonindex 42e63fa4a..f65e6a078 100644--- a/packages/types/package.json+++ b/packages/types/package.json@@ -6,6 +6,13 @@"url": "https://github.com/mercurjs/mercur","directory": "packages/types"},+ "keywords": [+ "marketplace",+ "multi-vendor",+ "medusajs",+ "ecommerce",+ "marketplace-types"+ ],"description": "Type definitions for Mercur","author": "Mercur","license": "MIT",diff --git a/templates/basic/AGENTS.md b/templates/basic/AGENTS.mdnew file mode 100644index 000000000..109250301--- /dev/null+++ b/templates/basic/AGENTS.md@@ -0,0 +1,84 @@+# Mercur Marketplace Project++**This is a Mercur marketplace project — an open-source AI-native multi-vendor marketplace built on MedusaJS v2.**++## Architecture++- **Foundation**: MedusaJS v2 (headless commerce)+- **Language**: TypeScript (strict)+- **Pattern**: Block-based — modules, workflows, API routes, and UI extensions installed via CLI++### Project Structure++```+├── packages/api/ # Backend API — modules, workflows, links, subscribers+├── apps/admin/ # Admin dashboard — operator panel+├── apps/vendor/ # Vendor portal — seller dashboard+└── blocks.json # Block configuration and registry aliases+```++## Documentation++- **Docs**: https://docs.mercurjs.com+- **MCP Server**: https://docs.mercurjs.com/mcp — connect your AI agent for documentation search+- **llms.txt**: https://docs.mercurjs.com/llms.txt — machine-readable project summary++## CLI Commands++```bash+# Add blocks from the Mercur registry+mercurjs add <block-name>++# Search available blocks+mercurjs search -q "commission"++# Generate TypeScript types from API routes+mercurjs codegen++# Start development server+bun run dev+```++## Block System++Mercur uses reusable blocks installed into your project:++- **Modules** — data models and business logic (sellers, commissions, offers)+- **Links** — relationships between modules+- **Workflows** — multi-step business processes (order splitting, payouts)+- **API Routes** — HTTP endpoints for admin, vendor, and storefront+- **Admin Extensions** — UI components for the admin dashboard+- **Vendor Extensions** — UI components for the vendor portal++Install blocks:++```bash+mercurjs add seller commission payout+```++## Skills++This project includes `.claude/skills/` with domain-specific patterns for:+- Admin and vendor UI (pages, forms, tabs)+- Block discovery and installation+- Code review and UI conformance++Skills are auto-loaded by Claude Code. See `CLAUDE.md` for the full workflow guide.++## Configuration Files++- `blocks.json` — block configuration and registry path aliases+- `packages/api/medusa-config.ts` — MedusaJS configuration+- `apps/admin/vite.config.ts` — admin dashboard build config+- `apps/vendor/vite.config.ts` — vendor portal build config++## Getting Started++```bash+bun run dev+```++This starts:+- Backend API at `http://localhost:9000`+- Admin Panel at `http://localhost:7000`+- Vendor Panel at `http://localhost:7001`diff --git a/templates/basic/CLAUDE.md b/templates/basic/CLAUDE.mdindex 00cc90ff7..ed0305886 100644--- a/templates/basic/CLAUDE.md+++ b/templates/basic/CLAUDE.md@@ -92,6 +92,14 @@ Typical checks:- If a task is about CLI choice, initialization, or registry commands, use `mercur-cli`.- If a task adds custom admin or vendor UI, load `medusa-ui-conformance` before inventing new components.+## AI Resources++- **Docs**: https://docs.mercurjs.com+- **MCP Server**: https://docs.mercurjs.com/mcp — connect your AI agent for documentation search+- **llms.txt**: https://docs.mercurjs.com/llms.txt — machine-readable project summary+- **Skills**: `.claude/skills/` — domain-specific patterns auto-loaded by Claude Code+- **AI Development Guide**: https://docs.mercurjs.com/v2/ai-development/mcp+## Lessons LearnedWhen you encounter a repeatable bug, a non-obvious gotcha, or learn something that would save time in future sessions, write it to `.claude/lessons.md`.