@dropins/mcp 0.1.0

package/dist/operations/search-docs.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const SearchDocsSchema: z.ZodObject<{
+    query: z.ZodString;
+    section: z.ZodOptional<z.ZodString>;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+    includeContent: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    section?: string | undefined;
+    maxResults?: number | undefined;
+    includeContent?: boolean | undefined;
+}, {
+    query: string;
+    section?: string | undefined;
+    maxResults?: number | undefined;
+    includeContent?: boolean | undefined;
+}>;
+export declare function findWordAnchor(lowerContent: string, word: string): number;
+export declare function searchDocsOperation(params: z.infer<typeof SearchDocsSchema>): Promise<{
+    success: boolean;
+    message: string;
+    data: unknown;
+}>;

package/dist/operations/search-docs.js

@@ -0,0 +1,298 @@
+import { z } from "zod";
+import { formatSuccessResponse, formatExceptionResponse, } from "../common/response-handling.js";
+import { DOCS_BASE_URL } from "../common/version.js";
+import { searchDocs, getDocsIndex, getDocsSection, searchExamples, getExamplesByDropin, searchSdk, searchGraphql, tokenizeQuery, scoreItem, topResults, } from "../common/registry-loader.js";
+import { expandQuery } from "../common/synonyms.js";
+function toDocsUrl(path) {
+    return `${DOCS_BASE_URL}/${path}`;
+}
+function toRelevance(score) {
+    if (score >= 15)
+        return "high";
+    if (score >= 5)
+        return "medium";
+    return "low";
+}
+export const SearchDocsSchema = z.object({
+    query: z
+        .string()
+        .trim()
+        .min(1, { message: "query must not be empty" })
+        .describe('Search query (e.g. "CORS setup", "cart slots", "payment method integration")'),
+    section: z
+        .string()
+        .optional()
+        .describe('Limit search to a specific section (e.g. "setup", "dropins/cart", "merchants")'),
+    maxResults: z
+        .number()
+        .int()
+        .min(1, { message: "maxResults must be a positive integer" })
+        .optional()
+        .describe("Maximum total results to return across all sources combined (default: 10). Each source is searched independently and the top results are selected from the combined pool."),
+    includeContent: z
+        .boolean()
+        .optional()
+        .describe("Include full page content in results (default: false, returns snippets)"),
+});
+export function findWordAnchor(lowerContent, word) {
+    try {
+        const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const m = new RegExp(`\\b${escaped}\\b`).exec(lowerContent);
+        return m ? m.index : -1;
+    }
+    catch {
+        return lowerContent.indexOf(word);
+    }
+}
+function extractSnippet(content, query, contextChars = 200, extraWords = []) {
+    const lowerContent = content.toLowerCase();
+    const lowerQuery = query.toLowerCase();
+    const idx = lowerContent.indexOf(lowerQuery);
+    if (idx === -1) {
+        const words = [
+            ...lowerQuery.split(/\s+/).filter((w) => w.length > 1),
+            ...extraWords.map((w) => w.toLowerCase()),
+        ];
+        for (const word of words) {
+            const wordIdx = findWordAnchor(lowerContent, word);
+            if (wordIdx !== -1) {
+                const start = Math.max(0, wordIdx - contextChars / 2);
+                const end = Math.min(content.length, wordIdx + word.length + contextChars / 2);
+                return ((start > 0 ? "..." : "") +
+                    content.slice(start, end).trim() +
+                    (end < content.length ? "..." : ""));
+            }
+        }
+        return (content.slice(0, contextChars) +
+            (content.length > contextChars ? "..." : ""));
+    }
+    const start = Math.max(0, idx - contextChars / 2);
+    const end = Math.min(content.length, idx + query.length + contextChars / 2);
+    return ((start > 0 ? "..." : "") +
+        content.slice(start, end).trim() +
+        (end < content.length ? "..." : ""));
+}
+export async function searchDocsOperation(params) {
+    try {
+        const parsed = SearchDocsSchema.safeParse(params);
+        if (!parsed.success) {
+            return formatExceptionResponse(new Error(parsed.error.issues.map((i) => i.message).join("; ")), "validating search query");
+        }
+        params = parsed.data;
+        const index = getDocsIndex();
+        const docsAvailable = !!(index.sections && index.sections.length > 0);
+        const maxResults = params.maxResults ?? 10;
+        const includeContent = params.includeContent ?? false;
+        const { extraWords, synonymsApplied } = expandQuery(params.query);
+        if (params.section) {
+            if (!docsAvailable) {
+                return formatSuccessResponse("Documentation not available — cannot search by section", {
+                    query: params.query,
+                    hint: 'Run "yarn generate:docs" to generate documentation, or omit the section parameter to search SDK, examples, and GraphQL.',
+                });
+            }
+            const sectionData = getDocsSection(params.section);
+            if (!sectionData) {
+                const available = index.sections.map((s) => s.section);
+                return formatSuccessResponse(`Section "${params.section}" not found`, {
+                    availableSections: available,
+                });
+            }
+            const sectionEntry = index.sections.find((s) => s.section === params.section);
+            const sectionLabel = sectionEntry?.label ?? params.section;
+            const { lowerQuery, words } = tokenizeQuery(params.query, extraWords);
+            const scored = topResults(sectionData.pages
+                .map((page) => ({
+                page,
+                score: scoreItem(words, lowerQuery, [
+                    { value: page.title ?? "", wordWeight: 10, fullMatchWeight: 20 },
+                    {
+                        value: page.description ?? "",
+                        wordWeight: 5,
+                        fullMatchWeight: 10,
+                    },
+                    { value: page.content ?? "", wordWeight: 1 },
+                ]),
+            }))
+                .filter((r) => r.score > 0), maxResults);
+            const results = scored.map((r) => ({
+                path: r.page.path,
+                url: toDocsUrl(r.page.path),
+                title: r.page.title,
+                description: r.page.description,
+                section: params.section,
+                sectionLabel,
+                relevance: toRelevance(r.score),
+                ...(includeContent
+                    ? { content: r.page.content }
+                    : {
+                        snippet: extractSnippet(r.page.content ?? "", params.query, 200, extraWords),
+                    }),
+            }));
+            return formatSuccessResponse(results.length > 0
+                ? `Found ${results.length} result(s) in "${sectionLabel}" for: "${params.query}"`
+                : `No results found in "${sectionLabel}" for: "${params.query}"`, {
+                query: params.query,
+                section: params.section,
+                ...(synonymsApplied.length > 0 && { synonymsApplied }),
+                results,
+                note: "Registry data from dropin source code takes precedence over documentation when there are conflicts.",
+            });
+        }
+        const sdkResults = searchSdk(params.query, maxResults, extraWords);
+        const exampleResults = searchExamples(params.query, maxResults, extraWords);
+        const docResults = docsAvailable
+            ? searchDocs(params.query, maxResults, extraWords)
+            : [];
+        const graphqlResults = searchGraphql(params.query, maxResults, extraWords);
+        const sdkEntries = sdkResults.map((r) => ({
+            source: "sdk",
+            type: r.type,
+            package: r.packageName,
+            ...r.item,
+            relevance: toRelevance(r.score),
+            _score: r.score,
+        }));
+        const exampleEntries = exampleResults.map((r) => {
+            const result = {
+                source: "example",
+                type: r.type,
+                dropin: r.dropin,
+                ...r.example,
+                relevance: toRelevance(r.score),
+                _score: r.score,
+            };
+            if (includeContent && r.type === "extension") {
+                const dropinData = getExamplesByDropin(r.dropin);
+                const ext = dropinData?.extensions?.find((e) => e.id === r.example.id);
+                if (ext) {
+                    result.files = ext.files;
+                    if (ext.sharedFiles?.length) {
+                        const sharedFileContents = {};
+                        for (const sf of ext.sharedFiles) {
+                            if (dropinData?.sharedExtensionFiles?.[sf]) {
+                                sharedFileContents[sf] = dropinData.sharedExtensionFiles[sf];
+                            }
+                        }
+                        result.sharedFileContents = sharedFileContents;
+                    }
+                }
+            }
+            if (includeContent && r.type === "block") {
+                const dropinData = getExamplesByDropin(r.dropin);
+                const block = dropinData?.blocks?.find((b) => b.name === r.example.name);
+                if (block) {
+                    result.files = block.files;
+                }
+            }
+            if (includeContent && r.type === "guide") {
+                const dropinData = getExamplesByDropin(r.dropin);
+                if (dropinData?.extensionGuide) {
+                    result.content = dropinData.extensionGuide;
+                }
+            }
+            return result;
+        });
+        const docEntries = docResults.map((r) => {
+            const sectionData = getDocsSection(r.section);
+            const fullPage = sectionData?.pages?.find((p) => p.path === r.page.path);
+            return {
+                source: "documentation",
+                path: r.page.path,
+                url: toDocsUrl(r.page.path),
+                title: r.page.title,
+                description: r.page.description,
+                section: r.section,
+                sectionLabel: r.sectionLabel,
+                relevance: toRelevance(r.score),
+                _score: r.score,
+                ...(includeContent
+                    ? { content: fullPage?.content ?? "" }
+                    : {
+                        snippet: extractSnippet(fullPage?.content ?? "", params.query, 200, extraWords),
+                    }),
+            };
+        });
+        const graphqlEntries = graphqlResults.map((r) => {
+            if ("fragment" in r) {
+                const fr = r;
+                return {
+                    source: "graphql",
+                    kind: "fragment",
+                    dropin: fr.dropin,
+                    name: fr.fragment.name,
+                    exportName: fr.fragment.exportName,
+                    file: fr.fragment.file,
+                    onType: fr.fragment.onType,
+                    exported: fr.fragment.exported,
+                    fragmentDependencies: fr.fragment.fragmentDependencies,
+                    relevance: toRelevance(fr.score),
+                    _score: fr.score,
+                };
+            }
+            const op = r;
+            return {
+                source: "graphql",
+                kind: "operation",
+                dropin: op.dropin,
+                name: op.operation.name,
+                type: op.operation.type,
+                exportName: op.operation.exportName,
+                file: op.operation.file,
+                variables: op.operation.variables,
+                fragmentDependencies: op.operation.fragmentDependencies,
+                relevance: toRelevance(op.score),
+                _score: op.score,
+            };
+        });
+        const allResults = [
+            ...sdkEntries,
+            ...exampleEntries,
+            ...graphqlEntries,
+            ...docEntries,
+        ]
+            .sort((a, b) => b._score - a._score)
+            .slice(0, maxResults)
+            .map(({ _score: _s, ...rest }) => rest);
+        if (allResults.length === 0) {
+            return formatSuccessResponse(`No documentation or examples found for: "${params.query}"`, {
+                query: params.query,
+                ...(docsAvailable
+                    ? {
+                        availableSections: index.sections.map((s) => ({
+                            section: s.section,
+                            label: s.label,
+                            pageCount: s.pageCount,
+                        })),
+                    }
+                    : {
+                        hint: 'Documentation snapshot not available. Run "yarn generate:docs" to enable doc search. SDK, examples, and GraphQL were searched.',
+                    }),
+                ...(!docsAvailable
+                    ? {}
+                    : {
+                        hint: "Try broader search terms, or browse a specific section",
+                    }),
+            });
+        }
+        const cappedSdk = allResults.filter((r) => r.source === "sdk");
+        const cappedExamples = allResults.filter((r) => r.source === "example");
+        const cappedGraphql = allResults.filter((r) => r.source === "graphql");
+        const cappedDocs = allResults.filter((r) => r.source === "documentation");
+        return formatSuccessResponse(`Found ${allResults.length} result(s) for: "${params.query}" (${cappedSdk.length} SDK, ${cappedExamples.length} examples, ${cappedGraphql.length} GraphQL, ${cappedDocs.length} docs)`, {
+            query: params.query,
+            ...(synonymsApplied.length > 0 && { synonymsApplied }),
+            ...(!docsAvailable && {
+                warning: 'Documentation snapshot not available. Run "yarn generate:docs" to enable doc search.',
+            }),
+            sdk: cappedSdk,
+            examples: cappedExamples,
+            graphql: cappedGraphql,
+            documentation: cappedDocs,
+            note: "SDK results show StorefrontSDK package APIs. Examples are working implementations. GraphQL results show dropin queries/mutations. Registry data takes precedence over documentation when there are conflicts.",
+        });
+    }
+    catch (error) {
+        return formatExceptionResponse(error, "searching documentation");
+    }
+}

package/dist/operations/suggest-event-handler.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export declare const SuggestEventHandlerSchema: z.ZodObject<{
+    request: z.ZodString;
+    projectDir: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    projectDir: string;
+    request: string;
+}, {
+    projectDir: string;
+    request: string;
+}>;
+export declare function suggestEventHandler(params: z.infer<typeof SuggestEventHandlerSchema>): Promise<{
+    success: boolean;
+    message: string;
+    data: unknown;
+}>;

package/dist/operations/suggest-event-handler.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { formatSuccessResponse, formatExceptionResponse, } from "../common/response-handling.js";
+import { getEventCatalog, findModel } from "../common/registry-loader.js";
+import { projectDirGuard, listBlocks, readBlockFile, extractImportsFromBlock, } from "../common/project-reader.js";
+import { sanitizeForComment } from "../common/sanitize.js";
+export const SuggestEventHandlerSchema = z.object({
+    request: z
+        .string()
+        .describe('What the merchant wants (e.g. "Show popup when order is placed", "Refresh mini-cart when product is added")'),
+    projectDir: z
+        .string()
+        .describe("Absolute path to the merchant storefront project root"),
+});
+function scoreEventRelevance(request, event) {
+    const lowerReq = request.toLowerCase();
+    const lowerName = event.name.toLowerCase();
+    const lowerDesc = (event.description ?? "").toLowerCase();
+    let score = 0;
+    const eventParts = lowerName.split("/");
+    for (const part of eventParts) {
+        if (lowerReq.includes(part))
+            score += 5;
+    }
+    if (lowerReq.includes("order") && lowerName.includes("order"))
+        score += 5;
+    if (lowerReq.includes("cart") && lowerName.includes("cart"))
+        score += 5;
+    if (lowerReq.includes("checkout") && lowerName.includes("checkout"))
+        score += 5;
+    if (lowerReq.includes("login") && lowerName.includes("authenticated"))
+        score += 5;
+    if (lowerReq.includes("auth") && lowerName.includes("authenticated"))
+        score += 5;
+    if (lowerReq.includes("add") && lowerName.includes("added"))
+        score += 4;
+    if (lowerReq.includes("update") && lowerName.includes("updated"))
+        score += 4;
+    if (lowerReq.includes("place") && lowerName.includes("placed"))
+        score += 5;
+    if (lowerReq.includes("search") && lowerName.includes("search"))
+        score += 5;
+    if (lowerReq.includes("product") && lowerName.includes("product"))
+        score += 3;
+    if (lowerReq.includes("wishlist") && lowerName.includes("wishlist"))
+        score += 5;
+    if (lowerReq.includes("quote") && lowerName.includes("quote"))
+        score += 5;
+    const reqWords = lowerReq.split(/\s+/);
+    for (const word of reqWords) {
+        if (word.length > 3 && lowerDesc.includes(word))
+            score += 2;
+    }
+    return score;
+}
+function generateEventHandlerCode(event, request) {
+    const payloadVar = event.payloadType?.includes("{")
+        ? "data"
+        : event.payloadType?.toLowerCase().replace(/\s+/g, "") || "payload";
+    return `import { events } from '@dropins/tools/event-bus.js';
+
+// ${sanitizeForComment(request)}
+events.on('${event.name}', (${payloadVar}) => {
+  // Payload type: ${event.payloadType}
+  // ${sanitizeForComment(event.description ?? "")}
+
+  // Implement your handler logic here
+  console.log('${event.name} received:', ${payloadVar});
+});`;
+}
+function partitionEventRefs(refs) {
+    const boilerplateBlocks = [];
+    const storefrontDropins = [];
+    for (const { dropin } of refs) {
+        if (dropin.startsWith("boilerplate/")) {
+            boilerplateBlocks.push(dropin.replace("boilerplate/", ""));
+        }
+        else if (dropin.startsWith("storefront-")) {
+            storefrontDropins.push(dropin);
+        }
+    }
+    return { boilerplateBlocks, storefrontDropins };
+}
+function blocksImportingDropins(dropins, blockImportMap) {
+    const result = [];
+    for (const [blockName, imports] of blockImportMap) {
+        if (imports.some((p) => dropins.some((d) => p.includes(`@dropins/${d}/`)))) {
+            result.push(blockName);
+        }
+    }
+    return result;
+}
+function suggestPlacement(event, blockImportMap) {
+    const allRefs = [...(event.emittedBy ?? []), ...(event.consumedBy ?? [])];
+    const { boilerplateBlocks, storefrontDropins } = partitionEventRefs(allRefs);
+    const presentBoilerplateBlocks = [...new Set(boilerplateBlocks)].filter((name) => blockImportMap.has(name));
+    if (presentBoilerplateBlocks.length > 0) {
+        return `Place in one of: ${presentBoilerplateBlocks.join(", ")} (known integration block for this event)`;
+    }
+    const importingBlocks = blocksImportingDropins([...new Set(storefrontDropins)], blockImportMap);
+    if (importingBlocks.length > 0) {
+        return `Place in one of: ${importingBlocks.join(", ")} (already imports the related dropin)`;
+    }
+    const uniqueBoilerplateBlocks = [...new Set(boilerplateBlocks)];
+    if (uniqueBoilerplateBlocks.length > 0) {
+        return `Consider adding this handler in: ${uniqueBoilerplateBlocks.join(", ")}`;
+    }
+    return "Place in your main commerce block or a shared script file";
+}
+export async function suggestEventHandler(params) {
+    try {
+        const guard = projectDirGuard(params.projectDir);
+        if (guard)
+            return guard;
+        const catalog = getEventCatalog();
+        const allBlocks = listBlocks(params.projectDir);
+        const blockImportMap = new Map();
+        const existingEventUsage = [];
+        for (const block of allBlocks) {
+            const content = readBlockFile(params.projectDir, block.name);
+            if (!content)
+                continue;
+            const imports = extractImportsFromBlock(content);
+            blockImportMap.set(block.name, imports.dropinImports);
+            if (imports.eventImports) {
+                existingEventUsage.push({ block: block.name, usesEventBus: true });
+            }
+        }
+        const scored = (catalog.events ?? [])
+            .map((event) => ({
+            event,
+            score: scoreEventRelevance(params.request, event),
+        }))
+            .filter(({ score }) => score > 0)
+            .sort((a, b) => b.score - a.score);
+        const suggestions = scored
+            .slice(0, 5)
+            .map(({ event, score }) => ({
+            eventName: event.name,
+            payloadType: event.payloadType,
+            description: event.description,
+            relevance: score >= 8 ? "high" : score >= 4 ? "medium" : "low",
+            codeSnippet: generateEventHandlerCode(event, params.request),
+            placementSuggestion: suggestPlacement(event, blockImportMap),
+        }));
+        const resolvedTypes = {};
+        for (const suggestion of suggestions) {
+            const rawType = suggestion.payloadType;
+            if (!rawType || rawType.includes("{"))
+                continue;
+            const namedTypes = rawType.match(/\b[A-Z][A-Za-z0-9]+\b/g) ?? [];
+            for (const typeName of namedTypes) {
+                if (typeName in resolvedTypes)
+                    continue;
+                const matches = findModel(typeName);
+                if (matches.length > 0) {
+                    resolvedTypes[typeName] = matches[0].definition;
+                }
+            }
+        }
+        return formatSuccessResponse(suggestions.length > 0
+            ? `Found ${suggestions.length} event suggestion(s) for: "${params.request}"`
+            : `No matching events found for: "${params.request}"`, {
+            request: params.request,
+            suggestions,
+            existingEventUsage,
+            ...(Object.keys(resolvedTypes).length > 0 && { resolvedTypes }),
+            hint: suggestions.length === 0
+                ? "Try rephrasing your request, or use list_events to browse all available events"
+                : undefined,
+        });
+    }
+    catch (error) {
+        return formatExceptionResponse(error, "suggesting event handler");
+    }
+}

package/dist/operations/suggest-slot-implementation.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export declare const SuggestSlotSchema: z.ZodObject<{
+    request: z.ZodString;
+    blockName: z.ZodString;
+    projectDir: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    projectDir: string;
+    blockName: string;
+    request: string;
+}, {
+    projectDir: string;
+    blockName: string;
+    request: string;
+}>;
+export declare function suggestSlotImplementation(params: z.infer<typeof SuggestSlotSchema>): Promise<{
+    success: boolean;
+    message: string;
+    data: unknown;
+}>;