hermes-skills/searxng-smart-search/SKILL.md

name, description, version, author

name	description	version	author
searxng-smart-search	Smart SearXNG MCP search with auto-category routing, score filtering, and time-range defaults.	1.1.0	Hermes Agent

SearXNG Smart Search

USER PREFERENCE — CRITICAL: ALL web searches MUST use mcp_searxng_searxng_web_search. The built-in web_search tool is NOT to be used under any circumstances. This is a hard preference — the user explicitly requires SearXNG MCP for all factual verification and research.

Use mcp_searxng_searxng_web_search with these defaults per query type. Never use web_search, web_extract, or curl — always route through MCP.

Category Routing

Query type	categories	time_range	min_score
Tech/code/ML	it,science	month	0.2
News/current	news	week	0.3
General/research	general	year	0.2
Academic/papers	science	year	0.1
Social/Reddit	social media	month	0.2
Images	images	—	—
Video	videos	—	—

Defaults

• num_results: 5 (general), 10 (research), 3 (quick lookup)
• language: en unless user specifies otherwise
• safesearch: 1 (moderate)
• response_format: json for programmatic, text for human reading
• Global fallback: time_range=year, min_score=0.2 — apply to any query that doesn't match a specific category above

Post-search

After search, use mcp_searxng_web_url_read on top 1-2 results for full content. Use section param to extract specific headings.

Instance check

Run mcp_searxng_searxng_instance_info once per session to confirm engines are healthy. Flag any unresponsive_engines in results. Full engine inventory and known-broken engines documented in references/searxng-instance.md.

PITFALL — Default engines may all be broken: SearXNG uses server-side defaults (google, duckduckgo, brave, startpage). If all are broken, every search returns zero results with no error. Diagnose by hitting the SearXNG API directly:

# Check which engines actually work
curl -s "http://10.0.0.8:8888/search?q=test&format=json&engines=bing,google,duckduckgo,brave,startpage" | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Results: {len(d.get(\"results\",[]))}'); print(f'Unresponsive: {d.get(\"unresponsive_engines\",[])}')"

If only Bing works, pass engines=bing in every mcp_searxng_searxng_web_search call until the server-side defaults are fixed. The MCP tool does NOT specify engines by default — it relies entirely on SearXNG's server-side defaults.

Reference files

• references/instance-config.md — full SearXNG instance snapshot (engines, categories, plugins, locales)
• references/mcp-server-config.md — MCP server setup, tool list, verification commands
• references/searxng-instance.md — engine inventory and known-broken engines
• references/telegram-bot-api-2026.md — Telegram Bot API features relevant to Hermes integration (overlaps with telegram-integration/references/bot-api-2026.md — curator will consolidate)

Disabling the built-in web toolset (SearXNG-only mode)

To force ALL web searches through SearXNG MCP and prevent the agent from ever using the built-in web_search/web_extract tools, two config changes are required:

1. Disable the web toolset globally:

# ~/.hermes/config.yaml
agent:
  disabled_toolsets: ["web"]

2. Remove web from platform toolsets (CLI and any other active platforms):

# ~/.hermes/config.yaml
platform_toolsets:
  cli:
    - browser
    - clarify
    - code_execution
    # ... all others ...
    - vision
    # web REMOVED from this list

3. Verify SearXNG is the configured backend (already set if you followed the MCP setup):

web:
  backend: searxng
  search_backend: searxng
  extract_backend: firecrawl  # SearXNG is search-only; pair with an extract provider
  searxng_url: http://10.0.0.8:8888

With both disabled_toolsets and platform_toolsets updated, the web_search and web_extract tools are completely unavailable. The agent must use mcp_searxng_searxng_web_search and mcp_searxng_web_url_read for all web access.

Full reference config snippet: references/disable-builtin-web.md

Setup / Troubleshooting

SEARXNG_URL — Two Separate Requirements

The built-in web_search tool and the MCP SearXNG tools read SEARXNG_URL from DIFFERENT sources. Both must be set independently:

Tool	Reads from	Config location
Built-in web_search	os.environ → ~/.hermes/.env	SEARXNG_URL=http://10.0.0.8:8888 in .env
MCP searxng__* tools	MCP subprocess env	mcp_servers.searxng.env.SEARXNG_URL in config.yaml

Critical pitfall — config.yaml web.searxng_url does NOT feed the built-in tool: The built-in web_search tool's availability check (_has_env("SEARXNG_URL") in tools/web_tools.py) calls get_env_value() which reads os.environ first, then ~/.hermes/.env. It does NOT read web.searxng_url from config.yaml. If SEARXNG_URL is only in config.yaml and not in .env, the built-in web_search returns empty results with no error — the tool silently falls through to "no provider configured."

Diagnostic: web_search returning empty {"data": {"web": []}} with no error message = SEARXNG_URL missing from .env. The MCP tools working fine at the same time confirms the instance is healthy — the gap is only in the built-in tool's env source.

Fix: Add SEARXNG_URL=http://10.0.0.8:8888 to ~/.hermes/.env AND all profile .env files. The MCP server config in config.yaml already passes SEARXNG_URL via its env block:

mcp_servers:
  searxng:
    env:
      SEARXNG_URL: http://10.0.0.8:8888

But this only covers the MCP subprocess — the main Hermes process still needs it in .env for the built-in tool.

Verification after fix: Start a new session (/reset) — env vars are read at startup. Then web_search("test") should return results. The MCP tools should continue working as before.

Bulk .env update: When adding SEARXNG_URL to .env, update ALL profile .env files (base + all 15 profiles). Use hermes-config-bulk-update skill pattern — same 16-location rule applies to .env as to config.yaml. Check with: for p in ~/.hermes/profiles/*/; do grep -l SEARXNG_URL "$p/.env" 2>/dev/null || echo "MISSING: $(basename $p)"; done

• DuckDuckGo and Startpage engines are broken (CAPTCHA/crash) — ignore their failures
• time_range only works with news and general categories
• min_score above 0.5 often returns zero results
• categories must be comma-separated, no spaces: it,science not it, science
• web_extract (Hermes built-in) does NOT work with SearXNG backend — it needs firecrawl/tavily/exa. Use mcp_searxng_web_url_read instead for URL content extraction. When the built-in web toolset is disabled, this is enforced automatically.

References

• references/mcp-server-config.md — full MCP server setup, tool list, verification commands
• references/searxng-mcp-only-policy.md — USER PREFERENCE: ALL web searches must use SearXNG MCP, never built-in web_search