sfcc-dev-mcp 1.0.15 → 1.0.19

package/tests/mcp/README.md

@@ -6,6 +6,8 @@ This document describes the MCP (Model Context Protocol) tests for the SFCC Deve
 
 The project includes comprehensive MCP tests using both **YAML** and **Node.js** approaches with the [mcp-aegis](https://aegis.rhino-inquisitor.com/) testing library. The tests verify both **documentation-only mode** and **full mode with credentials**.
 
+> Note: The server is capability-gated. In real usage there is also an intermediate “WebDAV-only” surface (30 tools) when `hostname` + `username/password` are present (logs + job logs), but `client-id/client-secret` are not (so OCAPI Data API tools are not exposed). The test configs in this folder currently cover docs-only (17) and full (38).
+
 ## Test Structure
 
 ```
@@ -28,12 +30,12 @@ tests/mcp/
 ### Documentation-Only Mode
 - **File**: `aegis.config.docs-only.json`
 - **Command**: `node dist/index.js` (no credentials)
-- **Tools**: 15 tools (documentation, best practices, SFRA, cartridge generation)
+- **Tools**: 17 tools (documentation, SFRA, ISML, cartridge generation, agent instruction bootstrap)
 
 ### Full Mode with Credentials  
 - **File**: `aegis.config.with-dw.json`
 - **Command**: `node dist/index.js --dw-json ./tests/mcp/test-fixtures/dw.json`
-- **Tools**: 36 tools (includes log analysis, system objects, job logs, code versions)
+- **Tools**: 38 tools (includes log + job log analysis, system objects, code versions)
 
 ## Available Test Commands
 
@@ -79,15 +81,15 @@ npm run test:mcp:ci
 
 ### 2. Documentation-Only Mode Tests
 - **SFCC Documentation Tools** (5 tools): Class info, search, method discovery
-- **Best Practices Tools** (4 tools): Guides, search, hook references  
 - **SFRA Documentation Tools** (5 tools): Documents, search, categories
+- **ISML Documentation Tools** (5 tools): Element docs, category browsing, search
+- **Agent Instruction Tools** (2 tools): Sync AGENTS.md + bundled skills into a workspace, disable sync suggestions
 - **Cartridge Generation Tools** (1 tool): Structure generation
 - **Tool Availability**: Verifies log/OCAPI tools are NOT available
 
 ### 3. Full Mode Tests
 - **All Documentation Tools**: Same as documentation-only mode
-- **Log Analysis Tools** (8 tools): Error/warn/info/debug logs, search, summarization
-- **Job Log Tools** (5 tools): Job log files, entries, search, execution summaries
+- **Log & Job Log Tools** (13 tools): Runtime log tails + search, plus job log discovery/entries/search/execution summaries
 - **System Object Tools** (6 tools): System objects, attributes, site preferences
 - **Code Version Tools** (2 tools): List and activate code versions
 - **Authentication Testing**: Graceful handling of connection failures
@@ -163,24 +165,26 @@ To test full functionality:
 
 ## Test Coverage
 
-### Tools Tested in Documentation-Only Mode (15 tools)
+### Tools Tested in Documentation-Only Mode (17 tools)
 1. `get_sfcc_class_info` - SFCC class information
 2. `search_sfcc_classes` - SFCC class search
 3. `search_sfcc_methods` - SFCC method search  
 4. `list_sfcc_classes` - Complete SFCC class list
 5. `get_sfcc_class_documentation` - Raw SFCC class documentation
-6. `get_available_best_practice_guides` - Best practices list
-7. `get_best_practice_guide` - Specific best practice guide
-8. `search_best_practices` - Best practices search
-9. `get_hook_reference` - Hook reference tables
-10. `get_available_sfra_documents` - SFRA documents list
-11. `get_sfra_document` - Specific SFRA document
-12. `search_sfra_documentation` - SFRA documentation search
-13. `get_sfra_documents_by_category` - SFRA documents by category
-14. `get_sfra_categories` - SFRA document categories
-15. `generate_cartridge_structure` - Cartridge generation
-
-### Additional Tools in Full Mode (+21 tools = 36 total)
+6. `sync_agent_instructions` - Agent instruction bootstrap (AGENTS.md + bundled skills)
+7. `get_available_sfra_documents` - SFRA documents list
+8. `get_sfra_document` - Specific SFRA document
+9. `search_sfra_documentation` - SFRA documentation search
+10. `get_sfra_documents_by_category` - SFRA documents by category
+11. `get_sfra_categories` - SFRA document categories
+12. `list_isml_elements` - ISML element listing
+13. `get_isml_element` - ISML element documentation
+14. `search_isml_elements` - ISML element search
+15. `get_isml_elements_by_category` - ISML elements by category
+16. `get_isml_categories` - ISML categories
+17. `generate_cartridge_structure` - Cartridge generation
+
+### Additional Tools in Full Mode (+21 tools = 38 total)
 
 **Log Analysis Tools (8)**:
 - `get_latest_error`, `get_latest_warn`, `get_latest_info`, `get_latest_debug`

package/tests/mcp/node/activate-code-version-advanced.full-mode.programmatic.test.js

@@ -49,7 +49,7 @@ describe('activate_code_version Advanced Programmatic Tests (Full Mode)', () =>
       
       assert.ok(activateTool, 'activate_code_version tool should be available');
       assert.equal(activateTool.name, 'activate_code_version');
-      assert.ok(activateTool.description.includes('Activate a specific code version'));
+      assert.ok(activateTool.description.includes('Activate a code version'));
       
       // Validate input schema
       assert.equal(activateTool.inputSchema.type, 'object');
@@ -112,22 +112,21 @@ describe('activate_code_version Advanced Programmatic Tests (Full Mode)', () =>
     });
 
     test('should handle edge case codeVersionId values', async () => {
-      const edgeCases = [
-        'a'.repeat(1000),                    // Very long ID
-        'test-version-with-special-chars!@#$%^&*()', // Special characters
-        'version with spaces',                // Spaces
-        'UPPERCASE-VERSION',                  // Case variations
-        'version_nonexistent_test',          // Non-existent version
-        'version.with.dots',                 // Dots
-        '123-numeric-start',                 // Starting with numbers
-        'unicode-测试-version',               // Unicode characters
+      // Edge cases that pass client-side validation (valid format but non-existent)
+      // These should reach the SFCC API and get 404 errors
+      const validFormatEdgeCases = [
+        'a'.repeat(100),                     // Long but valid ID
+        'UPPERCASE-VERSION',                  // Case variations (valid)
+        'version_nonexistent_test',          // Non-existent version (valid format)
+        'version.with.dots',                 // Dots (valid)
+        '123-numeric-start',                 // Starting with numbers (valid)
       ];
 
-      for (const edgeCase of edgeCases) {
+      for (const edgeCase of validFormatEdgeCases) {
         const result = await client.callTool('activate_code_version', { codeVersionId: edgeCase });
         assert.equal(result.isError, true, `Should handle edge case: ${edgeCase}`);
         
-        // Should get 404 or similar SFCC error, not parameter validation error
+        // Should get 404 or similar SFCC error for valid-format but non-existent versions
         assert.ok(
           result.content[0].text.includes('404') || 
           result.content[0].text.includes('not found') ||
@@ -135,6 +134,25 @@ describe('activate_code_version Advanced Programmatic Tests (Full Mode)', () =>
           `Should get SFCC API error for edge case: ${edgeCase}, got: ${result.content[0].text}`
         );
       }
+
+      // Edge cases that fail client-side validation (invalid characters)
+      // These should be caught early with validation errors for security
+      const invalidFormatEdgeCases = [
+        'test-version-with-special-chars!@#$%^&*()', // Special characters
+        'version with spaces',                // Spaces
+        'unicode-测试-version',               // Unicode characters
+      ];
+
+      for (const edgeCase of invalidFormatEdgeCases) {
+        const result = await client.callTool('activate_code_version', { codeVersionId: edgeCase });
+        assert.equal(result.isError, true, `Should reject invalid format: ${edgeCase}`);
+        
+        // Should get client-side validation error for invalid format
+        assert.ok(
+          result.content[0].text.includes('Invalid code version ID format'),
+          `Should get validation error for invalid format: ${edgeCase}, got: ${result.content[0].text}`
+        );
+      }
     });
   });
 

package/tests/mcp/node/evaluate-script.full-mode.programmatic.test.js

@@ -0,0 +1,387 @@
+import { test, describe, before, after, beforeEach } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { connect } from 'mcp-aegis';
+
+describe('evaluate_script - Full Mode Programmatic Tests', () => {
+  let client;
+
+  before(async () => {
+    client = await connect('./aegis.config.with-dw.json');
+  });
+
+  after(async () => {
+    if (client?.connected) {
+      await client.disconnect();
+    }
+  });
+
+  beforeEach(() => {
+    // CRITICAL: Clear all buffers to prevent leaking into next tests
+    client.clearAllBuffers();
+  });
+
+  // Helper functions for common validations
+  function assertValidMCPResponse(result) {
+    assert.ok(result.content, 'Should have content');
+    assert.ok(Array.isArray(result.content), 'Content should be array');
+    assert.equal(typeof result.isError, 'boolean', 'isError should be boolean');
+    assert.equal(result.content[0].type, 'text', 'Content should be text type');
+  }
+
+  function parseResultJSON(result) {
+    const text = result.content[0].text;
+    return JSON.parse(text);
+  }
+
+  function assertSuccessResponse(result) {
+    assertValidMCPResponse(result);
+    assert.equal(result.isError, false, 'Should not be an MCP error response');
+
+    const data = parseResultJSON(result);
+    assert.equal(data.success, true, 'Script execution should be successful');
+    assert.ok(typeof data.executionTimeMs === 'number', 'Should include execution time');
+    assert.ok(data.result !== undefined, 'Should include result');
+  }
+
+  // Core functionality tests
+  describe('Core Functionality', () => {
+    test('should evaluate simple arithmetic expression', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1'
+      });
+      
+      assertSuccessResponse(result);
+      
+      const data = parseResultJSON(result);
+      assert.equal(data.result, '2', 'Should return correct arithmetic result');
+    });
+
+    test('should evaluate expression with return statement', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: 'return 1 + 1;'
+      });
+      
+      assertSuccessResponse(result);
+      
+      const data = parseResultJSON(result);
+      assert.equal(data.result, '2', 'Should handle return statement');
+    });
+
+    test('should include execution time in response', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1'
+      });
+      
+      assertSuccessResponse(result);
+      
+      const data = parseResultJSON(result);
+      assert.ok(data.executionTimeMs >= 0, 'Execution time should be non-negative');
+      assert.ok(data.executionTimeMs < 30000, 'Execution time should be reasonable');
+    });
+
+    test('should evaluate SFCC Site API expression', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: 'var Site = require("dw/system/Site"); return Site.current.ID;'
+      });
+      
+      assertSuccessResponse(result);
+      
+      const data = parseResultJSON(result);
+      assert.equal(data.result, 'MockSiteID', 'Should return mocked Site ID');
+    });
+
+    test('should evaluate ProductMgr expression', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: 'var ProductMgr = require("dw/catalog/ProductMgr"); return ProductMgr.getProduct("12345");'
+      });
+      
+      assertSuccessResponse(result);
+      
+      const data = parseResultJSON(result);
+      assert.equal(data.result, 'MockProduct', 'Should return mocked product');
+    });
+
+    test('should evaluate JSON.stringify expression', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: 'return JSON.stringify({test: "hello"});'
+      });
+      
+      assertSuccessResponse(result);
+      
+      const data = parseResultJSON(result);
+      assert.equal(data.result, '{"test":"hello"}', 'Should return JSON string');
+    });
+  });
+
+  // Parameter handling tests
+  describe('Parameter Handling', () => {
+    test('should accept siteId parameter', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1',
+        siteId: 'RefArch'
+      });
+      
+      assertSuccessResponse(result);
+    });
+
+    test('should accept different siteId values', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1',
+        siteId: 'RefArchGlobal'
+      });
+      
+      assertSuccessResponse(result);
+    });
+
+    test('should accept siteId in Sites-{id}-Site format', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1',
+        siteId: 'Sites-RefArchGlobal-Site'
+      });
+
+      assertSuccessResponse(result);
+    });
+
+    test('should accept locale parameter', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1',
+        locale: 'default'
+      });
+
+      assertSuccessResponse(result);
+    });
+
+    test('should accept timeout parameter', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1',
+        timeout: 15000
+      });
+      
+      assertSuccessResponse(result);
+    });
+
+    test('should accept custom breakpoint parameters', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1',
+        breakpointFile: '/app_storefront_base/cartridge/controllers/Default.js',
+        breakpointLine: 26
+      });
+      
+      assertSuccessResponse(result);
+    });
+
+    test('should accept custom breakpoint file without line (defaults to strategic lines)', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1',
+        breakpointFile: '/app_storefront_base/cartridge/controllers/Default.js'
+      });
+
+      assertSuccessResponse(result);
+    });
+
+    test('should use default siteId when not provided', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1'
+      });
+      
+      assertSuccessResponse(result);
+      // Default siteId is RefArch - script should still execute successfully
+    });
+  });
+
+  // Error handling tests
+  describe('Error Handling', () => {
+    test('should fail when script parameter is missing', async () => {
+      const result = await client.callTool('evaluate_script', {});
+      
+      assertValidMCPResponse(result);
+      assert.equal(result.isError, true, 'Should be an error when script is missing');
+      assert.ok(result.content[0].text.toLowerCase().includes('script') || 
+                result.content[0].text.toLowerCase().includes('required'),
+        'Error should mention script or required');
+    });
+
+    test('should fail when script parameter is empty string', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: ''
+      });
+      
+      assertValidMCPResponse(result);
+      assert.equal(result.isError, true, 'Should be an error when script is empty');
+    });
+
+    test('should handle null script parameter', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: null
+      });
+      
+      assertValidMCPResponse(result);
+      assert.equal(result.isError, true, 'Should be an error when script is null');
+    });
+  });
+
+  // Response structure tests
+  describe('Response Structure', () => {
+    test('should return properly structured success response', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1'
+      });
+      
+      assertValidMCPResponse(result);
+      assert.equal(result.isError, false, 'Should not be an MCP error');
+      
+      const data = parseResultJSON(result);
+      
+      // Verify all expected fields
+      assert.ok('success' in data, 'Should have success field');
+      assert.ok('result' in data, 'Should have result field');
+      assert.ok('executionTimeMs' in data, 'Should have executionTimeMs field');
+      
+      assert.equal(typeof data.success, 'boolean', 'success should be boolean');
+      assert.equal(typeof data.executionTimeMs, 'number', 'executionTimeMs should be number');
+    });
+
+    test('should return properly structured error response', async () => {
+      const result = await client.callTool('evaluate_script', {});
+      
+      assertValidMCPResponse(result);
+      // Validation errors should have isError true
+      assert.equal(result.isError, true, 'Validation error should have isError=true');
+    });
+
+    test('should return JSON-formatted text content', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1'
+      });
+      
+      assertValidMCPResponse(result);
+      
+      // Verify content is valid JSON
+      const text = result.content[0].text;
+      let parsed;
+      assert.doesNotThrow(() => {
+        parsed = JSON.parse(text);
+      }, 'Content should be valid JSON');
+      
+      assert.ok(typeof parsed === 'object', 'Parsed content should be an object');
+    });
+  });
+
+  // Tool metadata tests
+  describe('Tool Metadata', () => {
+    test('should be listed in available tools', async () => {
+      const tools = await client.listTools();
+      const toolNames = tools.map(t => t.name);
+      
+      assert.ok(toolNames.includes('evaluate_script'), 'evaluate_script should be in tool list');
+    });
+
+    test('should have correct input schema', async () => {
+      const tools = await client.listTools();
+      const evalTool = tools.find(t => t.name === 'evaluate_script');
+      
+      assert.ok(evalTool, 'Tool should exist');
+      assert.ok(evalTool.inputSchema, 'Tool should have inputSchema');
+      assert.equal(evalTool.inputSchema.type, 'object', 'Schema type should be object');
+      
+      // Check required fields
+      assert.ok(evalTool.inputSchema.required.includes('script'), 'script should be required');
+      
+      // Check properties
+      const props = evalTool.inputSchema.properties;
+      assert.ok(props.script, 'Should have script property');
+      assert.ok(props.siteId, 'Should have siteId property');
+      assert.ok(props.locale, 'Should have locale property');
+      assert.ok(props.timeout, 'Should have timeout property');
+    });
+
+    test('should have description', async () => {
+      const tools = await client.listTools();
+      const evalTool = tools.find(t => t.name === 'evaluate_script');
+      
+      assert.ok(evalTool.description, 'Tool should have description');
+      assert.ok(evalTool.description.length > 20, 'Description should be meaningful');
+    });
+  });
+
+  // Performance tests
+  describe('Performance', () => {
+    test('should complete simple evaluation within timeout', async () => {
+      const startTime = Date.now();
+      
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1',
+        timeout: 10000
+      });
+      
+      const elapsed = Date.now() - startTime;
+      
+      assertSuccessResponse(result);
+      assert.ok(elapsed < 10000, `Should complete within timeout (took ${elapsed}ms)`);
+    });
+
+    test('should report accurate execution time', async () => {
+      const result = await client.callTool('evaluate_script', {
+        script: '1 + 1'
+      });
+      
+      assertSuccessResponse(result);
+      
+      const data = parseResultJSON(result);
+      // Execution time should be positive and reasonable
+      assert.ok(data.executionTimeMs > 0, 'Execution time should be positive');
+      assert.ok(data.executionTimeMs < 15000, 'Execution time should be less than 15 seconds');
+    });
+  });
+
+  // Multi-step workflow tests
+  describe('Multi-step Workflows', () => {
+    test('should execute multiple scripts sequentially', async () => {
+      // First evaluation
+      const result1 = await client.callTool('evaluate_script', {
+        script: '1 + 1'
+      });
+      assertSuccessResponse(result1);
+      
+      // Clear buffers between calls
+      client.clearAllBuffers();
+      
+      // Second evaluation
+      const result2 = await client.callTool('evaluate_script', {
+        script: '2 + 2'
+      });
+      assertSuccessResponse(result2);
+      
+      // Both should have succeeded independently
+      const data1 = parseResultJSON(result1);
+      const data2 = parseResultJSON(result2);
+      
+      assert.equal(data1.result, '2', 'First result should be 2');
+      // Note: Mock server returns 'MockResult' for unrecognized expressions
+      assert.ok(data2.result, 'Second result should exist');
+    });
+
+    test('should handle alternating success and error scenarios', async () => {
+      // Success case
+      const successResult = await client.callTool('evaluate_script', {
+        script: '1 + 1'
+      });
+      assertSuccessResponse(successResult);
+      
+      client.clearAllBuffers();
+      
+      // Error case (missing script)
+      const errorResult = await client.callTool('evaluate_script', {});
+      assertValidMCPResponse(errorResult);
+      assert.equal(errorResult.isError, true, 'Should be an error');
+      
+      client.clearAllBuffers();
+      
+      // Success case again (should still work after error)
+      const successResult2 = await client.callTool('evaluate_script', {
+        script: '1 + 1'
+      });
+      assertSuccessResponse(successResult2);
+    });
+  });
+});

package/tests/mcp/node/generate-cartridge-structure.docs-only.programmatic.test.js

@@ -556,15 +556,21 @@ describe('generate_cartridge_structure Programmatic Tests', () => {
         fullProjectSetup: false
       });
 
-      // The tool should either succeed or provide a clear error message about name length
-      if (result.isError) {
-        assert.ok(result.content[0].text.includes('Error'), 'Should provide clear error for long names');
-      } else {
-        const response = parseToolResponse(result);
-        assert.equal(response.success, true, 'Should handle long cartridge names if accepted');
-        
+      // The tool should return a response with success: false for names exceeding 64 characters
+      const response = parseToolResponse(result);
+      
+      if (response.success) {
+        // If somehow accepted, verify structure was created
         const cartridgeDir = join(testDir, 'cartridges', longCartridgeName);
-        assert.ok(await directoryExists(cartridgeDir), 'Should create directory with long name');
+        assert.ok(await directoryExists(cartridgeDir), 'Should create directory with long name if accepted');
+      } else {
+        // Should provide clear error message about name constraints
+        assert.ok(
+          response.message.includes('too long') || 
+          response.message.includes('64 characters') ||
+          response.message.includes('valid identifier'),
+          `Should provide clear error for long names, got: ${response.message}`
+        );
       }
     });
   });