@dropins/mcp 0.1.0

package/dist/common/sanitize.d.ts

@@ -0,0 +1,8 @@
+export declare function validateIdentifier(value: string, label: string): string | null;
+export declare function validatePathContainment(basePath: string, childPath: string): boolean;
+export declare function sanitizeForComment(value: string): string;
+export declare function escapeJsString(value: string): string;
+export declare function validateUrl(value: string, label: string): string | null;
+export declare function validateBlockName(blockName: string): string | null;
+export declare function validateExtensionId(extensionId: string): string | null;
+export declare function sanitizeErrorMessage(message: string): string;

package/dist/common/sanitize.js

@@ -0,0 +1,45 @@
+import { resolve, normalize } from "path";
+const SAFE_IDENTIFIER = /^[a-zA-Z0-9_-]+$/;
+const SAFE_URL = /^https?:\/\/[^\s'"`;]+$/;
+export function validateIdentifier(value, label) {
+    if (!SAFE_IDENTIFIER.test(value)) {
+        return `Invalid ${label}: "${value}". Only alphanumeric characters, hyphens, and underscores are allowed.`;
+    }
+    return null;
+}
+export function validatePathContainment(basePath, childPath) {
+    const resolvedBase = resolve(basePath);
+    const resolvedChild = resolve(basePath, childPath);
+    const normalizedBase = normalize(resolvedBase) + "/";
+    const normalizedChild = normalize(resolvedChild);
+    return (normalizedChild.startsWith(normalizedBase) ||
+        normalizedChild === resolve(basePath));
+}
+export function sanitizeForComment(value) {
+    return value
+        .replace(/\r?\n/g, " ")
+        .replace(/\*\//g, "* /")
+        .replace(/\/\*/g, "/ *");
+}
+export function escapeJsString(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/'/g, "\\'")
+        .replace(/\r?\n/g, "\\n")
+        .replace(/\r/g, "\\r");
+}
+export function validateUrl(value, label) {
+    if (!SAFE_URL.test(value)) {
+        return `Invalid ${label}: "${value}". Only http/https URLs without quotes or backticks are allowed.`;
+    }
+    return null;
+}
+export function validateBlockName(blockName) {
+    return validateIdentifier(blockName, "block name");
+}
+export function validateExtensionId(extensionId) {
+    return validateIdentifier(extensionId, "extension ID");
+}
+export function sanitizeErrorMessage(message) {
+    return message.replace(/\/[^\s:]+/g, "[path]");
+}

package/dist/common/synonyms.d.ts

@@ -0,0 +1,9 @@
+export declare const SYNONYM_MAP: Record<string, string[]>;
+export interface SynonymExpansion {
+    term: string;
+    expanded: string[];
+}
+export declare function expandQuery(query: string): {
+    extraWords: string[];
+    synonymsApplied: SynonymExpansion[];
+};

package/dist/common/synonyms.js

@@ -0,0 +1,127 @@
+export const SYNONYM_MAP = {
+    address: ["AddressForm", "Addresses"],
+    addresses: ["AddressForm", "Addresses"],
+    billing: ["AddressForm", "Addresses"],
+    shipping: ["AddressForm", "Addresses", "ShippingMethods", "EstimateShipping"],
+    payment: ["PaymentMethods", "CreditCard"],
+    pay: ["PaymentMethods", "PlaceOrder"],
+    paying: ["PaymentMethods"],
+    apple: ["ApplePay"],
+    "credit-card": ["CreditCard"],
+    basket: ["MiniCart"],
+    minicart: ["MiniCart"],
+    cart: ["MiniCart", "CartSummaryList", "CartSummaryGrid"],
+    product: ["ProductDetails", "ProductGallery", "ProductList"],
+    pdp: ["ProductDetails", "ProductGallery", "ProductHeader"],
+    plp: ["ProductList", "Facets", "SortBy"],
+    catalog: ["ProductList", "Facets"],
+    gallery: ["ProductGallery"],
+    image: ["ProductGallery"],
+    photo: ["ProductGallery"],
+    photos: ["ProductGallery"],
+    price: ["ProductPrice", "OrderCostSummary"],
+    quantity: ["ProductQuantity"],
+    options: ["ProductOptions"],
+    attributes: ["ProductAttributes"],
+    search: ["SearchResults", "Facets"],
+    find: ["SearchResults"],
+    filter: ["Facets"],
+    facets: ["Facets"],
+    sort: ["SortBy"],
+    sorting: ["SortBy"],
+    login: ["SignIn", "LoginForm"],
+    "log-in": ["SignIn", "LoginForm"],
+    signin: ["SignIn", "LoginForm"],
+    "sign-in": ["SignIn", "LoginForm"],
+    logout: ["SignIn"],
+    register: ["SignUp"],
+    signup: ["SignUp"],
+    "sign-up": ["SignUp"],
+    registration: ["SignUp", "CompanyRegistration"],
+    password: ["ResetPassword", "UpdatePassword"],
+    forgot: ["ResetPassword"],
+    reset: ["ResetPassword"],
+    checkout: ["PlaceOrder", "ShippingMethods", "EstimateShipping"],
+    submit: ["PlaceOrder"],
+    place: ["PlaceOrder"],
+    terms: ["TermsAndConditions"],
+    conditions: ["TermsAndConditions"],
+    delivery: ["ShippingMethods", "EstimateShipping"],
+    freight: ["ShippingMethods"],
+    estimate: ["EstimateShipping"],
+    order: ["OrdersList", "OrderHeader", "OrderCostSummary"],
+    orders: ["OrdersList"],
+    history: ["OrdersList"],
+    invoice: ["OrderHeader", "OrderCostSummary"],
+    receipt: ["OrderHeader", "OrderCostSummary"],
+    confirmation: ["SuccessNotification", "PurchaseOrderConfirmation"],
+    success: ["SuccessNotification"],
+    "thank-you": ["SuccessNotification"],
+    thankyou: ["SuccessNotification"],
+    return: ["CreateReturn", "ReturnsList"],
+    returns: ["CreateReturn", "ReturnsList"],
+    rma: ["CreateReturn", "ReturnsList"],
+    refund: ["CreateReturn"],
+    wishlist: ["Wishlist", "WishlistToggle"],
+    favorites: ["Wishlist", "WishlistToggle"],
+    favourite: ["Wishlist", "WishlistToggle"],
+    "save-for-later": ["WishlistToggle"],
+    coupon: ["Coupons"],
+    coupons: ["Coupons"],
+    promo: ["Coupons", "GiftOptions"],
+    discount: ["Coupons"],
+    voucher: ["Coupons"],
+    gift: ["GiftCards", "GiftOptions"],
+    gifting: ["GiftCards", "GiftOptions"],
+    wrapping: ["GiftOptions"],
+    company: ["CompanyProfile", "CompanyUsers", "CompanyStructure"],
+    b2b: ["CompanyProfile", "CompanyRegistration", "CompanyUsers"],
+    corporate: ["CompanyProfile"],
+    team: ["CompanyUsers", "RolesAndPermissions"],
+    role: ["RolesAndPermissions"],
+    roles: ["RolesAndPermissions"],
+    permissions: ["RolesAndPermissions"],
+    purchase: ["PurchaseOrder", "CustomerPurchaseOrders"],
+    po: ["PurchaseOrder"],
+    quote: ["RequestNegotiableQuoteForm", "QuotesListTable"],
+    quotes: ["QuotesListTable"],
+    negotiable: ["RequestNegotiableQuoteForm", "ManageNegotiableQuote"],
+    rfq: ["RequestNegotiableQuoteForm"],
+    requisition: ["RequisitionListForm", "RequisitionListView"],
+    account: ["CustomerDetails", "CustomerInformation"],
+    profile: ["CustomerDetails", "CustomerInformation"],
+    customer: ["CustomerDetails", "CustomerInformation"],
+    bulk: ["QuickOrderItems", "QuickOrderMultipleSku"],
+    quick: ["QuickOrderItems"],
+    csv: ["QuickOrderCsvUpload"],
+    sku: ["QuickOrderItems", "QuickOrderMultipleSku"],
+    skus: ["QuickOrderItems", "QuickOrderMultipleSku"],
+    empty: ["EmptyCart", "OutOfStock"],
+    stock: ["OutOfStock"],
+    unavailable: ["OutOfStock"],
+    pagination: ["Pagination"],
+    paging: ["Pagination"],
+};
+export function expandQuery(query) {
+    const words = query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 1);
+    const synonymsApplied = [];
+    const extraWords = [];
+    const seen = new Set(words);
+    for (const word of words) {
+        const syns = SYNONYM_MAP[word];
+        if (!syns?.length)
+            continue;
+        const newSyns = syns.filter((s) => !seen.has(s.toLowerCase()));
+        if (newSyns.length === 0)
+            continue;
+        synonymsApplied.push({ term: word, expanded: newSyns });
+        for (const s of newSyns) {
+            seen.add(s.toLowerCase());
+            extraWords.push(s);
+        }
+    }
+    return { extraWords, synonymsApplied };
+}

package/dist/common/telemetry.d.ts

@@ -0,0 +1,14 @@
+export interface TelemetryEntry {
+    ts: string;
+    tool: string;
+    dropin?: string;
+    query?: string;
+    durationMs: number;
+    empty: boolean;
+    error?: string;
+}
+export interface TelemetryBackend {
+    record(entry: TelemetryEntry): void | Promise<void>;
+}
+export declare function setBackend(backend: TelemetryBackend): void;
+export declare function record(tool: string, params: Record<string, unknown>, result: unknown, durationMs: number, error?: string): void;

package/dist/common/telemetry.js

@@ -0,0 +1,54 @@
+const NoopBackend = {
+    record: () => { },
+};
+let activeBackend = NoopBackend;
+export function setBackend(backend) {
+    activeBackend = backend;
+}
+function isEmptyResult(result) {
+    if (result == null)
+        return true;
+    if (typeof result !== "object")
+        return false;
+    const obj = result;
+    if (obj.success === false)
+        return false;
+    const data = obj.data;
+    if (data == null)
+        return true;
+    if (Array.isArray(data) && data.length === 0)
+        return true;
+    if (typeof data === "object" && Object.keys(data).length === 0)
+        return true;
+    if (typeof data === "object" && !Array.isArray(data)) {
+        const values = Object.values(data);
+        const arrays = values.filter((v) => Array.isArray(v));
+        if (arrays.length > 0 && arrays.every((a) => a.length === 0))
+            return true;
+    }
+    return false;
+}
+function extractDropin(params) {
+    const val = params.dropin ?? params.dropinName;
+    return typeof val === "string" ? val : undefined;
+}
+function extractQuery(params) {
+    const val = params.query ?? params.keyword;
+    return typeof val === "string" ? val : undefined;
+}
+export function record(tool, params, result, durationMs, error) {
+    try {
+        const entry = {
+            ts: new Date().toISOString(),
+            tool,
+            dropin: extractDropin(params),
+            query: extractQuery(params),
+            durationMs,
+            empty: isEmptyResult(result),
+            ...(error ? { error } : {}),
+        };
+        void activeBackend.record(entry);
+    }
+    catch {
+    }
+}

package/dist/common/types.d.ts

@@ -0,0 +1,308 @@
+export interface SlotEntry {
+    name: string;
+    description: string;
+    contextType: string;
+    customMethods: string[];
+    dynamic: boolean;
+    example: string;
+}
+export interface SlotContainerData {
+    slots: SlotEntry[];
+}
+export interface SlotDropinData {
+    containers: Record<string, SlotContainerData>;
+}
+export interface DefaultSlotContextProperty {
+    type: string;
+    description: string;
+}
+export interface DefaultSlotContextInfo {
+    description: string;
+    properties: Record<string, DefaultSlotContextProperty>;
+}
+export interface SlotRegistry {
+    version: string;
+    description: string;
+    defaultSlotContext?: DefaultSlotContextInfo;
+    defaultSlotMethods: Record<string, string>;
+    dropins: Record<string, SlotDropinData>;
+}
+export interface EventRef {
+    dropin: string;
+    file?: string;
+    function: string;
+}
+export interface EventEntry {
+    name: string;
+    payloadType: string;
+    description: string;
+    emittedBy: EventRef[];
+    consumedBy: EventRef[];
+}
+export interface EventCatalog {
+    version: string;
+    description: string;
+    events: EventEntry[];
+}
+export interface ContainerEntry {
+    name: string;
+    importPath: string;
+    description: string;
+    props: Record<string, string>;
+    extendsHTMLAttributes?: boolean;
+    slotNames: string[];
+}
+export interface ContainerDropinData {
+    version: string;
+    renderImport: string;
+    apiImport: string;
+    containers: ContainerEntry[];
+}
+export interface ContainerRegistry {
+    version: string;
+    description: string;
+    dropins: Record<string, ContainerDropinData>;
+}
+export interface ApiFunctionParam {
+    name: string;
+    type: string;
+    optional: boolean;
+}
+export interface ApiFunctionEntry {
+    name: string;
+    signature: string;
+    parameters: ApiFunctionParam[];
+    returnType: string;
+    description: string;
+}
+export interface ApiFunctionUtilModule {
+    description: string;
+    functions: {
+        name: string;
+        signature: string;
+        description: string;
+    }[];
+}
+export interface ApiFunctionUtils {
+    importPath: string;
+    description: string;
+    modules: Record<string, ApiFunctionUtilModule>;
+}
+export interface ApiFunctionDropinData {
+    version: string;
+    importPath: string;
+    functions: ApiFunctionEntry[];
+    utils?: ApiFunctionUtils;
+}
+export interface ApiFunctionRegistry {
+    version: string;
+    description: string;
+    sharedFunctions: Record<string, string>;
+    dropins: Record<string, ApiFunctionDropinData>;
+}
+export interface ToolsComponentEntry {
+    name: string;
+    importPath: string;
+    props: string[];
+    extendsHTMLAttributes: boolean;
+}
+export interface ToolsComponentsRegistry {
+    version: string;
+    description: string;
+    importPath: string;
+    components: ToolsComponentEntry[];
+}
+export interface DesignToken {
+    cssVariable: string;
+    defaultValue: string;
+    description: string;
+}
+export interface DesignTokenCategory {
+    description: string;
+    tokens: DesignToken[];
+}
+export interface DesignTokenRegistry {
+    version: string;
+    cssScope: string;
+    overrideExample: string;
+    categories: Record<string, DesignTokenCategory>;
+}
+export interface ExtensionHook {
+    name: string;
+    description: string;
+    whenFired: string;
+    contextShape: Record<string, string>;
+}
+export interface ExistingExtension {
+    id: string;
+    name: string;
+    hooks: string[];
+    externalScripts: string[];
+    externalStyles: string[];
+    sourceFile: string;
+}
+export interface ExtensionRegistry {
+    version: string;
+    description: string;
+    managerImport: string;
+    managerDescription: string;
+    hooks: ExtensionHook[];
+    existingExtensions: ExistingExtension[];
+}
+export interface GraphqlVariable {
+    name: string;
+    type: string;
+}
+export interface GraphqlOperation {
+    name: string;
+    type: "query" | "mutation";
+    exportName: string;
+    file?: string;
+    variables: GraphqlVariable[];
+    fragmentDependencies: string[];
+    source?: string;
+}
+export interface GraphqlFragment {
+    name: string;
+    exportName: string;
+    file?: string;
+    onType: string;
+    source?: string;
+    fragmentDependencies: string[];
+    exported: boolean;
+}
+export interface GraphqlDropinData {
+    version: string;
+    operationCount: number;
+    fragmentCount: number;
+    operations: GraphqlOperation[];
+    fragments: GraphqlFragment[];
+}
+export interface GraphqlRegistry {
+    version: string;
+    description: string;
+    dropins: Record<string, GraphqlDropinData>;
+}
+export interface SdkPropInfo {
+    name: string;
+    type: string;
+    required: boolean;
+    isSlot?: boolean;
+}
+export interface SdkExportedType {
+    name: string;
+    source: string;
+    definition: string;
+}
+export interface SdkComponent {
+    name: string;
+    description: string;
+    propsInterface?: string;
+    props?: SdkPropInfo[];
+    slots?: string[];
+    extends?: string;
+    omits?: string[];
+}
+export interface SdkTypeEntry {
+    name: string;
+    definition: string;
+    description: string;
+}
+export interface SdkFunction {
+    name: string;
+    signature: string;
+    description: string;
+}
+export interface SdkPackage {
+    name: string;
+    description: string;
+    importPath: string;
+    components?: SdkComponent[];
+    functions?: SdkFunction[];
+    utilities?: SdkFunction[];
+    types?: SdkTypeEntry[];
+    exportedTypes?: SdkExportedType[];
+    usageExample?: string;
+    usageNotes?: string;
+}
+export interface SdkRegistry {
+    description: string;
+    packages: Record<string, SdkPackage>;
+}
+export interface I18nDropinData {
+    version: string;
+    keyCount: number;
+    keys: Record<string, string>;
+}
+export interface I18nRegistry {
+    version: string;
+    description: string;
+    dropins: Record<string, I18nDropinData>;
+}
+export interface BlockPattern {
+    name: string;
+    description: string;
+    template: string;
+    requiredImports: string[];
+    examples: string[];
+}
+export interface BlockPatternRegistry {
+    version: string;
+    description: string;
+    blockLifecycle: string;
+    initializerPattern: string;
+    patterns: BlockPattern[];
+}
+export interface DocsSectionEntry {
+    section: string;
+    label: string;
+    pageCount: number;
+    file: string;
+}
+export interface DocsIndex {
+    totalPages: number;
+    totalSections: number;
+    priority: string;
+    sections: DocsSectionEntry[];
+}
+export interface DocsPage {
+    path: string;
+    title: string;
+    description: string;
+    content: string;
+}
+export interface DocsSection {
+    pages: DocsPage[];
+}
+export interface ExamplesDropinEntry {
+    dropin: string;
+    file: string;
+    extensionCount: number;
+    blockCount: number;
+}
+export interface ExamplesIndex {
+    version: string;
+    totalExtensions: number;
+    totalBlocks: number;
+    dropins: ExamplesDropinEntry[];
+}
+export interface ExampleExtension {
+    id: string;
+    name: string;
+    provider: string;
+    description: string;
+    hooks: string[];
+    files: Record<string, string>;
+    sharedFiles?: string[];
+}
+export interface ExampleBlock {
+    name: string;
+    description: string;
+    files: Record<string, string>;
+}
+export interface ExamplesDropinData {
+    extensions: ExampleExtension[];
+    blocks: ExampleBlock[];
+    extensionGuide?: string;
+    sharedExtensionFiles?: Record<string, string>;
+}

package/dist/common/types.js

@@ -0,0 +1 @@
+export {};

package/dist/common/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: string;
+export declare const DOCS_BASE_URL = "https://experienceleague.adobe.com/developer/commerce/storefront";

package/dist/common/version.js

@@ -0,0 +1,14 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+const _require = createRequire(import.meta.url);
+const _dir = dirname(fileURLToPath(import.meta.url));
+const _pkgPath = ["../package.json", "../../package.json"]
+    .map((rel) => join(_dir, rel))
+    .find(existsSync);
+if (!_pkgPath)
+    throw new Error("Cannot find package.json for @dropins/mcp");
+const _pkg = _require(_pkgPath);
+export const VERSION = _pkg.version;
+export const DOCS_BASE_URL = "https://experienceleague.adobe.com/developer/commerce/storefront";

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};