Home

Web Search MCP — Design Docs

This wiki is the design companion to the README. It covers how to choose and chain tools, not how to install.

Install, prerequisites, environment variables, and troubleshooting → README.md. Read that first if you haven't set the server up.

Page	Purpose
Tool Selection Guide	Decision matrix — which tool for which job, plus auth-at-a-glance.
Recommended Workflows	Proven multi-tool chains for real research tasks.
Known Quirks	Edge cases, upstream gotchas, and auth traps.
Plugin Setup	Install as a Claude Code plugin + the bundled research skills.

The server is built for low-friction expansion — each engine/utility is an isolated module, so a bug in one parser can't crash another.

Modular tooling — one standalone function per module.
Schema-first API — all I/O validated via Pydantic; consistent shapes reduce LLM hallucination and client parse errors.
Unified error shape — every tool returns a consistent ErrorResponse (_utils/formatting.py) so the LLM can tell auth failure from rate limit and pivot.
Keyless-first — Reddit, HN, Wikipedia, arXiv, DuckDuckGo, LinkedIn work with zero config. Auth needed only for X/Twitter; optional for Exa/GitHub.
Depth-based enrichment — Reddit, HN, LinkedIn, GitHub, X use quick / default / deep tiers balancing latency against depth.