mcp-searxng-local: Instructions file for Codex

AGENTS.md

Project Overview

MCP server for local web search via SearXNG — zero API keys, zero cost, 100% local. Exposes 3 tools: web_search, web_search_advanced, web_fetch.

Tech Stack

• Runtime: Node.js >= 20
• Language: TypeScript (strict, ESM)
• MCP SDK: @modelcontextprotocol/sdk v1
• Validation: Zod v3
• HTTP: axios (SearXNG API), native fetch (web_fetch)
• HTML parsing: cheerio
• Tests: vitest (48 tests)
• Backend: SearXNG (Docker) + Valkey (cache)
• Env loading: dotenv (.env files auto-loaded in entry points)

Build & Test

npm run build        # tsc → dist/
npm run typecheck    # tsc --noEmit
npx vitest run       # 48 tests
npm run dev          # tsx watch (development)
npm start            # node dist/index.js (production)

Always run npm run build && npx vitest run before committing.

Project Structure

See docs/ARCHITECTURE.md for full directory tree with descriptions.

src/
├── index.ts              # Entry point (stdio)
├── http.ts               # Entry point (Streamable HTTP)
├── server.ts             # McpServer factory + tool registration
├── types.ts              # Shared interfaces
├── tools/                # webSearch.ts, webFetch.ts
├── engines/              # searxng.ts, fetchHtml.ts, github.ts
├── utils/                # formatter.ts, errors.ts, retry.ts, cache.ts, logger.ts
└── __tests__/            # vitest (48 tests)

Key Architecture Decisions

• stdio is primary transport (compatible with all MCP clients). HTTP via src/http.ts for remote access.
• Unified handler: web_search and web_search_advanced share the same registerSearchTool() function in webSearch.ts. _advanced is a hint to the LLM to use filters more carefully.
• All user-facing strings in English. Tool descriptions, error messages, Zod .describe(), log messages — everything the user/LLM sees is EN.
• Identifiers in English. Function names, variable names, types, interfaces.
• Cache: LRU in-memory (100 entries, 5min TTL). SearXNG also caches via Valkey.
• Retry: withRetry() with exponential backoff + jitter. 3 retries for SearXNG, 2 for web_fetch.
• Rate limit handling: Auto-fallback to public SearXNG instances when all local engines are unresponsive. Configured via SEARXNG_FALLBACK_URLS env var.