diff --git a/astro.sidebar.mjs b/astro.sidebar.mjs index f0128f469..51c008020 100644 --- a/astro.sidebar.mjs +++ b/astro.sidebar.mjs @@ -31,6 +31,7 @@ export function generateSidebar() { { label: 'Browser compatibility', link: '/get-started/browser-compatibility/' }, { label: 'Performance best practices', link: '/get-started/performance/' }, { label: 'Documentation bundles for AI tools', link: '/get-started/build-with-ai/' }, + { label: 'Dropins MCP', link: '/get-started/dropins-mcp/' }, ], }, { @@ -197,6 +198,7 @@ export function generateSidebar() { // ---------- REFERENCE ---------- { label: 'Reference', link: '/reference/', attrs: { class: 'sidebar-section-label large' } }, + { label: 'Dropins MCP', link: '/reference/dropins-mcp/' }, // ---------- B2C DROP-INS ---------- { diff --git a/src/content/docs/get-started/dropins-mcp.mdx b/src/content/docs/get-started/dropins-mcp.mdx new file mode 100644 index 000000000..c5e0c8e27 --- /dev/null +++ b/src/content/docs/get-started/dropins-mcp.mdx @@ -0,0 +1,133 @@ +--- +title: Dropins MCP +description: Install and configure the Dropins MCP server to give your AI editor live knowledge of Adobe Commerce drop-in APIs, slots, events, and design tokens. +--- + +import Link from '@components/Link.astro'; +import TableWrapper from '@components/TableWrapper.astro'; +import { Tabs, TabItem, Steps, Aside } from '@astrojs/starlight/components'; + +The Dropins MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI editors and agents live, accurate knowledge of Adobe Commerce drop-in components. Instead of relying on training data that may not reflect the latest APIs, the MCP queries a registry generated directly from drop-in source code so slots, events, containers, and API functions are always current. + +Once configured, your AI editor can answer questions like _"What slots does CartSummaryList have?"_, scaffold a new block with the right imports, check whether your project references any renamed or removed APIs, and generate working event handler and slot code without guessing. + +## Prerequisites + +- Node.js 18 or later (`node -v` to confirm) +- An AI editor that supports MCP servers: [Cursor](https://cursor.sh), [VS Code with GitHub Copilot](https://code.visualstudio.com), or [Claude Desktop](https://claude.ai/download) + +## Installation + + + +1. **Add the server to your editor configuration.** Choose your editor below and paste the snippet into the correct config file. + + + + Add to `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` inside a specific project: + + ```json + { + "mcpServers": { + "dropins": { + "command": "npx", + "args": ["@dropins/mcp"] + } + } + } + ``` + + + Add to `.vscode/mcp.json` inside your project: + + ```json + { + "servers": { + "dropins": { + "type": "stdio", + "command": "npx", + "args": ["@dropins/mcp"] + } + } + } + ``` + + + Add to `claude_desktop_config.json`: + + ```json + { + "mcpServers": { + "dropins": { + "command": "dropins-mcp" + } + } + } + ``` + + Claude Desktop spawns processes without the shell's PATH, so `npx` may not resolve. Using the installed binary directly (`dropins-mcp`) is more reliable. First install the package globally: + + ```bash + npm install -g @dropins/mcp + ``` + + If you use `nvm`, replace `dropins-mcp` with the full path to the binary: + + ``` + ~/.nvm/versions/node//bin/dropins-mcp + ``` + + + +2. **Restart your editor.** The Dropins MCP appears in the tool list with 20 tools available. + +3. **Verify the connection.** Ask your AI assistant: + + > _"Use the dropins MCP — what slots does the CartSummaryList container have?"_ + + If it returns a list of slot names with context types, the MCP is connected and working. + + If the server does not appear, open your editor's MCP logs and confirm that `npx @dropins/mcp` runs without errors in a terminal outside the editor. + + + +## Optional: enable AI-powered documentation search + +The `search_commerce_docs` tool provides semantic search across the full Adobe Commerce documentation using the Adobe I/O CLI. Without it, the MCP still works fully local documentation snapshots are always available through `search_docs`. + +To enable it: + +```bash +npm install -g @adobe/aio-cli +aio auth login +``` + +## What you can ask + +The MCP works best with concrete, task-oriented prompts. A few examples: + +- _"What events does the checkout dropin emit when a payment method is selected?"_ +- _"Scaffold a block that combines CartSummaryList and OrderConfirmation"_ +- _"Are there any stale containers or removed APIs in my commerce-cart block?"_ +- _"What GraphQL mutation does checkout use to place an order?"_ +- _"Generate a slot implementation that adds a loyalty points badge next to the cart line item price"_ +- _"Am I using the latest drop-in versions?"_ +- _"What CSS design tokens control button colors?"_ + + + +## Drop-in coverage + +The MCP covers the full drop-in suite and SDK packages. + +**B2C drop-ins:** Cart, Checkout, Order, User Auth, User Account, Product Details, Product Discovery, Wishlist, Recommendations, Payment Services, Personalization. + +**B2B drop-ins:** Quote Management, Requisition List, Company Management, Company Switcher, Purchase Order, Quick Order. + +**SDK packages:** Elsie UI components, Event Bus, Fetch GraphQL, Build Tools, reCAPTCHA, Storefront Design tokens. + +For the full tools reference all 20 tools with parameters and usage examples see [Dropins MCP reference](/reference/dropins-mcp/). + +For troubleshooting connection and configuration issues, see [FAQ](/troubleshooting/faq/#dropins-mcp). diff --git a/src/content/docs/reference/dropins-mcp/index.mdx b/src/content/docs/reference/dropins-mcp/index.mdx new file mode 100644 index 000000000..ffb559083 --- /dev/null +++ b/src/content/docs/reference/dropins-mcp/index.mdx @@ -0,0 +1,383 @@ +--- +title: Dropins MCP reference +description: All 20 tools available in the Dropins MCP server, grouped by category, with parameters and usage examples. +tableOfContents: + maxHeadingLevel: 3 +--- + +import TableWrapper from '@components/TableWrapper.astro'; +import { Aside } from '@astrojs/starlight/components'; + +The Dropins MCP exposes 20 tools across four categories. Each tool reads from a registry generated from drop-in source code, so results always reflect the current API surface not training data. + +For installation and editor configuration, see [Dropins MCP](/get-started/dropins-mcp/). + +--- + +## Discovery tools + +These tools answer questions about what exists in the drop-in ecosystem: containers, slots, events, API functions, GraphQL operations, design tokens, i18n keys, and data models. + +### `analyze_project` + +Scans a merchant project and reports which drop-ins are installed, which blocks are present, and the current configuration state. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `projectDir` | string | Yes | Absolute path to the merchant storefront project root | + + + +**Example:** _"Use the dropins MCP to analyze my project at /Users/me/my-storefront"_ + +--- + +### `list_containers` + +Lists available containers for one or all drop-ins, including their props and slot names. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `dropin` | string | No | Drop-in name (for example, `storefront-cart`). Omit to list all. | + + + +**Example:** _"What containers does the checkout drop-in expose?"_ + +--- + +### `list_slots` + +Lists slots for drop-in containers, including context types and available methods. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `dropin` | string | No | Drop-in name (for example, `storefront-cart`). Omit to list all. | +| `container` | string | No | Container name (for example, `CartSummaryList`). Requires `dropin`. | + + + +**Example:** _"What slots does the MiniCart container have?"_ + +--- + +### `list_events` + +Lists event bus events with emitters, consumers, and payload types, optionally filtered by drop-in and direction. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `dropin` | string | No | Drop-in name (for example, `storefront-cart`) | +| `direction` | `emitted` \| `consumed` \| `all` | No | Filter by direction. Default: `all` | + + + +**Example:** _"What events does the cart drop-in emit?"_ + +--- + +### `list_api_functions` + +Lists public API functions for one or all drop-ins, including their signatures and parameters. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `dropin` | string | No | Drop-in name (for example, `storefront-cart`). Omit to list all. | + + + +**Example:** _"What API functions does the account drop-in expose?"_ + +--- + +### `list_graphql_queries` + +Lists GraphQL queries, mutations, and extensible fragments for drop-ins. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `dropin` | string | No | Drop-in name (for example, `storefront-cart`). Omit to list all. | +| `type` | `query` \| `mutation` | No | Filter by operation type | +| `name` | string | No | Case-insensitive substring search on operation or fragment name | + + + +**Example:** _"What GraphQL mutation does checkout use to place an order?"_ + +--- + +### `list_design_tokens` + +Lists CSS custom properties (design tokens) by category. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `category` | string | No | Token category: `colors`, `typography`, `spacing`, `shapes`, `grid`. Omit to list all. | + + + +**Example:** _"What CSS tokens control button colors?"_ + +--- + +### `list_i18n_keys` + +Lists i18n dictionary keys and their default English values, filterable by drop-in, container, or substring. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `dropin` | string | No | Drop-in name (for example, `storefront-checkout`). Omit to search all. | +| `query` | string | No | Substring filter applied to key paths and values. Case-insensitive. | +| `containerName` | string | No | Filter to keys used by a specific container (for example, `MiniCart`). | + + + +**Example:** _"What are all the i18n keys for the CartSummaryList container?"_ + +--- + +### `list_models` + +Lists model definitions (interfaces and type aliases) from drop-in source files. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `dropin` | string | No | Drop-in name (for example, `storefront-cart`) | +| `model` | string | No | Specific model name (for example, `CartModel`, `Price`). Returns the full definition. | + + + +**Example:** _"What is the CartModel type definition?"_ + +--- + +## Code generation tools + +These tools generate working boilerplate for blocks, extensions, slots, and event handlers based on your request. + +### `scaffold_block` + +Generates an AEM block with drop-in container imports, layout, and slot stubs. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `projectDir` | string | Yes | Absolute path to the merchant storefront project root | +| `blockName` | string | Yes | Block name (for example, `commerce-custom-cart`). Used as folder and file name. | +| `dropin` | string | No | Primary drop-in for single-dropin mode. Requires `containers`. | +| `containers` | string[] | No | Container names for single-dropin mode. Requires `dropin`. | +| `containersByDropin` | object | No | Multi-dropin mode: map of drop-in name to container names | +| `slots` | object | No | Slots per container to include as stubs | +| `withEvents` | boolean | No | Include event bus wiring boilerplate. Default: `false`. | + + + +**Example:** _"Scaffold a block that uses CartSummaryList and MiniCart from the cart drop-in"_ + +--- + +### `scaffold_extension` + +Generates a checkout extension with selected hooks, an extension manager, and an index file. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `projectDir` | string | Yes | Absolute path to the merchant storefront project root | +| `extensionName` | string | Yes | Human-readable name (for example, `Stripe Payment`) | +| `extensionId` | string | Yes | Unique ID used as folder name and `id` field (for example, `stripe-payment`) | +| `hooks` | string[] | Yes | Hook names to implement (for example, `["checkout/payment-methods"]`) | +| `externalScripts` | string[] | No | External script URLs to load | +| `externalStyles` | string[] | No | External stylesheet URLs to load | + + + +**Example:** _"Create a checkout extension for a custom payment method called Stripe"_ + +--- + +### `scaffold_slot` + +Generates production-ready slot implementation boilerplate for a specific container slot. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `projectDir` | string | Yes | Absolute path to the merchant storefront project root | +| `containerName` | string | Yes | Container name (for example, `MiniCart`) | +| `slotName` | string | Yes | Slot name to scaffold (for example, `Thumbnail`) | +| `dropin` | string | No | Drop-in package name. Provide to resolve ambiguity when the same container name exists in multiple drop-ins. | + + + +**Example:** _"Generate a slot implementation for the Thumbnail slot in CartSummaryList"_ + +--- + +### `suggest_slot_implementation` + +Suggests slot implementation code for a UI customization request on an existing block. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `projectDir` | string | Yes | Absolute path to the merchant storefront project root | +| `request` | string | Yes | What you want to achieve (for example, `"Add a loyalty points badge next to the price in cart"`) | +| `blockName` | string | Yes | Block name (for example, `commerce-cart`) | + + + +**Example:** _"Add a custom banner above the place order button in my commerce-checkout block"_ + +--- + +### `suggest_event_handler` + +Suggests event handler code for cross-drop-in interactions based on a natural-language request. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `projectDir` | string | Yes | Absolute path to the merchant storefront project root | +| `request` | string | Yes | What you want to achieve (for example, `"Show a popup when an order is placed"`) | + + + +**Example:** _"When the cart emits an item removed event, update a custom loyalty points counter"_ + +--- + +### `explain_event_flow` + +Traces the full lifecycle of an event: who emits it, who consumes it, the payload type, and ready-to-use code for both sides. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `eventName` | string | Yes | Exact or partial event name (for example, `cart/data`). Prefix matching is supported. | +| `dropin` | string | No | Filter results to events involving a specific drop-in | + + + +**Example:** _"Explain the full lifecycle of the cart/data event"_ + +--- + +## Health and upgrade tools + +These tools inspect your project against the registry and report issues, available upgrades, and migration notes. + +### `check_block_health` + +Validates drop-in usage in one or all blocks against the registry. Detects invalid containers, unknown props, missing slots, renamed events, and removed API functions. Supports a fixer mode that includes a concrete fix suggestion for each finding. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `projectDir` | string | Yes | Absolute path to the merchant project root | +| `block` | string | No | Block directory name (for example, `commerce-cart`). Omit to scan all blocks. | +| `fix` | boolean | No | When `true`, each finding includes a concrete fix suggestion | + + + +**Example:** _"Check the health of my commerce-checkout block and suggest fixes for any issues"_ + +--- + +### `check_config` + +Validates a merchant project's configuration files: `config.json`, `package.json`, dropin integrity, and initializers. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `projectDir` | string | Yes | Absolute path to the merchant storefront project root | + + + +**Example:** _"Check the configuration of my storefront project"_ + +--- + +### `get_upgrade_diff` + +Compares installed drop-in versions against the registry and reports available upgrades, unused containers, and migration notes. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `projectDir` | string | Yes | Absolute path to the merchant storefront project root | + + + +**Example:** _"Am I using the latest drop-in versions? What do I need to update?"_ + +--- + +## Documentation tools + +These tools search across documentation, SDK references, working code examples, and GraphQL schemas. + +### `search_docs` + +Searches local documentation snapshots, SDK references, and working code examples. Always available no external authentication required. + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `query` | string | Yes | Search query (for example, `"CORS setup"`, `"cart slots"`) | +| `section` | string | No | Limit search to a specific documentation section (for example, `"setup"`, `"dropins/cart"`) | +| `maxResults` | number | No | Maximum results to return. Default: 10. | +| `includeContent` | boolean | No | Include full page content. Default: `false` (returns snippets). | + + + +**Example:** _"Search the docs for multi-step checkout setup"_ + +--- + +### `search_commerce_docs` + +AI-powered semantic search across the full Adobe Commerce documentation. Requires the Adobe I/O CLI (`aio auth login`). + + + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `query` | string | Yes | Natural-language search query | + + + + + +**Example:** _"How do I configure reCAPTCHA for the checkout drop-in?"_ diff --git a/src/content/docs/troubleshooting/faq.mdx b/src/content/docs/troubleshooting/faq.mdx index 1e88bd1e7..a0d4a4828 100644 --- a/src/content/docs/troubleshooting/faq.mdx +++ b/src/content/docs/troubleshooting/faq.mdx @@ -207,6 +207,57 @@ Product detail pages (PDPs) may return a 404 when the requested URL cannot be re ![productView JSON excerpt with an uppercase SKU](@images/troubleshoot/product-view-uppercase-sku.png) +## Dropins MCP + +### The MCP does not appear in my editor after installation + +Restart your editor after adding the MCP config snippet. The editor spawns the MCP process on startup, so changes to `mcp.json` or `.vscode/mcp.json` do not take effect in a running session. + +If the MCP still does not appear, confirm the `@dropins/mcp` package is installed and that `npx @dropins/mcp` runs without errors in your terminal. If you installed it with `npm install -g`, verify that the global `node_modules/.bin` is in your `PATH`. + +### A tool returns no results or says the registry is missing + +The MCP ships with a pre-built knowledge base. No drop-in repositories need to be cloned. If a tool returns no results, check that the package installed correctly by running `npx @dropins/mcp` and looking for a startup message. Reinstalling with `npm install -g @dropins/mcp` resolves most corrupted install issues. + +### `check_block_health` or `analyze_project` cannot find my project + +These tools require `projectDir` to be an absolute path to the project root (the folder that contains `package.json` and the `blocks/` directory). Relative paths are not supported. Use `pwd` in your terminal to get the correct absolute path. + +### The MCP connects but times out on first use + +The first time `npx @dropins/mcp` runs, it downloads the package from npm, which can take several seconds. Some editors have a short MCP startup timeout and will report a connection failure before the download completes. + +To avoid this, install the package globally before configuring your editor: + +```bash +npm install -g @dropins/mcp +``` + +Then update your config to use the installed binary instead of `npx`: + +```json +{ + "mcpServers": { + "dropins": { + "command": "dropins-mcp" + } + } +} +``` + +After the first `npx` run, the package is cached locally and subsequent startups are fast. + +### `search_commerce_docs` is not available + +This tool requires the Adobe I/O CLI authenticated with an Adobe ID. Install it and log in: + +```bash +npm install -g @adobe/aio-cli +aio auth login +``` + +Without it, `search_docs` provides local documentation coverage and is always available. + ## I can't preview, publish, or make content changes This is often a permissions issue. You are either missing or have insufficient site permissions on AEM Live. For site permissions, open **User Admin** on .