sfcc-dev-mcp 1.0.15 → 1.0.19

package/dist/core/tool-schemas/script-debugger-tools.js

@@ -0,0 +1,83 @@
+/**
+ * Script Debugger Tool Schemas
+ *
+ * Defines the MCP tool for evaluating scripts on SFCC instances
+ * using the Script Debugger API.
+ */
+export const SCRIPT_DEBUGGER_TOOLS = [
+    {
+        name: 'evaluate_script',
+        description: `Execute JavaScript code on the SFCC instance for quick testing and POC validation.
+
+This tool automates the entire workflow using the existing Default-Start endpoint:
+1. Creates a debugger session
+2. Sets a breakpoint on the Default.js controller (or custom file/line)
+3. Triggers the Default-Start endpoint via HTTP
+4. Evaluates your expression in the halted context
+5. Resumes and cleans up
+
+**Supports both SFRA and SiteGenesis** - automatically detects which storefront is deployed.
+
+**Use cases:**
+- Test SFCC API calls (e.g., ProductMgr, CustomerMgr)
+- Validate business logic before implementing in a cartridge
+- Quick POC to verify an approach works
+- Debug data issues by querying objects directly
+
+**Requirements:**
+- SFCC instance with script debugging enabled (Administration > Development Setup)
+- Business Manager user with "Modules - Script Debugger" functional permission
+- The site must have app_storefront_base (SFRA) or app_storefront_controllers (SiteGenesis) in its cartridge path
+
+**Example scripts:**
+- \`var ProductMgr = require('dw/catalog/ProductMgr'); return ProductMgr.getProduct('12345')?.name;\`
+- \`var Site = require('dw/system/Site'); return Site.current.ID;\`
+- \`return JSON.stringify({test: 'hello'});\`
+
+**Note:** Complex scripts with async operations may timeout. Keep scripts focused and synchronous.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                script: {
+                    type: 'string',
+                    description: `The JavaScript code to execute on the SFCC instance. 
+
+The script runs in a server-side context with access to all dw.* APIs.
+The expression is evaluated in the context of a halted request.
+
+Examples:
+- "var ProductMgr = require('dw/catalog/ProductMgr'); return ProductMgr.getProduct('SKU123')?.name;"
+- "var Site = require('dw/system/Site'); return Site.current.preferences.custom.myPreference;"
+- "return 1 + 1;"`,
+                },
+                timeout: {
+                    type: 'number',
+                    description: 'Maximum time in milliseconds to wait for script execution (default: 30000). Increase for complex scripts.',
+                    default: 30000,
+                },
+                siteId: {
+                    type: 'string',
+                    description: 'The site ID to execute the script against (e.g., "RefArch", "RefArchGlobal").',
+                    default: 'RefArch',
+                },
+                locale: {
+                    type: 'string',
+                    description: 'Storefront locale segment to use when triggering the Default-Start request (default: "default"). If the instance supports locale-less trigger, it will be tried first and locale will be used as fallback.',
+                    default: 'default',
+                },
+                breakpointFile: {
+                    type: 'string',
+                    description: `Optional: Custom controller file path for the breakpoint. Use this if automatic detection fails.
+Format: /{cartridge}/cartridge/controllers/{Controller}.js
+Example: "/app_storefront_base/cartridge/controllers/Default.js"`,
+                },
+                breakpointLine: {
+                    type: 'number',
+                    description: 'Optional: Specific line number for a single breakpoint. If omitted, breakpoints are set on strategic lines (1, 10, 20, 30, 40, 50) to catch executable code.',
+                },
+            },
+            required: ['script'],
+        },
+    },
+];
+//# sourceMappingURL=script-debugger-tools.js.map

package/dist/core/tool-schemas/script-debugger-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-debugger-tools.js","sourceRoot":"","sources":["../../../src/core/tool-schemas/script-debugger-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC;QACE,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;mGA2BkF;QAC/F,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE;;;;;;;;kBAQL;iBACT;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2GAA2G;oBACxH,OAAO,EAAE,KAAK;iBACf;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+EAA+E;oBAC5F,OAAO,EAAE,SAAS;iBACnB;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,4MAA4M;oBACzN,OAAO,EAAE,SAAS;iBACnB;gBACD,cAAc,EAAE;oBACd,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE;;iEAE0C;iBACxD;gBACD,cAAc,EAAE;oBACd,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,8JAA8J;iBAC5K;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;SACrB;KACF;CACF,CAAC"}

package/dist/core/tool-schemas/sfra-tools.d.ts

@@ -0,0 +1,63 @@
+/**
+ * SFRA Documentation Tool Schemas
+ */
+export declare const SFRA_DOCUMENTATION_TOOLS: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            documentName?: undefined;
+            query?: undefined;
+            category?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            documentName: {
+                type: string;
+                description: string;
+            };
+            query?: undefined;
+            category?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            documentName?: undefined;
+            category?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            category: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            documentName?: undefined;
+            query?: undefined;
+        };
+        required: string[];
+    };
+})[];
+//# sourceMappingURL=sfra-tools.d.ts.map

package/dist/core/tool-schemas/sfra-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sfra-tools.d.ts","sourceRoot":"","sources":["../../../src/core/tool-schemas/sfra-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA4DpC,CAAC"}

package/dist/core/tool-schemas/sfra-tools.js

@@ -0,0 +1,65 @@
+/**
+ * SFRA Documentation Tool Schemas
+ */
+export const SFRA_DOCUMENTATION_TOOLS = [
+    {
+        name: 'get_available_sfra_documents',
+        description: 'List all SFRA documentation including Server, Request, Response, QueryString, render module, and 26+ model docs (cart, account, billing, shipping, products, pricing).',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'get_sfra_document',
+        description: 'Get complete SFRA class or model documentation with properties, methods, and examples. Use for implementing controllers, middleware, or working with SFRA models.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                documentName: {
+                    type: 'string',
+                    description: 'Document name, e.g., "server", "request", "cart", "product-full", "account". Use get_available_sfra_documents for full list.',
+                },
+            },
+            required: ['documentName'],
+        },
+    },
+    {
+        name: 'search_sfra_documentation',
+        description: 'Search across all SFRA docs for concepts or functionality. Returns relevance-scored results with categorization.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Search term, e.g., "middleware", "routing", "cache", "cart", "pricing".',
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'get_sfra_documents_by_category',
+        description: 'Get SFRA documents filtered by functional area (core classes, product models, order/cart, customer, pricing, store).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    enum: ['core', 'product', 'order', 'customer', 'pricing', 'store', 'other'],
+                    description: 'Category to filter by: core (Server, Request, Response, etc.), product (product models), order (cart, billing, shipping), customer (account, address), pricing (price models), store (store models), other (utilities)',
+                },
+            },
+            required: ['category'],
+        },
+    },
+    {
+        name: 'get_sfra_categories',
+        description: 'Get all SFRA document categories with counts. Use to understand documentation organization before browsing.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+];
+//# sourceMappingURL=sfra-tools.js.map

package/dist/core/tool-schemas/sfra-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sfra-tools.js","sourceRoot":"","sources":["../../../src/core/tool-schemas/sfra-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC;QACE,IAAI,EAAE,8BAA8B;QACpC,WAAW,EAAE,wKAAwK;QACrL,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE;SACf;KACF;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,mKAAmK;QAChL,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,8HAA8H;iBAC5I;aACF;YACD,QAAQ,EAAE,CAAC,cAAc,CAAC;SAC3B;KACF;IACD;QACE,IAAI,EAAE,2BAA2B;QACjC,WAAW,EAAE,kHAAkH;QAC/H,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yEAAyE;iBACvF;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;KACF;IACD;QACE,IAAI,EAAE,gCAAgC;QACtC,WAAW,EAAE,sHAAsH;QACnI,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC;oBAC3E,WAAW,EAAE,wNAAwN;iBACtO;aACF;YACD,QAAQ,EAAE,CAAC,UAAU,CAAC;SACvB;KACF;IACD;QACE,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EAAE,6GAA6G;QAC1H,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE;SACf;KACF;CACF,CAAC"}

package/dist/core/tool-schemas/shared-schemas.d.ts

@@ -0,0 +1,350 @@
+/**
+ * Shared MCP Tool Schema Components
+ *
+ * Reusable schema definitions for MCP tool definitions.
+ * DRY: These are used across multiple tool categories.
+ */
+/**
+ * Common query schema for OCAPI search operations
+ */
+export declare const QUERY_SCHEMA: {
+    readonly type: "object";
+    readonly description: "Query to filter results";
+    readonly properties: {
+        readonly text_query: {
+            readonly type: "object";
+            readonly description: "Search for text in specific fields";
+            readonly properties: {
+                readonly fields: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Fields to search in (e.g., [\"id\", \"display_name\", \"description\"])";
+                };
+                readonly search_phrase: {
+                    readonly type: "string";
+                    readonly description: "Text to search for";
+                };
+            };
+            readonly required: readonly ["fields", "search_phrase"];
+        };
+        readonly term_query: {
+            readonly type: "object";
+            readonly description: "Search for exact term matches";
+            readonly properties: {
+                readonly fields: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Fields to search in";
+                };
+                readonly operator: {
+                    readonly type: "string";
+                    readonly description: "Query operator (e.g., \"is\", \"one_of\")";
+                };
+                readonly values: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Values to match";
+                };
+            };
+            readonly required: readonly ["fields", "operator", "values"];
+        };
+        readonly bool_query: {
+            readonly type: "object";
+            readonly description: "Combine multiple queries with boolean logic";
+            readonly properties: {
+                readonly must: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                    };
+                    readonly description: "Queries that must match (AND)";
+                };
+                readonly must_not: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                    };
+                    readonly description: "Queries that must not match";
+                };
+                readonly should: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                    };
+                    readonly description: "Queries that should match (OR)";
+                };
+            };
+        };
+        readonly match_all_query: {
+            readonly type: "object";
+            readonly description: "Match all documents - useful when you want all results or to filter with sorts/pagination only.";
+            readonly properties: {};
+        };
+    };
+};
+/**
+ * Common sorts schema for OCAPI search operations
+ */
+export declare const SORTS_SCHEMA: {
+    readonly type: "array";
+    readonly description: "Sort criteria";
+    readonly items: {
+        readonly type: "object";
+        readonly properties: {
+            readonly field: {
+                readonly type: "string";
+                readonly description: "Field to sort by";
+            };
+            readonly sort_order: {
+                readonly type: "string";
+                readonly enum: readonly ["asc", "desc"];
+                readonly description: "Sort order (default: asc)";
+            };
+        };
+        readonly required: readonly ["field"];
+    };
+};
+/**
+ * Common pagination schema for OCAPI search operations
+ */
+export declare const PAGINATION_SCHEMA: {
+    readonly start: {
+        readonly type: "number";
+        readonly description: "Start index for pagination (default: 0)";
+        readonly default: 0;
+    };
+    readonly count: {
+        readonly type: "number";
+        readonly description: "Number of results to return (default: 200)";
+        readonly default: 200;
+    };
+    readonly select: {
+        readonly type: "string";
+        readonly description: "Property selector (e.g., '(**)' for all properties)";
+    };
+};
+/**
+ * Factory to create search request schema with optional description override
+ */
+export declare function createSearchRequestSchema(queryDescription?: string): {
+    type: string;
+    description: string;
+    properties: {
+        start: {
+            readonly type: "number";
+            readonly description: "Start index for pagination (default: 0)";
+            readonly default: 0;
+        };
+        count: {
+            readonly type: "number";
+            readonly description: "Number of results to return (default: 200)";
+            readonly default: 200;
+        };
+        select: {
+            readonly type: "string";
+            readonly description: "Property selector (e.g., '(**)' for all properties)";
+        };
+        query: {
+            readonly type: "object";
+            readonly description: "Query to filter results";
+            readonly properties: {
+                readonly text_query: {
+                    readonly type: "object";
+                    readonly description: "Search for text in specific fields";
+                    readonly properties: {
+                        readonly fields: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                            readonly description: "Fields to search in (e.g., [\"id\", \"display_name\", \"description\"])";
+                        };
+                        readonly search_phrase: {
+                            readonly type: "string";
+                            readonly description: "Text to search for";
+                        };
+                    };
+                    readonly required: readonly ["fields", "search_phrase"];
+                };
+                readonly term_query: {
+                    readonly type: "object";
+                    readonly description: "Search for exact term matches";
+                    readonly properties: {
+                        readonly fields: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                            readonly description: "Fields to search in";
+                        };
+                        readonly operator: {
+                            readonly type: "string";
+                            readonly description: "Query operator (e.g., \"is\", \"one_of\")";
+                        };
+                        readonly values: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                            readonly description: "Values to match";
+                        };
+                    };
+                    readonly required: readonly ["fields", "operator", "values"];
+                };
+                readonly bool_query: {
+                    readonly type: "object";
+                    readonly description: "Combine multiple queries with boolean logic";
+                    readonly properties: {
+                        readonly must: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                            };
+                            readonly description: "Queries that must match (AND)";
+                        };
+                        readonly must_not: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                            };
+                            readonly description: "Queries that must not match";
+                        };
+                        readonly should: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                            };
+                            readonly description: "Queries that should match (OR)";
+                        };
+                    };
+                };
+                readonly match_all_query: {
+                    readonly type: "object";
+                    readonly description: "Match all documents - useful when you want all results or to filter with sorts/pagination only.";
+                    readonly properties: {};
+                };
+            };
+        } | {
+            description: string;
+            type: "object";
+            properties: {
+                readonly text_query: {
+                    readonly type: "object";
+                    readonly description: "Search for text in specific fields";
+                    readonly properties: {
+                        readonly fields: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                            readonly description: "Fields to search in (e.g., [\"id\", \"display_name\", \"description\"])";
+                        };
+                        readonly search_phrase: {
+                            readonly type: "string";
+                            readonly description: "Text to search for";
+                        };
+                    };
+                    readonly required: readonly ["fields", "search_phrase"];
+                };
+                readonly term_query: {
+                    readonly type: "object";
+                    readonly description: "Search for exact term matches";
+                    readonly properties: {
+                        readonly fields: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                            readonly description: "Fields to search in";
+                        };
+                        readonly operator: {
+                            readonly type: "string";
+                            readonly description: "Query operator (e.g., \"is\", \"one_of\")";
+                        };
+                        readonly values: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                            readonly description: "Values to match";
+                        };
+                    };
+                    readonly required: readonly ["fields", "operator", "values"];
+                };
+                readonly bool_query: {
+                    readonly type: "object";
+                    readonly description: "Combine multiple queries with boolean logic";
+                    readonly properties: {
+                        readonly must: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                            };
+                            readonly description: "Queries that must match (AND)";
+                        };
+                        readonly must_not: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                            };
+                            readonly description: "Queries that must not match";
+                        };
+                        readonly should: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                            };
+                            readonly description: "Queries that should match (OR)";
+                        };
+                    };
+                };
+                readonly match_all_query: {
+                    readonly type: "object";
+                    readonly description: "Match all documents - useful when you want all results or to filter with sorts/pagination only.";
+                    readonly properties: {};
+                };
+            };
+        };
+        sorts: {
+            readonly type: "array";
+            readonly description: "Sort criteria";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly field: {
+                        readonly type: "string";
+                        readonly description: "Field to sort by";
+                    };
+                    readonly sort_order: {
+                        readonly type: "string";
+                        readonly enum: readonly ["asc", "desc"];
+                        readonly description: "Sort order (default: asc)";
+                    };
+                };
+                readonly required: readonly ["field"];
+            };
+        };
+    };
+};
+/**
+ * Common date parameter schema
+ */
+export declare const DATE_PARAM_SCHEMA: {
+    readonly type: "string";
+    readonly description: "Date in YYYYMMDD format (default: today)";
+};
+/**
+ * Common limit parameter schema
+ */
+export declare function createLimitSchema(defaultValue: number, description?: string): {
+    type: string;
+    description: string;
+    default: number;
+};
+//# sourceMappingURL=shared-schemas.d.ts.map

package/dist/core/tool-schemas/shared-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schemas.d.ts","sourceRoot":"","sources":["../../../src/core/tool-schemas/shared-schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoEf,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;CAkBf,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;CAepB,CAAC;AAEX;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,gBAAgB,CAAC,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYlE;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;CAGpB,CAAC;AAEX;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;;;;EAM3E"}