Zero-config search works immediately through Exa MCP free. /web adds provider, API-key, SearXNG, and proxy configuration without requiring manual JSON edits.

Install

pi install npm:@bytetrue/pi-web-search

Restart or reload Pi, then ask it to search the web. Run /web only when you want to change provider or network settings.

[!IMPORTANT] Remove any extension that already registers web_search or web_fetch; Pi tool names must be unique.

Tools

web_search

| Argument | Required | Meaning | | --- | --- | --- | | query | Yes | Search text | | max_results | No | 1–10 results; default 5 |

Search follows the provider chain configured in /web: the first provider is tried first, then configured fallbacks after provider creation, request, or timeout failures. User cancellation stops the whole chain; an empty successful result does not trigger fallback.

web_fetch

| Argument | Required | Meaning | | --- | --- | --- | | url | Yes | Public HTTP(S) URL | | raw | No | Return raw HTML instead of extracted text |

Search-provider choice never changes fetch routing. Every URL uses the same generic transport with redirect revalidation, SSRF checks, text-only enforcement, and a 10 MiB decoded-body limit. Large accepted text is truncated for context and saved to a temporary file for later reading.

Configure with /web

The TUI can select an active provider, configure an ordered fallback chain, enter provider keys, set a SearXNG base URL, and configure an HTTP proxy. /web --show reports the provider chain with credentials masked. The API-key field is visible while typing; prefer the provider's environment variable when sharing or recording your terminal.

| Provider | Environment variable | Notes | | --- | --- | --- | | Exa MCP free | — | Keyless default | | Bing | — | Keyless; useful in mainland China without a proxy | | SearXNG | SEARXNG_URL | Self-hosted base URL | | Bocha 博查 | BOCHA_API_KEY | China AI-search API | | Tavily | TAVILY_API_KEY | Search API | | Exa | EXA_API_KEY | Search API | | Brave | BRAVE_SEARCH_API_KEY | Search API | | Jina | JINA_API_KEY | Search API | | Firecrawl | FIRECRAWL_API_KEY | Search API |

Provider API-key and base-URL environment variables override stored provider values; a configured proxy overrides proxy environment variables. Configuration lives at ~/.pi/byte-pi-web/config.json; set PI_CONFIG_DIR to move the base directory. Writes are atomic with mode 0600, and malformed JSON is never overwritten.

Proxy behavior

Configure a proxy through /web, or set HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY before starting Pi. Provider requests honor NO_PROXY.

The dispatcher is package-scoped and never changes Node's process-global dispatcher. Arbitrary web_fetch targets intentionally do not use NO_PROXY to escape the guarded route. Set BYTE_PI_WEB_NO_PROXY=1 to disable proxy use for this package.

Direct fetches block private, loopback, link-local, metadata, and other non-public destinations after local DNS resolution and at redirect/connect time. With an explicit proxy, local/private hostnames and IP literals remain blocked while the proxy becomes the trusted boundary for target DNS resolution.

{
  "providers": ["exa-free", "bing"],
  "proxy": "http://127.0.0.1:7890",
  "apiKeys": { "tavily": "tvly-..." },
  "baseUrls": { "searxng": "http://127.0.0.1:8080" }
}

The /web flow is preferred. Only providers is read; a legacy singular provider field is ignored.

Development

npm --workspace @bytetrue/pi-web-search test
npm --workspace @bytetrue/pi-web-search run typecheck
npm --workspace @bytetrue/pi-web-search pack --dry-run

Live provider tests are opt-in:

npm --workspace @bytetrue/pi-web-search run test:e2e