pi-zai-tools 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+### Added
+- `zai_web_search` tool backed by Z.AI Web Search MCP
+- `zai_web_reader` tool backed by Z.AI Web Reader MCP
+- `zai_zread_search_doc` tool backed by Zread MCP
+- `zai_zread_get_repo_structure` tool backed by Zread MCP
+- `zai_zread_read_file` tool backed by Zread MCP
+- env-based module enable/disable with `ZAI_ENABLED_MODULES`
+- unit and live integration tests

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omer Ulusoy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# pi-zai-tools
+
+Pi package for Z.AI remote MCP tools.
+
+It bundles one pi extension that exposes these capabilities:
+- web search via Z.AI Web Search MCP
+- web page reading via Z.AI Web Reader MCP
+- public GitHub repository docs / structure / file access via Zread MCP
+
+## Included tools
+
+- `zai_web_search`
+- `zai_web_reader`
+- `zai_zread_search_doc`
+- `zai_zread_get_repo_structure`
+- `zai_zread_read_file`
+
+## Requirements
+
+- [pi](https://github.com/badlogic/pi-mono)
+- a valid Z.AI API key with GLM Coding Plan access
+
+## Install
+
+### With pi
+
+```bash
+pi install npm:pi-zai-tools
+```
+
+### From a local checkout
+
+```bash
+pi install /absolute/path/to/pi-zai-tools
+```
+
+## Configuration
+
+You can copy `examples.env` as a starting point for local development.
+
+
+### Required
+
+```bash
+export ZAI_API_KEY=your_api_key
+```
+
+### Optional
+
+Enable only selected modules:
+
+```bash
+export ZAI_ENABLED_MODULES=search,reader,zread
+```
+
+Defaults to all modules when omitted.
+
+Override timeout and base URL:
+
+```bash
+export ZAI_TIMEOUT_MS=30000
+export ZAI_BASE_URL=https://api.z.ai
+```
+
+## Module mapping
+
+- `search` → `zai_web_search`
+- `reader` → `zai_web_reader`
+- `zread` → `zai_zread_search_doc`, `zai_zread_get_repo_structure`, `zai_zread_read_file`
+
+## Usage examples
+
+### Search the web
+
+- “Search for recent React Server Components caching guidance”
+- “Find best practices for Python async retry strategies”
+
+### Read a page
+
+- “Read https://example.com and summarize it”
+- “Fetch this documentation page and list the migration steps”
+
+### Research a GitHub repo with Zread
+
+- “Search docs in vercel/ai for installation steps”
+- “Show me the structure of vercel/ai”
+- “Read package.json from vercel/ai”
+
+## Tool parameters
+
+### `zai_web_search`
+- `query: string`
+- `count?: number`
+
+### `zai_web_reader`
+- `url: string`
+
+### `zai_zread_search_doc`
+- `repo: string` (`owner/repo`)
+- `query: string`
+
+### `zai_zread_get_repo_structure`
+- `repo: string` (`owner/repo`)
+
+### `zai_zread_read_file`
+- `repo: string` (`owner/repo`)
+- `path: string`
+
+## Troubleshooting
+
+### Missing API key
+
+If a tool reports that `ZAI_API_KEY` is missing, export it in your shell before launching pi.
+
+### Invalid token / auth failure
+
+Check that:
+- the token is correct
+- the token is active
+- the token has quota left
+
+### Timeout
+
+Increase:
+
+```bash
+export ZAI_TIMEOUT_MS=60000
+```
+
+### Empty or weak results
+
+- try a broader search query
+- verify the target URL is public
+- verify the target repository is public and spelled as `owner/repo`
+
+## Validation status
+
+This package includes:
+- unit tests for config, truncation, service fallback behavior, and extension registration
+- live integration tests against Z.AI MCP endpoints when `ZAI_API_KEY` is available
+
+## Quota note
+
+Quota is controlled by your Z.AI plan, not by this package.
+
+## Security note
+
+Do not hardcode API keys in the package or your repo. Prefer environment variables.
+
+## License
+
+MIT

package/examples.env

@@ -0,0 +1,7 @@
+# Required
+ZAI_API_KEY=your_api_key
+
+# Optional
+# ZAI_ENABLED_MODULES=search,reader,zread
+# ZAI_TIMEOUT_MS=30000
+# ZAI_BASE_URL=https://api.z.ai

package/extensions/zai-tools.ts

@@ -0,0 +1,41 @@
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import { MCP_SERVER_PATHS } from '../src/constants.ts';
+import { loadConfig } from '../src/config.ts';
+import { createRemoteMcpClient } from '../src/client/remote-mcp.ts';
+import { createWebReaderService } from '../src/services/web-reader.ts';
+import { createWebSearchService } from '../src/services/web-search.ts';
+import { createZreadService } from '../src/services/zread.ts';
+import { createWebReaderTool } from '../src/tools/web-reader-tool.ts';
+import { createWebSearchTool } from '../src/tools/web-search-tool.ts';
+import { createZreadGetRepoStructureTool } from '../src/tools/zread-get-repo-structure-tool.ts';
+import { createZreadReadFileTool } from '../src/tools/zread-read-file-tool.ts';
+import { createZreadSearchDocTool } from '../src/tools/zread-search-doc-tool.ts';
+import type { EnvSource } from '../src/types.ts';
+
+interface ExtensionOptions {
+  env?: EnvSource;
+}
+
+export default function zaiToolsExtension(pi: ExtensionAPI, options?: ExtensionOptions) {
+  const config = loadConfig(options?.env);
+
+  if (config.enabledModules.includes('search')) {
+    const client = createRemoteMcpClient(config, MCP_SERVER_PATHS.search);
+    const service = createWebSearchService(client);
+    pi.registerTool(createWebSearchTool(service));
+  }
+
+  if (config.enabledModules.includes('reader')) {
+    const client = createRemoteMcpClient(config, MCP_SERVER_PATHS.reader);
+    const service = createWebReaderService(client);
+    pi.registerTool(createWebReaderTool(service));
+  }
+
+  if (config.enabledModules.includes('zread')) {
+    const client = createRemoteMcpClient(config, MCP_SERVER_PATHS.zread);
+    const service = createZreadService(client);
+    pi.registerTool(createZreadSearchDocTool(service));
+    pi.registerTool(createZreadGetRepoStructureTool(service));
+    pi.registerTool(createZreadReadFileTool(service));
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "pi-zai-tools",
+  "version": "0.1.0",
+  "description": "Pi package that exposes Z.AI Web Search, Web Reader, and Zread MCP tools.",
+  "type": "module",
+  "keywords": ["pi-package", "pi", "zai", "mcp", "search", "reader", "zread"],
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "examples.env"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "pi": {
+    "extensions": ["./extensions"]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "^0.34.41",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/src/client/remote-mcp.ts

@@ -0,0 +1,47 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { McpToolResult, ZaiConfig } from '../types.ts';
+import { AuthError, RemoteMcpError } from '../utils/errors.ts';
+
+export interface RemoteMcpClient {
+  callTool(toolName: string, args: Record<string, unknown>): Promise<McpToolResult>;
+}
+
+export function createRemoteMcpClient(config: ZaiConfig, path: string): RemoteMcpClient {
+  return {
+    async callTool(toolName, args) {
+      if (!config.apiKey) {
+        throw new AuthError();
+      }
+
+      const client = new Client({ name: 'pi-zai-tools', version: '0.1.0' });
+      const transport = new StreamableHTTPClientTransport(new URL(path, config.baseUrl), {
+        requestInit: {
+          headers: {
+            Authorization: `Bearer ${config.apiKey}`,
+          },
+        },
+      });
+
+      const timeout = setTimeout(() => transport.close().catch(() => undefined), config.timeoutMs);
+
+      try {
+        await client.connect(transport);
+        return (await client.callTool({ name: toolName, arguments: args })) as McpToolResult;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/401|403|unauthor/i.test(message)) {
+          throw new RemoteMcpError('Z.AI authentication failed. Check ZAI_API_KEY.');
+        }
+        if (/timeout|abort/i.test(message)) {
+          throw new RemoteMcpError(`Z.AI request timed out after ${config.timeoutMs}ms.`);
+        }
+        throw new RemoteMcpError(message);
+      } finally {
+        clearTimeout(timeout);
+        await transport.close().catch(() => undefined);
+        await client.close().catch(() => undefined);
+      }
+    },
+  };
+}

package/src/config.ts

@@ -0,0 +1,12 @@
+import { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS } from './constants.ts';
+import type { EnvSource, ZaiConfig } from './types.ts';
+import { parseEnabledModules, parseTimeoutMs } from './utils/validation.ts';
+
+export function loadConfig(env: EnvSource = process.env): ZaiConfig {
+  return {
+    apiKey: env.ZAI_API_KEY?.trim() || undefined,
+    baseUrl: env.ZAI_BASE_URL?.trim() || DEFAULT_BASE_URL,
+    timeoutMs: env.ZAI_TIMEOUT_MS?.trim() ? parseTimeoutMs(env.ZAI_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS,
+    enabledModules: parseEnabledModules(env.ZAI_ENABLED_MODULES),
+  };
+}

package/src/constants.ts

@@ -0,0 +1,18 @@
+export const DEFAULT_BASE_URL = 'https://api.z.ai';
+export const DEFAULT_TIMEOUT_MS = 30_000;
+
+export const ENABLED_MODULES = ['search', 'reader', 'zread'] as const;
+
+export const MCP_SERVER_PATHS = {
+  search: '/api/mcp/web_search_prime/mcp',
+  reader: '/api/mcp/web_reader/mcp',
+  zread: '/api/mcp/zread/mcp',
+} as const;
+
+export const MCP_TOOL_NAMES = {
+  webSearch: ['web_search_prime', 'webSearchPrime', 'web_search_prime_web_search_prime'],
+  webReader: 'webReader',
+  zreadSearchDoc: 'search_doc',
+  zreadGetRepoStructure: 'get_repo_structure',
+  zreadReadFile: 'read_file',
+} as const;

package/src/services/web-reader.ts

@@ -0,0 +1,42 @@
+import { MCP_TOOL_NAMES } from '../constants.ts';
+import type { McpCaller, McpToolResult } from '../types.ts';
+import { validateUrl } from '../utils/validation.ts';
+
+const ARG_SHAPES = [
+  (url: string) => ({ url }),
+  (url: string) => ({ target_url: url }),
+  (url: string) => ({ webpage_url: url }),
+];
+
+export function createWebReaderService(client: McpCaller) {
+  return {
+    async read(url: string) {
+      const normalizedUrl = validateUrl(url);
+      return tryArgumentShapes(client, normalizedUrl);
+    },
+  };
+}
+
+async function tryArgumentShapes(client: McpCaller, url: string) {
+  let lastError: unknown;
+
+  for (const shape of ARG_SHAPES) {
+    try {
+      const raw = await client.callTool(MCP_TOOL_NAMES.webReader, shape(url));
+      return { payload: extractPayload(raw), raw };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  throw lastError;
+}
+
+function extractPayload(result: McpToolResult) {
+  if (result.structuredContent && typeof result.structuredContent === 'object') {
+    return result.structuredContent as Record<string, unknown>;
+  }
+
+  const text = result.content?.find((item) => item.type === 'text');
+  return { content: text?.text ?? '' };
+}

package/src/services/web-search.ts

@@ -0,0 +1,55 @@
+import { MCP_TOOL_NAMES } from '../constants.ts';
+import type { McpCaller, McpToolResult } from '../types.ts';
+import { assertNonEmptyString } from '../utils/validation.ts';
+
+export function createWebSearchService(client: McpCaller) {
+  return {
+    async search(query: string, count = 5) {
+      const normalizedQuery = assertNonEmptyString(query, 'query');
+      const normalizedCount = Math.min(Math.max(Math.trunc(count), 1), 10);
+      const result = await tryToolNames(client, {
+        search_query: normalizedQuery,
+        content_size: 'medium',
+      });
+
+      const items = extractItems(result).slice(0, normalizedCount);
+      return { items, raw: result };
+    },
+  };
+}
+
+async function tryToolNames(client: McpCaller, args: Record<string, unknown>) {
+  let lastError: unknown;
+
+  for (const toolName of MCP_TOOL_NAMES.webSearch) {
+    try {
+      return await client.callTool(toolName, args);
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  throw lastError;
+}
+
+function extractItems(result: McpToolResult): Array<Record<string, unknown>> {
+  if (result.structuredContent && typeof result.structuredContent === 'object') {
+    const structured = result.structuredContent as Record<string, unknown>;
+    const candidates = [structured.items, structured.results, structured.data];
+    for (const candidate of candidates) {
+      if (Array.isArray(candidate)) {
+        return toRecords(candidate);
+      }
+    }
+  }
+
+  return toRecords(result.content ?? []);
+}
+
+function toRecords(values: unknown[]): Array<Record<string, unknown>> {
+  return values.filter(isRecord).map((value) => ({ ...value }));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/services/zread.ts

@@ -0,0 +1,90 @@
+import { MCP_TOOL_NAMES } from '../constants.ts';
+import type { McpCaller, McpToolResult } from '../types.ts';
+import { validatePath, validateRepo } from '../utils/validation.ts';
+
+const SEARCH_DOC_ARG_SHAPES = [
+  (repo: string, query: string) => ({ repo_name: repo, query }),
+  (repo: string, query: string) => ({ repo, query }),
+  (repo: string, query: string) => ({ repository: repo, query }),
+  (repo: string, query: string) => ({ repo, search_query: query }),
+];
+
+const REPO_STRUCTURE_ARG_SHAPES = [
+  (repo: string) => ({ repo_name: repo }),
+  (repo: string) => ({ repo }),
+  (repo: string) => ({ repository: repo }),
+];
+
+const READ_FILE_ARG_SHAPES = [
+  (repo: string, path: string) => ({ repo_name: repo, file_path: path }),
+  (repo: string, path: string) => ({ repo_name: repo, path }),
+  (repo: string, path: string) => ({ repo, path }),
+  (repo: string, path: string) => ({ repository: repo, file_path: path }),
+];
+
+export function createZreadService(client: McpCaller) {
+  return {
+    async searchDoc(repo: string, query: string) {
+      const normalizedRepo = validateRepo(repo);
+      const normalizedQuery = query.trim();
+      const raw = await tryCandidates(client, MCP_TOOL_NAMES.zreadSearchDoc, SEARCH_DOC_ARG_SHAPES.map((shape) => shape(normalizedRepo, normalizedQuery)));
+      return { items: extractItems(raw), raw };
+    },
+    async getRepoStructure(repo: string) {
+      const normalizedRepo = validateRepo(repo);
+      const raw = await tryCandidates(client, MCP_TOOL_NAMES.zreadGetRepoStructure, REPO_STRUCTURE_ARG_SHAPES.map((shape) => shape(normalizedRepo)));
+      return { payload: extractPayload(raw), raw };
+    },
+    async readFile(repo: string, path: string) {
+      const normalizedRepo = validateRepo(repo);
+      const normalizedPath = validatePath(path);
+      const raw = await tryCandidates(client, MCP_TOOL_NAMES.zreadReadFile, READ_FILE_ARG_SHAPES.map((shape) => shape(normalizedRepo, normalizedPath)));
+      return { payload: { ...extractPayload(raw), path: normalizedPath }, raw };
+    },
+  };
+}
+
+async function tryCandidates(client: McpCaller, toolName: string, candidates: Array<Record<string, unknown>>) {
+  let lastError: unknown;
+
+  for (const candidate of candidates) {
+    try {
+      return await client.callTool(toolName, candidate);
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  throw lastError;
+}
+
+function extractItems(result: McpToolResult): Array<Record<string, unknown>> {
+  if (result.structuredContent && typeof result.structuredContent === 'object') {
+    const structured = result.structuredContent as Record<string, unknown>;
+    for (const key of ['items', 'results', 'docs', 'data']) {
+      const value = structured[key];
+      if (Array.isArray(value)) {
+        return toRecords(value);
+      }
+    }
+  }
+
+  return toRecords(result.content ?? []);
+}
+
+function toRecords(values: unknown[]): Array<Record<string, unknown>> {
+  return values.filter(isRecord).map((value) => ({ ...value }));
+}
+
+function extractPayload(result: McpToolResult) {
+  if (result.structuredContent && typeof result.structuredContent === 'object') {
+    return result.structuredContent as Record<string, unknown>;
+  }
+
+  const text = result.content?.find((item) => item.type === 'text');
+  return { content: text?.text ?? '' };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/tools/web-reader-tool.ts

@@ -0,0 +1,21 @@
+import { Type } from '@sinclair/typebox';
+import { formatReaderResult } from '../utils/formatting.ts';
+
+export function createWebReaderTool(service: { read: (url: string) => Promise<{ payload: Record<string, unknown>; raw: unknown }> }) {
+  return {
+    name: 'zai_web_reader',
+    label: 'Z.AI Web Reader',
+    description: 'Read a web page using the Z.AI Web Reader MCP server.',
+    parameters: Type.Object({
+      url: Type.String({ description: 'The URL to read' }),
+    }),
+    async execute(_toolCallId: string, params: { url: string }) {
+      const result = await service.read(params.url);
+      const formatted = formatReaderResult(result.payload);
+      return {
+        content: [{ type: 'text' as const, text: formatted.summary }],
+        details: { ...formatted.details, raw: result.raw },
+      };
+    },
+  };
+}

package/src/tools/web-search-tool.ts

@@ -0,0 +1,22 @@
+import { Type } from '@sinclair/typebox';
+import { formatSearchResults } from '../utils/formatting.ts';
+
+export function createWebSearchTool(service: { search: (query: string, count?: number) => Promise<{ items: Array<Record<string, unknown>>; raw: unknown }> }) {
+  return {
+    name: 'zai_web_search',
+    label: 'Z.AI Web Search',
+    description: 'Search the web using the Z.AI Web Search MCP server.',
+    parameters: Type.Object({
+      query: Type.String({ description: 'Search query' }),
+      count: Type.Optional(Type.Number({ description: 'Maximum number of results to format', minimum: 1, maximum: 10 })),
+    }),
+    async execute(_toolCallId: string, params: { query: string; count?: number }) {
+      const result = await service.search(params.query, params.count);
+      const formatted = formatSearchResults(result.items);
+      return {
+        content: [{ type: 'text' as const, text: formatted.summary }],
+        details: { ...formatted.details, raw: result.raw },
+      };
+    },
+  };
+}

package/src/tools/zread-get-repo-structure-tool.ts

@@ -0,0 +1,21 @@
+import { Type } from '@sinclair/typebox';
+import { formatRepoStructure } from '../utils/formatting.ts';
+
+export function createZreadGetRepoStructureTool(service: { getRepoStructure: (repo: string) => Promise<{ payload: Record<string, unknown>; raw: unknown }> }) {
+  return {
+    name: 'zai_zread_get_repo_structure',
+    label: 'Z.AI Zread Repo Structure',
+    description: 'Get a public GitHub repository structure using Zread.',
+    parameters: Type.Object({
+      repo: Type.String({ description: 'Repository in owner/repo format' }),
+    }),
+    async execute(_toolCallId: string, params: { repo: string }) {
+      const result = await service.getRepoStructure(params.repo);
+      const formatted = formatRepoStructure(result.payload);
+      return {
+        content: [{ type: 'text' as const, text: formatted.summary }],
+        details: { ...formatted.details, raw: result.raw },
+      };
+    },
+  };
+}

package/src/tools/zread-read-file-tool.ts

@@ -0,0 +1,22 @@
+import { Type } from '@sinclair/typebox';
+import { formatFileContent } from '../utils/formatting.ts';
+
+export function createZreadReadFileTool(service: { readFile: (repo: string, path: string) => Promise<{ payload: Record<string, unknown>; raw: unknown }> }) {
+  return {
+    name: 'zai_zread_read_file',
+    label: 'Z.AI Zread Read File',
+    description: 'Read a file from a public GitHub repository using Zread.',
+    parameters: Type.Object({
+      repo: Type.String({ description: 'Repository in owner/repo format' }),
+      path: Type.String({ description: 'File path within the repository' }),
+    }),
+    async execute(_toolCallId: string, params: { repo: string; path: string }) {
+      const result = await service.readFile(params.repo, params.path);
+      const formatted = formatFileContent(result.payload);
+      return {
+        content: [{ type: 'text' as const, text: formatted.summary }],
+        details: { ...formatted.details, raw: result.raw },
+      };
+    },
+  };
+}

package/src/tools/zread-search-doc-tool.ts

@@ -0,0 +1,22 @@
+import { Type } from '@sinclair/typebox';
+import { formatSearchResults } from '../utils/formatting.ts';
+
+export function createZreadSearchDocTool(service: { searchDoc: (repo: string, query: string) => Promise<{ items: Array<Record<string, unknown>>; raw: unknown }> }) {
+  return {
+    name: 'zai_zread_search_doc',
+    label: 'Z.AI Zread Search Docs',
+    description: 'Search documentation and repository knowledge for a public GitHub repo using Zread.',
+    parameters: Type.Object({
+      repo: Type.String({ description: 'Repository in owner/repo format' }),
+      query: Type.String({ description: 'Documentation query' }),
+    }),
+    async execute(_toolCallId: string, params: { repo: string; query: string }) {
+      const result = await service.searchDoc(params.repo, params.query);
+      const formatted = formatSearchResults(result.items);
+      return {
+        content: [{ type: 'text' as const, text: formatted.summary }],
+        details: { ...formatted.details, raw: result.raw },
+      };
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,38 @@
+import { ENABLED_MODULES } from './constants.ts';
+
+export type EnabledModule = (typeof ENABLED_MODULES)[number];
+
+export type EnvSource = Record<string, string | undefined>;
+
+export interface ZaiConfig {
+  apiKey?: string;
+  baseUrl: string;
+  timeoutMs: number;
+  enabledModules: EnabledModule[];
+}
+
+export interface TextContentItem {
+  type: 'text';
+  text: string;
+}
+
+export interface JsonContentItem {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface McpToolResult {
+  content?: Array<TextContentItem | JsonContentItem>;
+  structuredContent?: unknown;
+  [key: string]: unknown;
+}
+
+export interface McpCaller {
+  callTool: (toolName: string, args: Record<string, unknown>) => Promise<McpToolResult>;
+}
+
+export interface FormattedToolResult {
+  summary: string;
+  details: Record<string, unknown>;
+}
+

package/src/utils/errors.ts

@@ -0,0 +1,27 @@
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+export class AuthError extends Error {
+  constructor(message = 'Missing ZAI_API_KEY. Set it in your environment before using pi-zai-tools.') {
+    super(message);
+    this.name = 'AuthError';
+  }
+}
+
+export class RemoteMcpError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RemoteMcpError';
+  }
+}

package/src/utils/formatting.ts

@@ -0,0 +1,41 @@
+import type { FormattedToolResult } from '../types.ts';
+import { truncateText } from './truncation.ts';
+
+export function formatSearchResults(items: Array<Record<string, unknown>>): FormattedToolResult {
+  if (items.length === 0) {
+    return { summary: 'No search results returned.', details: { items } };
+  }
+
+  const lines = items.map((item, index) => {
+    const title = String(item.title ?? item.name ?? `Result ${index + 1}`);
+    const url = String(item.url ?? item.link ?? '');
+    const summary = String(item.summary ?? item.snippet ?? '').trim();
+    return [`${index + 1}. ${title}`, url && `   ${url}`, summary && `   ${summary}`]
+      .filter(Boolean)
+      .join('\n');
+  });
+
+  return { summary: lines.join('\n\n'), details: { items } };
+}
+
+export function formatReaderResult(payload: Record<string, unknown>): FormattedToolResult {
+  const title = String(payload.title ?? 'Untitled page');
+  const content = String(payload.content ?? payload.mainContent ?? payload.text ?? '');
+  const truncated = truncateText(content, { maxChars: 8_000, label: 'page content' });
+  const summary = [`# ${title}`, truncated.text].filter(Boolean).join('\n\n');
+  return { summary, details: { ...payload, truncated: truncated.truncated } };
+}
+
+export function formatRepoStructure(payload: Record<string, unknown>): FormattedToolResult {
+  const structure = String(payload.structure ?? payload.tree ?? payload.content ?? '');
+  const truncated = truncateText(structure, { maxChars: 8_000, label: 'repo structure' });
+  return { summary: truncated.text || 'No repository structure returned.', details: { ...payload, truncated: truncated.truncated } };
+}
+
+export function formatFileContent(payload: Record<string, unknown>): FormattedToolResult {
+  const path = String(payload.path ?? 'unknown');
+  const content = String(payload.content ?? payload.text ?? '');
+  const truncated = truncateText(content, { maxChars: 8_000, label: 'file content' });
+  const summary = [`# ${path}`, truncated.text].join('\n\n');
+  return { summary, details: { ...payload, truncated: truncated.truncated } };
+}

package/src/utils/truncation.ts

@@ -0,0 +1,20 @@
+export interface TruncateOptions {
+  maxChars: number;
+  label?: string;
+}
+
+export interface TruncateResult {
+  text: string;
+  truncated: boolean;
+}
+
+export function truncateText(text: string, options: TruncateOptions): TruncateResult {
+  if (text.length <= options.maxChars) {
+    return { text, truncated: false };
+  }
+
+  const label = options.label ?? 'content';
+  const head = text.slice(0, options.maxChars);
+  const suffix = `\n\n[${label} truncated: showing ${options.maxChars} of ${text.length} characters]`;
+  return { text: `${head}${suffix}`, truncated: true };
+}

package/src/utils/validation.ts

@@ -0,0 +1,63 @@
+import { ENABLED_MODULES } from '../constants.ts';
+import type { EnabledModule } from '../types.ts';
+import { ConfigError, ValidationError } from './errors.ts';
+
+const enabledModuleSet = new Set<string>(ENABLED_MODULES);
+
+export function parseEnabledModules(value?: string): EnabledModule[] {
+  if (!value?.trim()) return [...ENABLED_MODULES];
+
+  return value
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => {
+      if (!enabledModuleSet.has(part)) {
+        throw new ConfigError(`Unknown ZAI module: ${part}`);
+      }
+      return part as EnabledModule;
+    });
+}
+
+export function parseTimeoutMs(value?: string): number {
+  if (!value?.trim()) return 30_000;
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new ConfigError('ZAI_TIMEOUT_MS must be a positive integer');
+  }
+  return parsed;
+}
+
+export function assertNonEmptyString(value: string, label: string): string {
+  if (!value.trim()) {
+    throw new ValidationError(`${label} must not be empty`);
+  }
+  return value.trim();
+}
+
+export function validateRepo(repo: string): string {
+  const normalized = assertNonEmptyString(repo, 'repo');
+  if (!/^[^/\s]+\/[^/\s]+$/.test(normalized)) {
+    throw new ValidationError('Invalid repo format. Expected "owner/repo".');
+  }
+  return normalized;
+}
+
+export function validateUrl(url: string): string {
+  const normalized = assertNonEmptyString(url, 'url');
+  try {
+    const parsed = new URL(normalized);
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+      throw new ValidationError('URL must start with http:// or https://');
+    }
+    return parsed.toString();
+  } catch (error) {
+    if (error instanceof ValidationError) throw error;
+    throw new ValidationError('Invalid URL');
+  }
+}
+
+export function validatePath(path: string): string {
+  return assertNonEmptyString(path, 'path');
+}