Merge branch 'develop' into feature/address-autocompletion

Author: dannyphan2000

packages/pwa-kit-mcp/CHANGELOG.md

@@ -1,5 +1,6 @@
 ## 0.5.0-dev (Oct 24, 2025)
 - Retired the pwakit_create_component tool [#3437](https://github.com/SalesforceCommerceCloud/pwa-kit/issues/3437)
+- Added the fallback path for the custom Api tool [#3458] (https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3458)
 
 ## 0.4.0 (Oct 24, 2025)
 - Unexposed the extra parameters on create_page tool. [#3359] (https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3359), [#3379] (https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3379)

packages/pwa-kit-mcp/README.md

@@ -51,9 +51,13 @@ The PWA Kit MCP Server offers the following intelligent tools tailored to Salesf
   *Example: `How do I get a product?`*
 
 * **`scapi_custom_api_discovery`**:
-  Discovers custom SCAPI APIs registered on BM, and fetches the schema of those APIs. Requires credential configuration described in the  🔧 Configuration Options section.  
+  Discovers custom SCAPI APIs registered on BM, and fetches the schema of those APIs. Requires credential configuration described in the 🔧 Configuration Options section.  
   *Note: Ensure your API Client has access to your instance and has 'sfcc.custom-apis' as allowed scope*
 
+  **Fallback Mode**: If SFCC credentials are not available, the tool will search for `api.json` and `schema.yaml` files locally in the following order:
+  1. `SFCC_CARTRIDGE_PATH` environment variable (if set) - searches recursively up to 10 levels deep
+  2. `PWA_STOREFRONT_APP_PATH` - searches current directory and parent directories (up to filesystem root or home directory, max 10 levels), then recursively down 10 levels in each
+  
   *Custom API DX Endpoint Documentation*: [https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-apis?meta=getEndpoints](https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-apis?meta=getEndpoints)
 
 
@@ -139,7 +143,55 @@ SFCC_CLIENT_ID=your-client-id
 SFCC_CLIENT_SECRET=your-client-secret
 ```
 
-**Note:** Environment variables take precedence over`dw.json` values if both are provided.
+**Note:** Environment variables take precedence over `dw.json` values if both are provided.
+
+#### Option 3: Local Custom API Files (Fallback for Custom API Discovery)
+
+For the `scapi_custom_api_discovery` tool, if SFCC credentials are not available, you can provide local custom API files:
+
+**Method 1: Direct Path** - Set the `SFCC_CARTRIDGE_PATH` environment variable to point to your custom API cartridge directory:
+
+```json
+{
+  "mcpServers": {
+    "pwa-kit": {
+      "command": "npx",
+      "args": ["-y", "@salesforce/pwa-kit-mcp"],
+      "env": {
+        "PWA_STOREFRONT_APP_PATH": "{{path-to-app-directory}}",
+        "SFCC_CARTRIDGE_PATH": "/path/to/your/cartridge"
+      }
+    }
+  }
+}
+```
+
+**Method 2: Auto-discovery** - If `SFCC_CARTRIDGE_PATH` is not set, the tool will automatically search for `api.json` and `schema.yaml` files starting from `PWA_STOREFRONT_APP_PATH` and traversing up through parent directories until it reaches the filesystem root or home directory (max 10 levels). At each directory level, it searches recursively down through subdirectories (up to 10 levels deep).
+
+**File Structure Expected:**
+```
+your-custom-api-directory/
+├── api.json          # Custom API metadata
+└── schema.yaml       # OpenAPI schema (optional)
+```
+
+**Example `api.json`:**
+```json
+{
+  "apiName": "reviews",
+  "apiVersion": "v1",
+  "cartridgeName": "plugin_custom_api_intro",
+  "endpointPath": "reviews",
+  "httpMethod": "GET",
+  "securityScheme": "bearer",
+  "baseUrl": "https://your-shortcode.api.commercecloud.salesforce.com/custom/reviews/v1"
+}
+```
+
+**Search Priority:**
+1. SFCC credentials (dw.json or environment variables)
+2. `SFCC_CARTRIDGE_PATH` environment variable - searches recursively up to 10 levels deep in subdirectories
+3. `PWA_STOREFRONT_APP_PATH` and up to 5 parent directories - searches recursively up to 10 levels deep in subdirectories at each level
 
 ## 📊 Telemetry
 

packages/pwa-kit-mcp/src/tools/custom-api-discovery.js

@@ -4,7 +4,13 @@
  * SPDX-License-Identifier: BSD-3-Clause
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
-import {loadConfig, getOAuthToken, callCustomApiDxEndpoint, logMCPMessage} from '../utils/utils.js'
+import {
+    loadConfig,
+    getOAuthToken,
+    callCustomApiDxEndpoint,
+    logMCPMessage,
+    loadCustomApiFromFallbackPath
+} from '../utils/utils.js'
 import {
     parseWebDAVDirectories,
     parseWebDAVResponse,
@@ -91,15 +97,28 @@ function fetchAndValidateConfigs() {
     const config = loadConfig()
     const {clientId, clientSecret, organizationId, instanceId, shortCode, hostname} = config
 
-    // Validate configuration fields
-    const nullConfigFields = Object.entries(config)
-        .filter(([, value]) => value === null || value === undefined)
-        .map(([key]) => key)
+    // Define which fields are critical for SFCC API connection
+    const criticalFields = ['clientId', 'clientSecret', 'organizationId', 'instanceId']
+
+    // Check which critical fields are missing
+    const missingCriticalFields = criticalFields.filter(
+        (field) => !config[field] || config[field].trim() === ''
+    )
+
+    // If all critical fields are missing, use fallback mode (local file search)
+    if (missingCriticalFields.length === criticalFields.length) {
+        return {isFallback: true}
+    }
 
-    if (nullConfigFields.length > 0) {
-        throw new Error(`Required configuration fields are null: ${nullConfigFields.join(', ')}`)
+    // If some (but not all) critical fields are missing, throw an error with helpful message
+    if (missingCriticalFields.length > 0) {
+        throw new Error(
+            `Required SFCC API credentials are missing: ${missingCriticalFields.join(', ')}. ` +
+                `Either provide all credentials or use SFCC_CARTRIDGE_PATH environment variable for local fallback.`
+        )
     }
 
+    // All critical fields present, return config
     return {clientId, clientSecret, organizationId, instanceId, shortCode, hostname}
 }
 
@@ -207,6 +226,37 @@ async function searchRecursivelyForApiName(
     return {searchResults}
 }
 
+/**
+ * Processes custom API data from local fallback path
+ * @returns {Array} Array of processed custom API entries
+ */
+function processFallbackCustomApi() {
+    const fallbackData = loadCustomApiFromFallbackPath()
+
+    if (!fallbackData) {
+        return []
+    }
+
+    const {apiJson, schemaYaml, source} = fallbackData
+
+    // Transform api.json structure to match expected output format
+    const processedEntry = {
+        apiName: apiJson.apiName || apiJson.name,
+        apiVersion: apiJson.apiVersion || apiJson.version,
+        cartridgeName: apiJson.cartridgeName || 'local-fallback',
+        endpointPath: apiJson.endpointPath || apiJson.path,
+        httpMethod: apiJson.httpMethod || apiJson.method,
+        status: 'active',
+        securityScheme: apiJson.securityScheme || 'unknown',
+        siteId: apiJson.siteId || null,
+        baseUrl: apiJson.baseUrl || 'local-fallback',
+        schema: schemaYaml,
+        source: source
+    }
+
+    return [processedEntry]
+}
+
 export default {
     name: 'scapi_custom_api_discovery',
     description:
@@ -215,8 +265,67 @@ export default {
     fn: async () => {
         let dxEndpointResponse = null
         let activeCodeVersion = null
-        const {clientId, clientSecret, organizationId, instanceId, shortCode, hostname} =
-            fetchAndValidateConfigs()
+
+        const config = fetchAndValidateConfigs()
+
+        // Handle fallback scenario
+        if (config.isFallback) {
+            try {
+                const fallbackApis = processFallbackCustomApi()
+
+                if (fallbackApis.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(
+                                    {
+                                        metadata: {
+                                            fallback: true,
+                                            activeCodeVersion: null,
+                                            timestamp: new Date().toISOString(),
+                                            totalApis: 0,
+                                            message:
+                                                'No SFCC configuration found (dw.json or env vars) and no local fallback path available. Please configure SFCC_CARTRIDGE_PATH environment variable or PWA_STOREFRONT_APP_PATH, or provide SFCC credentials.'
+                                        },
+                                        customApis: []
+                                    },
+                                    null,
+                                    2
+                                )
+                            }
+                        ]
+                    }
+                }
+
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(
+                                {
+                                    metadata: {
+                                        fallback: true,
+                                        activeCodeVersion: 'local-filesystem',
+                                        timestamp: new Date().toISOString(),
+                                        totalApis: fallbackApis.length,
+                                        source: fallbackApis[0]?.source || 'local-fallback'
+                                    },
+                                    customApis: fallbackApis
+                                },
+                                null,
+                                2
+                            )
+                        }
+                    ]
+                }
+            } catch (error) {
+                return toErrorResponse(error, [])
+            }
+        }
+
+        // Continue with existing SFCC API logic
+        const {clientId, clientSecret, organizationId, instanceId, shortCode, hostname} = config
         const customApiHost = `${shortCode}.api.commercecloud.salesforce.com`
         const oauthScope = `SALESFORCE_COMMERCE_API:${instanceId} sfcc.custom-apis`
 

packages/pwa-kit-mcp/src/tools/custom-api-discovery.test.js

@@ -21,9 +21,13 @@ jest.mock('../utils/utils.js', () => ({
     throwCustomApiError: jest.fn(),
     getOAuthToken: jest.fn(),
     callCustomApiDxEndpoint: jest.fn(),
-    logMCPMessage: jest.fn()
+    logMCPMessage: jest.fn(),
+    loadCustomApiFromFallbackPath: jest.fn()
 }))
 
+// Import mocked utilities
+import {loadConfig, loadCustomApiFromFallbackPath} from '../utils/utils.js'
+
 // Mock fetch globally
 global.fetch = jest.fn()
 
@@ -380,7 +384,117 @@ describe('CustomApiTool', () => {
         })
 
         await expect(CustomApiTool.fn()).rejects.toThrow(
-            'Required configuration fields are null: clientSecret, organizationId'
+            'Required SFCC API credentials are missing: clientSecret, organizationId'
         )
     })
+
+    describe('Fallback path scenarios', () => {
+        beforeEach(() => {
+            jest.clearAllMocks()
+        })
+
+        test('should use fallback path when all SFCC config fields are null', async () => {
+            // Mock all config fields as null (triggers fallback)
+            loadConfig.mockReturnValue({
+                clientId: null,
+                clientSecret: null,
+                organizationId: null,
+                instanceId: null,
+                shortCode: null,
+                hostname: null
+            })
+
+            // Mock fallback data
+            loadCustomApiFromFallbackPath.mockReturnValue({
+                apiJson: {
+                    apiName: 'reviews',
+                    apiVersion: 'v1',
+                    cartridgeName: 'plugin_custom_api_intro',
+                    endpointPath: 'reviews',
+                    httpMethod: 'GET',
+                    securityScheme: 'bearer',
+                    baseUrl: 'https://test.api.commercecloud.salesforce.com/custom/reviews/v1'
+                },
+                schemaYaml: 'openapi: 3.0.0...',
+                source: 'SFCC_CARTRIDGE_PATH'
+            })
+
+            const result = await CustomApiTool.fn()
+
+            expect(result.content[0].type).toBe('text')
+            const parsedResult = JSON.parse(result.content[0].text)
+            expect(parsedResult.metadata.fallback).toBe(true)
+            expect(parsedResult.metadata.source).toBe('SFCC_CARTRIDGE_PATH')
+            expect(parsedResult.customApis).toHaveLength(1)
+            expect(parsedResult.customApis[0].apiName).toBe('reviews')
+        })
+
+        test('should return empty response when fallback path returns no data', async () => {
+            // Mock all config fields as null (triggers fallback)
+            loadConfig.mockReturnValue({
+                clientId: null,
+                clientSecret: null,
+                organizationId: null,
+                instanceId: null,
+                shortCode: null,
+                hostname: null
+            })
+
+            // Mock fallback returning null
+            loadCustomApiFromFallbackPath.mockReturnValue(null)
+
+            const result = await CustomApiTool.fn()
+
+            expect(result.content[0].type).toBe('text')
+            const parsedResult = JSON.parse(result.content[0].text)
+            expect(parsedResult.metadata.fallback).toBe(true)
+            expect(parsedResult.metadata.totalApis).toBe(0)
+            expect(parsedResult.customApis).toEqual([])
+            expect(parsedResult.metadata.message).toContain('No SFCC configuration found')
+        })
+
+        test('should use fallback when all critical fields are missing', async () => {
+            // Mock all 4 critical fields as null (triggers fallback)
+            loadConfig.mockReturnValue({
+                clientId: null,
+                clientSecret: null,
+                organizationId: null,
+                instanceId: null,
+                shortCode: 'test',
+                hostname: 'test.com'
+            })
+
+            loadCustomApiFromFallbackPath.mockReturnValue({
+                apiJson: {
+                    apiName: 'test-api',
+                    apiVersion: 'v1'
+                },
+                schemaYaml: null,
+                source: 'PWA_STOREFRONT_APP_PATH'
+            })
+
+            const result = await CustomApiTool.fn()
+
+            expect(result.content[0].type).toBe('text')
+            const parsedResult = JSON.parse(result.content[0].text)
+            expect(parsedResult.metadata.fallback).toBe(true)
+            expect(parsedResult.metadata.source).toBe('PWA_STOREFRONT_APP_PATH')
+        })
+
+        test('should not use fallback when only some critical fields are missing', async () => {
+            // Mock only 2 critical fields as null (should throw error, not use fallback)
+            loadConfig.mockReturnValue({
+                clientId: 'test-id',
+                clientSecret: null,
+                organizationId: null,
+                instanceId: 'test-instance',
+                shortCode: 'test',
+                hostname: 'test.com'
+            })
+
+            await expect(CustomApiTool.fn()).rejects.toThrow(
+                'Required SFCC API credentials are missing'
+            )
+        })
+    })
 })