@dropins/mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { VERSION } from "./common/version.js";
+import { getResourceHandlers } from "./resources/handlers.js";
+import * as telemetry from "./common/telemetry.js";
+import * as analyzeProject from "./operations/analyze-project.js";
+import * as listSlots from "./operations/list-slots.js";
+import * as listEvents from "./operations/list-events.js";
+import * as listContainers from "./operations/list-containers.js";
+import * as listApiFunctions from "./operations/list-api-functions.js";
+import * as listDesignTokens from "./operations/list-design-tokens.js";
+import * as listI18nKeys from "./operations/list-i18n-keys.js";
+import * as checkConfig from "./operations/check-config.js";
+import * as scaffoldBlock from "./operations/scaffold-block.js";
+import * as scaffoldExtension from "./operations/scaffold-extension.js";
+import * as scaffoldSlot from "./operations/scaffold-slot.js";
+import * as suggestSlot from "./operations/suggest-slot-implementation.js";
+import * as suggestEventHandler from "./operations/suggest-event-handler.js";
+import * as explainEventFlow from "./operations/explain-event-flow.js";
+import * as getUpgradeDiff from "./operations/get-upgrade-diff.js";
+import * as searchDocs from "./operations/search-docs.js";
+import * as searchCommerceDocs from "./operations/search-commerce-docs.js";
+import * as listGraphqlQueries from "./operations/list-graphql-queries.js";
+import * as checkBlockHealth from "./operations/check-block-health.js";
+import * as listModels from "./operations/list-models.js";
+const server = new Server({
+    name: "dropins-mcp-server",
+    version: VERSION,
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+    },
+});
+const resourceHandlers = getResourceHandlers();
+server.setRequestHandler(ListResourcesRequestSchema, resourceHandlers.listResources);
+server.setRequestHandler(ListResourceTemplatesRequestSchema, resourceHandlers.listResourceTemplates);
+server.setRequestHandler(ReadResourceRequestSchema, resourceHandlers.readResource);
+function tool(name, description, schema, handler) {
+    return {
+        name,
+        description,
+        schema,
+        handler: handler,
+    };
+}
+const toolRegistry = [
+    tool("analyze_project", "Analyze a merchant storefront project: detect installed dropins, blocks, config, and versions", analyzeProject.AnalyzeProjectSchema, analyzeProject.analyzeProject),
+    tool("list_slots", "AUTHORITATIVE source for slot data. List available slots for dropin containers with context shapes and examples. Use this instead of search tools for slot questions", listSlots.ListSlotsSchema, listSlots.listSlots),
+    tool("list_events", "AUTHORITATIVE source for event data. List events emitted and consumed by dropins with payload shapes. Use this instead of search tools for event questions", listEvents.ListEventsSchema, listEvents.listEvents),
+    tool("list_containers", "AUTHORITATIVE source for container data. List available dropin containers with props and slot names. Use this instead of search tools for container questions", listContainers.ListContainersSchema, listContainers.listContainers),
+    tool("list_api_functions", "AUTHORITATIVE source for API function data. List available API functions for dropins with signatures. Use this instead of search tools for API questions", listApiFunctions.ListApiFunctionsSchema, listApiFunctions.listApiFunctions),
+    tool("list_design_tokens", "List design tokens (CSS custom properties) for theming", listDesignTokens.ListDesignTokensSchema, listDesignTokens.listDesignTokens),
+    tool("list_i18n_keys", "List i18n dictionary keys and their default English values, filterable by dropin and substring query on key path or value", listI18nKeys.ListI18nKeysSchema, listI18nKeys.listI18nKeys),
+    tool("list_models", "Look up TypeScript interface and type definitions (CartModel, Price, Item, etc.) used in event payloads and slot contexts. Use when a payloadType or contextType references a named model you need to understand.", listModels.ListModelsSchema, listModels.listModels),
+    tool("check_config", "Validate a merchant storefront project configuration", checkConfig.CheckConfigSchema, checkConfig.checkConfig),
+    tool("scaffold_block", "Generate a new AEM block with dropin containers. Supports single dropin (dropin + containers) or multi-dropin (containersByDropin) with automatic provider aliases.", scaffoldBlock.ScaffoldBlockSchema, scaffoldBlock.scaffoldBlock),
+    tool("scaffold_extension", "Generate a checkout extension with selected hooks, extension manager, and index file", scaffoldExtension.ScaffoldExtensionSchema, scaffoldExtension.scaffoldExtension),
+    tool("scaffold_slot", "Generate production-ready slot implementation boilerplate for a specific container slot, including imports, context destructuring, and all available slot methods", scaffoldSlot.ScaffoldSlotSchema, scaffoldSlot.scaffoldSlot),
+    tool("suggest_slot_implementation", "Suggest slot implementation code for a UI customization request on an existing block", suggestSlot.SuggestSlotSchema, suggestSlot.suggestSlotImplementation),
+    tool("suggest_event_handler", "Suggest event handler code for a cross-dropin behavior request", suggestEventHandler.SuggestEventHandlerSchema, suggestEventHandler.suggestEventHandler),
+    tool("explain_event_flow", "Trace the full lifecycle of an event: who emits it, who consumes it, payload type, and ready-to-use listen and emit code. Supports exact, prefix, and substring matching.", explainEventFlow.ExplainEventFlowSchema, explainEventFlow.explainEventFlow),
+    tool("get_upgrade_diff", "Compare merchant dropin versions against registry and show containers, slots, and migration notes", getUpgradeDiff.GetUpgradeDiffSchema, getUpgradeDiff.getUpgradeDiff),
+    tool("search_docs", "Search local documentation snapshots, SDK packages, code examples, and GraphQL operations. For API data, prefer dedicated tools first (list_slots, list_containers, etc). Use this for cross-cutting searches or working code examples", searchDocs.SearchDocsSchema, searchDocs.searchDocsOperation),
+    tool("search_commerce_docs", "AI-powered semantic search for conceptual documentation: guides, tutorials, best practices, architecture. Optional enhancement requiring aio CLI authentication. NOT for API definitions (slots, events, containers) — use registry tools instead", searchCommerceDocs.SearchCommerceDocsSchema, searchCommerceDocs.searchCommerceDocs),
+    tool("list_graphql_queries", "AUTHORITATIVE source for GraphQL operations. List queries, mutations, and extensible fragments used by dropins with full resolved source and extensibility metadata", listGraphqlQueries.ListGraphqlQueriesSchema, listGraphqlQueries.listGraphqlQueries),
+    tool("check_block_health", "Check a merchant's AEM block against the current registry. Detects containers, slots, events, and API functions that no longer exist or have been renamed. Omit the block parameter to scan all dropin blocks and their initializer files at once. Pass fix: true to get a concrete rename or remove hint for every finding.", checkBlockHealth.CheckBlockHealthSchema, checkBlockHealth.checkBlockHealth),
+];
+const toolHandlers = new Map(toolRegistry.map((t) => [t.name, { schema: t.schema, handler: t.handler }]));
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: toolRegistry.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: zodToJsonSchema(t.schema),
+        })),
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const start = Date.now();
+    const toolName = request.params.name;
+    try {
+        const entry = toolHandlers.get(toolName);
+        if (!entry) {
+            throw new Error(`Unknown tool: ${toolName}`);
+        }
+        const parsed = entry.schema.parse(request.params.arguments ?? {});
+        const result = await entry.handler(parsed);
+        telemetry.record(toolName, parsed, result, Date.now() - start);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : "Unknown error occurred";
+        telemetry.record(toolName, (request.params.arguments ?? {}), null, Date.now() - start, errorMsg);
+        if (error instanceof z.ZodError) {
+            const fieldErrors = error.errors.map((e) => `${e.path.join(".")}: ${e.message}`);
+            throw new Error(`Invalid input: ${fieldErrors.join("; ")}`);
+        }
+        process.stderr.write(`Unexpected error: ${error instanceof Error ? error.stack : error}\n`);
+        throw new Error("An unexpected error occurred");
+    }
+});
+const execFileAsync = promisify(execFile);
+async function checkForUpdates() {
+    if (VERSION.includes("alpha") || VERSION.includes("beta")) {
+        return;
+    }
+    try {
+        const { stdout } = await execFileAsync("npm", ["show", "@dropins/mcp", "version"], { timeout: 10000 });
+        const latest = stdout.trim();
+        if (latest && latest !== VERSION) {
+            process.stderr.write(`\n⚠️  Dropins MCP update available: ${VERSION} → ${latest}\n` +
+                `   Run: npm update -g @dropins/mcp\n\n`);
+        }
+    }
+    catch {
+    }
+}
+async function runServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("Dropins MCP Server running on stdio\n");
+    checkForUpdates();
+}
+runServer().catch((error) => {
+    process.stderr.write(`Fatal error in main(): ${error}\n`);
+    process.exit(1);
+});

package/dist/operations/analyze-project.d.ts

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

package/dist/operations/analyze-project.js

@@ -0,0 +1,125 @@
+import { z } from "zod";
+import { formatSuccessResponse, formatExceptionResponse, } from "../common/response-handling.js";
+import { readPackageJson, readConfigJson, listBlocks, readBlockFile, listInitializers, projectDirGuard, extractDropinDependencies, extractImportsFromBlock, INITIALIZER_ALIASES, } from "../common/project-reader.js";
+import { getContainerRegistry } from "../common/registry-loader.js";
+export const AnalyzeProjectSchema = z.object({
+    projectDir: z
+        .string()
+        .describe("Absolute path to the merchant storefront project root"),
+});
+export async function analyzeProject(params) {
+    try {
+        const guard = projectDirGuard(params.projectDir);
+        if (guard)
+            return guard;
+        const pkg = readPackageJson(params.projectDir);
+        const config = readConfigJson(params.projectDir);
+        const blocks = listBlocks(params.projectDir);
+        const initializers = listInitializers(params.projectDir);
+        const registry = getContainerRegistry();
+        const dropinDeps = pkg ? extractDropinDependencies(pkg) : [];
+        const allBlockAnalysis = blocks.map((block) => {
+            const jsContent = readBlockFile(params.projectDir, block.name);
+            if (!jsContent) {
+                return {
+                    name: block.name,
+                    hasCss: block.hasCss,
+                    hasDropinImports: false,
+                    imports: null,
+                    note: "No JS file found",
+                };
+            }
+            const imports = extractImportsFromBlock(jsContent);
+            const hasDropinImports = imports.dropinImports.some((p) => p.includes("@dropins/storefront-"));
+            return {
+                name: block.name,
+                hasCss: block.hasCss,
+                hasDropinImports,
+                dropinImports: imports.dropinImports,
+                containerImports: imports.containerImports,
+                apiImports: imports.apiImports,
+                usesEventBus: imports.eventImports,
+            };
+        });
+        const commerceBlocks = allBlockAnalysis.filter((b) => b.hasDropinImports);
+        const blockAnalysis = commerceBlocks.map(({ hasDropinImports: _, ...rest }) => rest);
+        const issues = [];
+        const suggestions = [];
+        if (!pkg) {
+            issues.push("No package.json found — cannot detect dropin versions");
+        }
+        if (dropinDeps.length === 0 && pkg) {
+            issues.push("No @dropins/* dependencies found in package.json");
+        }
+        if (!config) {
+            issues.push("No config.json or demo-config.json found");
+        }
+        else {
+            const defaultConfig = config.public?.default;
+            if (!defaultConfig?.["commerce-endpoint"]) {
+                issues.push("Missing commerce-endpoint in config");
+            }
+            if (!defaultConfig?.["commerce-core-endpoint"]) {
+                suggestions.push("Consider adding commerce-core-endpoint for core GraphQL queries");
+            }
+        }
+        if (commerceBlocks.length === 0) {
+            issues.push("No blocks using dropin imports found in blocks/ directory");
+        }
+        if (initializers.length === 0) {
+            suggestions.push("No dropin initializers found in scripts/initializers/");
+        }
+        const registeredDropins = Object.keys(registry.dropins);
+        const installedDropinNames = dropinDeps.map((d) => d.name.replace("@dropins/", ""));
+        const missingInitializers = installedDropinNames.filter((name) => {
+            if (name === "tools" || name === "build-tools")
+                return false;
+            const alias = INITIALIZER_ALIASES[name];
+            return !initializers.some((init) => name.includes(init.name) || (alias && init.name === alias));
+        });
+        if (missingInitializers.length > 0) {
+            suggestions.push(`Dropins installed but missing initializers: ${missingInitializers.join(", ")}`);
+        }
+        const knownDropins = installedDropinNames.filter((name) => registeredDropins.includes(name));
+        const unknownDropins = installedDropinNames.filter((name) => !registeredDropins.includes(name) &&
+            name !== "tools" &&
+            name !== "build-tools");
+        return formatSuccessResponse("Project analysis complete", {
+            projectName: pkg?.name ?? "unknown",
+            projectVersion: pkg?.version ?? "unknown",
+            dropins: {
+                installed: dropinDeps.map((d) => ({
+                    name: d.name,
+                    version: d.version,
+                    isDev: d.isDev,
+                    knownInRegistry: registeredDropins.includes(d.name.replace("@dropins/", "")),
+                })),
+                count: dropinDeps.length,
+                knownDropins,
+                unknownDropins,
+            },
+            config: config
+                ? {
+                    found: true,
+                    commerceEndpoint: config.public?.default?.["commerce-endpoint"] ?? null,
+                    commerceCoreEndpoint: config.public?.default?.["commerce-core-endpoint"] ?? null,
+                    hasHeaders: !!config.public?.default?.headers,
+                    hasAnalytics: !!config.public?.default?.analytics,
+                }
+                : { found: false },
+            blocks: {
+                total: blocks.length,
+                commerceBlocks: blockAnalysis,
+                nonCommerceBlocks: allBlockAnalysis
+                    .filter((b) => !b.hasDropinImports)
+                    .map((b) => b.name),
+            },
+            initializers: initializers.map((i) => i.name),
+            issues,
+            suggestions,
+        });
+    }
+    catch (error) {
+        return formatExceptionResponse(error, "analyzing project");
+    }
+}

package/dist/operations/check-block-health.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export declare const CheckBlockHealthSchema: z.ZodObject<{
+    projectDir: z.ZodString;
+    block: z.ZodOptional<z.ZodString>;
+    fix: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    projectDir: string;
+    block?: string | undefined;
+    fix?: boolean | undefined;
+}, {
+    projectDir: string;
+    block?: string | undefined;
+    fix?: boolean | undefined;
+}>;
+export declare function checkBlockHealth(params: z.infer<typeof CheckBlockHealthSchema>): Promise<{
+    success: boolean;
+    message: string;
+    data: unknown;
+}>;