@dropins/mcp 0.1.0

package/dist/resources/guides.js

@@ -0,0 +1,625 @@
+export const guides = [
+    {
+        uri: "storefront://guides/getting-started",
+        name: "Getting Started with Adobe Commerce Storefront",
+        description: "Overview of the storefront architecture, dropins, AEM blocks, and how to set up a merchant project",
+        content: `# Getting Started with Adobe Commerce Storefront
+
+## Architecture Overview
+
+The Adobe Commerce Storefront is built on a modular architecture with these core concepts:
+
+### Dropins
+Dropins are self-contained UI modules that provide functionality for specific commerce pages:
+- **storefront-cart** — Shopping cart display and management
+- **storefront-checkout** — Multi-step or single-step checkout flow
+- **storefront-order** — Order confirmation and history
+- **storefront-pdp** — Product detail pages
+- **storefront-product-discovery** — Search results and filtering
+- **storefront-auth** — Authentication and login
+- **storefront-account** — Customer account management
+- **storefront-requisition-list** — B2B requisition lists
+- **storefront-quote-management** — B2B quote workflows
+
+Each dropin exposes:
+- **Containers** — Top-level components you render in AEM blocks
+- **Slots** — Customization points within containers for injecting/replacing UI
+- **API functions** — Programmatic access to commerce data
+- **Events** — Cross-dropin communication via event bus
+
+### AEM Blocks
+AEM blocks are the integration layer between the storefront page and dropins.
+Each block typically:
+1. Imports dropin modules (render, containers, API)
+2. Initializes the dropin via the initializer pattern
+3. Renders containers into the block's DOM
+4. Configures slots, events, and extensions
+
+### Project Structure
+A merchant storefront project typically contains:
+\`\`\`
+├── blocks/                  # AEM blocks (one folder per block)
+│   ├── commerce-cart/       # Cart page block
+│   ├── commerce-checkout/   # Checkout page block
+│   └── ...
+├── scripts/
+│   └── commerce.js          # Dropin initializer and config loader
+├── config.json              # Storefront configuration
+└── styles/                  # Global and dropin-specific CSS
+\`\`\`
+
+## Key Concepts
+
+### Initializer Pattern
+Every dropin is initialized through a standard pattern:
+\`\`\`javascript
+import { initializer } from '@dropins/storefront-cart/render.js';
+
+await initializer.register({
+  // configuration
+});
+\`\`\`
+
+### Slots Pattern
+Slots allow merchants to customize specific areas of a container:
+\`\`\`javascript
+render(CartSummaryList, {
+  routeProduct: (item) => \`/products/\${item.url.urlKey}\`,
+  slots: {
+    Thumbnail: (ctx) => {
+      const { item, appendChild } = ctx;
+      // Custom thumbnail rendering
+    }
+  }
+})(document.getElementById('cart'));
+\`\`\`
+
+### Event Bus
+Dropins communicate through a shared event bus:
+\`\`\`javascript
+import { events } from '@dropins/tools/event-bus.js';
+
+events.on('cart/data', (cartData) => {
+  // React to cart changes
+});
+\`\`\`
+`,
+    },
+    {
+        uri: "storefront://guides/slots",
+        name: "Customizing UI with Slots",
+        description: "Complete guide to using slots for dropin UI customization including context methods and patterns",
+        content: `# Customizing UI with Slots
+
+## What Are Slots?
+
+Slots are named extension points inside dropin containers. They allow merchants to:
+- **Append** new content alongside existing UI
+- **Replace** the entire slot content
+- **Modify** HTML within the slot
+- **Add** agreements or custom elements
+
+## Slot Context
+
+Every slot callback receives a context object with:
+
+### Default Methods (available on all slots)
+- \`appendChild(element)\` — Add a child element to the slot
+- \`prependChild(element)\` — Add a child before existing content
+- \`replaceWith(element)\` — Replace the slot's entire content
+- \`removeChild(element)\` — Remove a child element
+- \`appendAgreement(config)\` — Add a checkbox agreement
+- \`replaceHTML(htmlString)\` — Replace inner HTML directly
+
+### Custom Context Properties
+Some slots provide additional context specific to their purpose:
+- Cart slots may include \`item\`, \`cart\`, \`prices\`
+- Checkout slots may include \`shippingAddress\`, \`billingAddress\`
+- Order slots may include \`order\`, \`orderData\`
+
+## Usage Patterns
+
+### Appending Content
+\`\`\`javascript
+slots: {
+  ProductDetails: (ctx) => {
+    const badge = document.createElement('span');
+    badge.textContent = 'New!';
+    badge.className = 'custom-badge';
+    ctx.appendChild(badge);
+  }
+}
+\`\`\`
+
+### Replacing Content
+\`\`\`javascript
+slots: {
+  Thumbnail: (ctx) => {
+    const img = document.createElement('img');
+    img.src = ctx.item?.thumbnail?.url;
+    img.alt = ctx.item?.thumbnail?.label;
+    ctx.replaceWith(img);
+  }
+}
+\`\`\`
+
+### Adding Agreements (Checkout)
+\`\`\`javascript
+slots: {
+  PlaceOrder: (ctx) => {
+    ctx.appendAgreement({
+      text: 'I accept the terms and conditions',
+      required: true,
+    });
+  }
+}
+\`\`\`
+
+### Dynamic Slots
+Some containers have dynamic slots with index-based names:
+- \`ProductListItem_{index}\` — Per-item slots in lists
+- \`Step_{index}\` — Per-step slots in checkout
+
+## Finding Available Slots
+
+Use the MCP tools to discover slots:
+1. \`list_slots\` — Browse all slots by dropin and container
+2. \`list_containers\` — See which containers have which slot names
+3. Each slot includes its context type, custom methods, and examples
+`,
+    },
+    {
+        uri: "storefront://guides/extensions",
+        name: "Checkout Extensions",
+        description: "Guide to building checkout extensions for payment methods, validation, and order placement",
+        content: `# Checkout Extensions
+
+## What Are Extensions?
+
+Extensions are a hook-based system exclusive to the checkout dropin. They let merchants:
+- Add custom payment methods
+- Validate checkout steps
+- Intercept order placement
+- Customize address forms
+- Handle payment responses
+
+## Extension Interface
+
+\`\`\`typescript
+interface Extension {
+  name: string;                        // Unique extension name
+  callbacks: {
+    'checkout/payment-response'?: (ctx) => Promise<PaymentResponse>;
+    'checkout/payment-methods'?: (ctx) => Promise<PaymentMethodConfig[]>;
+    'checkout/validate'?: (ctx) => Promise<boolean>;
+    'checkout/place-order'?: (ctx) => Promise<PlaceOrderResult>;
+    'checkout/address-form-render'?: (ctx) => void;
+  };
+}
+\`\`\`
+
+## Available Hooks
+
+### checkout/payment-methods
+Register custom payment methods in the checkout UI.
+- **When fired:** During payment method rendering
+- **Context:** \`{ paymentMethods, cart }\`
+- **Returns:** Array of payment method configurations
+
+### checkout/validate
+Add custom validation logic before order placement.
+- **When fired:** When the user clicks "Place Order"
+- **Context:** \`{ cart, shippingAddress, billingAddress, paymentMethod }\`
+- **Returns:** \`true\` to continue, \`false\` to block
+
+### checkout/place-order
+Customize or intercept the order placement process.
+- **When fired:** After validation passes
+- **Context:** \`{ cart, paymentMethod, shippingAddress, billingAddress }\`
+- **Returns:** Order placement result
+
+### checkout/payment-response
+Handle payment gateway responses.
+- **When fired:** After payment processing
+- **Context:** \`{ response, paymentMethod, orderId }\`
+- **Returns:** Processed payment response
+
+### checkout/address-form-render
+Customize the address form rendering (add fields, modify layout).
+- **When fired:** When address form mounts
+- **Context:** \`{ form, type ('shipping' | 'billing') }\`
+
+## Registering Extensions
+
+\`\`\`javascript
+import { initializer } from '@dropins/storefront-checkout/render.js';
+
+const myPaymentExtension = {
+  name: 'my-custom-payment',
+  callbacks: {
+    'checkout/payment-methods': async (ctx) => {
+      return [{
+        code: 'my_payment',
+        title: 'My Custom Payment',
+        icon: '/icons/payment.svg',
+      }];
+    },
+    'checkout/validate': async (ctx) => {
+      // Custom validation logic
+      return true;
+    },
+  },
+};
+
+initializer.register({
+  extensions: [myPaymentExtension],
+});
+\`\`\`
+
+## Existing Extension Examples
+
+The storefront-checkout repository includes reference extensions for:
+- Braintree payments (Credit Card, Apple Pay, Google Pay)
+- PayPal
+- Purchase Orders
+- Offline payment methods (Check/Money Order, Bank Transfer)
+- Free method
+`,
+    },
+    {
+        uri: "storefront://guides/events",
+        name: "Cross-Dropin Communication with Events",
+        description: "Guide to using the event bus for communication between dropins",
+        content: `# Cross-Dropin Communication with Events
+
+## Event Bus Overview
+
+The event bus (\`@dropins/tools/event-bus.js\`) enables decoupled communication between dropins. Any dropin can emit events and any other dropin (or custom code) can listen.
+
+## Core API
+
+\`\`\`javascript
+import { events } from '@dropins/tools/event-bus.js';
+
+// Listen for an event
+events.on('cart/data', (payload) => {
+  console.log('Cart updated:', payload);
+});
+
+// Emit an event
+events.emit('authenticated', { isAuthenticated: true });
+\`\`\`
+
+## Common Event Patterns
+
+### Cart Events
+- \`cart/data\` — Cart data changed (items, totals, etc.)
+- \`cart/updated\` — Cart was updated (add/remove/quantity change)
+- \`cart/merged\` — Guest cart merged with customer cart
+
+### Checkout Events
+- \`checkout/data\` — Full checkout data updated
+- \`checkout/order\` — Order placed successfully
+- \`checkout/shipping\` — Shipping method selected
+- \`checkout/address\` — Address updated
+
+### Authentication Events
+- \`authenticated\` — User authentication state changed
+
+### PDP Events
+- \`pdp/data\` — Product data loaded
+- \`addToCart\` — Product added to cart
+
+### Order Events
+- \`order/data\` — Order data loaded
+
+## Wiring Pattern
+
+A typical AEM block wires events to connect dropins:
+
+\`\`\`javascript
+// In commerce-cart block
+import { events } from '@dropins/tools/event-bus.js';
+
+events.on('addToCart', () => {
+  // Refresh mini-cart when product added
+  refreshMiniCart();
+});
+
+events.on('authenticated', ({ isAuthenticated }) => {
+  if (isAuthenticated) {
+    // Merge guest cart
+    mergeCarts();
+  }
+});
+\`\`\`
+
+## Event Payload Types
+
+Each event has a defined payload type. Use the \`list_events\` tool to see:
+- Full payload type definitions
+- Which dropins emit each event
+- Which dropins consume each event
+- Usage context and examples
+`,
+    },
+    {
+        uri: "storefront://guides/design-tokens",
+        name: "Theming with Design Tokens",
+        description: "Guide to customizing storefront visuals using CSS custom properties and design tokens",
+        content: `# Theming with Design Tokens
+
+## Overview
+
+The storefront uses CSS custom properties (design tokens) scoped under \`.dropin-design\` for consistent theming. Merchants override these tokens in their project CSS to customize the look and feel.
+
+## Token Categories
+
+### Colors
+Control the color palette:
+- \`--color-brand\` — Primary brand color
+- \`--color-neutral-*\` — Grayscale palette (50 through 900)
+- \`--color-positive-*\` — Success states
+- \`--color-warning-*\` — Warning states
+- \`--color-negative-*\` — Error states
+- \`--color-alert-*\` — Alert/info states
+
+### Typography
+Control font properties:
+- \`--type-body-*-size\` — Body text sizes (1 through 3)
+- \`--type-headline-*-size\` — Headline sizes (1 through 3)
+- \`--type-display-*-size\` — Display/hero sizes
+- \`--type-body-font-family\` — Body font family
+- \`--type-headline-font-family\` — Heading font family
+
+### Spacing
+Control layout spacing:
+- \`--spacing-xxsmall\` through \`--spacing-xxlarge\`
+- \`--spacing-small\` = 8px (default)
+- \`--spacing-medium\` = 16px (default)
+- \`--spacing-large\` = 24px (default)
+
+### Shapes
+Control borders and radius:
+- \`--shape-border-radius-*\` — Border radius (1 through 4)
+- \`--shape-border-width-*\` — Border widths
+- \`--shape-icon-stroke-width\` — Icon stroke width
+
+### Grid
+Control layout grid:
+- \`--grid-1-columns\` through \`--grid-5-columns\`
+- \`--grid-*-margin\` — Grid margins
+- \`--grid-*-gutter\` — Grid gutters
+
+## Applying Overrides
+
+Create a CSS file in your project:
+
+\`\`\`css
+/* styles/dropin-overrides.css */
+.dropin-design {
+  --color-brand: #e03e2d;
+  --type-body-font-family: 'Inter', sans-serif;
+  --type-headline-font-family: 'Playfair Display', serif;
+  --spacing-medium: 20px;
+  --shape-border-radius-1: 8px;
+}
+\`\`\`
+
+## Best Practices
+
+1. **Override at the root level** — Set tokens on \`.dropin-design\` not on individual components
+2. **Use the token hierarchy** — Tokens cascade; override high-level tokens first
+3. **Test across dropins** — Token changes affect ALL dropins consistently
+4. **Respect semantic meaning** — \`--color-positive\` should always indicate success
+5. **Use \`list_design_tokens\` tool** — See all available tokens with default values
+`,
+    },
+    {
+        uri: "storefront://guides/block-patterns",
+        name: "AEM Block Patterns",
+        description: "Guide to creating AEM blocks that render dropin containers with various patterns",
+        content: `# AEM Block Patterns
+
+## Block Lifecycle
+
+Every AEM block follows this lifecycle:
+1. **Decorate** — The \`decorate(block)\` function is called with the block DOM element
+2. **Initialize** — Import and register the dropin initializer
+3. **Render** — Render dropin containers into the block
+4. **Configure** — Set up slots, events, and extensions
+
+## Basic Block Structure
+
+\`\`\`javascript
+import { initializer } from '@dropins/storefront-cart/render.js';
+import * as Cart from '@dropins/storefront-cart/containers/CartSummaryList.js';
+
+export default async function decorate(block) {
+  // Initialize the dropin
+  await initializer.register({
+    // dropin config
+  });
+
+  // Render a container
+  return Cart.render(Cart.CartSummaryList, {
+    routeProduct: (item) => \\\`/products/\\\${item.url.urlKey}\\\`,
+    slots: {
+      // slot customizations
+    },
+  })(block);
+}
+\`\`\`
+
+## Common Patterns
+
+### Single Container
+The simplest pattern — one block, one container.
+
+### Multi-Container
+Render multiple containers in a single block with layout:
+\`\`\`javascript
+const left = document.createElement('div');
+const right = document.createElement('div');
+block.append(left, right);
+
+Cart.render(CartSummaryList, { ... })(left);
+Cart.render(OrderSummary, { ... })(right);
+\`\`\`
+
+### With Events
+Wire cross-dropin communication:
+\`\`\`javascript
+import { events } from '@dropins/tools/event-bus.js';
+
+events.on('cart/updated', () => {
+  // Refresh related UI
+});
+\`\`\`
+
+### With Extensions (Checkout)
+Register checkout extensions:
+\`\`\`javascript
+initializer.register({
+  extensions: [myPaymentExtension, myValidationExtension],
+});
+\`\`\`
+
+### With Config
+Read from storefront configuration:
+\`\`\`javascript
+const config = readBlockConfig(block);
+// Use config values for conditional rendering
+\`\`\`
+
+## Block Discovery
+
+Use the \`scaffold_block\` tool (Phase 4) to generate blocks from templates.
+Use the \`list_containers\` tool to see which containers to render in your block.
+`,
+    },
+    {
+        uri: "storefront://guides/graphql-overrides",
+        name: "Extending GraphQL Queries",
+        description: "Guide to overriding and extending default GraphQL queries in dropins using overrideGQLOperations from build-tools",
+        content: `# Extending GraphQL Queries
+
+## Overview
+
+Each dropin uses pre-defined GraphQL queries, mutations, and fragments. Merchants can extend these at build time using \`overrideGQLOperations\` from \`@dropins/build-tools\`, or explore them with the \`list_graphql_queries\` tool.
+
+Use cases:
+- Add custom attributes to product, cart, or checkout data
+- Include additional fields in order responses
+- Remove unused fragments to reduce payload size
+- Support B2B-specific or custom module fields
+
+## Discovering Available Queries
+
+Use the \`list_graphql_queries\` tool to see what each dropin fetches:
+- \`list_graphql_queries({ dropin: "storefront-checkout" })\` — full resolved source with fragments
+- \`list_graphql_queries({ type: "mutation" })\` — all mutations across dropins
+- \`list_graphql_queries({ name: "getCart" })\` — search by operation name
+
+Each operation includes the complete GraphQL source with all fragments resolved, so you can see exactly which fields are queried.
+
+## Override Method: overrideGQLOperations (Recommended)
+
+The official way to extend GraphQL is via \`overrideGQLOperations\` in your project's \`build.mjs\`:
+
+\`\`\`javascript
+// build.mjs (project root)
+import { overrideGQLOperations } from '@dropins/build-tools/gql-extend.js';
+
+overrideGQLOperations([
+  // Example 1: Add a custom field to the cart fragment
+  {
+    npm: '@dropins/storefront-cart',
+    operations: [
+      \\\`fragment CART_FRAGMENT on Cart {
+        gift_message {
+          from
+          to
+          message
+        }
+        my_custom_field
+      }\\\`,
+    ],
+  },
+
+  // Example 2: Remove an unused fragment to reduce payload
+  {
+    npm: '@dropins/storefront-cart',
+    skipFragments: ['DOWNLOADABLE_CART_ITEMS_FRAGMENT'],
+    operations: [],
+  },
+
+  // Example 3: Extend checkout data
+  {
+    npm: '@dropins/storefront-checkout',
+    operations: [
+      \\\`fragment CHECKOUT_DATA_FRAGMENT on Cart {
+        delivery_estimate
+        loyalty_points_earned
+      }\\\`,
+    ],
+  },
+]);
+\`\`\`
+
+## How It Works
+
+1. Each dropin publishes a \`fragments.js\` file containing all its GraphQL fragments
+2. \`overrideGQLOperations\` modifies these fragment files in \`node_modules\` at build time
+3. **operations**: Fragment strings that get merged into existing fragments (adds fields, does not replace)
+4. **skipFragments**: Fragment names to completely remove from the dropin's queries
+
+The merge is additive — your fragment fields are added to the existing fragment. You do NOT need to provide the full fragment, only the new fields.
+
+## Important Notes
+
+1. **Additive merge** — \`operations\` adds fields to existing fragments, it does not replace them
+2. **Match fragment names** — Use the exact fragment name from the dropin (check with \`list_graphql_queries\`)
+3. **Match type condition** — Your fragment must use the same GraphQL type (e.g., \`on Cart\`, \`on CartAddress\`)
+4. **Build-time only** — Overrides are applied during build, not at runtime
+5. **Backup system** — The first build creates \`fragments.original.js\`; subsequent builds restore from it before applying overrides
+
+## Common Patterns
+
+### Adding custom product attributes
+\`\`\`javascript
+{
+  npm: '@dropins/storefront-pdp',
+  operations: [
+    \\\`fragment PRODUCT_FRAGMENT on ProductInterface {
+      delivery_estimate
+      custom_label
+    }\\\`,
+  ],
+}
+\`\`\`
+
+### Adding B2B fields to checkout
+\`\`\`javascript
+{
+  npm: '@dropins/storefront-checkout',
+  operations: [
+    \\\`fragment CHECKOUT_DATA_FRAGMENT on Cart {
+      purchase_order_number
+      company_credit { balance { value currency } }
+    }\\\`,
+  ],
+}
+\`\`\`
+
+### Reducing payload size
+\`\`\`javascript
+{
+  npm: '@dropins/storefront-order',
+  skipFragments: ['DOWNLOADABLE_ORDER_ITEMS_FRAGMENT'],
+  operations: [],
+}
+\`\`\`
+`,
+    },
+];

package/dist/resources/handlers.d.ts

@@ -0,0 +1,31 @@
+interface RegistryResourceDef {
+    uri: string;
+    name: string;
+    mimeType: string;
+    description: string;
+}
+export declare const getResourceHandlers: () => {
+    listResources: () => Promise<{
+        resources: RegistryResourceDef[];
+    }>;
+    listResourceTemplates: () => Promise<{
+        resourceTemplates: {
+            uriTemplate: string;
+            name: string;
+            mimeType: string;
+            description: string;
+        }[];
+    }>;
+    readResource: (request: {
+        params: {
+            uri: string;
+        };
+    }) => Promise<{
+        contents: {
+            uri: string;
+            mimeType: string;
+            text: string;
+        }[];
+    }>;
+};
+export {};