Merge pull request #284 from czlonkowski/fix/resourcelocator-validation

fix: Add resourceLocator validation for AI model nodes

CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.17.3] - 2025-10-07
+
+### 🔧 Validation
+
+**Fixed critical validation gap for AI model nodes with resourceLocator properties.**
+
+This release adds validation for `resourceLocator` type properties, fixing a critical issue where AI agents could create invalid configurations that passed validation but failed at runtime.
+
+#### Fixed
+
+- **resourceLocator Property Validation**
+  - **Issue:** No validation existed for `resourceLocator` type properties used in AI model nodes
+  - **Impact:**
+    - AI agents could create invalid configurations like `model: "gpt-4o-mini"` (string) instead of `model: {mode: "list", value: "gpt-4o-mini"}` (object)
+    - Invalid configs passed validation but failed at runtime in n8n
+    - Affected many langchain nodes: OpenAI Chat Model (v1.2+), Anthropic, Cohere, DeepSeek, Groq, Mistral, OpenRouter, xAI Grok, and embeddings nodes
+  - **Root Cause:** `validatePropertyTypes()` method in ConfigValidator only validated `string`, `number`, `boolean`, and `options` types - `resourceLocator` was completely missing
+  - **Fix:** Added comprehensive resourceLocator validation in `config-validator.ts:237-274`
+    - Validates value is an object (not string, number, null, or array)
+    - Validates required `mode` property exists and is a string
+    - Validates required `value` property exists
+    - Provides helpful error messages with exact fix suggestions
+    - Example error: `Property 'model' is a resourceLocator and must be an object with 'mode' and 'value' properties, got string`
+    - Example fix: `Change model to { mode: "list", value: "gpt-4o-mini" } or { mode: "id", value: "gpt-4o-mini" }`
+
+#### Added
+
+- Comprehensive resourceLocator validation with 14 test cases covering:
+  - String value rejection with helpful fix suggestions
+  - Null and array value rejection
+  - Missing `mode` or `value` property detection
+  - Invalid `mode` type detection (e.g., number instead of string)
+  - Invalid `mode` value validation (must be 'list', 'id', or 'url')
+  - Empty object detection (missing both mode and value)
+  - Extra properties handling (ignored gracefully)
+  - Valid resourceLocator acceptance for "list", "id", and "url" modes
+  - JSDoc documentation explaining resourceLocator structure and common mistakes
+  - All 29 tests passing (100% coverage for new validation logic)
+
 ## [2.17.1] - 2025-10-07
 
 ### 🔧 Telemetry

README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/n8n-mcp.svg)](https://www.npmjs.com/package/n8n-mcp)
 [![codecov](https://codecov.io/gh/czlonkowski/n8n-mcp/graph/badge.svg?token=YOUR_TOKEN)](https://codecov.io/gh/czlonkowski/n8n-mcp)
 [![Tests](https://img.shields.io/badge/tests-3336%20passing-brightgreen.svg)](https://github.com/czlonkowski/n8n-mcp/actions)
-[![n8n version](https://img.shields.io/badge/n8n-^1.113.3-orange.svg)](https://github.com/n8n-io/n8n)
+[![n8n version](https://img.shields.io/badge/n8n-^1.114.3-orange.svg)](https://github.com/n8n-io/n8n)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fczlonkowski%2Fn8n--mcp-green.svg)](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp",
-  "version": "2.17.1",
+  "version": "2.17.3",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "bin": {
@@ -132,15 +132,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.2",
-    "@n8n/n8n-nodes-langchain": "^1.112.2",
+    "@n8n/n8n-nodes-langchain": "^1.113.1",
     "@supabase/supabase-js": "^2.57.4",
     "dotenv": "^16.5.0",
     "express": "^5.1.0",
     "express-rate-limit": "^7.1.5",
     "lru-cache": "^11.2.1",
-    "n8n": "^1.113.3",
-    "n8n-core": "^1.112.1",
-    "n8n-workflow": "^1.110.0",
+    "n8n": "^1.114.3",
+    "n8n-core": "^1.113.1",
+    "n8n-workflow": "^1.111.0",
     "openai": "^4.77.0",
     "sql.js": "^1.13.0",
     "uuid": "^10.0.0",

package.runtime.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp-runtime",
-  "version": "2.17.1",
+  "version": "2.17.3",
   "description": "n8n MCP Server Runtime Dependencies Only",
   "private": true,
   "dependencies": {

src/scripts/fetch-templates.ts

@@ -417,12 +417,28 @@ async function generateTemplateMetadata(db: any, service: TemplateService) {
       } catch (error) {
         console.warn(`Failed to parse workflow for template ${t.id}:`, error);
       }
-      
+
+      // Parse nodes_used safely
+      let nodes: string[] = [];
+      try {
+        if (t.nodes_used) {
+          nodes = JSON.parse(t.nodes_used);
+          // Ensure it's an array
+          if (!Array.isArray(nodes)) {
+            console.warn(`Template ${t.id} has invalid nodes_used (not an array), using empty array`);
+            nodes = [];
+          }
+        }
+      } catch (error) {
+        console.warn(`Failed to parse nodes_used for template ${t.id}:`, error);
+        nodes = [];
+      }
+
       return {
         templateId: t.id,
         name: t.name,
         description: t.description,
-        nodes: JSON.parse(t.nodes_used),
+        nodes: nodes,
         workflow
       };
     });

src/services/config-validator.ts

@@ -234,8 +234,56 @@ export class ConfigValidator {
           message: `Property '${key}' must be a boolean, got ${typeof value}`,
           fix: `Change ${key} to true or false`
         });
+      } else if (prop.type === 'resourceLocator') {
+        // resourceLocator validation: Used by AI model nodes (OpenAI, Anthropic, etc.)
+        // Must be an object with required properties:
+        //   - mode: string ('list' | 'id' | 'url')
+        //   - value: any (the actual model/resource identifier)
+        // Common mistake: passing string directly instead of object structure
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+          const fixValue = typeof value === 'string' ? value : JSON.stringify(value);
+          errors.push({
+            type: 'invalid_type',
+            property: key,
+            message: `Property '${key}' is a resourceLocator and must be an object with 'mode' and 'value' properties, got ${typeof value}`,
+            fix: `Change ${key} to { mode: "list", value: ${JSON.stringify(fixValue)} } or { mode: "id", value: ${JSON.stringify(fixValue)} }`
+          });
+        } else {
+          // Check required properties
+          if (!value.mode) {
+            errors.push({
+              type: 'missing_required',
+              property: `${key}.mode`,
+              message: `resourceLocator '${key}' is missing required property 'mode'`,
+              fix: `Add mode property: { mode: "list", value: ${JSON.stringify(value.value || '')} }`
+            });
+          } else if (typeof value.mode !== 'string') {
+            errors.push({
+              type: 'invalid_type',
+              property: `${key}.mode`,
+              message: `resourceLocator '${key}.mode' must be a string, got ${typeof value.mode}`,
+              fix: `Set mode to "list" or "id"`
+            });
+          } else if (!['list', 'id', 'url'].includes(value.mode)) {
+            errors.push({
+              type: 'invalid_value',
+              property: `${key}.mode`,
+              message: `resourceLocator '${key}.mode' must be 'list', 'id', or 'url', got '${value.mode}'`,
+              fix: `Change mode to "list", "id", or "url"`
+            });
+          }
+
+          if (value.value === undefined) {
+            errors.push({
+              type: 'missing_required',
+              property: `${key}.value`,
+              message: `resourceLocator '${key}' is missing required property 'value'`,
+              fix: `Add value property to specify the ${prop.displayName || key}`
+            });
+          }
+        }
       }
-      
+
       // Options validation
       if (prop.type === 'options' && prop.options) {
         const validValues = prop.options.map((opt: any) => 

src/templates/template-fetcher.ts

@@ -45,19 +45,22 @@ export class TemplateFetcher {
    * Fetch all templates and filter to last 12 months
    * This fetches ALL pages first, then applies date filter locally
    */
-  async fetchTemplates(progressCallback?: (current: number, total: number) => void): Promise<TemplateWorkflow[]> {
+  async fetchTemplates(progressCallback?: (current: number, total: number) => void, sinceDate?: Date): Promise<TemplateWorkflow[]> {
     const allTemplates = await this.fetchAllTemplates(progressCallback);
-    
-    // Apply date filter locally after fetching all
-    const oneYearAgo = new Date();
-    oneYearAgo.setMonth(oneYearAgo.getMonth() - 12);
-    
+
+    // Use provided date or default to 12 months ago
+    const cutoffDate = sinceDate || (() => {
+      const oneYearAgo = new Date();
+      oneYearAgo.setMonth(oneYearAgo.getMonth() - 12);
+      return oneYearAgo;
+    })();
+
     const recentTemplates = allTemplates.filter((w: TemplateWorkflow) => {
       const createdDate = new Date(w.createdAt);
-      return createdDate >= oneYearAgo;
+      return createdDate >= cutoffDate;
     });
-    
-    logger.info(`Filtered to ${recentTemplates.length} templates from last 12 months (out of ${allTemplates.length} total)`);
+
+    logger.info(`Filtered to ${recentTemplates.length} templates since ${cutoffDate.toISOString().split('T')[0]} (out of ${allTemplates.length} total)`);
     return recentTemplates;
   }
   

src/templates/template-repository.ts

@@ -442,7 +442,19 @@ export class TemplateRepository {
     const rows = this.db.prepare('SELECT id FROM templates').all() as { id: number }[];
     return new Set(rows.map(r => r.id));
   }
-  
+
+  /**
+   * Get the most recent template creation date
+   * Used in update mode to fetch only newer templates
+   */
+  getMostRecentTemplateDate(): Date | null {
+    const result = this.db.prepare('SELECT MAX(created_at) as max_date FROM templates').get() as { max_date: string | null } | undefined;
+    if (!result || !result.max_date) {
+      return null;
+    }
+    return new Date(result.max_date);
+  }
+
   /**
    * Check if a template exists in the database
    */

src/templates/template-service.ts

@@ -319,22 +319,38 @@ export class TemplateService {
       
       // Get existing template IDs if in update mode
       let existingIds: Set<number> = new Set();
+      let sinceDate: Date | undefined;
+
       if (mode === 'update') {
         existingIds = this.repository.getExistingTemplateIds();
         logger.info(`Update mode: Found ${existingIds.size} existing templates in database`);
+
+        // Get most recent template date and fetch only templates from last 2 weeks
+        const mostRecentDate = this.repository.getMostRecentTemplateDate();
+        if (mostRecentDate) {
+          // Fetch templates from 2 weeks before the most recent template
+          sinceDate = new Date(mostRecentDate);
+          sinceDate.setDate(sinceDate.getDate() - 14);
+          logger.info(`Update mode: Fetching templates since ${sinceDate.toISOString().split('T')[0]} (2 weeks before most recent)`);
+        } else {
+          // No templates yet, fetch from last 2 weeks
+          sinceDate = new Date();
+          sinceDate.setDate(sinceDate.getDate() - 14);
+          logger.info(`Update mode: No existing templates, fetching from last 2 weeks`);
+        }
       } else {
         // Clear existing templates in rebuild mode
         this.repository.clearTemplates();
         logger.info('Rebuild mode: Cleared existing templates');
       }
-      
+
       // Fetch template list
       logger.info(`Fetching template list from n8n.io (mode: ${mode})`);
       const templates = await fetcher.fetchTemplates((current, total) => {
         progressCallback?.('Fetching template list', current, total);
-      });
+      }, sinceDate);
       
-      logger.info(`Found ${templates.length} templates from last 12 months`);
+      logger.info(`Found ${templates.length} templates matching date criteria`);
       
       // Filter to only new templates if in update mode
       let templatesToFetch = templates;

tests/unit/services/config-validator-basic.test.ts

@@ -439,4 +439,335 @@ describe('ConfigValidator - Basic Validation', () => {
       expect(result.suggestions.length).toBeGreaterThanOrEqual(0);
     });
   });
+
+  describe('resourceLocator validation', () => {
+    it('should reject string value when resourceLocator object is required', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: 'gpt-4o-mini' // Wrong - should be object with mode and value
+      };
+      const properties = [
+        {
+          name: 'model',
+          displayName: 'Model',
+          type: 'resourceLocator',
+          required: true,
+          default: { mode: 'list', value: 'gpt-4o-mini' }
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0]).toMatchObject({
+        type: 'invalid_type',
+        property: 'model',
+        message: expect.stringContaining('must be an object with \'mode\' and \'value\' properties')
+      });
+      expect(result.errors[0].fix).toContain('mode');
+      expect(result.errors[0].fix).toContain('value');
+    });
+
+    it('should accept valid resourceLocator with mode and value', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: {
+          mode: 'list',
+          value: 'gpt-4o-mini'
+        }
+      };
+      const properties = [
+        {
+          name: 'model',
+          displayName: 'Model',
+          type: 'resourceLocator',
+          required: true,
+          default: { mode: 'list', value: 'gpt-4o-mini' }
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('should reject null value for resourceLocator', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: null
+      };
+      const properties = [
+        {
+          name: 'model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e =>
+        e.property === 'model' &&
+        e.type === 'invalid_type'
+      )).toBe(true);
+    });
+
+    it('should reject array value for resourceLocator', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: ['gpt-4o-mini']
+      };
+      const properties = [
+        {
+          name: 'model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e =>
+        e.property === 'model' &&
+        e.type === 'invalid_type' &&
+        e.message.includes('must be an object')
+      )).toBe(true);
+    });
+
+    it('should detect missing mode property in resourceLocator', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: {
+          value: 'gpt-4o-mini'
+          // Missing mode property
+        }
+      };
+      const properties = [
+        {
+          name: 'model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e =>
+        e.property === 'model.mode' &&
+        e.type === 'missing_required' &&
+        e.message.includes('missing required property \'mode\'')
+      )).toBe(true);
+    });
+
+    it('should detect missing value property in resourceLocator', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: {
+          mode: 'list'
+          // Missing value property
+        }
+      };
+      const properties = [
+        {
+          name: 'model',
+          displayName: 'Model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e =>
+        e.property === 'model.value' &&
+        e.type === 'missing_required' &&
+        e.message.includes('missing required property \'value\'')
+      )).toBe(true);
+    });
+
+    it('should detect invalid mode type in resourceLocator', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: {
+          mode: 123, // Should be string
+          value: 'gpt-4o-mini'
+        }
+      };
+      const properties = [
+        {
+          name: 'model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e =>
+        e.property === 'model.mode' &&
+        e.type === 'invalid_type' &&
+        e.message.includes('must be a string')
+      )).toBe(true);
+    });
+
+    it('should accept resourceLocator with mode "id"', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: {
+          mode: 'id',
+          value: 'gpt-4o-2024-11-20'
+        }
+      };
+      const properties = [
+        {
+          name: 'model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('should reject number value when resourceLocator is required', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: 12345 // Wrong type
+      };
+      const properties = [
+        {
+          name: 'model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors[0].type).toBe('invalid_type');
+      expect(result.errors[0].message).toContain('must be an object');
+    });
+
+    it('should provide helpful fix suggestion for string to resourceLocator conversion', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: 'gpt-4o-mini'
+      };
+      const properties = [
+        {
+          name: 'model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.errors[0].fix).toContain('{ mode: "list", value: "gpt-4o-mini" }');
+      expect(result.errors[0].fix).toContain('{ mode: "id", value: "gpt-4o-mini" }');
+    });
+
+    it('should reject invalid mode values', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: {
+          mode: 'invalid-mode',
+          value: 'gpt-4o-mini'
+        }
+      };
+      const properties = [
+        {
+          name: 'model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e =>
+        e.property === 'model.mode' &&
+        e.type === 'invalid_value' &&
+        e.message.includes("must be 'list', 'id', or 'url'")
+      )).toBe(true);
+    });
+
+    it('should accept resourceLocator with mode "url"', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: {
+          mode: 'url',
+          value: 'https://api.example.com/models/custom'
+        }
+      };
+      const properties = [
+        {
+          name: 'model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('should detect empty resourceLocator object', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: {} // Empty object, missing both mode and value
+      };
+      const properties = [
+        {
+          name: 'model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.length).toBeGreaterThanOrEqual(2); // Both mode and value missing
+      expect(result.errors.some(e => e.property === 'model.mode')).toBe(true);
+      expect(result.errors.some(e => e.property === 'model.value')).toBe(true);
+    });
+
+    it('should handle resourceLocator with extra properties gracefully', () => {
+      const nodeType = '@n8n/n8n-nodes-langchain.lmChatOpenAi';
+      const config = {
+        model: {
+          mode: 'list',
+          value: 'gpt-4o-mini',
+          extraProperty: 'ignored' // Extra properties should be ignored
+        }
+      };
+      const properties = [
+        {
+          name: 'model',
+          type: 'resourceLocator',
+          required: true
+        }
+      ];
+
+      const result = ConfigValidator.validate(nodeType, config, properties);
+
+      expect(result.valid).toBe(true); // Should pass with extra properties
+      expect(result.errors).toHaveLength(0);
+    });
+  });
 });

tests/unit/services/template-service.test.ts

@@ -79,6 +79,7 @@ describe('TemplateService', () => {
       getTemplateCount: vi.fn(),
       getTemplateStats: vi.fn(),
       getExistingTemplateIds: vi.fn(),
+      getMostRecentTemplateDate: vi.fn(),
       clearTemplates: vi.fn(),
       saveTemplate: vi.fn(),
       rebuildTemplateFTS: vi.fn(),
@@ -471,6 +472,7 @@ describe('TemplateService', () => {
       }));
 
       mockRepository.getExistingTemplateIds = vi.fn().mockReturnValue(new Set([1, 2]));
+      mockRepository.getMostRecentTemplateDate = vi.fn().mockReturnValue(new Date('2025-09-01'));
       mockRepository.saveTemplate = vi.fn();
       mockRepository.rebuildTemplateFTS = vi.fn();
 
@@ -498,6 +500,7 @@ describe('TemplateService', () => {
       }));
 
       mockRepository.getExistingTemplateIds = vi.fn().mockReturnValue(new Set([1, 2]));
+      mockRepository.getMostRecentTemplateDate = vi.fn().mockReturnValue(new Date('2025-09-01'));
       mockRepository.saveTemplate = vi.fn();
       mockRepository.rebuildTemplateFTS = vi.fn();