feat(search): validate and normalize categories/engines against live /config (FEAT-043)

Normalize comma-separated `categories` and `engines` case-insensitively to the
SearXNG instance's canonical names from cached `/config`, so miscased input
(e.g. `Google`, `Social Media`) no longer silently degrades to a default search.
Unknown values are rejected with a helpful error listing available values; a
stale cache is refreshed once before failing; when `/config` is unavailable the
values are forwarded as-is with a non-fatal warning. Also fixes category
extraction for instances whose `/config.categories` is an array of names.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Codex <noreply@openai.com>

Author: 3 people

README.md

@@ -91,8 +91,8 @@ AI Assistant (e.g. Claude)
     - `safesearch` (number, optional): Safe search filter level (0: None, 1: Moderate, 2: Strict) (default: instance setting)
     - `min_score` (number, optional): Minimum relevance score from 0.0 to 1.0. Results below this score are filtered out.
     - `num_results` (number, optional): Maximum number of results to return, from 1 to 20. `SEARXNG_MAX_RESULTS` applies as an operator ceiling.
-    - `categories` (string, optional): Comma-separated SearXNG categories (e.g. `"news"`, `"it,science"`). Supported values: `general`, `news`, `images`, `videos`, `it`, `science`, `files`, `social media`. Default: SearXNG instance default (usually `general`).
-    - `engines` (string, optional): Comma-separated SearXNG engine names (e.g. `"google,bing,ddg"`). Names are matched exactly when live `/config` validation is available.
+    - `categories` (string, optional): Comma-separated SearXNG categories (e.g. `"news"`, `"it,science"`). When live `/config` is available, values are trimmed and normalized case-insensitively to the instance's canonical category names; unknown values are rejected with available categories listed. If `/config` is unavailable, values are forwarded as-is with a warning. Default: SearXNG instance default.
+    - `engines` (string, optional): Comma-separated SearXNG engine names (e.g. `"google,bing,ddg"`, `"semantic scholar"`). When live `/config` is available, values are trimmed and normalized case-insensitively to canonical engine names, including engines disabled by default; unknown values are rejected with available engines listed. If `/config` is unavailable, values are forwarded as-is with a warning.
     - `response_format` (string, optional): Response format, either `"text"` for formatted agent-readable output or `"json"` for raw SearXNG JSON with filtered/sliced `results`. (default: `"text"`)
 
 - **searxng_search_suggestions**

__tests__/unit/instance-info.test.ts

@@ -47,6 +47,17 @@ function makeConfig() {
   return config;
 }
 
+function makeConfigWithCategoryArray() {
+  const config: any = makeConfig();
+  config.categories = ['general', 'social media', 'science'];
+  config.engines = [
+    { name: 'google', categories: ['general'], disabled: false },
+    { name: 'semantic scholar', categories: ['science'], disabled: false },
+    { name: 'mastodon', category: 'social media', disabled: false },
+  ];
+  return config;
+}
+
 async function runTests() {
   console.log('🧪 Testing: instance-info.ts\n');
 
@@ -71,6 +82,38 @@ async function runTests() {
     envManager.restore();
   }, results);
 
+  await testFunction('returns category names when /config categories is an array of strings', async () => {
+    clearInstanceInfoCacheForTests();
+    envManager.set('SEARXNG_URL', 'https://test-searx.example.com');
+    const mockServer = createMockServer();
+    fetchMocker.mock(createMockFetch({ json: makeConfigWithCategoryArray() }));
+
+    const result = await fetchInstanceInfo(mockServer as any, true, false);
+    const payload = JSON.parse(result);
+
+    assert.equal(payload.available, true);
+    assert.deepEqual(payload.categories, ['general', 'science', 'social media']);
+    assert.deepEqual(payload.engines.enabled, ['google', 'mastodon', 'semantic scholar']);
+
+    fetchMocker.restore();
+    envManager.restore();
+  }, results);
+
+  await testFunction('category filter works when /config categories is an array of strings', async () => {
+    clearInstanceInfoCacheForTests();
+    envManager.set('SEARXNG_URL', 'https://test-searx.example.com');
+    const mockServer = createMockServer();
+    fetchMocker.mock(createMockFetch({ json: makeConfigWithCategoryArray() }));
+
+    const result = JSON.parse(await fetchInstanceInfo(mockServer as any, true, false, 'social media'));
+
+    assert.deepEqual(result.categories, ['social media']);
+    assert.deepEqual(result.engines.enabled, ['mastodon']);
+
+    fetchMocker.restore();
+    envManager.restore();
+  }, results);
+
   await testFunction('second call returns cached result without fetching again', async () => {
     clearInstanceInfoCacheForTests();
     envManager.set('SEARXNG_URL', 'https://test-searx.example.com');

__tests__/unit/search.test.ts

@@ -30,10 +30,12 @@ function makeMockSearchResults(count: number) {
 
 function makeConfigWithEngines() {
   return {
+    categories: ['general', 'news', 'social media'],
     engines: [
       { name: 'google', disabled: false },
       { name: 'ddg', disabled: false },
       { name: 'bing', disabled: true },
+      { name: 'semantic scholar', disabled: false },
     ],
   };
 }
@@ -856,6 +858,43 @@ async function runTests() {
     envManager.restore();
   }, results);
 
+  await testFunction('mixed-case engines and categories normalize to canonical /config names', async () => {
+    clearInstanceInfoCacheForTests();
+    envManager.set('SEARXNG_URL', 'https://test-searx.example.com');
+
+    const mockServer = createMockServer();
+    const requestedUrls: string[] = [];
+
+    fetchMocker.mock(async (url) => {
+      requestedUrls.push(url.toString());
+      const parsedUrl = new URL(url.toString());
+      if (parsedUrl.pathname.endsWith('/config')) {
+        return createMockFetch({ json: makeConfigWithEngines() })(url);
+      }
+      return createMockFetch({ json: { results: [] } })(url);
+    });
+
+    await performWebSearch(
+      mockServer as any,
+      'test query',
+      1,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      ' News , SOCIAL MEDIA ',
+      ' Google , Semantic Scholar ',
+    );
+
+    const searchUrl = new URL(requestedUrls[1]);
+    assert.equal(searchUrl.searchParams.get('categories'), 'news,social media');
+    assert.equal(searchUrl.searchParams.get('engines'), 'google,semantic scholar');
+
+    fetchMocker.restore();
+    envManager.restore();
+  }, results);
+
   await testFunction('invalid engine names from live /config throw helpful validation error', async () => {
     clearInstanceInfoCacheForTests();
     envManager.set('SEARXNG_URL', 'https://test-searx.example.com');
@@ -885,7 +924,114 @@ async function runTests() {
     envManager.restore();
   }, results);
 
-  await testFunction('unavailable /config forwards engines and prepends text warning', async () => {
+  await testFunction('unknown category from live /config throws validation error with available categories', async () => {
+    clearInstanceInfoCacheForTests();
+    envManager.set('SEARXNG_URL', 'https://test-searx.example.com');
+
+    const mockServer = createMockServer();
+    let searchCalled = false;
+
+    fetchMocker.mock(async (url) => {
+      const parsedUrl = new URL(url.toString());
+      if (parsedUrl.pathname.endsWith('/config')) {
+        return createMockFetch({ json: makeConfigWithEngines() })(url);
+      }
+      searchCalled = true;
+      return createMockFetch({ json: { results: [] } })(url);
+    });
+
+    try {
+      await performWebSearch(mockServer as any, 'test query', 1, undefined, undefined, undefined, undefined, undefined, 'unknown');
+      assert.fail('Expected invalid category validation error');
+    } catch (error: any) {
+      assert.ok(error.message.includes('Invalid SearXNG category name(s): unknown'), error.message);
+      assert.ok(error.message.includes('Available categories: general, news, social media'), error.message);
+      assert.ok(error.message.includes('searxng_instance_info'), error.message);
+    }
+    assert.equal(searchCalled, false, 'Search should not run after validation failure');
+
+    fetchMocker.restore();
+    envManager.restore();
+  }, results);
+
+  await testFunction('unknown engine from live /config throws validation error with available engines', async () => {
+    clearInstanceInfoCacheForTests();
+    envManager.set('SEARXNG_URL', 'https://test-searx.example.com');
+
+    const mockServer = createMockServer();
+    let searchCalled = false;
+
+    fetchMocker.mock(async (url) => {
+      const parsedUrl = new URL(url.toString());
+      if (parsedUrl.pathname.endsWith('/config')) {
+        return createMockFetch({ json: makeConfigWithEngines() })(url);
+      }
+      searchCalled = true;
+      return createMockFetch({ json: { results: [] } })(url);
+    });
+
+    try {
+      await performWebSearch(mockServer as any, 'test query', 1, undefined, undefined, undefined, undefined, undefined, undefined, 'missing');
+      assert.fail('Expected invalid engine validation error');
+    } catch (error: any) {
+      assert.ok(error.message.includes('Invalid SearXNG engine name(s): missing'), error.message);
+      assert.ok(error.message.includes('Available engines:'), error.message);
+      assert.ok(error.message.includes('semantic scholar'), error.message);
+    }
+    assert.equal(searchCalled, false, 'Search should not run after validation failure');
+
+    fetchMocker.restore();
+    envManager.restore();
+  }, results);
+
+  await testFunction('stale config refreshes once and then normalizes newly available value', async () => {
+    clearInstanceInfoCacheForTests();
+    envManager.set('SEARXNG_URL', 'https://test-searx.example.com');
+
+    const mockServer = createMockServer();
+    const requestedUrls: string[] = [];
+    let configFetchCount = 0;
+
+    fetchMocker.mock(async (url) => {
+      requestedUrls.push(url.toString());
+      const parsedUrl = new URL(url.toString());
+      if (parsedUrl.pathname.endsWith('/config')) {
+        configFetchCount++;
+        const config = makeConfigWithEngines();
+        if (configFetchCount === 2) {
+          config.categories.push('software wikis');
+          config.engines.push({ name: 'annas archive', disabled: false });
+        }
+        return createMockFetch({ json: config })(url);
+      }
+      return createMockFetch({ json: { results: [] } })(url);
+    });
+
+    await performWebSearch(
+      mockServer as any,
+      'test query',
+      1,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      'Software Wikis',
+      'Annas Archive',
+    );
+
+    assert.equal(configFetchCount, 2, 'Expected cached config plus one refresh');
+    const configRequests = requestedUrls.filter((url) => new URL(url).pathname.endsWith('/config'));
+    assert.equal(configRequests.length, 2, 'Expected exactly one refresh request');
+    const searchUrl = new URL(requestedUrls[2]);
+    assert.equal(searchUrl.searchParams.get('categories'), 'software wikis');
+    assert.equal(searchUrl.searchParams.get('engines'), 'annas archive');
+
+    fetchMocker.restore();
+    envManager.restore();
+  }, results);
+
+  await testFunction('unavailable /config forwards engines and categories and prepends text warning', async () => {
     clearInstanceInfoCacheForTests();
     envManager.set('SEARXNG_URL', 'https://test-searx.example.com');
 
@@ -912,18 +1058,19 @@ async function runTests() {
       })(url);
     });
 
-    const result = await performWebSearch(mockServer as any, 'test query', 1, undefined, undefined, undefined, undefined, undefined, undefined, 'unknown');
+    const result = await performWebSearch(mockServer as any, 'test query', 1, undefined, undefined, undefined, undefined, undefined, 'Unknown Category', 'Unknown Engine');
 
-    assert.ok(result.startsWith('Note: engine names were not validated'), result);
+    assert.ok(result.startsWith('Note: categories and engines were not validated or normalized'), result);
     assert.ok(result.includes('Forwarded Result'), result);
     const searchUrl = requestedUrls[1];
-    assert.equal(new URL(searchUrl).searchParams.get('engines'), 'unknown');
+    assert.equal(new URL(searchUrl).searchParams.get('categories'), 'Unknown Category');
+    assert.equal(new URL(searchUrl).searchParams.get('engines'), 'Unknown Engine');
 
     fetchMocker.restore();
     envManager.restore();
   }, results);
 
-  await testFunction('unavailable /config includes warnings in JSON response when engines are provided', async () => {
+  await testFunction('unavailable /config includes warnings in JSON response when categories and engines are provided', async () => {
     clearInstanceInfoCacheForTests();
     envManager.set('SEARXNG_URL', 'https://test-searx.example.com');
 
@@ -937,10 +1084,10 @@ async function runTests() {
       return createMockFetch({ json: { query: 'test query', results: [] } })(url);
     });
 
-    const result = await performWebSearch(mockServer as any, 'test query', 1, undefined, undefined, undefined, undefined, undefined, undefined, 'unknown', 'json');
+    const result = await performWebSearch(mockServer as any, 'test query', 1, undefined, undefined, undefined, undefined, undefined, 'Unknown Category', 'Unknown Engine', 'json');
     const payload = JSON.parse(result);
 
-    assert.deepEqual(payload.warnings, ['Engine names were not validated because SearXNG /config is unavailable.']);
+    assert.deepEqual(payload.warnings, ['Categories and engines were not validated or normalized because SearXNG /config is unavailable.']);
 
     fetchMocker.restore();
     envManager.restore();

__tests__/unit/types.test.ts

@@ -254,12 +254,16 @@ async function runTests() {
     const properties = WEB_SEARCH_TOOL.inputSchema.properties as Record<string, any>;
     assert.ok(properties.categories, 'WEB_SEARCH_TOOL must expose categories parameter');
     assert.equal(properties.categories.type, 'string');
+    assert.ok(properties.categories.description.includes('case-insensitively'), properties.categories.description);
+    assert.ok(properties.categories.description.includes('/config'), properties.categories.description);
   }, results);
 
   await testFunction('WEB_SEARCH_TOOL schema includes engines property', () => {
     const properties = WEB_SEARCH_TOOL.inputSchema.properties as Record<string, any>;
     assert.ok(properties.engines, 'WEB_SEARCH_TOOL must expose engines parameter');
     assert.equal(properties.engines.type, 'string');
+    assert.ok(properties.engines.description.includes('case-insensitively'), properties.engines.description);
+    assert.ok(!properties.engines.description.includes('matched exactly'), properties.engines.description);
   }, results);
 
   await testFunction('WEB_SEARCH_TOOL schema includes response_format enum', () => {