Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

Feat/ai discoverability (#835)

Jakub Sieradzki019017771be2
diff --git a/.claude/skills/migration-guide/SKILL.md b/.claude/skills/migration-guide/SKILL.md
index 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 → middlewares
5. Port dashboard code (if applicable)
6. Verify at each checkpoint
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 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.md
index 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 your
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 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.mdx
index 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.mdx
index 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 order
All 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 lines
A **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.mdx
index 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 abstraction
The 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.mdx
index 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 points
The 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.mdx
index 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.json
new file mode 100644
index 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.json
index 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.json
index 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.json
index 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.json
index 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.md
new file mode 100644
index 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.md
index 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 Learned
When 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`.