feat(search): make non-JSON search-response error actionable (FEAT-053)

When SearXNG returns a 200 with a non-JSON body and SEARXNG_HTML_FALLBACK is
off, createJSONError now names both remediation fixes — enable `- json` under
search.formats in settings.yml, or set SEARXNG_HTML_FALLBACK=true — while
keeping the existing 100-char body preview. Closes the discoverability gap
reported in #137.

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

Author: 3 people

__tests__/unit/error-handler.test.ts

@@ -98,7 +98,12 @@ async function runTests() {
   await testFunction('Specialized error creators', () => {
     const context = { searxngUrl: 'https://searx.example.com' };
 
-    assert.ok(createJSONError('invalid json') instanceof MCPSearXNGError);
+    const jsonError = createJSONError('invalid json');
+    assert.ok(jsonError instanceof MCPSearXNGError);
+    assert.ok(jsonError.message.includes('invalid json'));
+    assert.ok(jsonError.message.includes('- json'));
+    assert.ok(jsonError.message.includes('search.formats'));
+    assert.ok(jsonError.message.includes('SEARXNG_HTML_FALLBACK=true'));
     assert.ok(createDataError() instanceof MCPSearXNGError);
     assert.ok(createURLFormatError('invalid-url') instanceof MCPSearXNGError);
     assert.ok(createContentError('test error', 'https://example.com') instanceof MCPSearXNGError);

__tests__/unit/search.test.ts

@@ -276,6 +276,18 @@ async function runTests() {
         error.message.includes('Invalid JSON response'),
         `expected response preview in error message, got: ${error.message}`
       );
+      assert.ok(
+        error.message.includes('- json'),
+        `expected SearXNG JSON format remediation in error message, got: ${error.message}`
+      );
+      assert.ok(
+        error.message.includes('search.formats'),
+        `expected SearXNG JSON format remediation in error message, got: ${error.message}`
+      );
+      assert.ok(
+        error.message.includes('SEARXNG_HTML_FALLBACK=true'),
+        `expected HTML fallback remediation in error message, got: ${error.message}`
+      );
     }
 
     fetchMocker.restore();

src/error-handler.ts

@@ -113,7 +113,7 @@ export function createServerError(status: number, statusText: string, responseBo
 
 export function createJSONError(responseText: string): MCPSearXNGError {
   const preview = responseText.substring(0, 100).replace(/\n/g, ' ');
-  return new MCPSearXNGError(`🔍 SearXNG Response Error: Invalid JSON format. Response: "${preview}..."`);
+  return new MCPSearXNGError(`🔍 SearXNG Response Error: Invalid JSON format. Response: "${preview}...". Enable - json under search.formats in your SearXNG settings.yml, or set SEARXNG_HTML_FALLBACK=true.`);
 }
 
 export function createDataError(): MCPSearXNGError {