nkapila6/mcpsurfr

mermaid
%%{init: {'theme': 'base'}}%%
flowchart TD
A[LLM] -->|query| S["Search with ddgs (auto: several engines, no keys)"]
S -->|"ragsearch, deepresearch"| R["Re-rank results locally (MobileBERT on numpy)"]
R --> P[Fetch top pages, keep the main content]
P -->|page text + URLs| A
S -->|search| T1["Tier 1: pick pages by their snippets"]
T1 --> T2["Tier 2: split into passages, keyword match (BM25)"]
T2 -->|few hits| OUT["Best passages + URLs (about 800 tokens)"]
T2 -->|too many or none| T3[Tier 3: rank them by meaning]
T3 --> OUT
OUT --> A
What's in it:
No API keys. Searches go through ddgs. Its auto mode asks several engines at once and skips blocked ones.
Ranked locally. A small MobileBERT model on plain numpy re-ranks results, so only the best pages get fetched.
Clean text. Pages are fetched with browser impersonation, and only the main content is kept: no menus, cookie banners or footers. Code blocks and tables keep their lines. The same page under two URLs comes back once.
Passages instead of pages. search returns just the paragraphs that answer the question, about a tenth of the tokens. When nothing matches well, it can ask you whether you want the full pages instead.
Says what it left out. Results list skipped pages with a reason (blocked, PDF, duplicate...), cut pages are marked truncated, and fallbacks and engine failures show up as warnings. Google blocks often, so it falls back to auto on its own.
Brings its own guide. It serves a skill and a research prompt, so clients pick up how to use it without setup.
| Tool | Use it for |
| search | Start here: returns only the relevant passages. Pass keywords for better hits |
| ragsearchddgs | Full pages as text (the original mode) |
| ragsearchgoogle | Same, via Google (falls back to auto when blocked) |
| deepresearch | Several search terms across backends, merged and de-duplicated |
| deepresearchddgs / deepresearchgoogle | deepresearch shortcuts |
Backends: auto (default), brave, duckduckgo, google, grokipedia, mojeek, startpage, wikipedia, yahoo. auto and brave are the dependable ones.
## Install
With uv:
json
"mcpServers": {
"mcpsurfr": {
"command": "uvx",
"args": ["--from", "git+https://github.com/nkapila6/mcpsurfr", "mcpsurfr"]
Or with Docker (amd64 and arm64):
json
"mcpServers": {
"mcpsurfr": {
"command": "docker",
"args": ["run", "--rm", "-i", "--init", "ghcr.io/nkapila6/mcpsurfr:latest"]
Full-page tools share a 40k-character budget per call (about 10k tokens). To change it, add "env": {"MCPSURFRMAXCHARS": "80000"} to the server entry.
Not sure where your config lives? See the MCP quickstart. Tested with Claude Desktop, Claude Code, Cursor and Goose.
Coming from mcp-local-rag? Your old config keeps working, since the old URL redirects and the mcp-local-rag command still exists. Switching to the config above gets you the new name and drops the --python=3.10 pin (3.10 reaches end of life this month).