pi-web-search

A web_search tool for the pi coding agent that uses your z.ai GLM Coding Plan's native web search via the web_search_prime MCP endpoint — included in the plan, no extra cost, no separate API key — with a free DuckDuckGo fallback.

Zero dependencies. Zero configuration. ~350 lines of TypeScript.

Goal

One thing, done well: lean native web search through the z.ai Coding Plan, falling back to DuckDuckGo otherwise.

It's search-only by design — there are already good web_fetch extensions out there, so this one doesn't ship a fetcher, and never will. Pair it with whichever you use and you get a full research pipeline: discover → read.

z.ai is the only native provider for now, simply because that's what I use. Other providers may be added down the line, but that's the most this extension will ever grow into.

How it works

web_search(query)
   │
   ├─ key: ZAI_API_KEY env → ~/.pi/agent/auth.json (zai)
   ▼
┌─────────────────────┐    fail / empty    ┌──────────────────────┐
│  ZAI MCP            │ ─────────────────► │  DuckDuckGo HTML     │
│  web_search_prime   │                    │  regex scrape        │
│  (raw results)      │                    │  (8 results)         │
└─────────────────────┘                    └──────────────────────┘
        trim to 8 → numbered list (title / URL / snippet)
        output annotated with which engine answered

ZAI MCP protocol (https://api.z.ai/api/mcp/web_search_prime/mcp):

1. POST JSON-RPC initialize → capture Mcp-Session-Id response header

2. POST tools/call with web_search_prime + { search_query } (session header)

3. Parse the SSE data: line → the text payload is a double-JSON-encoded array of { title, link, content, refer }

If native search fails or returns nothing, DuckDuckGo takes over automatically, with a visible > zai-mcp unavailable (...) note in the output so you always know which engine answered.

Install

Clone into pi's extensions directory:

git clone <this-repo> ~/.pi/agent/extensions/web-search

Restart pi (or run /reload). The web_search tool appears alongside the built-ins.

Or load it explicitly for a one-off:

pi -e /path/to/pi-web-search/index.ts

Usage

The model calls it on its own when it needs current information:

{ "query": "latest stable node version" }

Returns:

1. **Node.js 24.x is now LTS ...**
   https://nodejs.org/en/blog/announcements/v24-release
   Node.js 24 enters long-term support ...

2. **...**

Configuration

None required. Optional overrides:

Notes

• The Mcp-Session-Id header from the initialize response is required on tools/call

• The MCP text payload is double-JSON-encoded and needs two rounds of JSON.parse

• DuckDuckGo's HTML endpoint may bot-wall curl; testing with Node fetch (real browser User-Agent) matches what the extension actually does

• A fresh MCP session is created per search — fine at typical agent search volume

Future work

• Additional native provider backends (search only — a fetcher will never be part of this)

• Forward optional count / domain filters to the MCP endpoint once its input schema is mapped

• allowed_domains / blocked_domains tool parameters

• Fallback ladder (DDG POST variant → lite.duckduckgo.com → Mojeek) if DDG tightens bot detection