pi-web-access

Pi extension for web search and URL content extraction.

Tools

web_search

Search the web for information. Registered when a keyed search provider is available, or when the keyless parallel provider is explicitly selected.

Parameter	Type	Required	Description
query	string	yes	The search query
maxResults	number	no	Max results to return (default 5)
topic	"general" | "news"	no	Topic category
timeRange	"day" | "week" | "month" | "year"	no	Recency filter
includeDomains	string[]	no	Only include results from these domains
excludeDomains	string[]	no	Exclude results from these domains

web_fetch

Fetch a URL and return its content. When fetch.summary is configured, the summary model processes the content using prompt; otherwise the fetched content is returned directly and prompt is retained for compatibility but ignored. Only registered when fetch.provider or fetch.summary is configured.

Parameter	Type	Required	Description
url	string	yes	Public HTTP(S) URL; private, loopback, link-local, metadata, credentialed, and unsafe redirect destinations are rejected
prompt	string	yes	Instructions for the configured summary model; retained for compatibility but ignored when fetch.summary is not configured

x_search

Search X (Twitter) for posts and social media content. Only registered when xai provider has an API key.

Parameter	Type	Required	Description
query	string	yes	The search query on X
allowedHandles	string[]	no	Only include posts from these handles (max 20)
excludedHandles	string[]	no	Exclude posts from these handles (max 20)
fromDate	string	no	Start date (YYYY-MM-DD)
toDate	string	no	End date (YYYY-MM-DD)

image_search

Search the web for images. Only registered when an image search provider (dashscope or unsplash) has an API key. Also invocable directly via the /image-search <query> command.

Parameter	Type	Required	Description
query	string	yes	Description of the images to search for

Providers

Provider	Search	Fetch	X Search	Image Search	Default Base URL	Env Var	Default Model
parallel	✓	✗	✗	✗	https://search.parallel.ai/mcp	no key	-
tavily	✓	✓	✗	✗	https://api.tavily.com	TAVILY_API_KEY	-
brave	✓	✗	✗	✗	https://api.search.brave.com	BRAVE_API_KEY	-
firecrawl	✓	✓	✗	✗	https://api.firecrawl.dev	FIRECRAWL_API_KEY	-
kimi	✓	✗	✗	✗	https://api.moonshot.cn/v1	MOONSHOT_API_KEY	kimi-k3
mimo	✓	✗	✗	✗	https://api.xiaomimimo.com/v1	MIMO_API_KEY	mimo-v2.5-pro
zai	✓	✓	✗	✗	https://api.z.ai	ZAI_API_KEY	-
gemini	✓	✗	✗	✗	https://generativelanguage.googleapis.com/v1beta	GEMINI_API_KEY	gemini-2.5-flash
perplexity	✓	✓	✗	✗	https://api.perplexity.ai	PERPLEXITY_API_KEY	openai/gpt-5.5
deepseek	✓	✗	✗	✗	https://api.deepseek.com	DEEPSEEK_API_KEY	deepseek-v4-flash
openrouter	✓	✓	✗	✗	https://openrouter.ai/api/v1	OPENROUTER_API_KEY	openai/gpt-4.1-mini
xai	✓	✗	✓	✗	https://api.x.ai/v1	XAI_API_KEY	grok-4.3
openai	✓	✗	✗	✗	https://api.openai.com/v1	OPENAI_API_KEY	gpt-5.5
anthropic	✓	✓	✗	✗	https://api.anthropic.com/v1	ANTHROPIC_API_KEY	claude-sonnet-4-6
dashscope	✓	✓	✗	✓	https://dashscope.aliyuncs.com/compatible-mode/v1	DASHSCOPE_API_KEY	qwen3.8-flash
unsplash	✗	✗	✗	✓	https://api.unsplash.com	UNSPLASH_ACCESS_KEY	-
you	✓	✓	✗	✗	https://ydc-index.io	YDC_API_KEY	-

Custom Kimi base URLs must support both /chat/completions and /formulas/*.

You.com search returns web and news results in one call; topic: "news" prefers news results and applies a one-week freshness window. The Contents API (/v1/contents) returns clean Markdown for web_fetch. Get a key at you.com/platform/api-keys.

Custom DashScope base URLs must point to an OpenAI-compatible Responses API root — ${baseUrl}/responses is called for all capabilities. For the international site or a dedicated workspace endpoint, use e.g. https://dashscope-intl.aliyuncs.com/compatible-mode/v1. DashScope fetch uses the web_extractor tool and image search uses web_search_image; both are agent-style tools and can take minutes per call (default timeout 5 min, tune via timeoutMs). DashScope search supports only basic web search — includeDomains/excludeDomains filters are ignored.

Fetch fallback (when fetch.provider is not set): Jina Reader (r.jina.ai, free, JS-rendered) → local HTTP GET + turndown.

Configuration

Settings key: pi-web-access

Project .pi/settings.json values are loaded only after project trust is accepted and are not environment-interpolated. User and agent settings retain environment interpolation.

{
  "pi-web-access": {
    "search": {
      "provider": "kimi"
    },
    "fetch": {
      "provider": "zai",
      "summary": {
        "provider": "amaster",
        "model": "deepseek-v4-flash"
      }
    },
    "providers": {
      "kimi": {
        "apiKey": "AMASTER_API_KEY",
        "baseUrl": "https://credits.amaster.ai/v1"
      },
      "zai": {
        "apiKey": "${ZAI_API_KEY}"
      },
      "xai": {
        "apiKey": "${XAI_API_KEY}"
      }
    }
  }
}

search

Field	Description
provider	Which provider to use for web search. Not set = auto-select first provider with key. Explicitly selecting parallel enables keyless search; otherwise no key means the tool is not registered.

fetch

Field	Description
provider	Which provider to use for URL fetching. Not set = Jina Reader → local fallback.
summary	Model config for summarizing fetched content.
summary.provider	Model provider name (resolved via pi model registry).
summary.model	Model id.

If neither fetch.provider nor fetch.summary is configured, web_fetch is not registered.

imageSearch

Field	Description
provider	Which provider to use for image search (dashscope or unsplash). Not set = auto-select first provider with key. No key at all = tool not registered.

providers

Per-provider configuration. Each provider supports:

Field	Description
apiKey	API key. User and agent settings support $ENV_VAR and ${ENV_VAR}; only the braced form supports :-fallback. Project settings keep placeholders literal.
baseUrl	Override the default API endpoint.
model	Override the default model.
headers	Extra headers merged into every request.

Environment variables serve as fallbacks when apiKey is not set in config.

Parallel is opt-in and supports search only: it never enables image search or web_fetch, and it does not perform URL fetching or extraction. When selected, search objectives and queries leave the machine for https://search.parallel.ai/mcp; this can include agent-generated repository context and user-supplied URLs contained in those objectives or queries. Existing automatic provider selection, provider order, and keyed provider behavior are unchanged.

Architecture

Each provider implements the WebProvider interface via BaseProvider:

// providers/base.ts
export interface WebProvider {
  readonly id: BuiltInProviderId;
  search(params: SearchParams, provider: ResolvedProvider): Promise<SearchResponse>;
  fetch(url: string, provider: ResolvedProvider): Promise<FetchResponse>;
  imageSearch(params: ImageSearchParams, provider: ResolvedProvider): Promise<SearchResponse>;
}

export abstract class BaseProvider implements WebProvider {
  abstract readonly id: BuiltInProviderId;
  // Default implementations throw "not supported"
  async search(...) { throw new Error(`${this.id} does not support web_search.`); }
  async fetch(...) { throw new Error(`${this.id} does not support web_fetch.`); }
  async imageSearch(...) { throw new Error(`${this.id} does not support image_search.`); }
}

Providers only override methods they support. Provider-specific capabilities (like XaiProvider.xsearch) are exposed as additional methods on the class.

Tool Registration Rules

• web_search — registered when a search provider has an API key, or when keyless parallel is explicitly selected.
• web_fetch — registered when fetch.provider or fetch.summary is configured.
• x_search — registered when xai provider has an API key.
• image_search — registered when an image search provider (dashscope, unsplash) has an API key; /image-search command is registered alongside it. An imageSearch.provider that doesn't support image search (e.g. "openai") is treated as unconfigured.
• If none are configured, the extension loads silently with no tools registered.

Install

pi install npm:@amaster.ai/pi-web-access

Development

pnpm build      # tsc -b
pnpm typecheck  # tsc -b --pretty false
pnpm test       # vitest run src