sfcc-dev-mcp 1.0.16 → 1.0.20

package/src/core/tool-schemas/isml-tools.ts

@@ -1,89 +0,0 @@
-/**
- * ISML Documentation Tool Schemas
- */
-
-export const ISML_DOCUMENTATION_TOOLS = [
-  {
-    name: 'list_isml_elements',
-    description: 'List all ISML template elements with summaries. Includes control flow (isif, isloop), output (isprint), includes (isinclude, iscomponent), scripting (isscript), and caching (iscache).',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-    },
-  },
-  {
-    name: 'get_isml_element',
-    description: 'Get detailed documentation for an ISML element including syntax, attributes, examples, and use cases.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        elementName: {
-          type: 'string',
-          description: 'The ISML element name (e.g., \'isif\', \'isloop\', \'isprint\', \'isinclude\', \'iscomponent\'). The \'is\' prefix is optional.',
-        },
-        includeContent: {
-          type: 'boolean',
-          description: 'Whether to include full documentation content (default: true)',
-          default: true,
-        },
-        includeSections: {
-          type: 'boolean',
-          description: 'Whether to include section headings (default: true)',
-          default: true,
-        },
-        includeAttributes: {
-          type: 'boolean',
-          description: 'Whether to include attribute information (default: true)',
-          default: true,
-        },
-      },
-      required: ['elementName'],
-    },
-  },
-  {
-    name: 'search_isml_elements',
-    description: 'Search ISML elements by purpose, attribute name, or use case. Returns relevance-scored results with preview snippets.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        query: {
-          type: 'string',
-          description: 'Search term or concept (e.g., \'loop\', \'conditional\', \'format\', \'cache\', \'redirect\')',
-        },
-        category: {
-          type: 'string',
-          description: 'Optional category filter: control-flow, output, includes, scripting, cache, decorators, special, payment, or analytics',
-          enum: ['control-flow', 'output', 'includes', 'scripting', 'cache', 'decorators', 'special', 'payment', 'analytics'],
-        },
-        limit: {
-          type: 'number',
-          description: 'Maximum number of results to return',
-        },
-      },
-      required: ['query'],
-    },
-  },
-  {
-    name: 'get_isml_elements_by_category',
-    description: 'Get ISML elements filtered by category (control-flow, output, includes, scripting, cache, decorators, special, payment, analytics).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        category: {
-          type: 'string',
-          description: 'Category to filter by: control-flow (conditionals, loops), output (formatting), includes (templates, components), scripting (server-side code), cache (caching), decorators (layout), special (redirect, status), payment (payment elements), analytics (tracking)',
-          enum: ['control-flow', 'output', 'includes', 'scripting', 'cache', 'decorators', 'special', 'payment', 'analytics'],
-        },
-      },
-      required: ['category'],
-    },
-  },
-  {
-    name: 'get_isml_categories',
-    description: 'Get all ISML element categories with descriptions and counts.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-    },
-  },
-];

package/src/core/tool-schemas/log-tools.ts

@@ -1,196 +0,0 @@
-/**
- * Log Analysis Tool Schemas
- */
-
-import { DATE_PARAM_SCHEMA, createLimitSchema } from './shared-schemas.js';
-
-// Shared log level enum for consistency
-const LOG_LEVEL_ENUM = ['error', 'warn', 'info', 'debug'] as const;
-const JOB_LOG_LEVEL_ENUM = ['error', 'warn', 'info', 'debug', 'all'] as const;
-
-/**
- * Factory for creating get_latest_* tool definitions
- * DRY: Eliminates repetition for error/warn/info/debug tools
- */
-function createLatestLogToolSchema(level: string, description: string) {
-  return {
-    name: `get_latest_${level}`,
-    description,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        date: DATE_PARAM_SCHEMA,
-        limit: createLimitSchema(20, `Max ${level} entries to return (default: 20)`),
-      },
-    },
-  };
-}
-
-export const LOG_TOOLS = [
-  createLatestLogToolSchema(
-    'error',
-    'Get latest SFCC error log entries. Use for debugging crashes, exceptions, API failures, or when code throws errors.',
-  ),
-  createLatestLogToolSchema(
-    'warn',
-    'Get latest warning messages. Use to identify deprecations, potential issues, or suboptimal configurations.',
-  ),
-  createLatestLogToolSchema(
-    'info',
-    'Get latest info messages. Use to verify operations completed, track business logic execution, or monitor normal flow.',
-  ),
-  createLatestLogToolSchema(
-    'debug',
-    'Get latest debug messages. Use for step-by-step tracing, variable inspection, or when error logs lack context.',
-  ),
-  {
-    name: 'summarize_logs',
-    description: 'Get a health overview of all log activity with counts and key issues. Use as first step when investigating problems or for daily health checks.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        date: DATE_PARAM_SCHEMA,
-      },
-    },
-  },
-  {
-    name: 'search_logs',
-    description: 'Search logs for specific patterns, error messages, order numbers, user IDs, or custom identifiers. Essential for tracking specific transactions.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        pattern: {
-          type: 'string',
-          description: 'Search pattern or keyword to find in logs',
-        },
-        logLevel: {
-          type: 'string',
-          enum: LOG_LEVEL_ENUM,
-          description: 'Restrict search to specific log level for more focused results',
-        },
-        date: DATE_PARAM_SCHEMA,
-        limit: createLimitSchema(20, 'Number of matching entries to return (default: 20)'),
-      },
-      required: ['pattern'],
-    },
-  },
-  {
-    name: 'list_log_files',
-    description: 'List available log files with sizes and modification dates. Use to discover available log data or check log retention.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-    },
-  },
-  {
-    name: 'get_log_file_contents',
-    description: 'Read full contents of a specific log file. Use for detailed analysis when you need complete error traces or full context.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        filename: {
-          type: 'string',
-          description: 'Log filename or path. For standard logs: "error-blade-20240820-000000.log". For job logs: "jobs/JobName/Job-JobName-12345.log".',
-        },
-        maxBytes: {
-          type: 'number',
-          description: 'Maximum number of bytes to read from the file (default: 1MB). Use this to limit the amount of data returned for very large files.',
-          default: 1048576,
-        },
-        tailOnly: {
-          type: 'boolean',
-          description: 'Whether to read only the tail (end) of the file instead of the full contents (default: false). Set to true for large files to get recent entries.',
-          default: false,
-        },
-      },
-      required: ['filename'],
-    },
-  },
-];
-
-export const JOB_LOG_TOOLS = [
-  {
-    name: 'get_latest_job_log_files',
-    description: 'Get recent job log files from /Logs/jobs/. Job logs contain all log levels in single files. Use for debugging custom job steps.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        limit: createLimitSchema(10, 'Number of job log files to return (default: 10)'),
-      },
-    },
-  },
-  {
-    name: 'search_job_logs_by_name',
-    description: 'Find job log files by job name (partial match supported). Use to locate logs for a specific job.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        jobName: {
-          type: 'string',
-          description: 'The job name to search for (partial matches supported)',
-        },
-        limit: createLimitSchema(10, 'Number of job log files to return (default: 10)'),
-      },
-      required: ['jobName'],
-    },
-  },
-  {
-    name: 'get_job_log_entries',
-    description: 'Get job log entries by level (error/warn/info/debug/all). Unlike standard logs, job logs combine all levels in one file.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        level: {
-          type: 'string',
-          enum: JOB_LOG_LEVEL_ENUM,
-          description: 'Log level to retrieve (default: all). Use "all" to see all log levels from job executions.',
-          default: 'all',
-        },
-        limit: createLimitSchema(10, 'Number of job log entries to return (default: 10)'),
-        jobName: {
-          type: 'string',
-          description: 'Optional job name to filter results to a specific job',
-        },
-      },
-    },
-  },
-  {
-    name: 'search_job_logs',
-    description: 'Search job logs for patterns, error messages, or custom logging from job steps. Essential for debugging custom job code.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        pattern: {
-          type: 'string',
-          description: 'Search pattern or keyword to find in job logs',
-        },
-        level: {
-          type: 'string',
-          enum: JOB_LOG_LEVEL_ENUM,
-          description: 'Restrict search to specific log level (default: all)',
-          default: 'all',
-        },
-        limit: createLimitSchema(20, 'Number of matching entries to return (default: 20)'),
-        jobName: {
-          type: 'string',
-          description: 'Optional job name to restrict search to a specific job',
-        },
-      },
-      required: ['pattern'],
-    },
-  },
-  {
-    name: 'get_job_execution_summary',
-    description: 'Get execution summary for a job: timing, status, error counts, and step info. Use for monitoring job health and performance.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        jobName: {
-          type: 'string',
-          description: 'The job name to get execution summary for',
-        },
-      },
-      required: ['jobName'],
-    },
-  },
-];

package/src/core/tool-schemas/script-debugger-tools.ts

@@ -1,83 +0,0 @@
-/**
- * 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'],
-    },
-  },
-];

package/src/core/tool-schemas/sfra-tools.ts

@@ -1,65 +0,0 @@
-/**
- * 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: {},
-    },
-  },
-];

package/src/core/tool-schemas/shared-schemas.ts

@@ -1,158 +0,0 @@
-/**
- * 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 const QUERY_SCHEMA = {
-  type: 'object',
-  description: 'Query to filter results',
-  properties: {
-    text_query: {
-      type: 'object',
-      description: 'Search for text in specific fields',
-      properties: {
-        fields: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Fields to search in (e.g., ["id", "display_name", "description"])',
-        },
-        search_phrase: {
-          type: 'string',
-          description: 'Text to search for',
-        },
-      },
-      required: ['fields', 'search_phrase'],
-    },
-    term_query: {
-      type: 'object',
-      description: 'Search for exact term matches',
-      properties: {
-        fields: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Fields to search in',
-        },
-        operator: {
-          type: 'string',
-          description: 'Query operator (e.g., "is", "one_of")',
-        },
-        values: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Values to match',
-        },
-      },
-      required: ['fields', 'operator', 'values'],
-    },
-    bool_query: {
-      type: 'object',
-      description: 'Combine multiple queries with boolean logic',
-      properties: {
-        must: {
-          type: 'array',
-          items: { type: 'object' },
-          description: 'Queries that must match (AND)',
-        },
-        must_not: {
-          type: 'array',
-          items: { type: 'object' },
-          description: 'Queries that must not match',
-        },
-        should: {
-          type: 'array',
-          items: { type: 'object' },
-          description: 'Queries that should match (OR)',
-        },
-      },
-    },
-    match_all_query: {
-      type: 'object',
-      description: 'Match all documents - useful when you want all results or to filter with sorts/pagination only.',
-      properties: {},
-    },
-  },
-} as const;
-
-/**
- * Common sorts schema for OCAPI search operations
- */
-export const SORTS_SCHEMA = {
-  type: 'array',
-  description: 'Sort criteria',
-  items: {
-    type: 'object',
-    properties: {
-      field: {
-        type: 'string',
-        description: 'Field to sort by',
-      },
-      sort_order: {
-        type: 'string',
-        enum: ['asc', 'desc'],
-        description: 'Sort order (default: asc)',
-      },
-    },
-    required: ['field'],
-  },
-} as const;
-
-/**
- * Common pagination schema for OCAPI search operations
- */
-export const PAGINATION_SCHEMA = {
-  start: {
-    type: 'number',
-    description: 'Start index for pagination (default: 0)',
-    default: 0,
-  },
-  count: {
-    type: 'number',
-    description: 'Number of results to return (default: 200)',
-    default: 200,
-  },
-  select: {
-    type: 'string',
-    description: "Property selector (e.g., '(**)' for all properties)",
-  },
-} as const;
-
-/**
- * Factory to create search request schema with optional description override
- */
-export function createSearchRequestSchema(queryDescription?: string) {
-  return {
-    type: 'object',
-    description: 'The search request with query, sorting, and pagination options',
-    properties: {
-      query: queryDescription
-        ? { ...QUERY_SCHEMA, description: queryDescription }
-        : QUERY_SCHEMA,
-      sorts: SORTS_SCHEMA,
-      ...PAGINATION_SCHEMA,
-    },
-  };
-}
-
-/**
- * Common date parameter schema
- */
-export const DATE_PARAM_SCHEMA = {
-  type: 'string',
-  description: 'Date in YYYYMMDD format (default: today)',
-} as const;
-
-/**
- * Common limit parameter schema
- */
-export function createLimitSchema(defaultValue: number, description?: string) {
-  return {
-    type: 'number',
-    description: description ?? `Number of entries to return (default: ${defaultValue})`,
-    default: defaultValue,
-  };
-}