repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

fix(web): use Z.AI MCP search

810cbc238ef2202afd4848a348ed969570c97a65

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

pi/agent/extensions/web/index.ts

Modified
4 4 * Web Extension for pi
6 6 * Tools:
7 7 * web_fetch — fetch URL, route by Content-Type, extract content via pandoc
8 - * web_search — search Z.AI/MiniMax APIs with DDG fallback
8 + * web_search — search Z.AI Coding Plan MCP/MiniMax APIs with DDG fallback
9 9 * understand_image — analyze images using MiniMax VLM API
11 11 * Uses Node.js native fetch (HTTP/1.1 via undici) which helps avoid
720 720 label: "web_search",
721 721 description: `Search the web and return structured results.
723 -Uses Z.AI Web Search API when available (ZAI_API_KEY or zai provider), then MiniMax search API when available.
723 +Uses Z.AI Coding Plan Web Search MCP when available (ZAI_API_KEY or zai provider), then MiniMax search API when available.
724 724 Falls back to DuckDuckGo HTML.
726 726 Parameters:

pi/agent/extensions/web/zai.test.ts

Modified
5 5 const originalZaiKey = process.env.ZAI_API_KEY;
6 6 const originalZaiBase = process.env.ZAI_BASE_URL;
7 7 const originalZaiSearchBase = process.env.ZAI_SEARCH_BASE_URL;
8 +const originalZaiSearchMcp = process.env.ZAI_SEARCH_MCP_URL;
9 +const originalZaiSearchLocation = process.env.ZAI_SEARCH_LOCATION;
10 +const originalZaiSearchContentSize = process.env.ZAI_SEARCH_CONTENT_SIZE;
9 12 afterEach(() => {
10 13 globalThis.fetch = originalFetch;
14 17 else process.env.ZAI_BASE_URL = originalZaiBase;
15 18 if (originalZaiSearchBase === undefined) delete process.env.ZAI_SEARCH_BASE_URL;
16 19 else process.env.ZAI_SEARCH_BASE_URL = originalZaiSearchBase;
20 + if (originalZaiSearchMcp === undefined) delete process.env.ZAI_SEARCH_MCP_URL;
21 + else process.env.ZAI_SEARCH_MCP_URL = originalZaiSearchMcp;
22 + if (originalZaiSearchLocation === undefined) delete process.env.ZAI_SEARCH_LOCATION;
23 + else process.env.ZAI_SEARCH_LOCATION = originalZaiSearchLocation;
24 + if (originalZaiSearchContentSize === undefined) delete process.env.ZAI_SEARCH_CONTENT_SIZE;
25 + else process.env.ZAI_SEARCH_CONTENT_SIZE = originalZaiSearchContentSize;
17 26 delete process.env.ZAI_SEARCH_FRESHNESS;
20 -describe("zaiSearch", () => {
21 - test("calls direct Web Search API and maps results", async () => {
22 - process.env.ZAI_API_KEY = "test-key";
23 - process.env.ZAI_BASE_URL = "https://api.z.ai";
29 +function sse(data: unknown): string {
30 + return `id:1\nevent:message\ndata:${JSON.stringify(data)}\n\n`;
25 - let requestUrl = "";
26 - let requestBody: Record<string, unknown> = {};
33 +describe("zaiSearch", () => {
34 + test("calls Coding Plan MCP search and maps results", async () => {
35 + process.env.ZAI_API_KEY = "test-key";
37 + const requestUrls: string[] = [];
38 + let callBody: Record<string, unknown> = {};
27 39 globalThis.fetch = (async (input, init) => {
28 - requestUrl = String(input);
29 - requestBody = JSON.parse(String(init?.body));
40 + requestUrls.push(String(input));
41 + const body = JSON.parse(String(init?.body));
30 42 expect(init?.headers).toMatchObject({ Authorization: "Bearer test-key" });
31 - return new Response(JSON.stringify({
32 - id: "search-1",
33 - created: 123,
34 - search_result: [{
35 - title: "Example",
36 - content: "Summary",
37 - link: "https://example.com",
38 - publish_date: "2026-05-09",
39 - }],
40 - }), { status: 200, headers: { "Content-Type": "application/json" } });
44 + if (body.method === "initialize") {
45 + return new Response(sse({ jsonrpc: "2.0", id: 1, result: { protocolVersion: "2024-11-05" } }), {
46 + status: 200,
47 + headers: { "Content-Type": "text/event-stream", "mcp-session-id": "session-1" },
48 + });
49 + }
50 + if (body.method === "notifications/initialized") {
51 + expect(init?.headers).toMatchObject({ "mcp-session-id": "session-1" });
52 + return new Response("", { status: 200 });
53 + }
55 + callBody = body;
56 + expect(init?.headers).toMatchObject({ "mcp-session-id": "session-1" });
57 + const toolText = JSON.stringify(JSON.stringify([{
58 + title: "Example",
59 + content: "Summary",
60 + link: "https://example.com",
61 + publish_date: "2026-05-09",
62 + }]));
63 + return new Response(sse({
64 + jsonrpc: "2.0",
65 + id: 2,
66 + result: { content: [{ type: "text", text: toolText }] },
67 + }), { status: 200, headers: { "Content-Type": "text/event-stream" } });
41 68 }) as typeof fetch;
43 70 const results = await zaiSearch("example", undefined, undefined, { count: 3, freshness: "week" });
45 - expect(requestUrl).toBe("https://api.z.ai/api/paas/v4/web_search");
46 - expect(requestBody).toEqual({
47 - search_engine: "search-prime",
48 - search_query: "example",
49 - count: 3,
50 - search_recency_filter: "oneWeek",
72 + expect(requestUrls).toEqual([
73 + "https://api.z.ai/api/mcp/web_search_prime/mcp",
74 + "https://api.z.ai/api/mcp/web_search_prime/mcp",
75 + "https://api.z.ai/api/mcp/web_search_prime/mcp",
76 + ]);
77 + expect(callBody).toMatchObject({
78 + jsonrpc: "2.0",
79 + method: "tools/call",
80 + params: {
81 + name: "web_search_prime",
82 + arguments: {
83 + search_query: "example",
84 + content_size: "medium",
85 + location: "us",
86 + search_recency_filter: "oneWeek",
87 + },
88 + },
52 90 expect(results).toEqual([{ title: "Example", url: "https://example.com", snippet: "Summary", date: "2026-05-09" }]);
56 94 process.env.ZAI_API_KEY = "test-key";
57 95 process.env.ZAI_SEARCH_FRESHNESS = "month";
59 - let requestBody: Record<string, unknown> = {};
97 + let callArgs: Record<string, unknown> = {};
60 98 globalThis.fetch = (async (_input, init) => {
61 - requestBody = JSON.parse(String(init?.body));
62 - return new Response(JSON.stringify({ search_result: [] }), { status: 200 });
99 + const body = JSON.parse(String(init?.body));
100 + if (body.method === "initialize") {
101 + return new Response(sse({ jsonrpc: "2.0", id: 1, result: {} }), { status: 200, headers: { "mcp-session-id": "s" } });
103 + if (body.method === "notifications/initialized") return new Response("", { status: 200 });
104 + callArgs = body.params.arguments;
105 + return new Response(sse({ jsonrpc: "2.0", id: 2, result: { content: [{ type: "text", text: "[]" }] } }), { status: 200 });
63 106 }) as typeof fetch;
65 108 await zaiSearch("example", undefined, undefined, { count: 3 });
66 - expect(requestBody).toMatchObject({ search_recency_filter: "oneMonth" });
109 + expect(callArgs).toMatchObject({ search_recency_filter: "oneMonth" });
69 - test("normalizes base URLs that already include /api paths", async () => {
112 + test("normalizes base URLs to the MCP endpoint", async () => {
70 113 process.env.ZAI_API_KEY = "test-key";
71 - process.env.ZAI_BASE_URL = "https://api.z.ai/api/mcp/web_search_prime/mcp";
114 + process.env.ZAI_SEARCH_MCP_URL = "https://api.z.ai/api/mcp/web_search_prime/mcp";
73 116 let requestUrl = "";
74 - globalThis.fetch = (async (input) => {
117 + globalThis.fetch = (async (input, init) => {
75 118 requestUrl = String(input);
76 - return new Response(JSON.stringify({ search_result: [] }), { status: 200 });
119 + const body = JSON.parse(String(init?.body));
120 + if (body.method === "initialize") return new Response(sse({ jsonrpc: "2.0", id: 1, result: {} }), { status: 200, headers: { "mcp-session-id": "s" } });
121 + if (body.method === "notifications/initialized") return new Response("", { status: 200 });
122 + return new Response(sse({ jsonrpc: "2.0", id: 2, result: { content: [{ type: "text", text: "[]" }] } }), { status: 200 });
77 123 }) as typeof fetch;
79 125 await zaiSearch("example", undefined);
80 - expect(requestUrl).toBe("https://api.z.ai/api/paas/v4/web_search");
126 + expect(requestUrl).toBe("https://api.z.ai/api/mcp/web_search_prime/mcp");
83 - test("ZAI_SEARCH_BASE_URL overrides chat/provider base URL", async () => {
129 + test("ZAI_SEARCH_BASE_URL overrides with MCP endpoint normalization", async () => {
84 130 process.env.ZAI_API_KEY = "test-key";
85 - process.env.ZAI_BASE_URL = "https://wrong.example.com/api/paas/v4/chat/completions";
86 131 process.env.ZAI_SEARCH_BASE_URL = "https://api.z.ai/api/paas/v4";
88 133 let requestUrl = "";
89 - globalThis.fetch = (async (input) => {
134 + globalThis.fetch = (async (input, init) => {
90 135 requestUrl = String(input);
91 - return new Response(JSON.stringify({ search_result: [] }), { status: 200 });
136 + const body = JSON.parse(String(init?.body));
137 + if (body.method === "initialize") return new Response(sse({ jsonrpc: "2.0", id: 1, result: {} }), { status: 200, headers: { "mcp-session-id": "s" } });
138 + if (body.method === "notifications/initialized") return new Response("", { status: 200 });
139 + return new Response(sse({ jsonrpc: "2.0", id: 2, result: { content: [{ type: "text", text: "[]" }] } }), { status: 200 });
92 140 }) as typeof fetch;
94 142 await zaiSearch("example", undefined);
95 - expect(requestUrl).toBe("https://api.z.ai/api/paas/v4/web_search");
143 + expect(requestUrl).toBe("https://api.z.ai/api/mcp/web_search_prime/mcp");
98 146 test("classifies auth errors", async () => {

pi/agent/extensions/web/zai.ts

Modified
2 - * Z.AI Web Search API client.
3 - * Direct HTTP API, not MCP.
4 - * Docs: https://docs.z.ai/api-reference/tools/web-search
2 + * Z.AI Coding Plan Web Search client.
3 + * Uses the Coding Plan MCP endpoint, not the paid REST Web Search API.
4 + * Docs: https://docs.z.ai/devpack/mcp/search-mcp-server
7 7 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
15 15 title?: string;
16 16 content?: string;
17 17 link?: string;
18 + url?: string;
18 19 media?: string;
19 20 icon?: string;
20 21 refer?: string;
21 22 publish_date?: string;
23 + date?: string;
24 -interface ZaiSearchResponse {
25 - id?: string;
26 - created?: number;
27 - search_result?: ZaiSearchObjectResponse[];
26 +interface ZaiErrorResponse {
28 27 code?: number | string;
29 28 message?: string;
30 29 error?: { code?: number | string; message?: string };
32 +interface JsonRpcResponse<T = unknown> {
33 + jsonrpc?: string;
34 + id?: string | number | null;
35 + result?: T;
36 + error?: { code?: number | string; message?: string; data?: unknown };
39 +interface McpInitializeResult {
40 + protocolVersion?: string;
41 + capabilities?: Record<string, unknown>;
42 + serverInfo?: Record<string, unknown>;
45 +interface McpToolCallResult {
46 + content?: Array<{ type?: string; text?: string }>;
47 + isError?: boolean;
33 50 export type ZaiErrorKind =
34 51 | "auth"
35 52 | "quota"
58 -const DEFAULT_ZAI_BASE_URL = "https://api.z.ai";
75 +const DEFAULT_ZAI_MCP_URL = "https://api.z.ai/api/mcp/web_search_prime/mcp";
59 76 const ZAI_PROVIDER_NAMES = ["zai", "z-ai", "z.ai", "bigmodel"] as const;
60 77 const ZAI_API_KEY_ENV = ["ZAI_API_KEY", "Z_AI_API_KEY"] as const;
61 78 const ZAI_NO_FRESHNESS = new Set(["", "none", "nolimit", "no_limit"]);
106 123 return undefined;
109 -export function resolveZaiBaseUrl(ctx?: ExtensionContext): string {
110 - const envBase = process.env.ZAI_SEARCH_BASE_URL?.trim() || process.env.ZAI_BASE_URL?.trim();
111 - if (envBase) return envBase;
113 - const model = ctx?.modelRegistry.getAll().find((m) =>
114 - ZAI_PROVIDER_NAMES.includes(m.provider as typeof ZAI_PROVIDER_NAMES[number]),
115 - );
116 - return model?.baseUrl ?? DEFAULT_ZAI_BASE_URL;
126 +export function resolveZaiMcpUrl(): string {
127 + const envUrl = process.env.ZAI_SEARCH_MCP_URL?.trim() || process.env.ZAI_SEARCH_BASE_URL?.trim();
128 + if (envUrl) return normalizeMcpUrl(envUrl);
129 + return DEFAULT_ZAI_MCP_URL;
119 132 export async function isZaiAvailable(ctx?: ExtensionContext): Promise<boolean> {
120 133 return !!(await resolveZaiApiKey(ctx));
123 -function normalizeApiBaseUrl(baseUrl: string): string {
124 - const base = baseUrl.trim().replace(/\/+$/, "");
136 +function normalizeMcpUrl(input: string): string {
137 + const value = input.trim().replace(/\/+$/, "");
126 - const url = new URL(base);
127 - if (url.pathname === "/api" || url.pathname.startsWith("/api/")) {
128 - return `${url.origin}/api`;
129 - }
130 - return `${url.origin}${url.pathname}/api`.replace(/\/+api$/, "/api");
139 + const url = new URL(value);
140 + if (url.pathname.endsWith("/mcp")) return value;
141 + return `${url.origin}/api/mcp/web_search_prime/mcp`;
131 142 } catch {}
132 - return base.endsWith("/api") ? base : `${base}/api`;
143 + return value.endsWith("/mcp") ? value : `${value}/api/mcp/web_search_prime/mcp`;
135 146 function classifyZaiError(code: string | undefined, status: number | undefined, message: string): ZaiErrorKind {
161 172 const text = await response.text().catch(() => "");
162 173 if (!text) return makeZaiApiError(response.status, undefined, response.statusText || "request failed");
164 - const data = JSON.parse(text) as ZaiSearchResponse;
175 + const data = JSON.parse(text) as ZaiErrorResponse;
165 176 return makeZaiApiError(response.status, data.error?.code ?? data.code, data.error?.message ?? data.message ?? response.statusText);
166 177 } catch {}
167 178 return makeZaiApiError(response.status, undefined, `${response.statusText}: ${text.slice(0, 500)}`);
181 +function parseSseOrJson<T>(text: string): JsonRpcResponse<T> {
182 + const trimmed = text.trim();
183 + if (!trimmed) return {};
185 + const dataLines = trimmed
186 + .split(/\r?\n/)
187 + .filter((line) => line.startsWith("data:"))
188 + .map((line) => line.slice(5).trim())
189 + .filter(Boolean);
191 + if (dataLines.length > 0) {
192 + for (const dataLine of dataLines) {
193 + const parsed = JSON.parse(dataLine) as JsonRpcResponse<T>;
194 + if (parsed.result !== undefined || parsed.error !== undefined) return parsed;
196 + return JSON.parse(dataLines[dataLines.length - 1]) as JsonRpcResponse<T>;
199 + return JSON.parse(trimmed) as JsonRpcResponse<T>;
202 +async function postJsonRpc<T>(
203 + url: string,
204 + apiKey: string,
205 + payload: Record<string, unknown>,
206 + signal: AbortSignal,
207 + sessionId?: string,
208 +): Promise<{ data: JsonRpcResponse<T>; sessionId?: string }> {
209 + const response = await fetch(url, {
210 + method: "POST",
211 + headers: {
212 + "Authorization": `Bearer ${apiKey}`,
213 + "Content-Type": "application/json",
214 + "Accept": "application/json, text/event-stream",
215 + ...(sessionId ? { "mcp-session-id": sessionId } : {}),
216 + },
217 + body: JSON.stringify(payload),
218 + signal,
219 + });
221 + if (!response.ok) {
222 + throw await parseZaiError(response);
225 + const text = await response.text();
226 + if (!text.trim()) return { data: {}, sessionId: response.headers.get("mcp-session-id") ?? undefined };
228 + let data: JsonRpcResponse<T>;
229 + try {
230 + data = parseSseOrJson<T>(text);
231 + } catch {
232 + throw makeZaiApiError(response.status, undefined, `Malformed MCP response: ${text.slice(0, 500)}`);
235 + if (data.error) {
236 + throw makeZaiApiError(response.status, data.error.code, data.error.message);
239 + return { data, sessionId: response.headers.get("mcp-session-id") ?? undefined };
242 +async function initializeMcpSession(url: string, apiKey: string, signal: AbortSignal): Promise<string | undefined> {
243 + const { sessionId } = await postJsonRpc<McpInitializeResult>(url, apiKey, {
244 + jsonrpc: "2.0",
245 + id: 1,
246 + method: "initialize",
247 + params: {
248 + protocolVersion: "2025-03-26",
249 + capabilities: {},
250 + clientInfo: { name: "pi-web-extension", version: "0.1.0" },
251 + },
252 + }, signal);
254 + await postJsonRpc(url, apiKey, {
255 + jsonrpc: "2.0",
256 + method: "notifications/initialized",
257 + params: {},
258 + }, signal, sessionId);
260 + return sessionId;
263 +function decodeSearchItems(text: string): ZaiSearchObjectResponse[] {
264 + let value: unknown = text.trim();
266 + for (let i = 0; i < 3 && typeof value === "string"; i++) {
267 + try {
268 + value = JSON.parse(value);
269 + } catch {
270 + break;
274 + if (Array.isArray(value)) return value as ZaiSearchObjectResponse[];
275 + if (value && typeof value === "object") {
276 + const record = value as { search_result?: ZaiSearchObjectResponse[]; results?: ZaiSearchObjectResponse[] };
277 + if (Array.isArray(record.search_result)) return record.search_result;
278 + if (Array.isArray(record.results)) return record.results;
281 + return [];
284 +function mcpResultToSearchResults(result: McpToolCallResult): SearchResult[] {
285 + const text = result.content?.find((item) => item.type === "text" && item.text)?.text
286 + ?? result.content?.find((item) => item.text)?.text;
288 + if (result.isError) {
289 + throw makeZaiApiError(200, undefined, text ?? "MCP tool returned an error");
291 + if (!text) return [];
293 + return decodeSearchItems(text).map((r) => ({
294 + title: r.title ?? r.link ?? r.url ?? "Untitled",
295 + url: r.link ?? r.url ?? "",
296 + snippet: r.content ?? r.media ?? "",
297 + date: r.publish_date ?? r.date,
298 + })).filter((r) => r.url);
170 301 export async function zaiSearch(
171 302 query: string,
172 303 ctx: ExtensionContext | undefined,
178 309 throw new Error("Z.AI API key not configured. Set ZAI_API_KEY or configure a zai provider.");
181 - const count = Math.min(Math.max(Math.trunc(options?.count ?? 10), 1), 50);
182 - const body: Record<string, unknown> = {
183 - search_engine: "search-prime",
184 - search_query: query,
185 - count,
186 - };
187 312 const freshness = options?.freshness ?? resolveDefaultFreshness();
188 - if (freshness) {
189 - body.search_recency_filter = FRESHNESS_TO_RECENCY[freshness];
190 - }
313 + const toolArgs: Record<string, unknown> = {
314 + search_query: query,
315 + content_size: process.env.ZAI_SEARCH_CONTENT_SIZE?.trim() || "medium",
316 + location: process.env.ZAI_SEARCH_LOCATION?.trim() || "us",
317 + };
318 + if (freshness) toolArgs.search_recency_filter = FRESHNESS_TO_RECENCY[freshness];
192 - const url = `${normalizeApiBaseUrl(resolveZaiBaseUrl(ctx))}/paas/v4/web_search`;
193 320 const timeoutSignal = AbortSignal.timeout(options?.timeoutMs ?? 30_000);
194 321 const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
322 + const url = resolveZaiMcpUrl();
323 + const sessionId = await initializeMcpSession(url, apiKey, requestSignal);
196 - const response = await fetch(url, {
197 - method: "POST",
198 - headers: {
199 - "Authorization": `Bearer ${apiKey}`,
200 - "Content-Type": "application/json",
201 - "Accept-Language": "en-US,en",
325 + const { data } = await postJsonRpc<McpToolCallResult>(url, apiKey, {
326 + jsonrpc: "2.0",
327 + id: 2,
328 + method: "tools/call",
329 + params: {
330 + name: "web_search_prime",
331 + arguments: toolArgs,
203 - body: JSON.stringify(body),
204 - signal: requestSignal,
205 - });
333 + }, requestSignal, sessionId);
207 - if (!response.ok) {
208 - throw await parseZaiError(response);
209 - }
211 - const data = (await response.json()) as ZaiSearchResponse;
212 - if (data.error || data.code !== undefined) {
213 - throw makeZaiApiError(response.status, data.error?.code ?? data.code, data.error?.message ?? data.message);
214 - }
216 - const results = data.search_result ?? [];
217 - return results.map((r) => ({
218 - title: r.title ?? r.link ?? "Untitled",
219 - url: r.link ?? "",
220 - snippet: r.content ?? r.media ?? "",
221 - date: r.publish_date,
222 - })).filter((r) => r.url);
335 + const results = mcpResultToSearchResults(data.result ?? {});
336 + const count = Math.min(Math.max(Math.trunc(options?.count ?? results.length), 1), 50);
337 + return results.slice(0, count);