sfcc-dev-mcp 1.0.15 → 1.0.19

package/docs-site-v2/troubleshooting/index.md

@@ -0,0 +1,204 @@
+---
+title: Troubleshooting
+description: Diagnose SFCC Dev MCP startup, authentication, logs, OCAPI access, and client connection issues with quick fixes.
+---
+
+# Troubleshooting
+
+## Quick checks
+
+- Node.js 18+ is installed
+- `dw.json` exists and has `chmod 600` permissions
+- The SFCC sandbox is active and reachable
+
+<Callout title="Quick test" variant="info">
+Run `npx -y sfcc-dev-mcp --debug` to verify the server starts without errors.
+</Callout>
+
+## Server will not start
+
+```bash
+node --version
+npx -y sfcc-dev-mcp --debug
+```
+
+<Collapsible title="Node.js version mismatch" open>
+
+```bash
+node --version
+nvm install 18 && nvm use 18
+```
+
+If you work with older SFRA/SiteGenesis projects, set a higher default Node version for MCP:
+
+```bash
+nvm alias default 18
+nvm use 12.22.6
+```
+
+</Collapsible>
+
+<Collapsible title="File permissions">
+
+```bash
+chmod 600 dw.json
+ls -la dw.json
+```
+
+</Collapsible>
+
+<Collapsible title="Package installation">
+
+```bash
+npm install -g sfcc-dev-mcp
+npx -y sfcc-dev-mcp --version
+```
+
+</Collapsible>
+
+## Authentication issues
+
+- Verify `hostname`, `username`, and `password`
+- Regenerate `client-id` and `client-secret` if OCAPI calls fail
+- Confirm OCAPI resources in Business Manager match the configuration page
+
+<Collapsible title="Test connectivity">
+
+```bash
+curl -I https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com
+```
+
+</Collapsible>
+
+<Collapsible title="Regenerate API credentials">
+
+```bash
+curl -X POST \
+	https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com/dw/oauth2/access_token \
+	-H "Content-Type: application/x-www-form-urlencoded" \
+	-d "grant_type=client_credentials&client_id=NEW_ID&client_secret=NEW_SECRET"
+```
+
+</Collapsible>
+
+## Log tools return no data
+
+- Test WebDAV access directly:
+
+```bash
+curl -u "username:password" https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.servlet/webdav/Sites/Logs/
+```
+
+- Ensure logs exist for the requested date
+
+<Collapsible title="Wrong date format">
+
+```javascript
+get_latest_error({ date: "20241218" })
+```
+
+</Collapsible>
+
+## System object tools failing
+
+- Confirm Data API resources include `definition_search` endpoints (POST)
+- Ensure `client-id` matches the OCAPI client in Account Manager
+
+<Collapsible title="Required Data API resources">
+
+```json
+{
+	"_v": "23.2",
+	"clients": [{
+		"client_id": "YOUR_CLIENT_ID",
+		"resources": [
+			{ "resource_id": "/system_object_definitions", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
+			{ "resource_id": "/system_object_definitions/*", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
+			{ "resource_id": "/system_object_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+			{ "resource_id": "/system_object_definitions/*/attribute_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+			{ "resource_id": "/system_object_definitions/*/attribute_group_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+			{ "resource_id": "/custom_object_definitions/*/attribute_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+			{ "resource_id": "/site_preferences/preference_groups/*/*/preference_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+			{ "resource_id": "/code_versions", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
+			{ "resource_id": "/code_versions/*", "methods": ["get", "patch"], "read_attributes": "(**)", "write_attributes": "(**)" }
+		]
+	}]
+}
+```
+
+</Collapsible>
+
+## Job log tools issues
+
+<Collapsible title="Job log access">
+
+```bash
+curl -u "username:password" \
+	https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.servlet/webdav/Sites/Logs/jobs/
+```
+
+</Collapsible>
+
+<Collapsible title="Minimal health flow">
+
+```bash
+aegis query search_job_logs_by_name 'jobName:MyJob|limit:3'
+aegis query get_job_log_entries 'jobName:MyJob|limit:40'
+aegis query get_job_execution_summary 'jobName:MyJob'
+```
+
+</Collapsible>
+
+## AI client not connecting
+
+<Collapsible title="Validate MCP config">
+
+```bash
+python -m json.tool claude_desktop_config.json
+npx -y sfcc-dev-mcp --debug
+```
+
+</Collapsible>
+
+## Auto-discovery not working
+
+<Collapsible title="No tools after adding dw.json" open>
+
+- Ensure your client supports MCP `roots/list` (VS Code/Copilot/Cursor do).
+- Re-open the workspace after adding `dw.json`.
+- If your client does not support workspace roots, pass `--dw-json` explicitly.
+
+</Collapsible>
+
+## Debug logging
+
+```bash
+npx -y sfcc-dev-mcp --debug
+npx -y sfcc-dev-mcp --debug false --dw-json /path/to/dw.json
+```
+
+## Log file locations
+
+- macOS: `/var/folders/{user-id}/T/sfcc-mcp-logs/`
+- Linux: `/tmp/sfcc-mcp-logs/`
+- Windows: `%TEMP%\sfcc-mcp-logs\`
+
+```bash
+node -e "console.log(require('os').tmpdir() + '/sfcc-mcp-logs')"
+```
+
+## Getting help
+
+Collect diagnostic data and remove secrets before sharing:
+
+```bash
+node --version
+npm --version
+npm list sfcc-dev-mcp
+```
+
+## AI client not connecting
+
+- Validate your MCP config file JSON
+- Restart the client after changes
+- Ensure the MCP server command uses `npx` and an absolute `dw.json` path

package/eslint.config.js

@@ -127,11 +127,13 @@ export default tseslint.config(
       'dist/**',
       'node_modules/**',
       'coverage/**',
-      'docs-site/**',
+      'docs-site-v2/**',
       'docs-site-old/**',
       '*.config.js',
       'jest.config.js',
       'tests/servers/**',
+      '.github/skills/salesforce-developer-site-scraper/scripts/**',
+      '.github/skills/salesforce-help-site-scraper/scripts/**',
     ],
   },
 );

package/memories/repo/docs-site-v2-build.json

@@ -0,0 +1,11 @@
+{
+  "subject": "docs-site-v2 build workflow",
+  "fact": "The docs-v2 site is built from the docs-site-v2 directory using `npm run build`, which runs `vitepress build .` and then generates `public/sitemap.xml` and `public/llms.txt` via node scripts.",
+  "citations": [
+    "docs-site-v2/package.json",
+    "docs-site-v2/scripts/generate-sitemap.js",
+    "docs-site-v2/scripts/generate-llms.js"
+  ],
+  "reason": "This verified command chain is useful for future documentation changes and release validation tasks.",
+  "category": "build"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfcc-dev-mcp",
-  "version": "1.0.15",
+  "version": "1.0.19",
   "description": "MCP server for Salesforce B2C Commerce Cloud development assistance including logs, debugging, and development tools",
   "mcpName": "io.github.taurgis/sfcc-dev-mcp",
   "main": "dist/index.js",
@@ -16,7 +16,7 @@
     "url": "https://github.com/taurgis/sfcc-dev-mcp/issues"
   },
   "scripts": {
-    "build": "tsc && rm -rf ./dist/docs && cp -r ./docs ./dist/docs",
+    "build": "rm -rf ./dist && tsc && cp -r ./docs ./dist/docs && cp -r ./ai-instructions ./dist/ai-instructions",
     "start": "node dist/main.js",
     "dev": "tsx src/main.ts",
     "inspector": "npx @modelcontextprotocol/inspector node dist/main.js",
@@ -24,6 +24,10 @@
     "convert-docs:test": "node scripts/convert-docs.js --test",
     "convert-docs:limit": "node scripts/convert-docs.js --limit 5",
     "github-pages": "cd docs-site && rm -f Gemfile.lock && bundle install --path vendor/bundle && bundle exec jekyll serve --livereload --host=0.0.0.0",
+    "docs:install": "npm --prefix docs-site-v2 install",
+    "docs:dev": "npm --prefix docs-site-v2 run dev",
+    "docs:build": "npm --prefix docs-site-v2 run build",
+    "docs:preview": "npm --prefix docs-site-v2 run preview",
     "test": "npm run test:all",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
@@ -36,7 +40,7 @@
     "test:mock-server:setup": "cd tests/servers/sfcc-mock-server && npm install && npm run setup",
     "test:mock-server:start": "cd tests/servers/sfcc-mock-server && npm start",
     "test:mock-server": "jest --testPathPatterns=sfcc-mock-server",
-    "validate:server-json": "node -e \"const {readFileSync} = require('fs'); const serverJson = JSON.parse(readFileSync('./server.json', 'utf8')); console.log('server.json is valid JSON'); console.log('Server name:', serverJson.name); console.log('Version:', serverJson.version); console.log('Package identifier:', serverJson.packages[0].identifier);\"",
+    "validate:server-json": "node scripts/validate-server-json.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "lint:check": "eslint . --max-warnings 0",
@@ -61,23 +65,23 @@
   },
   "type": "module",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.18.0",
+    "@modelcontextprotocol/sdk": "1.26.0",
     "webdav": "5.8.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.36.0",
+    "@eslint/js": "9.39.2",
     "@types/eslint": "9.6.1",
     "@types/jest": "30.0.0",
-    "@types/node": "24.4.0",
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
-    "eslint": "9.36.0",
+    "@types/node": "25.0.3",
+    "ajv": "8.17.1",
+    "ajv-formats": "3.0.1",
+    "eslint": "9.39.2",
     "husky": "9.1.7",
-    "jest": "30.1.3",
+    "jest": "30.2.0",
     "mcp-aegis": "1.0.18",
-    "ts-jest": "29.4.4",
-    "tsx": "4.20.5",
-    "typescript": "5.9.2",
-    "typescript-eslint": "8.44.0"
+    "ts-jest": "29.4.6",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.52.0"
   }
 }

package/scripts/validate-server-json.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'fs';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import https from 'https';
+
+async function validateServerJson() {
+  try {
+    // Read server.json
+    const serverJson = JSON.parse(readFileSync('./server.json', 'utf8'));
+    console.log('✓ server.json is valid JSON');
+    
+    // Fetch the schema
+    const schemaUrl = serverJson.$schema;
+    console.log(`\nFetching schema from: ${schemaUrl}`);
+    
+    const schema = await new Promise((resolve, reject) => {
+      https.get(schemaUrl, (response) => {
+        let data = '';
+        response.on('data', chunk => data += chunk);
+        response.on('end', () => {
+          try {
+            resolve(JSON.parse(data));
+          } catch (e) {
+            reject(e);
+          }
+        });
+      }).on('error', reject);
+    });
+    
+    console.log('✓ Schema fetched successfully');
+    
+    // Validate against schema
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    
+    const validate = ajv.compile(schema);
+    const valid = validate(serverJson);
+    
+    if (valid) {
+      console.log('\n✅ server.json is valid according to the schema!');
+      console.log('\nServer details:');
+      console.log(`  Name: ${serverJson.name}`);
+      console.log(`  Description: ${serverJson.description}`);
+      console.log(`  Version: ${serverJson.version}`);
+      if (serverJson.repository) {
+        console.log(`  Repository: ${serverJson.repository.url}`);
+      }
+      console.log(`  Package identifier: ${serverJson.packages[0].identifier}`);
+      console.log(`  Package version: ${serverJson.packages[0].version}`);
+      console.log(`  Package registry: ${serverJson.packages[0].registryType}`);
+      return true;
+    } else {
+      console.error('\n❌ server.json validation failed:');
+      console.error(JSON.stringify(validate.errors, null, 2));
+      return false;
+    }
+  } catch (error) {
+    console.error('\n❌ Error during validation:');
+    console.error(error.message);
+    return false;
+  }
+}
+
+validateServerJson().then(valid => {
+  process.exit(valid ? 0 : 1);
+});

package/server.json

@@ -1,19 +1,17 @@
 {
-  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "io.github.taurgis/sfcc-dev-mcp",
   "description": "MCP server for Salesforce B2C Commerce Cloud development assistance",
-  "status": "active",
   "repository": {
     "url": "https://github.com/taurgis/sfcc-dev-mcp",
     "source": "github"
   },
-  "version": "1.0.14",
+  "version": "1.0.15",
   "packages": [
     {
-      "registry_type": "npm",
-      "registry_base_url": "https://registry.npmjs.org",
+      "registryType": "npm",
       "identifier": "sfcc-dev-mcp",
-      "version": "1.0.14",
+      "version": "1.0.15",
       "transport": {
         "type": "stdio"
       }