AG-Bureau/mcp-search

**A self-hosted MCP server for web search that reports how much of each answer to believe**
---
A search tool fails in ways that look exactly like success. An engine answers with
somebody else's subject. A page returns text that is an anti-bot shield. Sixteen
sources turn out to be two engines counted eight times. None of that raises an
error, and the model on the other end builds on it.
**This server's job is to make those cases distinguishable, in fields you can
branch on.** It runs on your machine, over your own metasearch instance, with your
own model key — or none at all.
🔧 Tools
| Tool | What it does | Required | Notable options |
|---|---|---|---|
| web_search | Finds pages **and reads the top ones** — one call, links with their text | query | read: false for links only · read_top how many to read · min_engines to force breadth · engines to name the engines yourself |
| web_read | Reads pages by address: text, PDF, or a scan recognised by a vision model | urls | mode: browser for JS-rendered pages · expect to assert what must be there · offset to continue |
| web_image_search | Finds images: the address of the FILE and, separately, of the page it sits on | query | max_results, page |
| web_screenshot | A PNG of a page **plus its text from the same visit**, so the two can be cross-checked | url | max_chars for how much text · full_page · expect |
| web_deep_search | Composes its own queries, reads in waves, and answers from several sources — saying what it could not confirm | question | waves |
Full argument reference, response shapes and failure modes: **HOWTO-CALL.md**.
📦 Install
From an open repository page to a working answer. Nothing is assumed to be on
your disk already:
The fourth and fifth lines are not decoration. Without a value in
SEARXNG_SECRET the up command refuses — and that refusal is deliberate: with
no key of its own the metasearch does not fail, it comes up with a publicly known
one from its image template, silently. BROWSER_WS_SECRET is the secret path of
the browser sidecar's endpoint, and up refuses without it too: on a guessable
path, anything that can open a WebSocket to the sidecar — any container on the
compose network, and any page the browser itself opens — gets a browser of its
own, outside every check the module applies to the pages it reads. The compose
file hands the same value to the sidecar and, at the end of BROWSER_WS_URL, to
the adapter; neither prints it.
The sixth line creates the two paths the compose file mounts for caller
authentication and TLS — both off by default. A path that does not exist is
created by Docker as a root-owned DIRECTORY, and a token "file" that is a
directory reads as an unreadable list (see Configuration below).
Both are in .gitignore: they hold secrets once you use them.
The overlay publishes the port **on loopback only**. A published container port
does not go through the host firewall's usual chain, so exposing it more widely
is a separate, deliberate step — see Deployment.
Two transports
MCP has two, and they answer different questions. **HTTP** — the commands above —
is for a server that is already running somewhere. **stdio** is the protocol's
default: the client starts the server as a process and talks to it through the
pipes, which is how most desktop clients and wrappers work.
One JSON-RPC object per line in, one answer per line out. The mode is chosen
explicitly and never guessed from whether a terminal is attached — that sign
merely sits next to the subject, and one day it answers for a case nobody meant.
In stdio mode **stdout is the protocol**: answers and nothing else, with the log
on stderr. One stray line of anything else breaks the client reading it.
**Each process started this way is an instance of its own**, even inside the
running container: its browser sessions (BROWSER_MAX_SESSIONS), its engine and
domain pacing and its /stats counters are separate from the HTTP server's.
Several stdio clients on one sidecar add up in its pids_limit like several
adapters do.
The sidecars do not depend on the choice; the metasearch does: SEARXNG_URL
must reach one, or every search refuses with cause: upstream (the default,
http://searxng:8080, is a name only the compose network knows). Started by a
client with no compose project around it, the module names what else is missing
instead of pretending: the browser path reports not_wired_up, and trouble
carries pool_unmeasured — the engine pool was never computed from observation.
⬆️ Upgrading to 0.3.5 — no new variable