pi-web-tools

A pi package providing web search and web fetch tools for coding agents.

Tools

Quick Start

# Install from npm
pi install npm:@yandy0725/pi-web-tools

# Or install from a local checkout
pi install ./path/to/pi-web-tools

# Or run directly
npm install
pi -e ./index.ts

Prerequisites

• websearch: No config needed — Exa MCP free tier (150 calls/day). Optional: set DEEPSEEK_API_KEY (or configure a deepseek provider in pi) for the DeepSeek fallback slot; set ALIYUN_API_KEY (or configure an aliyun provider) for the Aliyun fallback slot.
• webfetch: No config needed — direct HTTP fetch. Optional: set DEEPSEEK_API_KEY (or configure a deepseek provider in pi) to enable the DeepSeek fallback, which renders JS-heavy pages server-side.

Configuration

API Keys (environment variables or pi provider config)

Config file (web-tools.json)

Optionally pin a default provider per tool. Global: <agent-dir>/web-tools.json; project: <cwd>/.pi/web-tools.json (project overrides global at section level).

{
	"websearch": { "provider": "deepseek" },
	"webfetch": { "provider": "deepseek" }
}

• Valid values: websearch → "exa" | "deepseek" | "aliyun"; webfetch → "local" | "deepseek".
• Precedence: tool-call provider parameter > config file > built-in fallback chain.
• A provider specified by parameter or config is used exclusively — no fallback to other providers on failure.
• An invalid config value produces an explicit error naming the file and the expected values.

Tools Reference

websearch

Search the web with automatic provider fallback.

Parameters:

Providers:

• Exa (default first) — AI-native search API. With EXA_API_KEY: full REST API. Without: MCP free tier (150 calls/day, 3 QPS). Always available, no key needed for basic usage.
• DeepSeek (fallback slot 2) — DeepSeek Search API, self-developed search engine. Good for Chinese queries; supports search syntax in the query (site:, lang:, after:, before:, quoted phrases). Returns LLM-oriented summaries as snippets. Requires DEEPSEEK_API_KEY env var or a configured deepseek provider in pi. Billed per successful request (¥5/1000; empty results are free).
• Aliyun (fallback slot 3) — Bailian WebSearch MCP. Requires ALIYUN_API_KEY env var or a configured aliyun provider in pi. Better for Chinese-language queries.

When a provider fails, the tool automatically falls back to the next one (exa → deepseek → aliyun). Providers without a configured key fail fast and are skipped in the chain.

webfetch

Fetch content from a URL as readable markdown, or as the raw response body.

Parameters:

• markdown (default) — HTML is reduced to its main content container (main → article → [role=main] → body, all matches joined) and converted to markdown, with the page <title> reported on the Title: line; JSON is pretty-printed; other text types are returned verbatim.
• origin — the response body unmodified, apart from the existing 100,000-character truncation.
• Binary responses are rejected in both formats, with the media type and byte size in the error.

Providers:

• Local (default first) — direct HTTP GET with the extraction described above.
• DeepSeek (fallback) — DeepSeek Fetch API, server-side fetch returning markdown. Handles JS-rendered pages that local fetch cannot. Requires DEEPSEEK_API_KEY env var or a configured deepseek provider in pi. Billed per successful request (¥5/1000; failures are free).

Fallback triggers (chain mode only): local hard failure (network error / timeout / non-2xx), or thin local content (< 200 meaningful characters); if DeepSeek also fails, the local result is returned as-is. The DeepSeek leg needs a key and runs only for format: "markdown". Binary responses and unknown format values never fall back — another provider cannot turn them into text either. With provider specified (parameter or config), it is used exclusively — except provider: "deepseek" + format: "origin", which auto-routes to local.

Development

# From repo root:
npm ci                    # Install all dependencies
npm run typecheck         # Type-check all packages
npm run lint              # Biome lint
npm test                  # Run all tests

# Package-specific:
pi -e ./index.ts          # Run the extension locally (from this dir)

License

MIT