@dropins/mcp 0.1.0

package/dist/resources/handlers.js

@@ -0,0 +1,322 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { DOCS_BASE_URL } from "../common/version.js";
+import { guides } from "./guides.js";
+import { getSlotRegistry, getEventCatalog, getContainerRegistry, getApiFunctionRegistry, getExtensionRegistry, getDesignTokenRegistry, getBlockPatternRegistry, getGraphqlRegistry, getSlotsByDropin, getSlotsByContainer, getEventsByDropin, getContainersByDropin, getApiFunctionsByDropin, getDesignTokensByCategory, getGraphqlByDropin, getAllDropinNames, getDocsIndex, getDocsSection, getExamplesIndex, getExamplesByDropin, getSdkRegistry, getSdkPackage, } from "../common/registry-loader.js";
+const registryResources = [
+    {
+        uri: "storefront://registry/slots",
+        name: "Slot Registry",
+        mimeType: "application/json",
+        description: "Complete slot definitions for all dropin containers (118 slots across 9 dropins)",
+    },
+    {
+        uri: "storefront://registry/events",
+        name: "Event Catalog",
+        mimeType: "application/json",
+        description: "All cross-dropin events with payload types and producer/consumer info (45 events)",
+    },
+    {
+        uri: "storefront://registry/containers",
+        name: "Container Registry",
+        mimeType: "application/json",
+        description: "All dropin containers with props and slot names (80 containers across 9 dropins)",
+    },
+    {
+        uri: "storefront://registry/api-functions",
+        name: "API Function Registry",
+        mimeType: "application/json",
+        description: "Public API functions for all dropins with signatures and parameters",
+    },
+    {
+        uri: "storefront://registry/extensions",
+        name: "Extension Registry",
+        mimeType: "application/json",
+        description: "Checkout extension hooks, interface definitions, and reference examples",
+    },
+    {
+        uri: "storefront://registry/design-tokens",
+        name: "Design Token Registry",
+        mimeType: "application/json",
+        description: "CSS custom properties for theming across all categories (colors, typography, spacing, shapes, grid)",
+    },
+    {
+        uri: "storefront://registry/block-patterns",
+        name: "Block Pattern Registry",
+        mimeType: "application/json",
+        description: "AEM block templates and patterns for rendering dropin containers",
+    },
+    {
+        uri: "storefront://docs",
+        name: "Documentation Index",
+        mimeType: "application/json",
+        description: "Index of all official storefront documentation sections and pages (supplementary to registry data)",
+    },
+    {
+        uri: "storefront://registry/examples",
+        name: "Examples Index",
+        mimeType: "application/json",
+        description: "Index of working code examples from dropin repositories (extensions, block patterns)",
+    },
+    {
+        uri: "storefront://registry/sdk",
+        name: "SDK Package Registry",
+        mimeType: "application/json",
+        description: "StorefrontSDK packages — elsie UI components (with props, slots, exported types), event-bus, fetch-graphql, build-tools, recaptcha",
+    },
+    {
+        uri: "storefront://registry/graphql",
+        name: "GraphQL Query Registry",
+        mimeType: "application/json",
+        description: "GraphQL queries, mutations, and extensible fragments used by all dropins with fully resolved sources and extensibility metadata",
+    },
+];
+const resourceTemplates = [
+    {
+        uriTemplate: "storefront://registry/slots/{dropinName}",
+        name: "Slots by Dropin",
+        mimeType: "application/json",
+        description: "Slot definitions for a specific dropin (e.g., storefront-cart)",
+    },
+    {
+        uriTemplate: "storefront://registry/slots/{dropinName}/{containerName}",
+        name: "Slots by Container",
+        mimeType: "application/json",
+        description: "Slot definitions for a specific container within a dropin",
+    },
+    {
+        uriTemplate: "storefront://registry/events/{dropinName}",
+        name: "Events by Dropin",
+        mimeType: "application/json",
+        description: "Events emitted and consumed by a specific dropin",
+    },
+    {
+        uriTemplate: "storefront://registry/containers/{dropinName}",
+        name: "Containers by Dropin",
+        mimeType: "application/json",
+        description: "Containers available in a specific dropin",
+    },
+    {
+        uriTemplate: "storefront://registry/api-functions/{dropinName}",
+        name: "API Functions by Dropin",
+        mimeType: "application/json",
+        description: "API functions available in a specific dropin",
+    },
+    {
+        uriTemplate: "storefront://registry/design-tokens/{category}",
+        name: "Design Tokens by Category",
+        mimeType: "application/json",
+        description: "Design tokens for a specific category (colors, typography, spacing, shapes, grid)",
+    },
+    {
+        uriTemplate: "storefront://docs/{section}",
+        name: "Documentation Section",
+        mimeType: "application/json",
+        description: "Official documentation pages for a specific section (e.g., dropins/cart, setup, merchants)",
+    },
+    {
+        uriTemplate: "storefront://registry/examples/{dropinName}",
+        name: "Examples by Dropin",
+        mimeType: "application/json",
+        description: "Working code examples for a specific dropin (extensions, blocks)",
+    },
+    {
+        uriTemplate: "storefront://registry/sdk/{packageName}",
+        name: "SDK Package Details",
+        mimeType: "application/json",
+        description: "Detailed API for a specific SDK package (elsie, event-bus, fetch-graphql, build-tools, recaptcha)",
+    },
+    {
+        uriTemplate: "storefront://registry/graphql/{dropinName}",
+        name: "GraphQL by Dropin",
+        mimeType: "application/json",
+        description: "GraphQL queries and mutations for a specific dropin with full resolved source",
+    },
+];
+const registryLoaders = {
+    slots: getSlotRegistry,
+    events: getEventCatalog,
+    containers: getContainerRegistry,
+    "api-functions": getApiFunctionRegistry,
+    extensions: getExtensionRegistry,
+    "design-tokens": getDesignTokenRegistry,
+    "block-patterns": getBlockPatternRegistry,
+    examples: getExamplesIndex,
+    sdk: getSdkRegistry,
+    graphql: getGraphqlRegistry,
+};
+function readRegistryResource(registryType) {
+    const loader = registryLoaders[registryType];
+    if (!loader) {
+        throw new McpError(ErrorCode.InvalidRequest, `Unknown registry type: ${registryType}`);
+    }
+    return JSON.stringify(loader(), null, 2);
+}
+const paramLookups = {
+    slots: {
+        getter: getSlotsByDropin,
+        notFound: (key) => `Dropin not found: ${key}. Available: ${getAllDropinNames().join(", ")}`,
+    },
+    events: {
+        getter: getEventsByDropin,
+    },
+    containers: {
+        getter: getContainersByDropin,
+        notFound: (key) => `Dropin not found: ${key}. Available: ${getAllDropinNames().join(", ")}`,
+    },
+    "api-functions": {
+        getter: getApiFunctionsByDropin,
+        notFound: (key) => `Dropin not found: ${key}. Available: ${getAllDropinNames().join(", ")}`,
+    },
+    examples: {
+        getter: getExamplesByDropin,
+        notFound: (key) => {
+            const available = (getExamplesIndex().dropins ?? []).map((d) => d.dropin);
+            return `No examples found for dropin: ${key}. Available: ${available.join(", ")}`;
+        },
+    },
+    sdk: {
+        getter: getSdkPackage,
+        notFound: (key) => `SDK package not found: ${key}. Available: ${Object.keys(getSdkRegistry().packages).join(", ")}`,
+    },
+    "design-tokens": {
+        getter: getDesignTokensByCategory,
+        notFound: (key) => `Category not found: ${key}. Available: ${Object.keys(getDesignTokenRegistry().categories).join(", ")}`,
+    },
+    graphql: {
+        getter: getGraphqlByDropin,
+        notFound: (key) => {
+            const available = Object.keys(getGraphqlRegistry().dropins ?? {});
+            return `No GraphQL operations found for dropin: ${key}. Available: ${available.join(", ")}`;
+        },
+    },
+};
+function readParameterizedResource(parts) {
+    const registryType = parts[0];
+    if (registryType === "slots" && parts.length === 3) {
+        const data = getSlotsByContainer(parts[1], parts[2]);
+        if (!data) {
+            throw new McpError(ErrorCode.InvalidRequest, `Container not found: ${parts[2]} in dropin ${parts[1]}`);
+        }
+        return {
+            mimeType: "application/json",
+            text: JSON.stringify(data, null, 2),
+        };
+    }
+    if (parts.length === 2) {
+        const lookup = paramLookups[registryType];
+        if (lookup) {
+            const data = lookup.getter(parts[1]);
+            if (data == null && lookup.notFound) {
+                throw new McpError(ErrorCode.InvalidRequest, lookup.notFound(parts[1]));
+            }
+            return {
+                mimeType: "application/json",
+                text: JSON.stringify(data, null, 2),
+            };
+        }
+    }
+    throw new McpError(ErrorCode.InvalidRequest, `Unsupported parameterized resource path: ${parts.join("/")}`);
+}
+export const getResourceHandlers = () => ({
+    listResources: async () => {
+        const guideResources = guides.map((guide) => ({
+            uri: guide.uri,
+            name: guide.name,
+            mimeType: "text/markdown",
+            description: guide.description,
+        }));
+        return {
+            resources: [...guideResources, ...registryResources],
+        };
+    },
+    listResourceTemplates: async () => {
+        return {
+            resourceTemplates,
+        };
+    },
+    readResource: async (request) => {
+        const uri = request.params.uri;
+        if (!uri.startsWith("storefront://")) {
+            throw new McpError(ErrorCode.InvalidRequest, `Invalid URI scheme. Expected storefront://, got: ${uri}`);
+        }
+        const path = uri.replace("storefront://", "");
+        const segments = path.split("/");
+        if (segments[0] === "guides") {
+            const guidePath = segments.slice(1).join("/");
+            const guide = guides.find((g) => g.uri === uri);
+            if (!guide) {
+                throw new McpError(ErrorCode.InvalidRequest, `Guide not found: ${guidePath}. Available: ${guides.map((g) => g.uri).join(", ")}`);
+            }
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: "text/markdown",
+                        text: guide.content,
+                    },
+                ],
+            };
+        }
+        if (segments[0] === "docs") {
+            if (segments.length === 1) {
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: "application/json",
+                            text: JSON.stringify(getDocsIndex(), null, 2),
+                        },
+                    ],
+                };
+            }
+            const sectionKey = segments.slice(1).join("/");
+            const sectionData = getDocsSection(sectionKey);
+            if (!sectionData) {
+                const index = getDocsIndex();
+                const available = index.sections?.map((s) => s.section) ?? [];
+                throw new McpError(ErrorCode.InvalidRequest, `Documentation section not found: ${sectionKey}. Available: ${available.join(", ")}`);
+            }
+            const enriched = {
+                ...sectionData,
+                pages: (sectionData.pages ?? []).map((page) => ({
+                    ...page,
+                    url: `${DOCS_BASE_URL}/${page.path}`,
+                })),
+            };
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify(enriched, null, 2),
+                    },
+                ],
+            };
+        }
+        if (segments[0] === "registry") {
+            const registryParts = segments.slice(1);
+            if (registryParts.length === 1) {
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: "application/json",
+                            text: readRegistryResource(registryParts[0]),
+                        },
+                    ],
+                };
+            }
+            const result = readParameterizedResource(registryParts);
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: result.mimeType,
+                        text: result.text,
+                    },
+                ],
+            };
+        }
+        throw new McpError(ErrorCode.InvalidRequest, `Unknown resource path: ${path}`);
+    },
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@dropins/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Adobe Commerce Storefront Dropins — provides AI assistants with deep knowledge of blocks, slots, extensions, events, and design tokens",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Adobe Commerce Storefront Team",
+  "type": "module",
+  "bin": {
+    "mcp-server-dropins": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "shx rm -rf dist && tsc && tsc --project tsconfig.scripts.json && shx cp -r registry dist/registry && tsx scripts/sanitize-registry.ts && shx chmod +x dist/*.js",
+    "sanitize:verbose": "tsx scripts/sanitize-registry.ts --verbose",
+    "typecheck": "tsc --noEmit && tsc --project tsconfig.scripts.json",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "generate": "tsx scripts/generate.ts",
+    "generate:registry": "tsx scripts/generate-registry.ts",
+    "generate:docs": "tsx scripts/generate-docs.ts",
+    "generate:examples": "tsx scripts/generate-examples.ts",
+    "stats": "tsx scripts/stats.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "audit:docs": "tsx scripts/audit-docs.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "zod": "^3.22.4",
+    "zod-to-json-schema": "^3.23.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "shx": "^0.3.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.2",
+    "vitest": "1"
+  }
+}