argus-web-mcp

Argus Panoptes - the all-seeing hundred-eyed giant. A self-hosted, unlimited, owned web fetch / scrape / search MCP server for SURIOTA. Mythological sibling to the Hermes AI Server. Every Claude Code / Codex CLI connects over remote HTTP -> zero local process on the client.

Contents

• Why Argus

• Architecture

• The 20 tools

• Hard guarantees

• Quickstart (local)

• Connect a CLI

• Benchmarked

• Repo map

• Status

Related MCP server: crawl4ai-mcp-server

Why Argus

We surveyed the 12 leading paid/free web tools. All meter requests, truncate content, or cost money. Argus is built on best-in-class OSS, self-hosted on the SURIOTA VPS - so it is unlimited, free per-request, returns full content (no truncation), and is owned end-to-end. It is tools, not a brain: the consuming agent (Claude Code's Opus 4.8 / Codex) does the reasoning - Argus needs no LLM.

Architecture

Fetch strategy (cheap -> expensive): httpx static -> trafilatura -> escalate to Crawl4AI/Playwright only when JS/thin -> Patchright stealth on anti-bot -> Wayback archive if the host is unreachable. Every hop is SSRF-guarded.

The 20 tools

Trading parsers are validated to >=99% field accuracy (100% on golden files).

Hard guarantees

• SSRF - resolve-then-validate, IP-pin anti-rebinding, scheme allowlist, per-hop redirect re-check, private/metadata/CGNAT deny -> 100% test coverage, line + branch (hard gate).

• No silent truncation - full documents always; the streaming body cap is a DoS guard, not a content cap.

• Tools never raise - every tool returns a structured err(code, msg, detail) instead of crashing into the client.

• Resilience - content-addressed cache (per-source TTL, stale-serve), per-host courtesy delay + circuit breaker, archive egress-fallback.

• Secure deploy - bearer/JWT auth + nginx TLS + fail2ban; runs unprivileged via systemd; secrets via EnvironmentFile.

Quickstart (all-in-Docker)

Argus plus its SearXNG backend in one stack. Container up = MCP up, container down = MCP down.

docker compose up -d --build          # MCP live at http://127.0.0.1:8090/mcp
docker compose down                   # MCP gone
claude mcp add --transport http argus-local http://127.0.0.1:8090/mcp

Loopback-only, no auth token needed (nothing is exposed off-host). Cache lives in the argus-cache volume.

Quickstart (local, no Docker for Argus itself)

uv venv --python 3.12 && uv pip install -e ".[dev]"
crawl4ai-setup && crawl4ai-doctor          # one-time Chromium
# optional extras: ".[semantic]" (find_similar/rerank), ".[pdf-quality]" (Docling)

# SearXNG (search backend) - loopback only
cd deploy/searxng && docker compose up -d

python -m argus.server                      # stdio (local dev)
# or HTTP:  uvicorn argus.server:app --host 127.0.0.1 --port 8090

Connect a CLI

Register with Claude Code:

claude mcp add --transport http argus https://argus.gifariksuryo.xyz/mcp \
  --header "Authorization: Bearer ${ARGUS_TOKEN}"

Register with Codex (~/.codex/config.toml):

[mcp_servers.argus]
url = "https://argus.gifariksuryo.xyz/mcp"
bearer_token_env_var = "ARGUS_TOKEN"

Benchmarked

Head-to-head vs Claude Code & Codex native web tools (4-way, n=25, identical queries): discovery parity, but Argus wins decisively on content depth (full content per query vs hits/summaries), freshness, and cost/ownership. In-process research() runs in 3-6s - Argus is not the latency bottleneck (CLI latency is the consuming agent + MCP transport). Claude+Argus stays token-neutral with the deepest synthesis; Codex+Argus trades +72% tokens for that depth. Semantic rerank quantified at +27% nDCG on conceptual queries. Full report: benchmark/reports/RESULTS.md (harness).

Repo map

Status

DEPLOYED LIVE. Public HTTPS at https://argus.gifariksuryo.xyz/mcp (bearer auth) on the SURIOTA VPS (103.172.172.29, Ubuntu 24.04): uvicorn 127.0.0.1:8090 --workers 1 behind nginx + Let's Encrypt TLS + fail2ban; SearXNG docker on 127.0.0.1:8888; /health + /metrics live. A systemd timer polls main every 5 minutes -> fast-forward only -> restart -> /health gate -> auto-rollback (and skips restart for docs/benchmark-only commits).

20 tools / 799 offline tests (+ browser, slow, and network extras) green / SSRF 100% (line + branch) / ruff clean / security-audited (no Critical/High). Optional and off by default: the LLM tier (ARGUS_ENABLE_LLM) and local-path PDF (ARGUS_ALLOW_LOCAL_PDF). Only open owner input: set ARGUS_S2_API_KEY to enable scholar_search's Semantic Scholar backend (CrossRef is the fallback). See docs/02-ROADMAP.md.