@leonardorick/pi-web-search

Web search tool for pi — Exa hosted MCP search with DuckDuckGo HTML fallback via wreq-js browser TLS fingerprinting. Companion to pi-smart-fetch.

Why

Pi's built-in web search relies on Anthropic's first-party web_search_20250305 tool, which is only available when running Claude models. This package fills the gap for any other model with a keyless web_search tool.

Search tries Exa's hosted MCP endpoint first (web_search_exa over JSON-RPC). If Exa MCP fails, rate-limits, or returns no results, the tool falls back to DuckDuckGo HTML search.

Bare Node fetch() (even with a spoofed User-Agent header) gets served DDG's anti-bot anomaly page (cc=botnet) because the TLS/HTTP2 fingerprint leaks "this is Node, not Chrome." wreq-js wraps native Rust bindings that emulate real browser TLS/HTTP2 fingerprints — same primitive pi-smart-fetch uses for web_fetch.

Install

// ~/.pi/agent/settings.json
{
  "packages": ["npm:@leonardorick/pi-web-search"],
}

Tool

Registers web_search:

| param | type | required | description | | ----------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | query | string | yes | Search query (min length 2) | | allowed_domains | string[] | no | Only return results from these domains | | blocked_domains | string[] | no | Exclude results from these domains | | numResults | integer | no | Result cap. Default 8, min 1, max 20. | | freshness | string | no | Time filter. day / week / month / year, or custom range YYYY-MM-DDtoYYYY-MM-DD. | | country | string | no | ISO 3166-1 alpha-2 country code for region-localised results (e.g. US, DE, BR). |

allowed_domains and blocked_domains are mutually exclusive. The tool translates filters to Exa site: / -site: query terms and also enforces them client-side. It over-fetches when filters are active so post-filter trimming can still meet the requested num_results cap.

Provider support matrix

| filter | Exa MCP | DuckDuckGo (fallback) | | ----------------- | ----------------------------- | --------------------- | | allowed_domains | yes (via site:) | yes (via site:) | | blocked_domains | yes (via -site:) | yes (via -site:) | | numResults | yes (native) | yes (post-filter) | | freshness | best-effort (may be ignored)¹ | yes (df= param) | | country | best-effort (may be ignored)¹ | yes (kl= param) |

¹ Exa MCP's documented schema only exposes query and numResults. Extra fields are sent best-effort: harmless if ignored, honored if Exa supports them in the future. The DuckDuckGo fallback enforces them reliably.

Output mirrors Claude Code's Web search results for query: "..." block, including the Links: [...] JSON line and the "REMINDER: include sources" suffix — the model is expected to append a Sources: markdown list to its reply.

Design notes

No prompt argument and no summarization step. Claude Code's WebSearchTool calls Haiku with the user-provided prompt to compress results before returning. Pi's built-in tools (read, grep, etc.) follow a "raw output, model digests it" pattern — this extension matches that convention.

Anonymous Exa MCP access is rate-limited by Exa (currently documented as 2 QPS and 50 tool calls/day per IP). The tool treats Exa as a best-effort first provider and keeps DDG as fallback.

TODO: Add an optional prompt parameter paired with configurable model/provider settings so results can be summarized before returning — matching Claude Code's behavior. The summarizer should use the active pi provider rather than hardcoding a specific model.

Limitations

• Anonymous Exa MCP quota is shared by client IP; heavy use can hit 429 and fall back to DDG.
• DDG HTML scraping is best-effort. If DDG changes its result markup the snippet regex is the most likely break point; titles + URLs degrade more gracefully.
• freshness and country are only guaranteed on the DDG fallback. On Exa MCP they ride along as extra fields and are silently ignored unless Exa expands the schema.
• This package only returns search results and snippets. Use web_fetch from pi-smart-fetch for page content extraction.

License

MIT